regression-js Compatibility on statili

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.

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.

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.