Encoding

Encoding is OrbCharts' "field-mapping layer": it determines which field in RawData maps to which of the chart's data dimensions (dataset, series, category, value, etc.), and lets you rename fields, sort, and aggregate along the way. In other words, instead of rewriting your data to fit the chart, you use Encoding to map your existing data in.

Encoding is passed through the encoding option when creating a chart, and can also be adjusted later with chart.updateEncoding(). For the data's own format, see Data formats overview.

Encoding structure

interface Encoding {
  dataset:  { from: string; sort: 'original' | 'alphabetical' | string[]; ignore?: boolean }
  series:   { from: string; sort: 'original' | 'alphabetical' | string[]; ignore?: boolean }
  category: { from: string; sort: 'original' | 'alphabetical' | string[]; ignore?: boolean }
  value:    { from: string; sort: 'original' | 'asc' | 'desc'; aggregate: 'sum' | 'mean' | 'median' | 'min' | 'max' | 'count' | 'none' }
  multivariate: Array<{ from: string; name: string }>
  color:    { by: 'index' | 'series' | 'category' | 'dataset' }
}

Default values

• Each dimension's from defaults to the same name as the dimension (e.g. series.from defaults to 'series').
• Each dimension's sort defaults to 'original' (keep the original order).
• dataset/series/category's ignore defaults to false (not ignored, see Ignoring a dimension below).
• value.aggregate defaults to 'none' (no aggregation).
• multivariate defaults to [{ from: 'x', name: 'x' }, { from: 'y', name: 'y' }, { from: 'z', name: 'z' }].
• color.by defaults to 'series' (color by series).

Tip: Encoding is deep-merged. With updateEncoding, you only write the fields you want to change; every other dimension and setting keeps its default.

Renaming fields

When your data's field names differ from the defaults, point from at the actual field. For example, if your data uses amount instead of value:

import { OrbCharts } from '@orbcharts/core'
import type { RawData } from '@orbcharts/core'
 
const data: RawData = [
  { series: 'A', amount: 30 },
  { series: 'B', amount: 70 },
]
 
const chart = new OrbCharts(element, {
  data,
  encoding: {
    value: { from: 'amount' },
  },
})

Now the amount field is used as the value dimension.

Sorting

sort controls the ordering of a dimension:

chart.updateEncoding({
  category: { sort: 'alphabetical' },  // categories sorted alphabetically
  value:    { sort: 'desc' },          // values from high to low
})

• dataset / series / category accept 'original', 'alphabetical', or a custom-order string[].
• value accepts 'original', 'asc', 'desc'.

// Order series in a custom sequence
chart.updateEncoding({
  series: { sort: ['North', 'Central', 'South'] },
})

Aggregation

value.aggregate combines multiple values within the same group into a single value—useful when your raw data is fine-grained and needs rolling up:

chart.updateEncoding({
  value: { aggregate: 'sum' },  // sum values within each group
})

Available aggregations:

Ignoring a dimension

dataset, series, and category can each be set to ignore: true, meaning the corresponding raw field is never read during processing — every row is treated as belonging to the same group on that dimension.

Note: Setting ignore: true on its own does not merge any data — it only makes rows that used to be in different groups fall into the same group; each row still produces its own ModelData entry. It's value.aggregate that actually merges rows within a group into one. In other words, ignore decides "what counts as the same group," and aggregate decides "whether — and how — to merge rows within that group." You need both set together to get the "ignore a dimension, merge the data" effect.

A common scenario: the same series × category data should show every series × category combination separately in a bar chart, but sum across categories per series when switched to a pie chart:

// Bar chart: series × category shown independently (default behavior)
chart.updateEncoding({ value: { aggregate: 'none' } })
 
// Pie chart: ignore category, sum everything within each series into one row
chart.updateEncoding({
  category: { ignore: true },
  value: { aggregate: 'sum' },
})

For an ignored dimension, the corresponding field in the output ModelData (e.g. category/categoryIndex) will be an empty string / 0, meaning "not applicable."

Adjusting at runtime

chart.updateEncoding({ value: { from: 'amount' } })  // partial update (deep merge)
chart.getEncoding()                                   // get the current Encoding (read-only)
chart.forceReplaceEncoding(fullEncoding)              // fully replace

See updateEncoding / forceReplaceEncoding / getEncoding on the OrbCharts Class page.

Related

• Data formats overview — RawData fields and each dimension's format
• OrbCharts Class — updateEncoding and related methods