# gizlang:stats

descriptive statistics over f64 samples: moments, order statistics and the sort they share; streaming moments, variance and least squares (the SQL aggregates and their merges).

```gizlang
import * as Stats from "gizlang:stats";
```

## Types

### `VarianceState`

```gizlang
type VarianceState = { mean: f64; m2: f64; }
```

A running mean and the sum of squared differences (Welford's method).

- `mean`: `f64`
- `m2`: `f64`

### `OlsFit`

```gizlang
type OlsFit = { coefficients: Vec<f64>; units: Vec<f64>; }
```

The fit of a least-squares regression: the coefficients and the unit of each.

- `coefficients`: `Vec<f64>`
- `units`: `Vec<f64>`

### `OlsInference`

```gizlang
type OlsInference = { rss: f64; degreesOfFreedom: i64; sigma: Option<f64>; covariance: Vec<Vec<f64>>; standardErrors: Vec<f64>; }
```

The inference of a least-squares fit: residual sum of squares, degrees of freedom, sigma, covariance and standard errors.

- `rss`: `f64`
- `degreesOfFreedom`: `i64`
- `sigma`: `_gizlang_sdk_core.Option<f64>`
- `covariance`: `Vec<Vec<f64>>`
- `standardErrors`: `Vec<f64>`

## Functions

### `mean`

```gizlang
function mean(xs: Vec<f64>): f64
```

The mean of `xs`.

Effects: fail.

### `variance`

```gizlang
function variance(xs: Vec<f64>, ddof: i64): f64
```

The variance with `ddof` degrees of freedom removed (0: population, 1: sample).

Effects: fail.

### `argsort`

```gizlang
function argsort(keys: Vec<f64>): Vec<i64>
```

The indices of `keys` in ascending order of their keys; equal keys keep their order (a merge sort).

Effects: fail.

### `sortIndices`

```gizlang
function sortIndices(keys: Vec<f64>, idx: mut Vec<i64>): void
```

Sorts `idx` in place by ascending `keys[idx[i]]`, stable.

Effects: fail.

### `sortedValues`

```gizlang
function sortedValues(xs: Vec<f64>): Vec<f64>
```

The values in ascending order: the merge sort of sortIndices on the values themselves (no index to follow), so
equal and unordered (NaN) values land where argsort puts them.

Effects: fail.

### `quantileSorted`

```gizlang
function quantileSorted(sorted: Vec<f64>, q: f64): f64
```

The q-quantile (0 ≤ q ≤ 1) of sorted values by linear interpolation between the closest ranks (NumPy's default).

Effects: fail.

### `median`

```gizlang
function median(xs: Vec<f64>): f64
```

The median: the middle value, or the mean of the two middle values.

Effects: fail.

### `weightedMedian`

```gizlang
function weightedMedian(xs: Vec<f64>, weights: Vec<f64>): f64
```

The smallest value whose cumulative weight reaches half of the total weight (scikit-learn's weighted median).

Effects: fail.

### `nearestHistogramRank`

```gizlang
function nearestHistogramRank(probability: f64, count: i64): i64
```

Exact ceil(probability * count), with zero selecting the first observation.
Preconditions: probability is finite in [0, 1], count is positive signed i64.
Splitting the 128-bit product preserves ranks above f64's exact integer range.

Effects: fail.

### `histogramBucket`

```gizlang
function histogramBucket(counts: Vec<i64>, probability: f64, count: i64): Option<i64>
```

Locate a nearest-rank histogram bucket; populations are validated by the caller.

Effects: fail.

### `validateMomentMatrix`

```gizlang
function validateMomentMatrix(co: Vec<f64>, dimensions: i64, count: i64): bool throws string
```

Validate retained means and centered products without storage or SQL state.

Effects: fail.

### `transitionMomentMatrix`

```gizlang
function transitionMomentMatrix(co: mut Vec<f64>, count: i64, values: Vec<f64>, weight: i64): i64 throws string
```

Signed repeated-observation update. A refused downdate leaves the prior matrix intact.

Effects: fail.

### `interpolate`

```gizlang
function interpolate(left: f64, right: f64, fraction: f64): f64
```

Linear interpolation avoids overflowing the difference of opposite extremes.

### `stepVariance`

```gizlang
function stepVariance(mean: f64, m2: f64, value: f64, count: i64): VarianceState
```

Welford update; count includes this observation.

### `mergeVariance`

```gizlang
function mergeVariance(mean: f64, m2: f64, count: i64, laterMean: f64, laterM2: f64, laterCount: i64): VarianceState
```

Chan merge retaining the scalar fold's exact arithmetic order.

Effects: fail.

### `stepMomentMatrix`

```gizlang
function stepMomentMatrix(co: mut Vec<f64>, a: Vec<f64>, count: i64): void
```

Means followed by the row-major centered-product matrix. count includes row.

Effects: fail.

### `mergeMomentMatrix`

```gizlang
function mergeMomentMatrix(co: mut Vec<f64>, count: i64, later: Vec<f64>, laterCount: i64, scaled: bool): void
```

Chan combination. scaled=true normalizes populations before products;
false preserves ordered SQL folds' inherited floating operation order.

Effects: fail.

### `boundedCorrelation`

```gizlang
function boundedCorrelation(cross: f64, left: f64, right: f64): f64
```

Centered products on an exact line can differ by rounding ulps.

### `stepOlsFactor`

```gizlang
function stepOlsFactor(co: mut Vec<f64>, a: Vec<f64>, count: i64): bool
```

Complete numerical row; count includes it. True records nonfinite input.
State holds d means followed by the d-by-d triangular design/RHS factor.

Effects: fail.

### `mergeOlsFactor`

```gizlang
function mergeOlsFactor(co: mut Vec<f64>, count: i64, later: Vec<f64>, laterCount: i64): void
```

Stack factors and the centered-mean correction without raw row replay.

Effects: fail.

### `qrSolve`

```gizlang
function qrSolve(co: Vec<f64>, d: i64, units: Vec<f64>, rhs: Vec<f64>): Vec<f64> throws string
```

Solve in exact power-of-two column units with compensated term order.
Wider temporaries use exponent-aware compensation instead of a global RHS scale.

Effects: fail.

### `olsInference`

```gizlang
function olsInference(co: Vec<f64>, count: i64, fit: OlsFit): OlsInference throws string
```

Residual uncertainty from the same centered square-root fit, independent of result formatting.

Effects: fail.

### `fitOls`

```gizlang
function fitOls(co: Vec<f64>, count: i64, overflow: bool): Option<OlsFit> throws string
```

Intercept-first least squares. None means too few rows or deficient rank.

Effects: fail.

## Constants

### `OLS_RANK_SQUARED_TOLERANCE`

```gizlang
const OLS_RANK_SQUARED_TOLERANCE = 0.000000000001
```

The squared tolerance under which a column of a least-squares fit is counted as dependent.

### `MOMENT_ROUNDOFF_ULPS`

```gizlang
const MOMENT_ROUNDOFF_ULPS = 64.0
```

The roundoff, in units in the last place, that a moment calculation allows for.

gizlang:stats

descriptive statistics over f64 samples: moments, order statistics and the sort they share; streaming moments, variance and least squares (the SQL aggregates and their merges).

gizlang

import * as Stats from "gizlang:stats";

Types

`VarianceState`

gizlang

type VarianceState = { mean: f64; m2: f64; }

A running mean and the sum of squared differences (Welford's method).

mean: f64
m2: f64

`OlsFit`

gizlang

type OlsFit = { coefficients: Vec<f64>; units: Vec<f64>; }

The fit of a least-squares regression: the coefficients and the unit of each.

coefficients: Vec<f64>
units: Vec<f64>

`OlsInference`

gizlang

type OlsInference = { rss: f64; degreesOfFreedom: i64; sigma: Option<f64>; covariance: Vec<Vec<f64>>; standardErrors: Vec<f64>; }

The inference of a least-squares fit: residual sum of squares, degrees of freedom, sigma, covariance and standard errors.

rss: f64
degreesOfFreedom: i64
sigma: _gizlang_sdk_core.Option<f64>
covariance: Vec<Vec<f64>>
standardErrors: Vec<f64>

Functions

`mean`

gizlang

function mean(xs: Vec<f64>): f64

The mean of xs.

Effects: fail.

`variance`

gizlang

function variance(xs: Vec<f64>, ddof: i64): f64

The variance with ddof degrees of freedom removed (0: population, 1: sample).

Effects: fail.

`argsort`

gizlang

function argsort(keys: Vec<f64>): Vec<i64>

The indices of keys in ascending order of their keys; equal keys keep their order (a merge sort).

Effects: fail.

`sortIndices`

gizlang

function sortIndices(keys: Vec<f64>, idx: mut Vec<i64>): void

Sorts idx in place by ascending keys[idx[i]], stable.

Effects: fail.

`sortedValues`

gizlang

function sortedValues(xs: Vec<f64>): Vec<f64>

The values in ascending order: the merge sort of sortIndices on the values themselves (no index to follow), so equal and unordered (NaN) values land where argsort puts them.

Effects: fail.

`quantileSorted`

gizlang

function quantileSorted(sorted: Vec<f64>, q: f64): f64

The q-quantile (0 ≤ q ≤ 1) of sorted values by linear interpolation between the closest ranks (NumPy's default).

Effects: fail.

`median`

gizlang

function median(xs: Vec<f64>): f64

The median: the middle value, or the mean of the two middle values.

Effects: fail.

`weightedMedian`

gizlang

function weightedMedian(xs: Vec<f64>, weights: Vec<f64>): f64

The smallest value whose cumulative weight reaches half of the total weight (scikit-learn's weighted median).

Effects: fail.

`nearestHistogramRank`

gizlang

function nearestHistogramRank(probability: f64, count: i64): i64

Exact ceil(probability * count), with zero selecting the first observation. Preconditions: probability is finite in [0, 1], count is positive signed i64. Splitting the 128-bit product preserves ranks above f64's exact integer range.

Effects: fail.

`histogramBucket`

gizlang

function histogramBucket(counts: Vec<i64>, probability: f64, count: i64): Option<i64>

Locate a nearest-rank histogram bucket; populations are validated by the caller.

Effects: fail.

`validateMomentMatrix`

gizlang

function validateMomentMatrix(co: Vec<f64>, dimensions: i64, count: i64): bool throws string

Validate retained means and centered products without storage or SQL state.

Effects: fail.

`transitionMomentMatrix`

gizlang

function transitionMomentMatrix(co: mut Vec<f64>, count: i64, values: Vec<f64>, weight: i64): i64 throws string

Signed repeated-observation update. A refused downdate leaves the prior matrix intact.

Effects: fail.

`interpolate`

gizlang

function interpolate(left: f64, right: f64, fraction: f64): f64

Linear interpolation avoids overflowing the difference of opposite extremes.

`stepVariance`

gizlang

function stepVariance(mean: f64, m2: f64, value: f64, count: i64): VarianceState

Welford update; count includes this observation.

`mergeVariance`

gizlang

function mergeVariance(mean: f64, m2: f64, count: i64, laterMean: f64, laterM2: f64, laterCount: i64): VarianceState

Chan merge retaining the scalar fold's exact arithmetic order.

Effects: fail.

`stepMomentMatrix`

gizlang

function stepMomentMatrix(co: mut Vec<f64>, a: Vec<f64>, count: i64): void

Means followed by the row-major centered-product matrix. count includes row.

Effects: fail.

`mergeMomentMatrix`

gizlang

function mergeMomentMatrix(co: mut Vec<f64>, count: i64, later: Vec<f64>, laterCount: i64, scaled: bool): void

Chan combination. scaled=true normalizes populations before products; false preserves ordered SQL folds' inherited floating operation order.

Effects: fail.

`boundedCorrelation`

gizlang

function boundedCorrelation(cross: f64, left: f64, right: f64): f64

Centered products on an exact line can differ by rounding ulps.

`stepOlsFactor`

gizlang

function stepOlsFactor(co: mut Vec<f64>, a: Vec<f64>, count: i64): bool

Complete numerical row; count includes it. True records nonfinite input. State holds d means followed by the d-by-d triangular design/RHS factor.

Effects: fail.

`mergeOlsFactor`

gizlang

function mergeOlsFactor(co: mut Vec<f64>, count: i64, later: Vec<f64>, laterCount: i64): void

Stack factors and the centered-mean correction without raw row replay.

Effects: fail.

`qrSolve`

gizlang

function qrSolve(co: Vec<f64>, d: i64, units: Vec<f64>, rhs: Vec<f64>): Vec<f64> throws string

Solve in exact power-of-two column units with compensated term order. Wider temporaries use exponent-aware compensation instead of a global RHS scale.

Effects: fail.

`olsInference`

gizlang

function olsInference(co: Vec<f64>, count: i64, fit: OlsFit): OlsInference throws string

Residual uncertainty from the same centered square-root fit, independent of result formatting.

Effects: fail.

`fitOls`

gizlang

function fitOls(co: Vec<f64>, count: i64, overflow: bool): Option<OlsFit> throws string

Intercept-first least squares. None means too few rows or deficient rank.

Effects: fail.

Constants

`OLS_RANK_SQUARED_TOLERANCE`

gizlang

const OLS_RANK_SQUARED_TOLERANCE = 0.000000000001

The squared tolerance under which a column of a least-squares fit is counted as dependent.

`MOMENT_ROUNDOFF_ULPS`

gizlang

const MOMENT_ROUNDOFF_ULPS = 64.0

The roundoff, in units in the last place, that a moment calculation allows for.