@statili/highcharts

Fitted series, uncertainty bands and accessible descriptions for Highcharts.

Also a drop-in replacement for highcharts-regression, which has been unchanged since October 2020 and ships no tests.

Install

npm install @statili/highcharts

Highcharts itself is a peer dependency. This package never imports it — it works purely off structural types, so it stays version-agnostic.

Usage

Add a fit to any series:

import { analyse } from "@statili/highcharts";

const { options, fits } = analyse({
  xAxis: { title: { text: "week" } },
  yAxis: { title: { text: "signups" } },
  series: [{
    type: "scatter",
    name: "Signups",
    data: [[1, 12], [2, 19], [3, 29], [4, 37]],
    fit: { method: "linear", showBand: true },
  }],
});

Highcharts.chart("container", options);

The fitted curve is drawn from the data the analysis produced — the chart never re-derives an equation. Methods: linear, polynomial, power, exponential, logarithmic and loess.

What you get beyond a trend line

An accessible description, built from the same numbers the chart draws, so prose and plot cannot drift apart:

options.accessibility.description;
// "Signups. Each additional unit of week is associated with an increase of 7.85
//  in signups. The slope of 7.85 is statistically significant (p = 8.7e-9…)"

Axis names come from your chart's own axis titles.

Structured facts you can act on programmatically:

fits[0].facts.map((f) => f.kind);
// ["trend.linear", "fit.significance", "fit.quality", "fit.error", "caveat.small-sample"]

fits[0].facts[0].claim;
// { direction: "rising", slope: 7.85, intercept: 4.55 }

Facts are JSON-serialisable and carry the provenance of every judgement. See @statili/forge.

Uncertainty bands via showBand, drawn as an arearange behind the fit. Requires Highcharts' highcharts-more module.

Replacing highcharts-regression

withRegression reads regression: true and regressionSettings exactly as the incumbent does:

import { withRegression } from "@statili/highcharts";

Highcharts.chart("container", withRegression(options).options);

Every documented option is supported. Several defects are fixed, two of which change what a migrated chart displays.

Full migration guide →

License

MIT