Class Statistics

Namespace

MathAssertions

Assembly

MathAssertions.dll

Statistical-property checks for ReadOnlySpan<T> of double: mean, variance, standard deviation, sum, median, percentile, and sigma-bound checks against the sample's own mean. Numerically stable single-pass mean and variance via Welford's online algorithm.

public static class Statistics

Inheritance

object

Statistics

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

0.1.0 Cluster 4. Sits alongside MathTolerance and Sequences in the same package; the MathAssertions.TUnit adapter delegates to these helpers from its [GenerateAssertion] extensions.

All variance and standard-deviation calculations use the unbiased N-1 denominator (sample variance), matching the convention in NIST/SEMATECH e-Handbook of Statistical Methods §1.3.5.6 and Knuth, The Art of Computer Programming Vol. 2, §4.2.2.

Methods

AreAllWithinSigmasOfMean(ReadOnlySpan<double>, double)

Returns true when every value in values lies within sigmas standard deviations of that same sample's mean. Returns false for samples with fewer than two observations (standard deviation undefined) and for samples that contain NaN or infinity (the envelope is undefined).

public static bool AreAllWithinSigmasOfMean(ReadOnlySpan<double> values, double sigmas)

Parameters

values ReadOnlySpan<double>

Sample to inspect, both as the reference and as the test set.

sigmas double

Number of standard deviations defining the envelope. Must be non-negative and not NaN.

Returns

bool

true if every value lies within the sigma envelope.

Remarks

Computes the sample's mean and standard deviation once and reuses them for every element check, so the method is O(N) rather than the O(N^2) shape that would result from per-element delegation to IsWithinSigmasOfMean(double, ReadOnlySpan<double>, double).

Non-finite inputs propagate NaN through the mean/variance/threshold path; the per-element check is written as !(|v - mean| <= threshold) rather than the equivalent-for-finite-inputs |v - mean| > threshold so that a NaN comparison short-circuits to false on the first element rather than silently passing every check (the IEEE 754 rule that any comparison against NaN is false would otherwise let the loop fall through to a vacuous-true return).

Exceptions

ArgumentOutOfRangeException

sigmas is NaN or negative.

HasMeanApproximately(ReadOnlySpan<double>, double, double)

Returns true when the sample mean is within tolerance of expected. The empty span returns false (no value has been observed).

public static bool HasMeanApproximately(ReadOnlySpan<double> values, double expected, double tolerance)

Parameters

values ReadOnlySpan<double>

Sample to inspect.

expected double

Expected mean.

tolerance double

Maximum allowed absolute difference. Must be non-negative and not NaN.

Returns

bool

true if the sample mean is approximately expected.

Exceptions

ArgumentOutOfRangeException

tolerance is NaN or negative.

HasMedianApproximately(ReadOnlySpan<double>, double, double)

Returns true when the median of values is within tolerance of expected. For even-length samples, the median is the mean of the two middle values after sorting. The empty span returns false.

public static bool HasMedianApproximately(ReadOnlySpan<double> values, double expected, double tolerance)

Parameters

values ReadOnlySpan<double>

Sample to inspect.

expected double

Expected median.

tolerance double

Maximum allowed absolute difference. Must be non-negative and not NaN.

Returns

bool

true if the median is approximately expected.

Remarks

Sorts a copy of the input, so callers do not observe a side effect on the original span backing store. The copy is the algorithm's only allocation.

Even-length median uses the overflow-safe form a/2 + b/2 rather than the textbook (a + b)/2. The latter overflows to PositiveInfinity for samples whose two middle values sum past MaxValue (for example [double.MaxValue, double.MaxValue]); the half-then-add form is exact for the same input.

Exceptions

ArgumentOutOfRangeException

tolerance is NaN or negative.

HasPercentileApproximately(ReadOnlySpan<double>, double, double, double)

Returns true when the percentile-percentile value of values is within tolerance of expected. Linear interpolation between adjacent ranks per the NIST/SEMATECH e-Handbook of Statistical Methods §1.3.5.6.

public static bool HasPercentileApproximately(ReadOnlySpan<double> values, double percentile, double expected, double tolerance)

Parameters

values ReadOnlySpan<double>

Sample to inspect.

percentile double

Percentile in the closed interval [0, 100].

expected double

Expected percentile value.

tolerance double

Maximum allowed absolute difference. Must be non-negative and not NaN.

Returns

bool

true if the percentile is approximately expected.

Remarks

Allocates a sorted copy of the input. The empty span returns false.

Interpolation uses the overflow-safe lerp form a*(1-f) + b*f rather than the textbook a + f*(b - a). The latter overflows when b - a exceeds MaxValue (for example [-double.MaxValue, double.MaxValue]), which would silently return PositiveInfinity for the median percentile of that input. The two forms are algebraically equal for finite inputs; the lerp form keeps each multiplication within the original magnitude band.

Exceptions

ArgumentOutOfRangeException

percentile is outside [0, 100] or NaN, or tolerance is NaN or negative.

HasStdDevApproximately(ReadOnlySpan<double>, double, double)

Returns true when the sample standard deviation is within tolerance of expected. Standard deviation is the square root of the unbiased sample variance and is undefined for fewer than two observations; the method returns false for empty and single-element spans.

public static bool HasStdDevApproximately(ReadOnlySpan<double> values, double expected, double tolerance)

Parameters

values ReadOnlySpan<double>

Sample to inspect.

expected double

Expected standard deviation.

tolerance double

Maximum allowed absolute difference. Must be non-negative and not NaN.

Returns

bool

true if the sample standard deviation is approximately expected.

Exceptions

ArgumentOutOfRangeException

tolerance is NaN or negative.

HasSumApproximately(ReadOnlySpan<double>, double, double)

Returns true when the sum of values is within tolerance of expected. The empty span has a sum of zero by convention, matching the identity element for addition.

public static bool HasSumApproximately(ReadOnlySpan<double> values, double expected, double tolerance)

Parameters

values ReadOnlySpan<double>

Sample to inspect.

expected double

Expected sum.

tolerance double

Maximum allowed absolute difference. Must be non-negative and not NaN.

Returns

bool

true if the sum is approximately expected.

Exceptions

ArgumentOutOfRangeException

tolerance is NaN or negative.

HasVarianceApproximately(ReadOnlySpan<double>, double, double)

Returns true when the sample variance is within tolerance of expected. Variance is undefined for fewer than two observations under the unbiased N-1 convention; the method returns false for empty and single-element spans.

public static bool HasVarianceApproximately(ReadOnlySpan<double> values, double expected, double tolerance)

Parameters

values ReadOnlySpan<double>

Sample to inspect.

expected double

Expected variance.

tolerance double

Maximum allowed absolute difference. Must be non-negative and not NaN.

Returns

bool

true if the sample variance is approximately expected.

Exceptions

ArgumentOutOfRangeException

tolerance is NaN or negative.

IsWithinSigmasOfMean(double, ReadOnlySpan<double>, double)

Returns true when value lies within sigmas standard deviations of the mean of sample. Returns false for samples with fewer than two observations, where standard deviation is undefined under the unbiased N-1 convention.

public static bool IsWithinSigmasOfMean(double value, ReadOnlySpan<double> sample, double sigmas)

Parameters

value double

Value to test.

sample ReadOnlySpan<double>

Reference sample whose mean and standard deviation define the envelope.

sigmas double

Number of standard deviations defining the envelope. Must be non-negative and not NaN.

Returns

bool

true if |value - mean| <= sigmas * stdDev.

Exceptions

ArgumentOutOfRangeException

sigmas is NaN or negative.

MeanAndVariance(ReadOnlySpan<double>)

Returns the sample mean and unbiased sample variance of values in a single numerically stable pass. The empty span yields (NaN, NaN); a single-element span yields (value, 0) because sample variance with the N-1 denominator is undefined for one observation.

public static (double Mean, double Variance) MeanAndVariance(ReadOnlySpan<double> values)

Parameters

values ReadOnlySpan<double>

Sample to summarize.

Returns

(double Mean, double Variance)

A tuple of mean and unbiased sample variance.

Remarks

Welford's online algorithm. Reference: Knuth, The Art of Computer Programming Vol. 2, §4.2.2. Numerically more stable than the textbook two-pass E[X^2] - E[X]^2 form, especially for long sequences with small variance relative to mean.