runningStatistics()
Calculate summary statistics (count, sum, mean, min, max, variance, and standard deviation) of a
Stream<BigDecimal> so far.Implementation Notes
This implementation is suitable for Stream<BigDecimal>, for a version that takes a user-specified mapping function see runningStatisticsBy().
By default, nulls are ignored and play no part in calculations, see treatNullAs() and treatNullAsZero() below for ways to change this behavior. The default MathContext
for all calculations is
MathContext.DECIMAL64, but this can be overridden (see withMathContext(), below).
Each emitted StatisticalSummary record describes every value seen so far:
| Field | Meaning |
|---|---|
count | How many values are summarized. Ignored null values are not counted. |
sum | The sum of the values |
mean | The arithmetic mean of the values |
min | The smallest value |
max | The largest value |
populationVariance | The variance, treating the values as the entire dataset (divided by n) |
populationStandardDeviation | The standard deviation, treating the values as the entire dataset |
sampleVariance | The variance, treating the values as a sample of a larger population (divided by n - 1). May be null. |
sampleStandardDeviation | The standard deviation, treating the values as a sample of a larger population. May be null. |
The sample variance and sample standard deviation of a single value are undefined, so sampleVariance and sampleStandardDeviation are null until at least two values have been summarized. Every other field always has a value.
Every value is the same as the corresponding single-statistic gatherer would produce for the same input. Each summary calculates every field, including two square roots, so if you only need one statistic, the dedicated gatherer is cheaper.
Signatures
runningStatistics()
Additional Methods
| Method | Purpose |
|---|---|
treatNullAsZero() | When encountering a null value in a stream, treat it as BigDecimal.ZERO instead. See example. |
treatNullAs(BigDecimal replacement) | When encountering a null value in a stream, treat it as the given replacement value instead. See example. |
treatNullAsOne() | When encountering a null value in a stream, treat it as BigDecimal.ONE instead. |
withMathContext(MathContext mathContext) | Replace the MathContext used for all mathematical operations performed by this gatherer. See example. |
withOriginal() | Include the original input value from the stream in addition to the calculated value in a WithOriginal record. See example. |
Examples
Running statistics
Stream
.of("1.0", "2.0", "10.0", "2.0")
.map(BigDecimal::new)
.gather(Gatherers4j.runningStatistics())
.toList();
// [
// StatisticalSummary[count=1, sum=1.0, mean=1.0, min=1.0, max=1.0, populationVariance=0.00, populationStandardDeviation=0.0, sampleVariance=null, sampleStandardDeviation=null]
// StatisticalSummary[count=2, sum=3.0, mean=1.5, min=1.0, max=2.0, populationVariance=0.25, populationStandardDeviation=0.5, sampleVariance=0.50, sampleStandardDeviation=0.7071067811865475]
// StatisticalSummary[count=3, sum=13.0, mean=4.333333333333333, min=1.0, max=10.0, populationVariance=16.22222222222222, populationStandardDeviation=4.02768199119819, sampleVariance=24.33333333333333, sampleStandardDeviation=4.932882862316247]
// StatisticalSummary[count=4, sum=15.0, mean=3.75, min=1.0, max=10.0, populationVariance=13.1875, populationStandardDeviation=3.631459761583488, sampleVariance=17.58333333333333, sampleStandardDeviation=4.193248541803041]
// ]
Showing nulls are ignored by default
Stream
.of(null, null, new BigDecimal("10.0"), new BigDecimal("2.0"))
.gather(Gatherers4j.runningStatistics())
.toList();
// [
// StatisticalSummary[count=1, sum=10.0, mean=10.0, min=10.0, max=10.0, populationVariance=0.00, populationStandardDeviation=0.0, sampleVariance=null, sampleStandardDeviation=null]
// StatisticalSummary[count=2, sum=12.0, mean=6.0, min=2.0, max=10.0, populationVariance=16.00, populationStandardDeviation=4.0, sampleVariance=32.00, sampleStandardDeviation=5.65685424949238]
// ]
Treating null as zero
Stream
.of(null, null, new BigDecimal("10.0"), new BigDecimal("2.0"))
.gather(Gatherers4j.runningStatistics().treatNullAsZero())
.toList();
// [
// StatisticalSummary[count=1, sum=0, mean=0, min=0, max=0, populationVariance=0, populationStandardDeviation=0, sampleVariance=null, sampleStandardDeviation=null]
// StatisticalSummary[count=2, sum=0, mean=0, min=0, max=0, populationVariance=0, populationStandardDeviation=0, sampleVariance=0, sampleStandardDeviation=0]
// StatisticalSummary[count=3, sum=10.0, mean=3.333333333333333, min=0, max=10.0, populationVariance=22.22222222222222, populationStandardDeviation=4.714045207910317, sampleVariance=33.33333333333333, sampleStandardDeviation=5.773502691896257]
// StatisticalSummary[count=4, sum=12.0, mean=3.0, min=0, max=10.0, populationVariance=17.00, populationStandardDeviation=4.123105625617661, sampleVariance=22.66666666666667, sampleStandardDeviation=4.760952285695234]
// ]
Replacing null with another BigDecimal
Stream
.of(null, null, new BigDecimal("10.0"), new BigDecimal("2.0"))
.gather(Gatherers4j.runningStatistics().treatNullAs(new BigDecimal("3.5")))
.toList();
// [
// StatisticalSummary[count=1, sum=3.5, mean=3.5, min=3.5, max=3.5, populationVariance=0.00, populationStandardDeviation=0.0, sampleVariance=null, sampleStandardDeviation=null]
// StatisticalSummary[count=2, sum=7.0, mean=3.5, min=3.5, max=3.5, populationVariance=0.00, populationStandardDeviation=0.0, sampleVariance=0.00, sampleStandardDeviation=0.0]
// StatisticalSummary[count=3, sum=17.0, mean=5.666666666666667, min=3.5, max=10.0, populationVariance=9.388888888888889, populationStandardDeviation=3.064129385141706, sampleVariance=14.08333333333333, sampleStandardDeviation=3.752776749732567]
// StatisticalSummary[count=4, sum=19.0, mean=4.75, min=2.0, max=10.0, populationVariance=9.5625, populationStandardDeviation=3.092329219213245, sampleVariance=12.75, sampleStandardDeviation=3.570714214271425]
// ]
Specifying a new MathContext
Stream
.of("1.0", "2.0", "10.0", "2.0")
.map(BigDecimal::new)
.gather(Gatherers4j
.runningStatistics()
.withMathContext(new MathContext(3, RoundingMode.DOWN))
)
.toList();
// [
// StatisticalSummary[count=1, sum=1.0, mean=1.0, min=1.0, max=1.0, populationVariance=0.00, populationStandardDeviation=0.0, sampleVariance=null, sampleStandardDeviation=null]
// StatisticalSummary[count=2, sum=3.0, mean=1.5, min=1.0, max=2.0, populationVariance=0.25, populationStandardDeviation=0.5, sampleVariance=0.50, sampleStandardDeviation=0.707]
// StatisticalSummary[count=3, sum=13.0, mean=4.33, min=1.0, max=10.0, populationVariance=16.2, populationStandardDeviation=4.02, sampleVariance=24.3, sampleStandardDeviation=4.92]
// StatisticalSummary[count=4, sum=15.0, mean=3.75, min=1.0, max=10.0, populationVariance=13.1, populationStandardDeviation=3.61, sampleVariance=17.5, sampleStandardDeviation=4.18]
// ]
Emitting a record containing the original and calculated values
Stream
.of("1.0", "2.0", "10.0", "2.0")
.map(BigDecimal::new)
.gather(Gatherers4j.runningStatistics().withOriginal())
.toList();
// [
// WithOriginal[original=1.0, calculated=StatisticalSummary[count=1, sum=1.0, mean=1.0, min=1.0, max=1.0, populationVariance=0.00, populationStandardDeviation=0.0, sampleVariance=null, sampleStandardDeviation=null]]
// WithOriginal[original=2.0, calculated=StatisticalSummary[count=2, sum=3.0, mean=1.5, min=1.0, max=2.0, populationVariance=0.25, populationStandardDeviation=0.5, sampleVariance=0.50, sampleStandardDeviation=0.7071067811865475]]
// WithOriginal[original=10.0, calculated=StatisticalSummary[count=3, sum=13.0, mean=4.333333333333333, min=1.0, max=10.0, populationVariance=16.22222222222222, populationStandardDeviation=4.02768199119819, sampleVariance=24.33333333333333, sampleStandardDeviation=4.932882862316247]]
// WithOriginal[original=2.0, calculated=StatisticalSummary[count=4, sum=15.0, mean=3.75, min=1.0, max=10.0, populationVariance=13.1875, populationStandardDeviation=3.631459761583488, sampleVariance=17.58333333333333, sampleStandardDeviation=4.193248541803041]]
// ]