IMcOMGlobalMcRankedHistogramValues Method

Parameters

HistogramArray

Type: SystemObject
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)

Type: SystemObject
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)

Type: SystemInt32
Number of ranks to compute for appending N-tiles to the results. The NumberOfRanks is the number of intervals that the input is to be broken into. For example, for quartiles (25, 50 and 75%) NumberOfRanks is given as 4. For deciles (10, 20, 30..., 90%) NumberOfRanks is given as 10. Since the Minimum and Maximum values are always returned (in the mcrvfiMinimum and mcrvfiMaximum elements of the results array), only the NumberOfRanks-1 inner ranks are appended to the end of the results (e.g., the three 25, 50 and 75% quartile ranks when NumberOfRanks is four). If NumberOfRanks is less than 2, then no N-tiles are appended and only the 6 basic results are returned; this is the default situation.

Return Value

Type: McObject
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.

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 75% quartiles are to be appended). One standard non-parametric statistic, the Mode, is not computed. To compute the Mode of a histogram look for the bin(s) with the maximum number of counts or highest weight (e.g., with the McOpMax method). When passed a 1-D array of bins, the routine returns a single length K array result computed from the values of the source array. When passed a 2-D or higher dimensioned array, then statistics are performed on the fastest moving dimension (the leftmost in VB, the rightmost in C/C++). This dimension must be the same size for all histogram arrays (i.e.,they must all have the same number of bins). The returned result from 2 and higher dimensioned arrays is an array of sets of the K results. This array is shaped like the HistogramArray except that the fastest moving dimension is replaced by the K results. Although the situation will rarely arise, missing values in Single or Double CalibratedBinValues sources are detected (see McMissingSingle, McMissingDouble, and McIsMissingValue). The bins corresponding to all such values are skipped and their accumulated bin counts or weights is placed in the mcrvfiCountOfMissing element of the results array. The first (mcrvfiCount) element of the results array is the accumulated count or weights of all of all bins with non-missing CalibratedBinValues. Should all CalibratedBinValues be missing, then mcrvfiCount element will be zero, the mcrvfiCountOfMissing element will be the length of the source array and all other elements of the returned results array are filled with the McMissingDouble value. If a set of HistogramArray bins is empty (all bins zero), then all elements of the results array will be zero, including the mcrvfiCount and 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.)

'******** Ranked Histogram Values Test
Private Sub J_RankedHistogramVals_Click()
Dim mcoT As McObject
Set mcoT = McOpCast(McOpFillIn(1, 101), "REAL") 'numbers from 1.0 thru 100.0
Dim mcoH As McObject
Set mcoH = McVectorHistogram(mcoT, 10, Array(1, 10))
Dim varRV1 As Variant
varRV1 = McRankedHistogramValues(mcoH, Array(5, 95), 4) 'get the rank info
Results.Text = McSprintf(McCStr("Basic Ranked Histogram vals of 1-100 mapped onto 10 bins: N= %f" & _
"\nMin: %f, Max: %f, Median: %f, Avg Abs Dev from Median: %f"), _
varRV1(mcrvfiCount), varRV1(mcrvfiMinimum), _
varRV1(mcrvfiMaximum), varRV1(mcrvfiMedian), varRV1(mcrvfiAvgDevFromMedian)) _
& McSprintf(McCStr("\nInterior (25,50,75) Quartile Ranks: %f, %f, %f"), _
varRV1(mcrvfiFirstNtileIndex + 0), _
varRV1(mcrvfiFirstNtileIndex + 1), _
varRV1(mcrvfiFirstNtileIndex + 2))
If ThisApplication.ActiveImage Is Nothing Then Exit Sub
With ThisApplication.ActiveImage.Histogram
.mode = mchmApplyIntensityCalibration Or mchmApplySpatialCalibration
.Interpretation = mciRGB
Dim varHistogramVals As Variant
varHistogramVals = .Values
Dim varBinCalibrations As Variant
varBinCalibrations = .BinXValues
Dim mcoRankedValuesMatrix As McObject 'will be 2-D array of info
Set mcoRankedValuesMatrix = McRankedHistogramValues(varHistogramVals, varBinCalibrations, 4)
Results.Text = Results.Text & vbCrlf & vbCrlf & "Color Histograms Ranked Values:"
Dim lC As Long
For lC = 0 To 2 'for each color channel's histogram
'Use SelectedValues to get the whole results array for one color
Dim varRV As Variant
varRV = mcoRankedValuesMatrix.SelectedValues(lC) 'get the whole array
Results.Text = Results.Text + McSprintf(McCStr("\n   Color: %d.  N= %f" & _
"\nMin: %f, Max: %f, Median: %f, Avg Abs Dev from Median: %f"), _
lC, varRV(mcrvfiCount), varRV(mcrvfiMinimum), _
varRV(mcrvfiMaximum), varRV(mcrvfiMedian), varRV(mcrvfiAvgDevFromMedian)) _
& McSprintf(McCStr("\nInterior (25,50,75) Quartile Ranks: %f, %f, %f"), _
varRV(mcrvfiFirstNtileIndex + 0), _
varRV(mcrvfiFirstNtileIndex + 1), _
varRV(mcrvfiFirstNtileIndex + 2))
Next lC 'color channel
End With 'ActiveImage.Histogram
End Sub 'J_RankedHistogramVals_Click