Highcharts on 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:

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.

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.

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.