viva_math - v1.2.103

viva_math/statistics

Descriptive statistics over List(Float).

All functions are pure and operate on lists. For large datasets prefer viva_tensor and stream reductions; this module targets emotion-scale data (10²–10⁴ samples).

Numerical notes

Types

Welford

</>

Online (mean, variance, count) accumulator from Welford’s algorithm.

pub type Welford {
  Welford(count: Int, mean: Float, m2: Float)
}

Constructors 

  • Welford(count: Int, mean: Float, m2: Float)

Values

covariance

</> 
pub fn covariance(
  xs: List(Float),
  ys: List(Float),
) -> Result(Float, Nil)

Population covariance Cov(X, Y) = E[(X - μₓ)(Y - μᵧ)].

cumulative_product

</> 
pub fn cumulative_product(xs: List(Float)) -> List(Float)

Running product [x₀, x₀·x₁, x₀·x₁·x₂, …].

cumulative_sum

</> 
pub fn cumulative_sum(xs: List(Float)) -> List(Float)

Running sum [x₀, x₀+x₁, x₀+x₁+x₂, …].

ema

</> 
pub fn ema(
  xs: List(Float),
  alpha: Float,
) -> Result(List(Float), Nil)

Exponential moving average with smoothing factor α ∈ (0, 1].

Recurrence: yₜ = α·xₜ + (1-α)·yₜ₋₁, y₀ = x₀.

ema_step

</> 
pub fn ema_step(
  previous: Float,
  observation: Float,
  alpha: Float,
) -> Float

Single-step EMA update. Useful for streaming.

geometric_mean

</> 
pub fn geometric_mean(xs: List(Float)) -> Result(Float, Nil)

Geometric mean: ⁿ√(∏ xᵢ). Requires strictly positive inputs.

harmonic_mean

</> 
pub fn harmonic_mean(xs: List(Float)) -> Result(Float, Nil)

Harmonic mean: n / Σ(1/xᵢ). Requires non-zero inputs.

iqr

</> 
pub fn iqr(xs: List(Float)) -> Result(Float, Nil)

Interquartile range Q3 - Q1.

kurtosis

</> 
pub fn kurtosis(xs: List(Float)) -> Result(Float, Nil)

Excess kurtosis via Pébay online accumulator. Zero for a Gaussian.

linear_space

</> 
pub fn linear_space(
  start: Float,
  stop: Float,
  steps: Int,
  endpoint: Bool,
) -> List(Float)

n evenly-spaced values between start and stop.

  • endpoint = True: includes stop (mimics NumPy linspace(...)).
  • endpoint = False: excludes stop (half-open, mimics arange-like).
  • n <= 0 → []. n == 1 → [start] regardless of endpoint.

logarithmic_space

</> 
pub fn logarithmic_space(
  start: Float,
  stop: Float,
  steps: Int,
  endpoint: Bool,
  base: Float,
) -> List(Float)

n values logarithmically spaced (in base) between base^start and base^stop. endpoint follows the same convention as linear_space.

max

</> 
pub fn max(xs: List(Float)) -> Result(Float, Nil)

Maximum of a list.

mean

</> 
pub fn mean(xs: List(Float)) -> Result(Float, Nil)

Arithmetic mean using Neumaier-compensated sum.

median

</> 
pub fn median(xs: List(Float)) -> Result(Float, Nil)

Median (50th percentile). Linearly interpolates for even-length lists.

min

</> 
pub fn min(xs: List(Float)) -> Result(Float, Nil)

Minimum of a list.

min_max_normalize

</> 
pub fn min_max_normalize(
  xs: List(Float),
) -> Result(List(Float), Nil)

Min-max normalisation to [0, 1].

moving_average

</> 
pub fn moving_average(
  xs: List(Float),
  window: Int,
) -> Result(List(Float), Nil)

Simple moving average over a sliding window of size window.

Output has length len(xs) - window + 1. Errors if window > len or < 1.

pearson

</> 
pub fn pearson(
  xs: List(Float),
  ys: List(Float),
) -> Result(Float, Nil)

Pearson correlation coefficient. Result in [-1, 1].

percentile

</> 
pub fn percentile(
  xs: List(Float),
  q: Float,
) -> Result(Float, Nil)

Percentile q ∈ [0, 1] using linear interpolation (NumPy default).

quartiles

</> 
pub fn quartiles(
  xs: List(Float),
) -> Result(#(Float, Float, Float), Nil)

Quartiles Q1, Q2 (median), Q3 as a tuple.

range

</> 
pub fn range(xs: List(Float)) -> Result(Float, Nil)

Range = max - min.

sample_stddev

</> 
pub fn sample_stddev(xs: List(Float)) -> Result(Float, Nil)

Sample standard deviation.

sample_variance

</> 
pub fn sample_variance(xs: List(Float)) -> Result(Float, Nil)

Sample variance s² = M₂ / (N - 1).

skewness

</> 
pub fn skewness(xs: List(Float)) -> Result(Float, Nil)

Skewness (Fisher-Pearson) via Pébay online accumulator.

Numerically stable: avoids the cancellation of Σ(x - μ)³ over a list.

stddev

</> 
pub fn stddev(xs: List(Float)) -> Result(Float, Nil)

Population standard deviation.

sum

</> 
pub fn sum(xs: List(Float)) -> Float

Sum of a list using Neumaier compensated summation. Returns 0.0 for empty.

Recovers up to 16 extra bits of precision vs naive fold (+.).

variance

</> 
pub fn variance(xs: List(Float)) -> Result(Float, Nil)

Population variance σ² = M₂ / N.

weighted_mean

</> 
pub fn weighted_mean(
  xs: List(Float),
  ws: List(Float),
) -> Result(Float, Nil)

Weighted mean: Σ(wᵢ · xᵢ) / Σwᵢ.

welford

</> 
pub fn welford(xs: List(Float)) -> Welford

Build a Welford accumulator from a list.

welford_empty

</> 
pub fn welford_empty() -> Welford

Empty Welford accumulator.

welford_update

</> 
pub fn welford_update(w: Welford, x: Float) -> Welford

Update a Welford accumulator with a new sample.

z_score

</> 
pub fn z_score(xs: List(Float)) -> Result(List(Float), Nil)

Z-score: (x - μ) / σ. Returns an error if the input has zero variance.

✨ Search Document