IMcOMGlobalMcHistogramStatistics Method

Parameters

HistogramArray

Type: SystemObject
A one or higher dimensioned array of histogram integral bin counts or floating point areas or weights on which 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).

Return Value

Type: Object
A Variant holding a scalar or array of BASIC_STATISTICS UDTs. If HistogramArray is a 1-D array of bins, 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 dimensioned array of UDT, where the shape of the array is identical to the shape of ArrayToTest up to the fastest moving dimension.

This method computes parametric statistics on one or more arrays of histogram bin counts or weights and returns one or more BASIC_STATISTICS structures filled with the results. Optionally, each histogram bin can be assigned an associated calibrated value. Bins can be assigned calibrated values individually or by ranges with intermediate bin values being interpolated as necessary. For non-parametric statistics, use the McRankedHistogramValues method. The HistogramArray argument supplies array(s) of histogram bins which may be either integral counts of bin frequencies or may be floating point weights (e.g., a total area of pixels in a bin) to apply to each bin's calibrated value. In either case, the statistics are based on the bin's calibrated value times the bin count or weight, with the sum of all bin array counts or weights used as the divisor for "N". For example, for K bins with K associated binvalues the Mean is computed as SumOverK(bin(i)*binvalue(i))/SumOverK(bin(i)). The sum of all bin counts or weights is returned as the BASIC_STATISTICS.Count result. When passed a 1-D array of bins, the routine returns a single scalar BASIC_STATISTICS structure with the results of statistics taken on the the source histogram array. When passed a 2-D or higher dimensioned array of bins, then statistics are performed on the fastest moving dimension (the leftmost in VB, the rightmost in C/C++). All histograms in the fastest moving dimension must be the same size (have the same number of bins). The returned result from 2 and higher dimensioned arrays is an array of BASIC_STATISTICS structures, with dimensionality one less than the HistogramArray (i.e., the fastest moving dimension is replaced by the BASIC_STATISTICS results). This case is illustrated in the Examples where all statistics from all three color channel histograms is are computed with a single call to McHistogramStatistics. The actual statistical computations are standard (see the McBasicStatistics Remarks for a general discussion). For histogram statistics the BASIC_STATISTICS.Count field is the sum of all bin counts or weights; it is not the number of bins. 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. The BASIC_STATISTICS.CountOfMissing field is always zero for McHistogramStatistics, since any bin with a non-zero count is included in the statistics. However, if you use the McVectorHistogram method to create a histogram from an array of Single or Double values, then missing values in those arrays (see McMissingSingle, McMissingDouble, and McIsMissingValue) will be skipped in building the histogram (see Examples). Other than the McVectorHistogram method, the usual source for histograms is the IQL McHistogram object, which builds histograms based on luminances found within McImage object frames. The McHistogram object exposes most of the statistics computed here and can optionally apply the current McImage.IntensityCalibration to calibrate bin values and the current McImage.SpatialCalibration to weight bin values by pixel area. However, you might want to call McVectorHistogram on the McHistogram.Value property to get Skew, Kurtosis or average absolute deviation from the mean. Or you might wish to get statistics on the histogram after excluding extreme values by setting low and/or high bins to zeros.

'******** Histogram Statistics Test
Private Sub G_HistStats_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 mcoH As McObject
Set mcoH = McVectorHistogram(mcoT, 9, Array(1, 1))
Dim bst As BASIC_STATISTICS
bst = McHistogramStatistics(mcoH, Array(1, 9)) 'get the stats as a scalar BASIC_STATISTICS
Results.Text = McSprintf(McCStr("Basic Histogram Stats: N= %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.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)
If ThisApplication.ActiveImage Is Nothing Then Exit Sub
With ThisApplication.ActiveImage.Histogram
Dim varHistogramVals As Variant
.mode = mchmApplyIntensityCalibration Or mchmApplySpatialCalibration
.Interpretation = mciRGB
varHistogramVals = .Values
Dim varBinCalibrations As Variant
varBinCalibrations = .BinXValues
Dim varBasicStats As Variant 'will be 1-D array of BASIC_STATISTICS
varBasicStats = McHistogramStatistics(varHistogramVals, varBinCalibrations)
Results.Text = Results.Text & vbCrlf & vbCrlf & "Color Histograms:"
Dim lC As Long
For lC = 0 To 2
Dim bs As BASIC_STATISTICS
bs = varBasicStats(lC) '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)
Results.Text = Results.Text & McSprintf(McCStr("\n   McHistogram Stats: " & _
" Min: %f, Max: %f, Range: %f, Mean: %f, StdDev: %f"), _
.Min(lC), .Max(lC), .AbsoluteRange(lC), .Mean(lC), .StdDev(lC))
Next lC
End With 'ActiveImage.Histogram
End Sub 'G_HistStats_Click