The SampleRTable(R, S, O) function converts a 1- or 2-D 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 sub-block 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 sub-block contains at least one value. A completely empty sub-block is represented by a 0 in the summary; if there are one or more entries in the sub-block, it is represented by a 1. A sub-block 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 sub-block is nonzero. The actual density of each sub-block 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 2-Vector 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 sub-block. 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 non-empty sub-blocks have the same density, then they have the value 127 when the density is scaled into the range -127..127. Similarly, if all sub-blocks 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 density-magnitude combinations.

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.