Published-release documentation · release compatibility

Series Encodings

At a glance

Series appearance is authored through color, stroke color, stroke dash, stroke width, and opacity. Each focused page owns the complete options, replacement behavior, and errors for that encoding.

Independent series identity

For a line with positions already assigned, this fragment creates four country paths even when the countries share just two continent colors:

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

program
  .encodeGroup({ field: "country" })
  .encodeColor({ field: "continent" });

Use encodeGroup({ fields: ["country", "scenario"] }) for one path per tuple. Then color can represent continent and dash can represent scenario. Group fields must be unique, non-empty names with nominal scalar values. { fields: ["country"] } normalizes to { field: "country" }; providing both forms is an error.

Appearance fields must have one raw value per complete series. Different values that happen to map to the same color still fail. Width and opacity never infer a group. Removing explicit grouping restores Line’s color/dash grouping and fails if the remaining appearance would be ambiguous. Ordinary ranged Areas support the same explicit identity; statistical and stacked-layout groups keep their existing owner restrictions.

The runnable series tutorial uses one shared program for country colors, tuple color/dash, and field width/opacity.

Explicit path topology

Contextual fragment. Use an ES module with the imports, data, and prepared resource state described in this section. Caller-provided receivers: program. Resolve these names from setup in this fragment or section; alternatives branch from the same base.

const ordered = program.encodePathOrder({
  field: "year",
  order: "ascending"
});

const automatic = ordered.removePathOrder();

encodePathOrder supports direct Cartesian quantitative/temporal lines and ordinary ranged areas backed by raw or row-preserving data. It sorts each color/group/stroke-dash series independently, keeps repeated positions, and uses source-row order to break ties. The field is quantitative, order is "ascending" or "descending", and neither action creates a scale or guide.

Aggregate lines, Polar lines, and generated density, error, or regression paths own their topology elsewhere and are rejected. Missing or non-finite order values reject the complete action instead of producing a partial path.

Focused series families

Parallel coordinates use one atomic ordered-dimension assignment rather than separate x/y calls. See Parallel Coordinates for dimension scales, row identity, missing policies, and lifecycle behavior.

Errors and limitations

Explicit group fields must be nominal. Color and stroke-dash fields may be nominal or ordinal. Without an explicit Line group, color and field-driven dash must use the same field. Explicit identity allows different appearance fields when each is unique within the series. Center/stack/fill Area retains matching single-field color/group ownership. Combined line legends also require matching ordered domains. Cartesian line and rule dash scales accept an explicit unknown style for valid categories outside a domain, preserving raw series and legend membership. Missing or malformed categories remain errors. See Stroke dash. Stroke width is quantitative and independent of point size. A line series must have exactly one width value across all contributing rows; segment-local and tapered widths are unsupported.

Related

Scale options · Legends · Position encodings