Chart Analysis API

The Analysis guide explains when to use each tool, its calculation method and limitations. These APIs belong to @revolist/charts; Pivot consumes the same contracts and native renderer.

Imports

import {
  resolveChartAnalysis,
  resolveCalculatedReferences,
  createParetoPreset,
  getChartFacetDimensions,
  chartDimensionFieldId,
  type ChartAnalysis,
  type ChartAnalysisResolution,
  type ChartCalculatedReference,
  type ChartFacets,
  type ChartBullet,
  type ChartParetoOptions,
  type ChartUnderlyingRecordsProvider,
} from '@revolist/charts/core';

The same exports are available from @revolist/charts. Per-type factories accept shared settings while retaining their fixed chart type. Use a multi-definition factory to switch between registered chart types.

Shared settings

Setting	Contract	Behavior
analysis	ChartAnalysis	Moving averages, regressions, calendar comparisons and linear forecasts.
annotations.calculated	ChartCalculatedReference[]	Mean, median, percentile lines and population-deviation bands.
facets	ChartFacets	Dimension-based line/bar/column/area panels and paging on smallMultiples.
bullet	ChartBullet	Qualitative performance ranges, authored bounds and target variance.
axes.x.interval	'day' | 'week' | 'month' | 'quarter' | 'year'	Minimum UTC tick cadence on time axes; cadence for explicit missing-period gaps.
axes.x.missingPeriods	'gap' | 'connect'	Gap or connect absent periods; gap requires an interval. Explicit nulls always break paths.
underlyingRecords	ChartUnderlyingRecordsProvider	Runtime-only source-record loader for the shared paginated view.

Settings are accepted at creation and through chart.update. Structured settings replace whole objects, so spread fields you want to preserve. Undefined preserves the current field during updates. Empty analysis: {}, facets: {} and bullet: {} clear those settings; annotations: {} clears all annotations. Invalid updates retain the previously accepted model and rendering.

Analytical overlays

Every overlay has a unique id, source seriesId, and optional label/color. At most 32 overlays are allowed across the arrays in analysis.

Array	Additional configuration
movingAverages	window from 2 to 1000, optional minPeriods from 1 to window. Trailing source-position window; finite values only.
regressions	Optional showConfidence, confidence and xSeriesId. Confidence is 0.9, 0.95 or 0.99.
periodComparisons	unit: 'week' | 'month' | 'quarter' | 'year', optional offset, partialPeriod: 'include' | 'exclude', asOf UTC epoch.
forecasts	Calendar unit: 'day' | 'week' | 'month' | 'quarter' | 'year', horizon from 1 to 120, optional confidence. Requires time X.

const result: ChartAnalysisResolution = resolveChartAnalysis(
  dataset,
  analysis,
  axes,
  { bindings, chartType: 'line' },
);

The pure resolver returns separate overlays, statuses, points, value domains and an optional future time domain. Regression diagnostics include sample count, degrees of freedom, slope/intercept, R², RMSE and residual standard error. Comparison points expose the matched reference category, difference, percentage change and partial-period flag. Forecast points have no source category index. Source rows and IDs are not rewritten. See the guide for supported families and statistical assumptions.

Calculated references

const reference: ChartCalculatedReference = {
  id: 'p90', seriesId: 'revenue', statistic: 'percentile', percentile: 90,
  scope: 'visible', label: '90th percentile',
};

The mean is an unweighted mean of the accepted chart cells, which may already be Pivot aggregates; it is not implicitly a raw-record weighted average. Statistics are mean, median, percentile and standardDeviation. percentile uses a percentage from 0 to 100. deviations controls the standard-deviation band multiplier and defaults to 1. Scopes are all, visible and selected; omitted scope means all. Optional axis is primary or secondary; otherwise the reference follows its source series assignment. An unavailable secondary plot, unknown series or nonfinite computed band rejects. IDs must be unique across references, notes and shapes.

resolveCalculatedReferences(renderInput) returns effective numeric references for a validated chart render input. Authored calculations remain in the model; the resolved numbers are transient.

Facets and grouped distributions

const facets: ChartFacets = {
  dimension: 'dimension:column:region',
  type: 'column', scaleMode: 'shared', pageSize: 6, page: 0,
};
const dimensions = getChartFacetDimensions(dataset);

Use the actual discovered field IDs. Facets require provider-owned dimension metadata and complete matrix-cell mappings. Without dimension, each measure gets a panel. Page is zero-based, page size is bounded from 1 to 100, and actual capacity also depends on the host. The shared controls keep later panels reachable. Grouped box plots use multiple genuine distribution series; no new chart type or synthetic samples are required.

Bullet configuration

ChartBullet supports finite minimum/maximum, ascending ranges: { to, label?, color? }[], showVariance and varianceFormat: 'absolute' | 'percent'. At most 20 qualitative ranges are allowed. This complements the bullet chart’s existing actual and target bindings. Zero targets have no defined percentage variance.

Pareto

const preset = createParetoPreset(dataset, {
  seriesId: 'revenue', threshold: 80, limit: 10,
});
// await createChart({ container, ...preset });

ChartParetoOptions also accepts othersLabel, cumulativeLabel and thresholdLabel. The preset returns a derived dataset plus combination-chart axes, series assignments and threshold annotations. Contributions must be nonnegative with a positive total. The full denominator includes Others. Cumulative share and synthetic Others are inspection-only.

Pivot integration

PivotChartCreateParams, PivotChartUpdatePatch and saved Pivot models accept analysis, facets, bullet, annotations.calculated and time-axis policies. Call charts.getChartData(...) to obtain source dataset/series IDs. A PivotChartRef has no getDataset() method.

charts.createParetoChart({ container, pareto, ...settings }) creates an unlinked analytical snapshot. charts.createChart({ ..., underlyingRecords: true }) enables native source-record access for a current linked chart without an independent query. A custom provider handles other scopes. Reattach providers through creation or restore options; callbacks are never saved.

Native renderers advertise capabilities.analysis and capabilities.underlyingRecords; unsupported backends reject those opt-ins. These flags are separate from type-specific geometry and data requirements. For the provider contract, see Underlying records.