IMcOMGlobalMcRankedValues Method

Parameters

ArrayToTest

Type: SystemObject
A one or higher dimensioned array of values on which ranked value statistics are to be computed for the fastest-moving dimension. All dimensions except the analyzed one must be one one size.

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 ArrayToTest. 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 ArrayToTest 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 of ArrayToTest 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 values. 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 basic parametric statistics, use the McBasicStatistics method. The results always computed for each input array 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. This is because the Mode (the value that appears most frequently in the input array) is so susceptible to being thrown off by tiny discrepancies in the input data. If you want to find peaks in the distribution of values (which is what the Mode is supposed to be), then a better approach is to pass your data array to the McVectorHistogram method and look for the bin(s) with the maximum number of counts. When passed a 1-D array, 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 may be variable in size, which can happen if the ArrayToTest is itself an array of Variant, where each Variant is an array (the McLineProfiles.ProfileValues used in the Examples is an property that is exposed in this way). The returned result from 2 and higher dimensioned arrays is an array of sets of the K results. This array is shaped like the ArrayToTest except that the fastest moving dimension is replaced by the K results. Missing values in Single or Double ArrayToTest sources are detected (see McMissingSingle, McMissingDouble, and McIsMissingValue). All such values are skipped and their number is placed in the mcrvfiCountOfMissing element of the results array. The first (mcrvfiCount) element of the results array is a count of all non-missing values analyzed. Should all values 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 the source array is empty (zero-length), then all elements of the results array will be zero, including the mcrvfiCount and mcrvfiCountOfMissing elements. If a rank result falls between two sorted samples (e.g., as the Median will for any input array with an even number of values), then the result is the value at the closest index. A 0.5 index fraction rounds down not up, so that the Median for an even number of samples is the value at the floor(N/2)'th sorted sample.

'******** Ranked Values Test
Private Sub H_RankedValues_Click()
Dim mcoT As McObject
Set mcoT = McOpCast(McOpFillIn(100, -1), "REAL") 'numbers from 100.0 down thru 0.0
mcoT.SelectedValues(Array(2, 5)) = McMissingDouble 'make two low values missing
Dim varRV1 As Variant
varRV1 = McRankedValues(mcoT, 4) 'append quartiles
Results.Text = McSprintf(McCStr("Basic Ranked vals of 100-1 w/ w missing: N= %f, Missing= %f" & _
"\nMin: %f, Max: %f, Median: %f, Avg Abs Dev from Median: %f"), _
varRV1(mcrvfiCount), varRV1(mcrvfiCountOfMissing), 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))
End Sub 'H_RankedValues_Click
'******** 3-D Ranked Values Test
Private Sub I_ColorLineRankedVals_Click()
If ThisApplication.ActiveImage Is Nothing Then Exit Sub
With ThisApplication.ActiveImage.LineFeatures
If .Count < 2 Then
MsgBox ("We need at least 2 ThisApplication.ActiveImage.LineFeatures lines.  Starting McGraphObjLine tool.")
.AutoDisplay = True
.AutoDisplayOverlay.SelectTool , "McGraphObjLine", mcgtStandardAutoDisplay
Exit Sub
End If 'count < 2
End With 'ActiveImage.LineFeatures
'Else we have 2 or more line features
With ThisApplication.ActiveImage.LineFeatures.Profiles
Dim varProfiles As Variant
.Interpretation = mciRGB
.SampleMode = mclpsmFixedSampleLength
.CalibratedLength = False
.LengthPerSampleDesired = 1 'one pixel per profile sample
varProfiles = .ProfileValues 'get color profiles from all lines
'as an array of Variants, each holding a 2-D array.
'When passed to McRankedValues, only the fastest moving
'dimension (each profile for one color) will vary in size.
Dim mcoRankedValuesMatrix As McObject 'will be 3-D array of ranked values info
Set mcoRankedValuesMatrix = McRankedValues(varProfiles, 4) 'append quartiles
Results.Text = "Ranked Values from Individual Profiles:"
Dim lP As Long, lC As Long
For lP = 0 To .CountOfProfiles - 1 'for each line feature profile
Results.Text = Results.Text & McSprintf(McCStr("\n\nProfile: %d"), lP)
For lC = 0 To 2 'for each color along a line profile
'get the ranked values for this profile and color as a 1-D array
Dim varRV As Variant
varRV = mcoRankedValuesMatrix.SelectedValues(lP, lC)
'Note that SelectedValues dimension ordering is C/C++, not VB, ordering
Results.Text = Results.Text + McSprintf(McCStr("\n   Color: %d.  N= %f, Missing= %f" & _
"\nMin: %f, Max: %f, Median: %f, Avg Abs Dev from Median: %f"), _
lC, varRV(mcrvfiCount), varRV(mcrvfiCountOfMissing), 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
Next lP 'line profile
End With 'ActiveImage.LineFeatures.Profiles
End Sub 'I_ColorLineRankedVals_Click