SampleRTable  convert rtable section to a Vector or Matrix

Calling Sequence


SampleRTable(R, S, O, t, v, f, c)


Parameters


R



rtable (type Array, Matrix, or Vector)

S



list of integers and/or integer ranges; portion of the rtable to convert

O



list of positive integers; dimensions of the resulting Vector or Matrix

t



(optional) BooleanOpt(transpose); specifies if selected rtable portion is transposed

v



(optional) equation of the form view=keyword where keyword is one of 'structure', 'density', or 'magnitude'; type of plot to return

f



(optional) equation of the form function=keyword where keyword is one of 'minimum', 'maximum', or 'average'; how to compute the plot in the case of the magnitude view

c



(optional) equation of the form clip=range where range is a range of integers; override the computed minimum and maximum bounds in the case of the magnitude view





Description


•

The SampleRTable(R, S, O) function converts a 1 or 2D portion S of an rtable to a Vector or Matrix of size O.


This is done by reducing blocks of values to a single value. For example, if a 1000 x 1000 entry portion of an rtable is to be reduced to a 250 x 250 entry Matrix, each entry in the resultant Matrix is computed based on a subblock that is 4 x 4 entries in size. The blocks may not all be exactly the same size; however, each entry in the input portion is counted only once.

•

If t is included in the calling sequence as transpose=true, the input portion of the rtable S is transposed.


The condition transpose=true can be abbreviated to transpose. The default value for t is transpose=false.

•

There are three types of plots available by including v in the calling sequence: structure, density, and magnitude.


A structure plot shows whether each subblock contains at least one value. A completely empty subblock is represented by a 0 in the summary; if there are one or more entries in the subblock, it is represented by a 1. A subblock whose entries are not stored and for which the value cannot be determined from the shape (indexing function) is represented by a 2.


A density plot returns both structure information (as described above) and, in a second Matrix or Vector, density information. The density summary uses a scale to show what proportion of a subblock is nonzero. The actual density of each subblock is computed (as a value between 0 and 1), then the actual range of densities is scaled into the range 127..127. A density of 128 means that there are NO entries in the summarized subregion. If there are any entries at all in the block, the density value will be at least 127.


A magnitude plot returns structure, density, and magnitude information. The magnitude information is returned via a third Matrix and a 2Vector containing the actual low and high magnitudes (in that order). The magnitude summary is computed in one of three ways: it is either the maximum, the minimum, or the average nonzero value in the subblock. The actual magnitude value is calculated for each sub block, then the actual magnitude range is scaled into the range 127..127. A magnitude of 128 means that the magnitude could not be computed, either because there were no entries or because a symbolic value was encountered.


Note: A computed value of 128 will be scaled into the range 127..127.


If all nonempty subblocks have the same density, then they have the value 127 when the density is scaled into the range 127..127. Similarly, if all subblocks have the same magnitude, then they have the value 127 when the magnitude is scaled into the range 127..127.


It may not always be appropriate to scale the actual magnitude range into the range 127..127. If there is a single extreme value (either high or low), undue clumping of the remaining values in a very narrow part of the output range occurs. If there is a narrow range (for example, a bitmap in which all the values are in the range 100..255), it may not be desirable to spread them out of the full output range. (In the case of the bitmap example, the picture would become very washed out.) To solve these magnitude difficulties, the user may specify a magnitude output range c. The specified output range is then scaled to 127..127. Values below the specified range are clipped and scaled to 127; values above the specified range are clipped and scaled to 127.


The following table indicates the meaning of the various densitymagnitude combinations.


magnitude = 128

magnitude > 128

density = 128

no entries

impossible (if there are no entries, no magnitude can be calculated)

density > 128

magnitude can't be computed (contained symbolic entries)

normal situation: at least one entry is present; magnitude as shown



•

It is an error to request an output object with more rows or columns than the input object.

•

The output type (Vector or Matrix) is based on the number of ranges found in parameter S. If there is one range, the output is a Vector; if there are two ranges, the output is a Matrix; if there are no ranges or more than two ranges, an error is generated.


If there are two ranges specified, the first one represents the rows of the output Matrix and the second represents the columns. This can be overridden by specifying parameter t as transpose or transpose=true.


If a portion of a Vector is requested, the output is returned as a column Vector. This can be overridden by specifying parameter t as transpose or transpose=true.



Examples


>

$M:=\u27e8\u27e81\,0\,0\,0\u27e9\\u27e8\'x\'\,2\,0\,0\u27e9\\u27e83\,4\,5\,0\u27e9\\u27e86\,7\,8\,9\u27e9\u27e9$

${M}{:=}\left[\begin{array}{cccc}{1}& {x}& {3}& {6}\\ {0}& {2}& {4}& {7}\\ {0}& {0}& {5}& {8}\\ {0}& {0}& {0}& {9}\end{array}\right]$
 (1) 
>

$\mathrm{SampleRTable}\left(M\,\left[1..4\,1..4\right]\,\left[2\,2\right]\right)$

$\left[\begin{array}{rr}{1}& {1}\\ {0}& {1}\end{array}\right]$
 (2) 
>

$\mathrm{SampleRTable}\left(M\,\left[1..4\,1..4\right]\,\left[2\,2\right]\,\mathrm{view}\=\mathrm{density}\right)$

$\left[\begin{array}{rr}{1}& {1}\\ {0}& {1}\end{array}\right]{\,}\left[\begin{array}{rr}{62}& {126}\\ {}{128}& {62}\end{array}\right]$
 (3) 
>

$\mathrm{SampleRTable}\left(M\,\left[1..4\,1..4\right]\,\left[2\,2\right]\,\mathrm{view}\=\mathrm{magnitude}\right)$

$\left[\begin{array}{rr}{1}& {1}\\ {0}& {1}\end{array}\right]{\,}\left[\begin{array}{rr}{62}& {126}\\ {}{128}& {62}\end{array}\right]{\,}\left[\begin{array}{rr}{}{128}& {103}\\ {}{127}& {127}\end{array}\right]{\,}\left[\begin{array}{c}{0.}\\ {5.50000000000000}\end{array}\right]$
 (4) 

