Cookbook — Uncertainty Visualization — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/cookbook/uncertainty-visualization

Uncertainty Visualization

Forecasts are only useful when they communicate how confident you are in the prediction. This recipe shows how to visualize a time series with a forecasted segment and a confidence interval cone, stitching together observed data and projected values in a single StreamXYFrame.

The Visualization

If you find yourself visualizing forecasts for time series data, the below example can help you communicate the forecast, as well as it's confidence interval

This example stitches together two separate lines - Actual (Observed) Values - Mean Forecast +3 Months with certainty values

... and uses the boundsAccessor prop to create the uncertainty cone, communicating the confidence interval

import { StreamXYFrame } from "semiotic" const frameProps = { /* --- Data --- */ data: [{ month: 1, pct: 100, lineGroup: "Curve A_actual", forecast: undefined }, { month: 2, pct: 30, lineGroup: "Curve A_actual", forecast: undefined }, ... ], chartType: "line", groupAccessor: "lineGroup", /* --- Size --- */ size: [700,400], margin: { left: 80, bottom: 50, right: 10, top: 40 }, /* --- Process --- */ xAccessor: "month", yAccessor: "pct", yExtent: [0,100], xExtent: [0,20], boundsAccessor: d => d.uncertainty || 0, /* --- Customize --- */ lineStyle: (d) => { const baseStyles = { stroke: "#E0488B", strokeWidth: 3 } if (!d.forecast) { return baseStyles } else if (d.forecast === "mean") { return { ...baseStyles, strokeDasharray: "5" } } else { return { stroke: "none", strokeWidth: 0 } } }, boundsStyle: { fill: "#E0488B", fillOpacity: 0.15, stroke: "none" }, title: "Uncertainty Visualization (Time Series)", showAxes: true, xLabel: "Months", yLabel: "Decay (%)", yFormat: (d12) => `${d12}%`, /* --- Interact --- */ enableHover: true, /* --- Annotate --- */ tooltipContent: d => { const datum = d.data || {} const isForecast = datum.forecast === "mean" return ( <div style={{ border: `thin solid ${"#E0488B"}`, backgroundColor: "var(--surface-1, #f8f9fa)", color: "var(--text-primary, #1a1a2e)", width: "100px", textAlign: "center", padding: "10px" }} > {isForecast && ( <div style={{ color: "#E0488B", fontWeight: "bold", marginBottom: "5px" }}> * mean forecast * </div> )} <div>{`Month: ${datum.month}`}</div> <div>{`Decay: ${datum.pct}%`}</div> </div> ) } } export default () => { return <StreamXYFrame {...frameProps} /> }

How It Works

The visualization is built from two line objects: one for observed values and one for the forecast. Each forecast data point includes anuncertainty value that widens over time. The forecast line is styled with a dashed stroke to visually distinguish it from actuals:

JSX

lineStyle: d => { let baseStyles = { stroke: theme[1], strokeWidth: "3px" } if (!d.forecast) { return baseStyles } else if (d.forecast === "mean") { return { ...baseStyles, strokeDasharray: "5px" } } else { return { strokeWidth: "0px" } } }

The confidence interval is created using thelinebounds summary type, which reads theuncertainty field from each data point to determine the width of the band:

JSX

summaryType: { type: "linebounds", boundingAccessor: d => d.uncertainty || 0 }, summaryDataAccessor: "data", summaryClass: "uncertainty_cone"

Key Takeaways

The linebounds summary type creates ribbon-like confidence intervals from a bounding accessor on each data point.
Multiple line objects with different styling (solid vs. dashed) can represent observed vs. forecasted segments.
Using defined to filter undefined points prevents rendering artifacts at segment boundaries.
Tooltips can inspect parentLine metadata to display context-aware information (e.g., "forecast" label).

StreamXYFrame — the underlying frame for line and summary rendering
LineChart — simpler line chart for time series
AreaChart — filled area visualizations