Automation Help

## IMcOMGlobalMcBasicStatistics Method |

Computes basic parametric statistics on one or more arrays.

Syntax

VB

Function McBasicStatistics ( ArrayToTest As Object ) As Object

- ArrayToTest
- Type: SystemObject

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

A Variant holding a scalar or array of BASIC_STATISTICS UDTs. If ArrayToTest is a 1-D array, then the returned Variant will be a scalar UDT. If ArrayToTest is an N-D array (where N is 2 or more), then the returned Variant will be an N-1 dimesioned array of UDT, where the shape of the array is identical to the shape of ArrayToTest up to the fastest moving dimension.

Remarks

This method computes parametric statistics on one or more arrays of
values and returns one or more BASIC_STATISTICS structures filled with the
results. For non-parametric statistics, use the McRankedValues method and
for basic histogram statistics, use the McHistogramStatistics method.
When passed a 1-D array, the routine returns a single scalar BASIC_STATISTICS
structure with the results of statistics taken on 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 BASIC_STATISTICS structures, with dimensionality one less than the
ArrayToTest (i.e., the fastest moving dimension is replaced by the
BASIC_STATISTICS 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 BASIC_STATISTICS.CountOfMissing field.
The BASIC_STATISTICS.Count field is a count of all non-missing values analyzed
and is the "N" used for all statistics. Should all values be missing, then
BASIC_STATISTICS.Count will be zero, BASIC_STATISTICS.CountOfMissing will be the
length of the source array and all other fields of the returned BASIC_STATISTICS
structure are filled with the McMissingDouble value. If the source array is
empty (zero-length), then BASIC_STATISTICS.Count will be zero,
BASIC_STATISTICS.CountOfMissing will be zero and all other fields of the
returned BASIC_STATISTICS structure will also be zero.
The actual statistical computations are standard, but a few items deserve
discussion. Variance is computed using a "corrected two-pass algorithm" (Chan,
Golub and LeVeque, 1983, American Statistician, vol. 37, pp. 242�247.), which
tends to minimize rounding error. Variance (the second moment) is averaged by
dividing the sum of squared deviations from the mean by N
(BASIC_STATISTICS.Count), not N-1. If you want the population estimated
Variance, then you can multiply BASIC_STATISTICS.Variance by N/(N-1).
The third moment, Skew, is presented in two ways. BASIC_STATISTICS.RawSkew
is the average cubed deviation from the mean. BASIC_STATISTICS.NormalizedSkew
is the above value divided by the standard deviation (BASIC_STATISTICS.StdDev) cubed,
which results in a dimensionless quantity with mean of zero and a standard deviation
on the order of sqrt(15/N) for gausian distributions. It will be negative for
skew to the left and positive for skew to the right.
The fourth moment, Kurtosis, is also presented in two ways.
BASIC_STATISTICS.RawKurtosis is the average 4th power of the deviation from the
mean. BASIC_STATISTICS.NormalizedKurtosis is the above value divided by the
fourth power of the standard deviation with 3 subtracted from that. This is a
dimensionless quantity with mean of zero and a standard deviation on the order
of sqrt(96/N) for gausian distributions. It will be negative for flat
distributions (bread-box shaped) and positive for pointy distibutions.
Be aware that both Skew and Kurtosis are extremely sensitive to outliers. See
Cramer, H. 1946, Mathematical Methods of Statistics (Princeton University Press),
and Press and Vettering, "Numerical Recipes in C", second edition (Cambridge
University Press). Section 14.1 for more details.

Examples

VB

'******** Basic Statistics Test on a 1-D array Private Sub D_Stats_Click() Dim mcoT As McObject Set mcoT = McOpCast(McOpFillIn(1, 10), "REAL") 'numbers from 1.0 thru 9.0 mcoT.SelectedValues(Array(2, 5)) = McMissingDouble 'make two values missing Dim bst As BASIC_STATISTICS bst = McBasicStatistics(mcoT) 'get the stats as a scalar BASIC_STATISTICS Results.Text = McSprintf(McCStr("Basic Stats: N= %f, Missing= %f" & _ "\nMin: %f at index %f, Max: %f at index %f, Range: %f, Sum: %f, Mean: %f, Avg Abs Dev: %f" & _ "\nVariance: %f, StdDev: %f" & _ "\nRaw Skew: %f, Normal Skew: %f, Raw Kurtosis: %f, Normal Kurtosis %f"), _ bst.Count, bst.CountOfMissing, bst.Minimum, bst.IndexOfMinimum, _ bst.Maximum, bst.IndexOfMaximum, bst.Range, bst.Sum, bst.Mean, bst.AverageAbsDev, _ bst.Variance, bst.StdDev, bst.RawSkew, bst.NormalizedSkew, _ bst.RawKurtosis, bst.NormalizedKurtosis) End Sub 'D_Stats_Click '******** 2-dimensional, variable array Basic Statistics Test Private Sub E_LineStats_Click() If ThisApplication.ActiveImage Is Nothing Then End If 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 = mciMonochrome .SampleMode = mclpsmFixedSampleLength .CalibratedLength = False .LengthPerSampleDesired = 1 'one pixel per profile sample varProfiles = .ProfileValues 'get profiles from all lines 'as a 1-D array of Variants, each holding a 1-D array. 'When passed to McBasicStatistics, only the fastest moving 'dimension, the profile samples, will vary in size. Dim varBasicStats As Variant 'will be a 1-D array of BASIC_STATISTICS varBasicStats = McBasicStatistics(varProfiles) Results.Text = "Individual Profiles:" Dim lP As Long For lP = 0 To .CountOfProfiles - 1 Dim bs As BASIC_STATISTICS bs = varBasicStats(lP) 'get the stats for this profile Results.Text = Results.Text & McSprintf(McCStr("\n\n Profile: %d. N= %f" & _ " Min: %f at index %f, Max: %f at index %f, Range: %f, Mean: %f, StdDev: %f"), _ lP, bs.Count, bs.Minimum, bs.IndexOfMinimum, _ bs.Maximum, bs.IndexOfMaximum, bs.Range, bs.Mean, bs.StdDev) Next lP End With 'ActiveImage.LineFeatures.Profiles 'Get combined statistics about the statistics for each feature's profile 'Now for the tricky part. We want to get statistics on some of the BASIC_STATISTICS fields '(e.g., we want the average and StdDev of the profile Mean's). To do so we want to do 'basic statistics across fields of the BASIC_STATISTICS array elements in varBasicStats. 'But McBasicStatistics only works on the fastest moving dimension, so we need to 'transpose the array so that for three profiles instead of being arranged as: ' BASIC_STATISTICS(0) ' BASIC_STATISTICS(1) ' BASIC_STATISTICS(2) 'It is arranged as: ' Count(0),Count(1),Count(2) ' CountOfMissing(0),CountOfMissing(1),CountOfMissing(2) ' Minimum(0),Minimum(1),Minimum(2) ' and so on. 'The McTranspose method will do the tranposition for us, but in the process 'BASIC_STATISTICS field names are lost, so that a length 3 array of 'BASIC_STATISTICS structures becomes a 16 by 3 array of Double with 'each row representing one of the 16 fields of the BASIC_STATISTICS structure. 'The mcobjBASIC_STATISTICS_FieldIndices enumeration gives readable names 'to the field indices when the structure has been cast to an array of Double. Dim mcoBSTransposed As McObject Set mcoBSTransposed = McTranspose(varBasicStats) Dim bsOfTransposed As Variant bsOfTransposed = McBasicStatistics(mcoBSTransposed) Results.Text = Results.Text & McSprintf(McCStr("\n\n Overall stats on %f profiles:\n" & _ "Avg Min: %f, Avg Max: %f, Avg Range: %f, Avg Mean: %f, StdDev of Means: %f, Avg StdDev: %f"), _ bsOfTransposed(mcbsfiCount).Count, bsOfTransposed(mcbsfiMinimum).Mean, _ bsOfTransposed(mcbsfiMaximum).Mean, bsOfTransposed(mcbsfiRange).Mean, _ bsOfTransposed(mcbsfiMean).Mean, bsOfTransposed(mcbsfiMean).StdDev, _ bsOfTransposed(mcbsfiStdDev).Mean) End Sub 'E_LineStats_Click '******** 3-dimensional array Statistics Test Private Sub F_ColorLineStats_Click() If ThisApplication.ActiveImage Is Nothing Then End If 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 McBasicStatistics, only the fastest moving 'dimension (each profile for one color) will vary in size. Dim varBasicStats As Variant 'will be 2-D array of BASIC_STATISTICS varBasicStats = McBasicStatistics(varProfiles) Results.Text = "Individual Profiles:" Dim lP As Long, lC As Long For lP = 0 To .CountOfProfiles - 1 Results.Text = Results.Text & McSprintf(McCStr("\n\nProfile: %d"), lP) For lC = 0 To 2 Dim bs As BASIC_STATISTICS bs = varBasicStats(lC, lP) 'get the stats for this profile and color Results.Text = Results.Text & McSprintf(McCStr("\n Color: %d. N= %f" & _ " Min: %f at index %f, Max: %f at index %f, Range: %f, Mean: %f, StdDev: %f"), _ lC, bs.Count, bs.Minimum, bs.IndexOfMinimum, _ bs.Maximum, bs.IndexOfMaximum, bs.Range, bs.Mean, bs.StdDev) Next lC Next lP End With 'ActiveImage.LineFeatures.Profiles End Sub 'F_ColorLineStats_Click

See Also