README
¶
stats Package
Incremental descriptive statistics for float64 observation streams.
Overview
The stats package provides StatVar, a compact accumulator for numeric metrics. It tracks count, sum, min, max, mean, variance, standard deviation, and median. Mean and variance are maintained with Welford's online algorithm, while exact median is computed from stored observations.
Public API
Types
| Type | Kind | Description |
|---|---|---|
StatVar |
struct | Accumulates observations and exposes descriptive statistics |
StatVar Methods
| Method | Signature | Description |
|---|---|---|
Add |
func(v float64) |
Adds one observation |
Count |
func() int |
Returns the number of observations |
Sum |
func() float64 |
Returns the arithmetic sum |
Min |
func() float64 |
Returns the minimum observed value (or 0 if empty) |
Max |
func() float64 |
Returns the maximum observed value (or 0 if empty) |
Mean |
func() float64 |
Returns the arithmetic mean (or 0 if empty) |
Variance |
func() float64 |
Returns population variance (N denominator) |
SampleVariance |
func() float64 |
Returns sample variance (N-1 denominator) |
StdDev |
func() float64 |
Returns population standard deviation |
SampleStdDev |
func() float64 |
Returns sample standard deviation |
Median |
func() float64 |
Returns the exact median (middle value or midpoint of two middle values) |
Dependencies
Standard library only:
math— square root for standard deviationsort— sorting copied values for exact median
Thread Safety
StatVar is not concurrency-safe. Use external synchronization when a single instance is shared across goroutines.
This specification is automatically maintained by the spec-extractor workflow.
Documentation
¶
Overview ¶
Package stats provides numerical statistics utilities for metric collection.
Index ¶
- type StatVar
- func (s *StatVar) Add(v float64)
- func (s *StatVar) Count() int
- func (s *StatVar) Max() float64
- func (s *StatVar) Mean() float64
- func (s *StatVar) Median() float64
- func (s *StatVar) Min() float64
- func (s *StatVar) SampleStdDev() float64
- func (s *StatVar) SampleVariance() float64
- func (s *StatVar) StdDev() float64
- func (s *StatVar) Sum() float64
- func (s *StatVar) Variance() float64
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type StatVar ¶
type StatVar struct {
// contains filtered or unexported fields
}
StatVar accumulates a stream of float64 observations and computes descriptive statistics: count, sum, min, max, mean, variance, standard deviation, and median. Mean and variance are maintained incrementally using Welford's online algorithm, which avoids catastrophic cancellation when values are large or tightly clustered. All observed values are also stored so that an exact median can be returned on demand.
Memory usage: all observations are stored to enable exact median computation. This is suitable for the expected scale of agentic workflow metrics (typically tens to a few hundred observations per session). For very large streams (thousands of observations), consider a streaming approximation instead.
func (*StatVar) Add ¶
Add records a new observation. Finite values are recommended; NaN and ±Inf will propagate through sum, mean, and variance, but Min and Max may not update correctly for NaN inputs because IEEE 754 comparisons with NaN always return false. In practice, observations come from time.Duration, token counts, and cost values, which are always finite.
func (*StatVar) Max ¶
Max returns the largest observed value, or 0 if no observations have been added.
func (*StatVar) Median ¶
Median returns the median of all observations. For an even number of observations the two middle values are averaged. Returns 0 if no observations have been added. The internal values slice is copied and sorted; the receiver is not modified.
func (*StatVar) Min ¶
Min returns the smallest observed value, or 0 if no observations have been added.
func (*StatVar) SampleStdDev ¶
SampleStdDev returns the sample standard deviation with Bessel's correction (sqrt of SampleVariance).
func (*StatVar) SampleVariance ¶
SampleVariance returns the sample variance with Bessel's correction (divides by N−1), giving an unbiased estimator when the observations are a random sample from a larger population. Returns 0 when fewer than two observations are present.
Source Files