statili

Migrating from `highcharts-regression`

Mon, 01 Jan 0001 00:00:00 +0000

@statili/highcharts reads regression: true and regressionSettings exactly as highcharts-regression does, so an existing chart config moves across without edits.

It fixes several defects in the incumbent — which has been unchanged since October 2020 and ships no test suite — and adds accessible chart descriptions for free.

The change

npm install @statili/highcharts

The incumbent installs itself by patching Highcharts.Chart.prototype. This one is a function you call on your options:

Migrating from `regression`

Mon, 01 Jan 0001 00:00:00 +0000

@statili/compat-regression is a drop-in replacement for regression (regression-js), which has been unchanged since December 2017.

Same five methods, same result shape, same equation strings. It fixes four defects in the original and adds a way to find out when a fit failed — something the original API has no room to express.

The change

- import regression from "regression";
+ import regression from "@statili/compat-regression";

npm install @statili/compat-regression

Nothing else changes. linear, exponential, logarithmic, power, polynomial and _round all keep their signatures, and require() works as before.

Activation Functions

Mon, 01 Jan 0001 00:00:00 +0000

@statili/math ·v0.0.1-beta.0 ·1 export

# sigmoid function

packages/math/src/activation.ts:33

signature

sigmoid(z: number): number

Sigmoid (logistic) activation function: σ(z) = 1 / (1 + e⁻ᶻ).

Maps any real-valued input to the open interval (0, 1), making it suitable for modelling probabilities. The function is smooth and differentiable everywhere, which is why it is used in gradient-based optimisation (e.g. logistic regression, neural networks).

Analyse

Mon, 01 Jan 0001 00:00:00 +0000

@statili/highcharts ·v0.0.1-beta.0 ·4 exports

# altText function

packages/highcharts/src/analyse.ts:339

signature

altText(outcome: FitOutcome, labels?: SeriesFit['labels']): string

A short text alternative for a chart, suitable for an aria-label.

Uses terse rendering, so it stays to one clause per fact rather than the paragraph analyse puts on accessibility.description.

Parameters

Name	Type	Description
outcome	FitOutcome	—
labelsoptional	AxisLabels \| undefined	—

Returns

string

# analyse function

packages/highcharts/src/analyse.ts:194

signature

analyse<T extends ChartOptions>(chartOptions: T): AnalyseResult<T>

Adds fitted curves, plot-line markers and accessible descriptions to a Highcharts options object.

Any series carrying a fit property is analysed with @statili/stats, described with @statili/forge, and given a companion series drawn from the curve annotation the facts carry. The input options are not mutated.

Currying

Mon, 01 Jan 0001 00:00:00 +0000

@statili/fp ·v0.0.2-beta.0 ·1 export

# curry function

packages/fp/src/curry.ts:105

signature

curry<T extends (...args: any[]) => any>(fn: T): Curried<Args<T>, Return<T>>

Creates a curried version of a function. A curried function can be called with all arguments at once for immediate execution, or with arguments one at a time (or in chunks) for partial application, returning new functions until all arguments are received.

This utility favors “data-last” arguments for better composability, meaning the data array should typically be the last parameter of the function being curried.

Type parameters

T: The type of the function to curry.

Parameters

Name	Type	Description
fn	T	The function to curry.

Returns

Curried<Args<T>, Return<T>>

A new function that is a curried version of fn.

Example

import { curry } from './curry';

// Example: A simple sum function with data-last
function sum(offset: number, numbers: number[]): number {
return numbers.reduce((acc, val) => acc + val + offset, 0);
}

const curriedSum = curry(sum);

// Partial application (curried form)
const sumWithOffsetOfTen = curriedSum(10);
console.log(sumWithOffsetOfTen([1, 2, 3])); // Output: 16

// Immediate execution (all arguments at once)
console.log(curriedSum(5, [1, 2, 3])); // Output: 11

// Example with a function returning a complex type (like LinearRegressionResult)
type Point = { x: number; y: number };
type RegressionResult = { ok: boolean, m?: number, b?: number, error?: string };

function _calculateRegression(options: { includeRSquared: boolean }, data: Point[]): RegressionResult {
// ... actual calculation logic ...
return { ok: true, m: 1, b: 0 };
}

const calculateRegression = curry(_calculateRegression);

// Partial application
const regressionWithRSquared = calculateRegression({ includeRSquared: true });
const resultPartial = regressionWithRSquared([{ x: 1, y: 1 }]);
console.log(resultPartial);

// Immediate execution
const resultImmediate = calculateRegression({ includeRSquared: false }, [{ x: 1, y: 1 }]);
console.log(resultImmediate);

Exponential

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·2 exports

# exponentialFacts function

packages/forge/src/regression/exponential.ts:47

signature

exponentialFacts(options: ExponentialFactOptions, statsResult: RegressionResult): FactResult

Generates facts from an exponential regression result.

Emits trend.exponential — with the per-step multiplier and the doubling time or half-life — plus fit.quality, fit.error, and a small-sample caveat.

Parameters

Name	Type	Description
options	CommonFactOptions	—
statsResult	RegressionResult	—

Returns

FactResult

# ExponentialFactOptions type

packages/forge/src/regression/exponential.ts:17

signature

type ExponentialFactOptions = LogarithmicFactOptions;

Options are the shared set — exponential adds no thresholds of its own.

Exponential

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# exponential function

packages/stats/src/regression/exponential.ts:49

signatures

exponential(arg1: Partial<RegressionOptions>): (args_0: DataPoint[]) => RegressionResult
exponential(suppliedOptions: Partial<RegressionOptions>, data: DataPoint[]): RegressionResult

Performs exponential regression to model the relationship y = a · e^(bx).

Captures constant proportional growth or decay — compound interest, viral spread, radioactive decay, unchecked adoption. The defining property is that Y multiplies by a fixed factor for each equal step in X, rather than adding a fixed amount as in linear regression.

Index

Mon, 01 Jan 0001 00:00:00 +0000

@statili/compat-regression ·v0.0.1-beta.0 ·7 exports

# _round function

packages/compat-regression/src/index.ts:22

signature

_round(number: number, precision: number): number

Rounds to precision decimal places.

Exported because regression exports it as _round, and some callers reach for it to format their own values consistently with the fit.

Parameters

Name	Type	Description
number	number	—
precision	number	—

Returns

number

# exponential function

packages/compat-regression/src/index.ts:122

signature

exponential(data: DataPoint[], options?: Partial<Options>): Result

Fits y = a·e^(bx). Returns coefficients as [a, b].

Uses the same y-weighted least squares as regression, which tracks the data in its original units more closely than plain regression on ln(y).

Parameters

Name	Type	Description
data	DataPoint[]	`[x, y]` pairs. Requires y > 0.
optionsoptional	Partial<Options> \| undefined	—

Returns

Result

# linear function

packages/compat-regression/src/index.ts:98

signature

linear(data: DataPoint[], options?: Partial<Options>): Result

Fits a straight line, y = mx + c. Returns coefficients as [m, c].

Parameters

Name	Type	Description
data	DataPoint[]	`[x, y]` pairs. Rows with a `null` y are skipped.
optionsoptional	Partial<Options> \| undefined	`{ precision }`.

Returns

Result

Example

const result = linear([[0, 1], [32, 67], [12, 79]]);
result.equation;  // [gradient, intercept]
result.predict(5);

# logarithmic function

packages/compat-regression/src/index.ts:137

signature

logarithmic(data: DataPoint[], options?: Partial<Options>): Result

Fits y = a + b·ln(x). Returns coefficients as [a, b].

Parameters

Name	Type	Description
data	DataPoint[]	`[x, y]` pairs. Requires x > 0.
optionsoptional	Partial<Options> \| undefined	—

Returns

Result

# polynomial function

packages/compat-regression/src/index.ts:172

signature

polynomial(data: DataPoint[], options?: Partial<Options>): Result

Fits a polynomial of the given order.

Returns coefficients highest power first — [aₙ, …, a₁, a₀] — matching regression. Note this is the reverse of @statili/stats, which orders them ascending.

Parameters

Name	Type	Description
data	DataPoint[]	`[x, y]` pairs.
optionsoptional	Partial<Options> \| undefined	`{ order, precision }`.

Returns

Result

# power function

packages/compat-regression/src/index.ts:152

signature

power(data: DataPoint[], options?: Partial<Options>): Result

Fits y = a·x^b. Returns coefficients as [a, b].

Parameters

Name	Type	Description
data	DataPoint[]	`[x, y]` pairs. Requires x > 0 and y > 0.
optionsoptional	Partial<Options> \| undefined	—

Returns

Result

# default const

packages/compat-regression/src/index.ts:209

signature

regression = { linear, exponential, logarithmic, power, polynomial, _round }

The five fitting methods, matching the default export of regression.

Examples

Before

import regression from "regression";
// After — the only line that changes
import regression from "@statili/compat-regression";

const result = regression.linear([[0, 1], [32, 67], [12, 79]]);

What the shim adds: a way to know the fit failed

const result = regression.linear([[1, 1], [1, 2], [1, 3]]);
if (!result.ok) console.warn(result.error.message);
// `regression` answers this with a confident horizontal line and r2 = 0.

Compat

Mon, 01 Jan 0001 00:00:00 +0000

@statili/highcharts ·v0.0.1-beta.0 ·5 exports

# fillPlaceholders function

packages/highcharts/src/compat.ts:128

signature

fillPlaceholders(template: string, stats: RegressionSuccess | SmoothSuccess, decimalPlaces: number): string

Substitutes %eq, %r2, %r and %se, globally rather than once each.

Parameters

Name	Type	Description
template	string	—
stats	RegressionSuccess \| SmoothSuccess	—
decimalPlaces	number	—

Returns

string

# withRegression function

packages/highcharts/src/compat.ts:252

signature

withRegression<T extends RegressionChartOptions>(chartOptions: T): AnalyseResult<T>

Drop-in replacement for highcharts-regression.

Reads regression: true and regressionSettings off each series exactly as the incumbent does, so an existing chart config needs no edits. Internally it translates to the native fit API and calls {@link analyse}, so the facts and accessible descriptions come along for free.

Descriptive Statistics

Mon, 01 Jan 0001 00:00:00 +0000

@statili/math ·v0.0.1-beta.0 ·12 exports

# covariance function

packages/math/src/descriptive.ts:300

signature

covariance(xs: number[], ys: number[]): number

Returns the sample covariance between two equal-length arrays xs and ys (divided by n − 1).

Covariance measures the joint variability of two variables — a positive value means they tend to increase together; a negative value means one tends to decrease as the other increases.

Linear Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# linearFacts function

packages/forge/src/regression/linear.ts:103

signature

linearFacts(options: LinearFactOptions, statsResult: RegressionResult): FactResult

Generates facts from a simple linear regression result.

Emits trend.linear, fit.quality, fit.error, and — where the sample supports it — fit.significance and a caveat.small-sample.

Parameters

Name	Type	Description
options	LinearFactOptions	Thresholds controlling the qualitative judgements.
statsResult	RegressionResult	The raw result from `@statili/stats` `linear()`.

Returns

FactResult

Facts, or an end-user facing error.

Example

const result = linearFacts({}, linear({}, data));
if (result.ok) result.facts.map(render({ labels: { x: "month", y: "sales" } }));

Linear Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# linear function

packages/stats/src/regression/linear.ts:59

signatures

linear(arg1: Partial<RegressionOptions>): (args_0: DataPoint[]) => RegressionResult
linear(suppliedOptions: Partial<RegressionOptions>, data: DataPoint[]): RegressionResult

Performs simple linear regression to model the relationship between a dependent variable (y) and an independent variable (x).

Fits a straight line (y = slope·x + intercept) through the data by minimising the sum of squared residuals between observed and predicted y values (Ordinary Least Squares).

Parameters

Name	Type	Description
suppliedOptions	Partial<RegressionOptions>	Optional overrides, e.g. `{ precision: 4 }`.
data	DataPoint[]	Array of `[x, y]` tuples. Requires at least 2 points with distinct x values.

Returns

RegressionResult

Discriminant union:

Pipe & Compose

Mon, 01 Jan 0001 00:00:00 +0000

@statili/fp ·v0.0.2-beta.0 ·1 export

# pipe function

packages/fp/src/pipe.ts:19

signatures

pipe<A, B>(f1: (input: A) => B): (input: A) => B
pipe<A, B, C>(f1: (input: A) => B, f2: (input: B) => C): (input: A) => C
pipe<A, B, C, D>(f1: (input: A) => B, f2: (input: B) => C, f3: (input: C) => D): (input: A) => D
pipe<A, B, C, D, E>(f1: (input: A) => B, f2: (input: B) => C, f3: (input: C) => D, f4: (input: D) => E): (input: A) => E
pipe<A, B, C, D, E, F>(f1: (input: A) => B, f2: (input: B) => C, f3: (input: C) => D, f4: (input: D) => E, f5: (input: E) => F): (input: A) => F
pipe<A, B, C, D, E, F, G>(f1: (input: A) => B, f2: (input: B) => C, f3: (input: C) => D, f4: (input: D) => E, f5: (input: E) => F, f6: (input: F) => G): (input: A) => G
pipe<A, B, C, D, E, F, G, H>(f1: (input: A) => B, f2: (input: B) => C, f3: (input: C) => D, f4: (input: D) => E, f5: (input: E) => F, f6: (input: F) => G, f7: (input: G) => H): (input: A) => H
pipe<F extends readonly [(...args: any[]) => any, ...Array<(arg: any) => any>]>(...fns: F): (input: PipeInput<F>) => PipeReturn<F>

Parameters

Name	Type	Description
f1	(input: A) => B	—
f2	(input: B) => C	—
f3	(input: C) => D	—
f4	(input: D) => E	—
f5	(input: E) => F	—
f6	(input: F) => G	—
f7	(input: G) => H	—

Returns

(input: A) => H

Types

Mon, 01 Jan 0001 00:00:00 +0000

@statili/compat-regression ·v0.0.1-beta.0 ·4 exports

# FitError interface

packages/compat-regression/src/types.ts:15

signature

interface FitError {
  /**
   * Machine-readable cause.
   *
   * - `InsufficientData` — too few usable points for this model.
   * - `DegenerateInput` — the x-values carry no variation to fit against.
   * - `InvalidInput` — a non-finite value, or an out-of-domain point.
   * - `MathError` — the fit produced non-finite coefficients.
   * - `NumericalStability` — the normal equations were singular or ill-conditioned.
   */
  type:
    | "InsufficientData"
    | "DegenerateInput"
    | "InvalidInput"
    | "MathError"
    | "NumericalStability";
  /** What went wrong, and what to do about it. */
  message: string;
}

Why a fit could not be produced.

# Options interface

packages/compat-regression/src/types.ts:5

signature

interface Options {
  /** Polynomial degree. @default 2 */
  order: number;
  /** Decimal places for rounding. @default 2 */
  precision: number;
  /** Accepted and ignored, as in `regression`. */
  period: number | null;
}

The five configuration keys regression accepts.

# Result interface

packages/compat-regression/src/types.ts:47

signature

interface Result {
  /**
   * Fitted coefficients.
   *
   * - `linear` — `[gradient, intercept]`
   * - `exponential` — `[a, b]` for y = ae^(bx)
   * - `logarithmic` — `[a, b]` for y = a + b·ln(x)
   * - `power` — `[a, b]` for y = ax^b
   * - `polynomial` — `[aₙ, …, a₁, a₀]`, highest power first
   *
   * Filled with `NaN` when `ok` is `false`.
   */
  equation: number[];
  /** Human-readable equation. Empty string when `ok` is `false`. */
  string: string;
  /**
   * Predicted `[x, y]` at each input x.
   *
   * Empty when `ok` is `false`. The original returns points full of `NaN`
   * instead, which charting libraries either throw on or render as garbage.
   */
  points: [number, number][];
  /** Coefficient of determination. `NaN` when `ok` is `false`. */
  r2: number;
  /** Predicted `[x, y]` at any x. Returns `[x, NaN]` when `ok` is `false`. */
  predict: (x: number) => [number, number];

  /** `false` when no fit could be produced. Not present in `regression`. */
  ok: boolean;
  /** Why the fit failed. Absent when `ok` is `true`. Not present in `regression`. */
  error?: FitError;
}

The result shape returned by regression, plus two additive fields.

equation, string, points, r2 and predict are byte-for-byte what the original returns on data it handles correctly. ok and error are new.

Distribution

Mon, 01 Jan 0001 00:00:00 +0000

@statili/math ·v0.0.1-beta.0 ·5 exports

# logGamma function

packages/math/src/distribution.ts:41

signature

logGamma(x: number): number

Natural logarithm of the gamma function, ln Γ(x), via the Lanczos approximation.

Γ(x) overflows a double for x greater than about 171, so the log form is used throughout — every consumer here needs ratios of gamma functions, which become differences of logs and stay in range.

Loess

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·2 exports

# loessFacts function

packages/forge/src/regression/loess.ts:47

signature

loessFacts(options: LoessFactOptions, smoothResult: SmoothResult): FactResult

Generates facts from a LOESS smoothing result.

Emits trend.smoothed — turning points and net direction — plus fit.quality, fit.error, and a small-sample caveat.

There is no trend fact with a rate or coefficient, because a smoother fits no equation. Its contribution is shape: “rises to a peak at week 12, then declines” is a claim no parametric fit in this library can make.

Logarithmic Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# logarithmic function

packages/stats/src/regression/logarithmic.ts:48

signatures

logarithmic(arg1: Partial<RegressionOptions>): (args_0: DataPoint[]) => RegressionResult
logarithmic(suppliedOptions: Partial<RegressionOptions>, data: DataPoint[]): RegressionResult

Performs logarithmic regression to model the relationship y = a + b · ln(x).

The model captures scenarios where Y grows (or decays) rapidly at first then progressively levels off as X increases — the classic diminishing-returns pattern.

Domain constraint: x must be strictly positive (> 0). Points with x ≤ 0 are silently excluded because ln(x) is undefined for non-positive values.

Types

Mon, 01 Jan 0001 00:00:00 +0000

@statili/highcharts ·v0.0.1-beta.0 ·7 exports

# AnalyseResult interface

packages/highcharts/src/types.ts:123

signature

interface AnalyseResult<T extends ChartOptions = ChartOptions> {
  /** The input options with fit series, plot lines and descriptions added. */
  options: AnalysedOptions<T>;
  /** One entry per series that carried a `fit`. */
  fits: FitOutcome[];
}

# ChartOptions interface

packages/highcharts/src/types.ts:77

signature

interface ChartOptions {
  series?: FittableSeries[];
  xAxis?: unknown;
  accessibility?: Record<string, unknown>;
  [key: string]: unknown;
}

Minimal shape of the chart options this module reads and rewrites.

# FitOutcome interface

packages/highcharts/src/types.ts:85

signature

interface FitOutcome {
  /** Index of the source series in the input `series` array. */
  sourceIndex: number;
  sourceName: string;
  method: FitMethod;
  /** Empty when the fit failed. */
  facts: Fact[];
  /** Sentences, one per fact, at full verbosity. */
  sentences: string[];
  /** One paragraph suitable for `accessibility.description`. */
  description: string;
  /**
   * The raw `@statili/stats` result, including `predict`.
   *
   * Facts are deliberately JSON-serialisable so they can be handed to an AI
   * pipeline as ground truth, which rules out carrying a function. Anything
   * that needs to evaluate the model outside the observed domain —
   * extrapolation, a denser curve, a hover readout — reads it from here.
   *
   * Absent when the fit failed.
   */
  stats?: RegressionSuccess | SmoothSuccess;
  /** Present when the fit could not be computed. */
  error?: { message: string; helpText: string; errorType: string };
}

What one fitted series produced.

# FittableSeries interface

packages/highcharts/src/types.ts:69

signature

interface FittableSeries {
  name?: string;
  data?: unknown;
  fit?: SeriesFit;
  [key: string]: unknown;
}

A series carrying a fit instruction. Structurally typed to stay Highcharts-version agnostic.

# SeriesFit interface

packages/highcharts/src/types.ts:20

signature

interface SeriesFit {
  method: FitMethod;
  /** Decimal places for the fitted coefficients. @default 2 */
  precision?: number;
  /** Polynomial degree. `polynomial` only. @default 2 */
  order?: number;
  /**
   * Fraction of the sample in each local neighbourhood. `loess` only.
   * @default 0.25
   */
  bandwidth?: number;
  /** R² at or above which a fit is called "moderate". @default 0.3 */
  rSquaredThresholdWeak?: number;
  /** R² at or above which a fit is called "strong". @default 0.7 */
  rSquaredThresholdStrong?: number;
  /** Axis names used when facts are rendered into prose. */
  labels?: AxisLabels;
  /** Units appended to rendered quantities. */
  units?: AxisUnits;
  /**
   * Extend the fitted curve this many steps past the last observation.
   *
   * The step size comes from the average spacing of the observed X values.
   * Extrapolation is forward only, matching what charting users expect of a
   * trend line.
   *
   * @default 0
   */
  extrapolate?: number;
  /** Options merged into the generated fit series. */
  seriesOptions?: Record<string, unknown>;
  /** Draw a plot line at any `marker` annotation the facts carry. @default true */
  showMarkers?: boolean;
  /**
   * Draw the uncertainty band as an `arearange` series behind the fit.
   *
   * Requires Highcharts' `highcharts-more` module, which supplies `arearange` —
   * hence off by default rather
// …truncated

Type shortened for readability — see the source for the full definition.

Linear Algebra

Mon, 01 Jan 0001 00:00:00 +0000

@statili/math ·v0.0.1-beta.0 ·1 export

# gaussianElimination function

packages/math/src/linalg.ts:40

signature

gaussianElimination(input: number[][], order: number): number[]

Solves the linear system Ax = b via Gaussian elimination with partial pivoting.

The augmented matrix [A | b] is passed as input: an n × (n+1) matrix where the first n columns represent A and the last column represents b. The function operates on a deep copy and does not mutate its input.

Logarithmic Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# logarithmicFacts function

packages/forge/src/regression/logarithmic.ts:59

signature

logarithmicFacts(options: LogarithmicFactOptions, statsResult: RegressionResult): FactResult

Generates facts from a logarithmic regression result.

Emits trend.logarithmic, effect.diminishing where the curve rises, fit.quality, fit.error, and a small-sample caveat.

Parameters

Name	Type	Description
options	CommonFactOptions	—
statsResult	RegressionResult	—

Returns

FactResult

Logistic Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# logistic function

packages/stats/src/regression/logistic.ts:62

signatures

logistic(arg1: Partial<LogisticRegressionOptions>): (args_0: MultiDataPoint[]) => MultiRegressionResult
logistic(suppliedOptions: Partial<LogisticRegressionOptions>, data: MultiDataPoint[]): MultiRegressionResult

Performs binary logistic regression via batch gradient descent.

Models the probability that an observation belongs to class 1: P(y=1 | x) = σ(b₀ + b₁x₁ + b₂x₂ + … + bₖxₖ) where σ is the sigmoid function. Predictions at P ≥ 0.5 are classified as 1.

Logistic Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# logisticFacts function

packages/forge/src/regression/logistic.ts:85

signature

logisticFacts(options: LogisticFactOptions, statsResult: MultiRegressionResult): FactResult

Generates facts from a binary logistic regression result.

Emits model.logistic, one effect.feature per predictor (with odds multipliers), effect.boundary, fit.quality on the McFadden pseudo-R² scale, and caveats for low accuracy and small samples.

No fit.error: RMSE on a 0/1 outcome is not a meaningful error measure.

Parameters

Name	Type	Description
options	LogisticFactOptions	—
statsResult	MultiRegressionResult	—

Returns

FactResult

Multilinear Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# multilinear function

packages/stats/src/regression/multilinear.ts:59

signatures

multilinear(arg1: Partial<RegressionOptions>): (args_0: MultiDataPoint[]) => MultiRegressionResult
multilinear(suppliedOptions: Partial<RegressionOptions>, data: MultiDataPoint[]): MultiRegressionResult

Performs Multiple Linear Regression (MLR) to model the relationship: y = b₀ + b₁x₁ + b₂x₂ + … + bₖxₖ

Coefficients are found by solving the normal equations: (Xᵀ X) β = Xᵀ y via Gaussian elimination with partial pivoting.

Parameters

Name	Type	Description
suppliedOptions	Partial<RegressionOptions>	Optional `{ precision }` overrides.
data	MultiDataPoint[]	Array of `{ x: number[], y: number \| null }` observations. All observations must share the same feature dimension (`x.length`). Observations with `y === null` are excluded from the fit.

Returns

MultiRegressionResult

Discriminant union:

Numeric Utilities

Mon, 01 Jan 0001 00:00:00 +0000

@statili/math ·v0.0.1-beta.0 ·4 exports

# clamp function

packages/math/src/numeric.ts:70

signature

clamp(lo: number, hi: number, value: number): number

Clamps value to the closed interval [lo, hi].

Useful when mapping statistical outputs (e.g. probabilities, normalised scores) to a bounded domain before rendering.

Parameters

Name	Type	Description
lo	number	Lower bound (inclusive).
hi	number	Upper bound (inclusive).
value	number	The value to clamp.

Returns

number

lo if value < lo, hi if value > hi, otherwise value.

Example

clamp(0, 1, -0.3)  // 0
clamp(0, 1, 1.7)   // 1
clamp(0, 1, 0.5)   // 0.5

// Partial application — create a unit-clamp helper
const unitClamp = clamp(0, 1);
unitClamp(sigmoid(-100))  // 0 (not quite, but clamped to 0)

# isFiniteNumber function

packages/math/src/numeric.ts:46

signature

isFiniteNumber(value: unknown): boolean

Returns true when value is a finite, non-NaN number (i.e., safe for arithmetic). Rejects NaN, Infinity, -Infinity, null, and undefined.

Replaces the inline isValid guard scattered across @statili/stats regression methods.

Parameters

Name	Type	Description
value	unknown	Any value to test.

Returns

boolean

true if value is a finite number, false otherwise.

Example

isFiniteNumber(3.14)      // true
isFiniteNumber(NaN)       // false
isFiniteNumber(Infinity)  // false
isFiniteNumber(null)      // false

# lerp function

packages/math/src/numeric.ts:95

signature

lerp(a: number, b: number, t: number): number

Linearly interpolates between a and b by factor t.

t = 0 returns a
t = 1 returns b
t = 0.5 returns the midpoint
Values outside [0, 1] extrapolate beyond the endpoints

Handy for generating evenly-spaced prediction points along a regression curve or animating transitions between two chart states.

Multilinear Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# multilinearFacts function

packages/forge/src/regression/multilinear.ts:41

signature

multilinearFacts(options: MultilinearFactOptions, statsResult: MultiRegressionResult): FactResult

Generates facts from a multiple linear regression result.

Emits model.multilinear, one effect.feature per predictor, fit.quality, fit.error, and a small-sample caveat.

No curve annotation: with several predictors there is no single X axis to draw against.

Parameters

Name	Type	Description
options	CommonFactOptions	—
statsResult	MultiRegressionResult	—

Returns

FactResult

Polynomial Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# polynomial function

packages/stats/src/regression/polynomial.ts:49

signatures

polynomial(arg1: Partial<RegressionOptions>): (args_0: DataPoint[]) => RegressionResult
polynomial(suppliedOptions: Partial<RegressionOptions>, data: DataPoint[]): RegressionResult

Performs polynomial regression of configurable degree.

Fits the curve y = c₀ + c₁x + c₂x² + … + cₙxⁿ by solving the normal equations via Gaussian elimination with partial pivoting.

Parameters

Name	Type	Description
suppliedOptions	Partial<RegressionOptions>	`{ precision?, order? }` — `order` sets the polynomial degree (default 2). Increasing degree improves fit but risks overfitting when `n` is close to `order + 1`.
data	DataPoint[]	Array of `[x, y]` tuples. Requires at least `order + 1` valid points.

Returns

RegressionResult

Discriminant union:

Polynomial Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# polynomialFacts function

packages/forge/src/regression/polynomial.ts:76

signature

polynomialFacts(options: PolynomialFactOptions, statsResult: RegressionResult): FactResult

Generates facts from a polynomial regression result.

Emits trend.polynomial (with a vertex marker for quadratics), fit.quality, fit.error, and caveats for overfitting and small samples.

Parameters

Name	Type	Description
options	PolynomialFactOptions	—
statsResult	RegressionResult	—

Returns

FactResult

Power Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# power function

packages/stats/src/regression/power.ts:50

signatures

power(arg1: Partial<RegressionOptions>): (args_0: DataPoint[]) => RegressionResult
power(suppliedOptions: Partial<RegressionOptions>, data: DataPoint[]): RegressionResult

Performs power law regression to model the relationship y = a · xᵇ.

The model is linearised by taking logarithms of both sides: ln(y) = ln(a) + b·ln(x), which becomes a simple linear regression in log-log space. The result is then transformed back to the original scale.

Power Regression

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# powerFacts function

packages/forge/src/regression/power.ts:63

signature

powerFacts(options: PowerFactOptions, statsResult: RegressionResult): FactResult

Generates facts from a power law regression result.

Emits trend.power (growth regime and doubling multiplier), effect.scale, fit.quality, fit.error, and a small-sample caveat.

Parameters

Name	Type	Description
options	PowerFactOptions	—
statsResult	RegressionResult	—

Returns

FactResult

Types

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·14 exports

# Interval interface

packages/stats/src/regression/types.ts:91

signature

interface Interval {
  /** The fitted value at x — the centre of the range. */
  fit: number;
  lower: number;
  upper: number;
}

A fitted value with an uncertainty range around it.

# LogisticRegressionOptions interface

packages/stats/src/regression/types.ts:141

signature

interface LogisticRegressionOptions {
  /** Gradient descent learning rate. @default 0.1 */
  learningRate: number;
  /** Number of gradient descent iterations. @default 1000 */
  iterations: number;
  /** Decimal places for rounding. @default 4 */
  precision: number;
}

# MultiRegressionError interface

packages/stats/src/regression/types.ts:132

signature

interface MultiRegressionError {
  ok: false;
  method?: "multilinear" | "logistic";
  errorType: RegressionErrorType;
  message: string;
}

# MultiRegressionSuccess interface

packages/stats/src/regression/types.ts:114

signature

interface MultiRegressionSuccess {
  ok: true;
  method: "multilinear" | "logistic";
  /** [intercept, b1, b2, ..., bk] */
  coefficients: number[];
  numFeatures: number;
  /** R2 for multilinear; McFadden pseudo-R2 for logistic. */
  r2: number;
  /** RMSE on training set. NaN for logistic. */
  rmse: number;
  n: number;
  points: PredictedMultiPoint[];
  predict: (x: number[]) => PredictedMultiPoint;
  equation: string;
  /** Training accuracy at 0.5 threshold (logistic only). */
  accuracy?: number;
}

# RegressionError interface

packages/stats/src/regression/types.ts:81

signature

interface RegressionError {
  ok: false;
  method?: "linear" | "logarithmic" | "exponential" | "power" | "polynomial";
  errorType: RegressionErrorType;
  message: string;
}

# RegressionOptions interface

packages/stats/src/regression/types.ts:98

signature

interface RegressionOptions {
  /** Decimal places for rounding. @default 2 */
  precision: number;
  /**
   * Confidence level for intervals, in `(0, 1)`. @default 0.95
   */
  confidenceLevel?: number;
  /** Polynomial degree (polynomial() only). @default 2 */
  order?: number;
}

# RegressionSuccess interface

packages/stats/src/regression/types.ts:11

signature

interface RegressionSuccess {
  ok: true;
  /** Primary slope / rate-of-change coefficient.
   * linear: slope m | polynomial: c1 | power: exponent b | logarithmic: ln-coeff b */
  slope: number;
  /** Y-intercept or constant term.
   * linear: y-int | polynomial: c0 | power: scale a | logarithmic: constant a */
  intercept: number;
  /** Coefficient of determination R2 in [0,1]. */
  r2: number;
  /** Root Mean Squared Error in the same units as Y. */
  rmse: number;
  /** Number of valid data points used. */
  n: number;
  method: "linear" | "logarithmic" | "exponential" | "power" | "polynomial";
  points: PredictedPoint[];
  predict: (x: number) => PredictedPoint;
  /** Full coefficient vector [c0,c1,...,cn] for polynomial. */
  coefficients?: number[];
  /** Polynomial degree. */
  degree?: number;
  /** Human-readable equation string. */
  equation?: string;
  // ── Inference on the slope ──────────────────────────────────────────────
  // Populated by `linear()` only. Left `undefined` by every other method —
  // polynomial needs the full coefficient covariance matrix, and the
  // log-linearised fits (power, logarithmic) would report significance in
  // transformed space, which is not what a caller would expect.
  //
  // All four are `null` when there are too few points to estimate them
  // (`n < 3`, i.e. `df < 1`), and `tM`/`pValueM` are additionally `null` for a
  /
// …truncated

Type shortened for readability — see the source for the full definition.

Loess

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·1 export

# loess function

packages/stats/src/smoothing/loess.ts:135

signatures

loess(arg1: Partial<LoessOptions>): (args_0: DataPoint[]) => SmoothResult
loess(suppliedOptions: Partial<LoessOptions>, data: DataPoint[]): SmoothResult

Performs LOESS (locally estimated scatterplot smoothing) with local linear fits and tricube weights.

Unlike every method in regression/, this fits no global model. Each output point comes from its own weighted line through nearby observations, which lets the curve follow structure no single equation could — several peaks, a plateau, a reversal partway through.

Regression Error

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·1 export

# regressionError function

packages/forge/src/regression/regressionError.ts:11

signature

regressionError(errorResult: RegressionError | MultiRegressionError): FactResultError

Translates a technical failure from @statili/stats into an end-user facing explanation with a concrete next step.

A failed analysis is not a fact — nothing was measured — so it stays on the ok: false branch rather than becoming a no-finding.

Parameters

Name	Type	Description
errorResult	RegressionError \| MultiRegressionError	—

Returns

FactResultError

Render

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·5 exports

# render function

packages/forge/src/render.ts:78

signatures

render(arg1: RenderOptions): (args_0: Fact) => string
render(options: RenderOptions, fact: Fact): string

Turns a {@link Fact} into a sentence.

Rendering is deliberately separate from fact generation: one claim can be spoken at several lengths, in several languages, with the consumer’s own axis names — none of which is possible once prose has been baked into the result. Swap this function out entirely to localise.

Parameters

Name	Type	Description
options	RenderOptions	Axis labels, units, and verbosity.
fact	Fact	The fact to render.

Returns

string

A sentence describing the fact.

Examples

const speak = render({ labels: { x: "week", y: "signups" }, units: { y: "users" } });
speak(fact);
// "Each additional unit of week is associated with an increase of 8.23 users
//  in signups. At week = 0 the fitted value of signups is 3.53 users."

Terse, for an aria-label

render({ labels: { x: "week", y: "signups" }, verbosity: "terse" })(fact);
// "signups: up 8.23 per additional unit of week."

# renderAnnotation function

packages/forge/src/render.ts:463

signatures

renderAnnotation(arg1: RenderOptions): (args_0: Annotation) => string
renderAnnotation(options: RenderOptions, annotation: Annotation): string

Turns an {@link Annotation} into a display label — a legend entry for a curve, a plot-line caption for a marker.

Lives here for the same reason {@link render} does: without it every consumer reimplements the "vertex" → "Vertex" mapping, and they drift apart the moment a new role is added.

Parameters

Name	Type	Description
options	RenderOptions	Axis labels and verbosity. Units are unused today.
annotation	Annotation	The annotation to label.

Returns

string

A short label, safe to put in a legend or on an axis.

Example

renderAnnotation({})(curve);                          // "Linear fit"
renderAnnotation({ labels: { x: "hour" } })(marker);  // "Vertex at hour = 3"

# AxisLabels interface

packages/forge/src/render.ts:9

signature

interface AxisLabels {
  x?: string;
  y?: string;
}

Axis names, so a rendered fact reads in the reader’s domain rather than in algebra. “As advertising spend increases, monthly sales tend to increase” beats “As X increases, Y tends to increase” — especially as chart alt text.

# AxisUnits interface

packages/forge/src/render.ts:15

signature

interface AxisUnits {
  x?: string;
  y?: string;
}

Units appended to quantities, e.g. { y: "£" } or { x: "days" }.

# RenderOptions interface

packages/forge/src/render.ts:20

signature

interface RenderOptions {
  labels?: AxisLabels;
  units?: AxisUnits;
  /**
   * `"terse"` yields a single clause suitable for an `aria-label` or a tooltip.
   * `"full"` yields one to three sentences for a `<desc>` or a body paragraph.
   * @default "full"
   */
  verbosity?: "terse" | "full";
}

Types

Mon, 01 Jan 0001 00:00:00 +0000

@statili/stats ·v0.0.2-beta.0 ·5 exports

# LoessOptions interface

packages/stats/src/smoothing/types.ts:47

signature

interface LoessOptions {
  /**
   * Fraction of the sample in each local neighbourhood, in `(0, 1]`.
   *
   * Smaller follows the data more closely and picks up more turning points;
   * larger produces a smoother curve. `highcharts-regression` exposes the same
   * control as `loessSmooth`, expressed as a percentage.
   *
   * @default 0.25
   */
  bandwidth: number;
  /** Decimal places for the smoothed values. @default 2 */
  precision: number;
  /**
   * Minimum change in Y for a direction reversal to count as a turning point,
   * as a fraction of the smoothed Y range. Suppresses noise-level wobble.
   *
   * @default 0.01
   */
  turningPointThreshold: number;
}

# SmoothError interface

packages/stats/src/smoothing/types.ts:38

signature

interface SmoothError {
  ok: false;
  method?: "loess";
  errorType: RegressionErrorType;
  message: string;
}

# SmoothSuccess interface

packages/stats/src/smoothing/types.ts:21

signature

interface SmoothSuccess {
  ok: true;
  method: "loess";
  /** Smoothed `[x, y]` at each observed x, in ascending x order. */
  points: PredictedPoint[];
  /** Fraction of the sample used in each local neighbourhood. */
  bandwidth: number;
  /** Proportion of variance the smoothed curve accounts for. */
  r2: number;
  rmse: number;
  n: number;
  /** Direction changes in the smoothed curve, in ascending x order. */
  turningPoints: TurningPoint[];
  /** Overall direction from the first smoothed value to the last. */
  netDirection: "rising" | "falling" | "flat";
}

The result of a scatterplot smoother.

Deliberately not a RegressionSuccess. A smoother fits no global model, so there is no slope, intercept or equation to report, and no predict — a LOESS value at an unobserved x requires refitting against the whole dataset, so the curve cannot be projected beyond the data it was built from.

Types

Mon, 01 Jan 0001 00:00:00 +0000

@statili/forge ·v0.0.2-beta.0 ·17 exports

# ClaimMap interface

packages/forge/src/types.ts:89

signature

interface ClaimMap {
  // ── Shape of the relationship ─────────────────────────────────────────────

  /** Direction and rate of a straight-line relationship. */
  "trend.linear": {
    direction: "rising" | "falling" | "flat";
    /** Change in Y per one-unit increase in X. */
    slope: number;
    intercept: number;
  };

  /** Shape of a fitted polynomial curve. */
  "trend.polynomial": {
    degree: number;
    leadingCoefficient: number;
    shape: "line" | "parabola-up" | "parabola-down" | "cubic" | "higher-order";
    /** X position of the extremum. Quadratics only; `null` otherwise. */
    vertexX: number | null;
    equation: string;
  };

  /** Growth regime of a fitted power law, y = a·x^b. */
  "trend.power": {
    /** The exponent b. */
    exponent: number;
    /** The scale coefficient a — the predicted Y at x = 1. */
    scale: number;
    regime: "superlinear" | "proportional" | "sublinear" | "flat" | "inverse";
    /** Y is multiplied by this when X doubles: 2^b. */
    doublingFactor: number;
    equation: string;
  };

  /** Constant proportional growth or decay, y = a·e^(bx). */
  "trend.exponential": {
    /** The growth rate b. */
    rate: number;
    /** The initial value a — the predicted Y at x = 0. */
    initial: number;
    direction: "growth" | "decay" | "flat";
    /** Y is multiplied by this for each unit step in X: e^b. */
    perStepFactor:
// …truncated

Type shortened for readability — see the source for the full definition.

Intro

Sun, 08 Mar 2026 14:55:25 +1100

@statili is a collection of robust, type-safe statistical algorithms built in TypeScript, engineered for numerical stability and high-performance data visualization. Designed with a functional, data-last API and rich error handling, it provides the precise foundations for deriving actionable insights in modern web applications.