Description
Computes basic non-parametric results from ranked values on one or more arrays.
-
Return Type
-
A McObject object.
A McObject of type mcobjTypeREAL holding an array or matrix of K results for each input array found in HistogramArray. The result array length, K is max(mcrvfiFirstNtileIndex + NumberOfRanks - 1, mcrvfiFirstNtileIndex), where mcrvfiFirstNtileIndex is 6 (the enum mcobjRankedValuesFieldIndices specifies mcrvfiCount, mcrvfiCountOfMissing, mcrvfiMinimum, mcrvfiMaximum, mcrvfiMedian, mcrvfiAvgDevFromMedian before mcrvfiFirstNtileIndex).
If HistogramArray is a 1-D array, then the returned result will be single length K array result. If ArrayToTest is an N-dimensioned array (where N is 2 or more), then the returned result will also be an N dimensioned array, where the shape of the results array is identical to the shape ofHistogramArray up to the fastest moving dimension, which is always of size K for the results array.
-
Syntax
-
object.McRankedHistogramValues (HistogramArray, [CalibratedBinValues], [NumberOfRanks])
The McRankedHistogramValues Method syntax has these parts: |
| object | An expression evaluating to an object of type McOMGlobal. | | HistogramArray | Required. A Variant value. A one or higher dimensioned array of histogram integral bin counts or floating point weights on which ranked value statistics are to be computed for the fastest-moving dimension. All dimensions must be one one size; the size of the fastest moving dimension will be the number of bins analyzed.
| | CalibratedBinValues | Optional. A Variant value. If given, must be a length 2 or longer array of calibrated values to be mapped onto the histogram bins. Usually either only two values are supplied or one value is supplied for each bin. If 2 values are supplied, they give to the values of the first and last bin; the intermediate bins are assigned linearly interpolated values. If one value is supplied for each bin, then an arbitrary value mapping is possible (e.g., an inverse log relationship between bin index and value would be used for optical density). The IQL McSpatialCalibration.LUT property exposes a suitable array of values for mapping the bin indices to calibrated values. And the McHistogram.BinXValues property is directly suitable when the McHistogram.Values property is used as the HistogramArray (see Examples).
| | NumberOfRanks | Optional. A Long value. is less than 2, then no N-tiles are appended and only the 6 basic results are returned; this is the default situation.
|
Remarks
This method computes basic non-parametric statistics on one or more arrays of histogram bin counts or weights. Optionally, it also computes a specified number of N-tiles (e.g., quartiles or deciles). The results are computed from values sorted (i.e., ranked) from the array to test. For parametric statistics, use the McHistogramStatistics method.
The basic results computed for each input array of histogram bins are: Count of non-missing values, Count of missing values, Minimum value, Maximum value, Median value and Average absolute deviation from the Median. These six values are returned as an array of Double followed by “inner” N-tiles (numbering NumberOfRanks-1, if NumberOfRanks is greater than 1). The enum mcobjRankedValuesFieldIndices specifies named index values for the 6 base results and an index value for the first of the N-tiles (mcrvfiCount, mcrvfiCountOfMissing, mcrvfiMinimum, mcrvfiMaximum, mcrvfiMedian, mcrvfiAvgDevFromMedian before mcrvfiFirstNtileIndex). The total length of the results will be K=max(mcrvfiFirstNtileIndex+NumberOfRanks-1,mcrvfiFirstNtileIndex); for example, K will be 6+4-1=9 if NumberOfRanks is 4 (the 25, 50 and 75McMissingSingle:IQL~McOMGlobal~McMissingSingle, McMissingDouble:IQL~McOMGlobal~McMissingDouble, and McIsMissingValue:IQL~McOMGlobal~McIsMissingValuemcrvfiCountOfMissing:IQL~mcobjRankedValuesFieldIndices~mcrvfiCountOfMissingmcrvfiCount:IQL~mcobjRankedValuesFieldIndices~mcrvfiCountmcrvfiCount:IQL~mcobjRankedValuesFieldIndices~mcrvfiCount element will be zero, the mcrvfiCountOfMissing:IQL~mcobjRankedValuesFieldIndices~mcrvfiCountOfMissing element will be the length of the source array and all other elements of the returned results array are filled with the McMissingDouble:IQL~McOMGlobal~McMissingDoublemcrvfiCount:IQL~mcobjRankedValuesFieldIndices~mcrvfiCount and mcrvfiCountOfMissing:IQL~mcobjRankedValuesFieldIndices~mcrvfiCountOfMissing% elements.
Negative bin counts are treated as zero (have no weight) and ignored without error. The Minimum and Maximum are values associated with the first and last, respectively, bins with non-zero count.
All rank results are given as the CalibratedBinValues associated with the bin index where the cumulative count or weight reaches the rank threshold. No attempt is made to interpolate results between bins, even for those rare cases where it might make sense (e.g., computing the Median when exactly 1/2 of all counts fall in the first and last bins with all others empty. McRankedHistogramValues will report the Media as the value associated with the first bin in this case.)
|
McRankedHistogramValues Method
