RunningStatistics<T> Struct
Definition
- Assembly
- Bodu.Numerics.dll
- Package
- Bodu.Numerics 1.0.0
Accumulates the count, minimum, maximum, mean, and variance of a sample stream in a single forward pass, using Welford's numerically stable online algorithm.
public struct RunningStatistics<T> where T : INumber<T>Type Parameters
TThe numeric type of the samples.
- Inherited Members
- Extension Methods
Examples
var stats = new RunningStatistics<double>();
foreach (var sample in new[] { 2.0, 4.0, 4.0, 4.0, 5.0, 5.0, 7.0, 9.0 })
stats.Add(sample);
stats.Count; // 8
stats.Mean; // 5
stats.PopulationStandardDeviation; // 2
stats.Minimum; // 2
stats.Maximum; // 9Remarks
Samples are absorbed one at a time through Add(T) in O(1) time and O(1) space - the accumulator never
stores the samples themselves. The minimum and maximum are tracked exactly in T; the mean
and the variance moments are accumulated in double (each sample is widened with
CreateChecked<TOther>(TOther)), so those results are floating-point estimates regardless of
the sample type. Welford's recurrence avoids the catastrophic cancellation of the naive sum-of-squares formulation,
keeping the variance accurate even when the samples are large and closely clustered.
This is a mutable value type. Store it in a mutable field or local and pass it by ref; do not capture it in a lambda or iterator that expects reference semantics - each copy accumulates independently from the point of the copy. That copy behaviour is also the supported way to checkpoint: assigning the accumulator to another variable snapshots its state. The default value is the valid empty accumulator.
Two independently filled accumulators merge losslessly with Combine(RunningStatistics<T>, RunningStatistics<T>), so a stream can be partitioned, accumulated in parallel, and recombined. Samples must be finite: NaN and infinite values are rejected by Add(T) because they would poison every subsequent moment irrecoverably. For a streaming quantile estimate, pair this type with RunningQuantile<T>.
Properties
Count
Gets the number of samples accumulated so far.
public readonly long Count { get; }Property Value
- long
The sample count; zero for the empty accumulator.
IsEmpty
Gets a value indicating whether the accumulator contains no samples.
public readonly bool IsEmpty { get; }Property Value
Maximum
Gets the largest sample accumulated so far, tracked exactly in T.
public readonly T Maximum { get; }Property Value
- T
The maximum sample.
Exceptions
- InvalidOperationException
The accumulator is empty.
Mean
Gets the arithmetic mean of the accumulated samples.
public readonly double Mean { get; }Property Value
Exceptions
- InvalidOperationException
The accumulator is empty.
Minimum
Gets the smallest sample accumulated so far, tracked exactly in T.
public readonly T Minimum { get; }Property Value
- T
The minimum sample.
Exceptions
- InvalidOperationException
The accumulator is empty.
PopulationStandardDeviation
Gets the population standard deviation - the square root of PopulationVariance.
public readonly double PopulationStandardDeviation { get; }Property Value
- double
The population standard deviation.
Exceptions
- InvalidOperationException
The accumulator is empty.
PopulationVariance
Gets the population variance of the accumulated samples - the squared deviations divided by Count.
public readonly double PopulationVariance { get; }Property Value
- double
The population variance; zero for a single sample.
Exceptions
- InvalidOperationException
The accumulator is empty.
SampleStandardDeviation
Gets the sample standard deviation - the square root of SampleVariance.
public readonly double SampleStandardDeviation { get; }Property Value
- double
The sample standard deviation.
Exceptions
- InvalidOperationException
The accumulator holds fewer than two samples.
SampleVariance
Gets the sample (Bessel-corrected) variance of the accumulated samples - the squared deviations divided by Count − 1.
public readonly double SampleVariance { get; }Property Value
- double
The unbiased sample variance.
Exceptions
- InvalidOperationException
The accumulator holds fewer than two samples.
Methods
Add(T)
Adds a sample to the accumulator, updating the count, minimum, maximum, mean, and variance moments in O(1).
public void Add(T value)Parameters
valueTThe sample to accumulate. Must be finite.
Exceptions
- ArgumentException
valueis NaN or infinite.- OverflowException
valueis finite but outside the range representable by double (possible only for unbounded integer sample types such as BigInteger).
Combine(RunningStatistics<T>, RunningStatistics<T>)
Merges two independently filled accumulators into one whose moments equal those of a single accumulator fed both sample streams.
public static RunningStatistics<T> Combine(RunningStatistics<T> left, RunningStatistics<T> right)Parameters
leftRunningStatistics<T>The first accumulator to merge.
rightRunningStatistics<T>The second accumulator to merge.
Returns
- RunningStatistics<T>
An accumulator equivalent to accumulating both operands' sample streams in sequence. When either operand is empty the other is returned unchanged.
Remarks
Uses the parallel-variance merge of Chan et al., so a stream may be partitioned across workers, accumulated independently, and recombined without loss beyond ordinary floating-point rounding. Because floating-point addition is not associative, different partitionings or merge orders can produce results that differ in the last bits; use a deterministic partitioning strategy and merge order when bitwise-reproducible results matter.
Reset()
Resets the accumulator to the empty state, discarding every accumulated moment.
public void Reset()ToString()
Returns a culture-invariant summary of the accumulator state for diagnostics.
public override readonly string ToString()Returns
- string
A string such as
"Count = 8, Mean = 5, Min = 2, Max = 9", or"Count = 0"when empty.
Applies to
| Product | Versions |
|---|---|
| .NET | 8, 10 |