Error Bars

createErrorBar() materializes vertical or horizontal intervals from either grouped statistics or existing center/lower/upper fields. It can infer its inputs from an already encoded layer or accept both channel roles directly.

At a glance

createErrorBar(options?)

const intervals = chart()
  .createCanvas()
  .createData({ values })
  .createErrorBar({
    x: { field: "group", fieldType: "nominal" },
    y: { field: "value" }
  });

createErrorBar({
  id?: string;
  target?: string;
  data?: string;
  x?: PositionChannel | StatisticalIntervalChannel | ExplicitIntervalChannel;
  y?: PositionChannel | StatisticalIntervalChannel | ExplicitIntervalChannel;
  groupBy?: string;
  coordinate?: string;
  caps?: boolean;
  capSize?: number;
  stroke?: string;
  strokeWidth?: number;
  strokeDash?: "solid" | "dashed" | "dotted" | "dashdot" | readonly number[];
  opacity?: number;
} = {})

The channel types are:

type PositionChannel = {
  field?: string;
  fieldType?: "nominal" | "ordinal" | "temporal";
  scale?: ScaleOptions;
};

type StatisticalIntervalChannel = {
  field?: string;
  center?: "mean" | "median";
  extent?: "stderr" | "stdev" | "ci" | "iqr";
  level?: number;
  scale?: ScaleOptions;
};

type ExplicitIntervalChannel = {
  center: string;
  lower: string;
  upper: string;
  scale?: ScaleOptions;
};

Exactly one channel is positional and the other is quantitative. Putting the interval on y creates vertical rules; putting it on x creates horizontal rules. No orientation flag is required. Statistical mean defaults to a two-sided 0.95 Student-t confidence interval. Median is supported only with extent: "iqr"; level is valid only for extent: "ci".

The independent position field is always part of statistical grouping. groupBy can add one more grouping field. Group order follows first appearance in the source data. Groups without enough valid quantitative values are omitted.

Horizontal intervals

const horizontal = chart()
  .createCanvas()
  .createData({ values })
  .createErrorBar({
    x: { field: "measurement" },
    y: { field: "group", fieldType: "nominal" }
  });

This stores y/x/x2 encodings and creates vertical fixed-pixel caps.

Existing interval fields

const explicit = chart()
  .createCanvas()
  .createData({ values: intervalRows })
  .createErrorBar({
    x: { field: "group", fieldType: "nominal" },
    y: {
      center: "meanValue",
      lower: "lowerValue",
      upper: "upperValue"
    },
    caps: false
  })
  .createGuides();

Explicit mode does not derive another dataset and does not accept groupBy, field, extent, or level on the interval channel. The center field becomes the interval-axis title unless a later guide action supplies another title.

Inference from an encoded layer

const overlay = chart()
  .createCanvas()
  .createData({ values })
  .createPointMark()
  .encodeX({ field: "group", fieldType: "ordinal" })
  .encodeY({ field: "value" })
  .createErrorBar();

With omitted x and y, target selects an existing layer. Without target, the action uses the current eligible layer, then one unique eligible layer. The layer may use any compatible mark type; eligibility comes from its complete field-based x/y encodings. Data, coordinate, and x/y scale IDs are reused. Passing only an existing scale id also preserves that scale’s stored domain, range, nice, and zero policy; interval defaults are used only for new scales.

A semantic group encoding is inferred as statistical grouping. Color remains appearance and does not silently change the statistic. Ambiguous eligible layers fail instead of selecting one arbitrarily.

Defaults and graphical result

Caps preserve their logical-pixel width when the Canvas or positional scales change. createGuides() infers the independent field title and a statistical interval-axis title such as mean(value).

Set caps: false to omit cap layers. capSize must be positive and affects enabled caps only. strokeWidth is non-negative, opacity is between 0 and 1, and strokeDash accepts a named style or an explicit non-negative dash array. The same appearance is assigned to the main rule and both caps.

const styled = intervals.createErrorBar({
  id: "styledErrorBar",
  data: "data",
  x: { field: "group", fieldType: "nominal", scale: { id: "styledX" } },
  y: { field: "value", scale: { id: "styledY" } },
  capSize: 16,
  stroke: "#d9485f",
  strokeWidth: 3,
  strokeDash: [8, 4],
  opacity: 0.8
});

Editing error bars

Use the stable error-bar owner instead of editing generated cap layers:

const edited = intervals.editErrorBar({
  caps: true,
  capSize: 16,
  stroke: "#d9485f",
  strokeWidth: 3,
  strokeDash: [8, 4],
  opacity: 0.8
});

The options are target, caps, capSize, stroke, strokeWidth, strokeDash, and opacity. Omitted values retain their current setting. Omit target when the current or unique error bar is unambiguous.

caps: false removes both owned cap resources. A later caps: true recreates them from the owner’s stored data, fields, coordinate, and scales. The main interval and its immutable statistical or explicit dataset remain unchanged. The complete request is validated before the wrapped rematerialization runs.

Errors and current limitations

The action rejects missing data, incompatible or ambiguous source layers, ambiguous channel roles, incomplete or non-quantitative explicit fields, invalid statistics or appearance values, and occupied generated IDs. Failed calls leave the earlier immutable program unchanged.

Center symbols, per-row cap sizes, field-driven rule widths, and statistical parameter revision are not part of the current edit action.

Related

Error-bar tutorial · Interval data · Rule marks · Guides