Source and Derived Data
createData({ id?, values })
| Option | Type | Required |
|---|---|---|
id |
string containing letters, numbers, _, or - |
no; first dataset defaults to "data" |
values |
array of plain row objects | yes |
const program = chart().createData({
values: [
{ horsepower: 130, mpg: 18 },
{ horsepower: 165, mpg: 15 }
]
});
Empty arrays are valid, and row properties may contain nested arrays or
objects. The action copies and freezes the supplied data. A dataset ID cannot
be created twice, and source values cannot be replaced after creation. The
first omitted ID is stored as "data". Once any dataset exists, another
createData call must provide an explicit ID; the library does not invent
data2-style names.
The most recently created dataset becomes the default for createPointMark,
createLineMark, or createBarMark. Creating data records semantic state only
and produces no graphics.
createDerivedData({ id, source, transform })
createDerivedData is the advanced provenance-assembly action behind the
higher-level data actions. transform must be a one-element array containing
one supported transform object; a bare object, an empty array, or a transform
pipeline is not accepted.
import { chart } from "ggaction";
const program = chart()
.createData({
id: "source",
values: [{ group: "A" }, { group: "B" }]
})
.createDerivedData({
id: "selected",
source: "source",
transform: [
{ type: "filter", field: "group", oneOf: ["A"] }
]
});
console.log(program.semanticSpec.datasets[1].transform[0].type);
// "filter"
The action stores the source ID and immutable transform provenance. It does
not compute or store values, and it does not create graphics. Prefer the
corresponding higher-level action when the library should materialize values:
type |
Public transform shape | Value-producing action |
|---|---|---|
"bin2d" |
{ type, x, y, bins, extent, includeEmpty, members, as, resolved? } |
createBin2DData |
"filter" |
{ type, field, oneOf }, { type, field, predicate }, or { type, field, range } |
filterData |
"regression" |
{ type, method, x, y, groupBy?, ...methodParameters } |
createRegressionData |
"density" |
{ type, field, groupBy?, bandwidth, extent, steps, kernel?, normalization?, as, resolve: "shared", resolved? } |
createDensityData |
"horizon" |
{ type, x, y, groupBy?, bands, baseline, extent, resolve, missing, overflow, palette, ... } |
encodeHorizon |
"interval" |
{ type, field, groupBy, center, extent, level?, as } |
createIntervalData |
"timeUnit" |
{ type, field, unit, as } |
createTimeUnitData |
"window" |
{ type, partitionBy, sortBy, operations } |
createWindowData |
For regression, linear and polynomial transforms require confidence and
interval; polynomial also requires degree. LOESS requires span and does
not accept interval properties. Density as is a two-field tuple. Interval
as contains distinct center, lower, and upper field names; mean CI
requires level, while median pairs only with IQR. Window transforms require
normalized arrays for partitionBy, sortBy, and operations; use
createWindowData to apply defaults and materialize rows. A materialized density
revision adds resolved: { bandwidth, extent } without replacing requested
"auto" values. See the higher-level action
sections below for accepted values and defaults before constructing normalized
provenance directly. Time-unit transforms use the same UTC interpretation as
temporal scales and store a finite bucket-start timestamp; use
createTimeUnitData to validate source fields and materialize rows.
DatasetTransform and CreateDerivedDataOptions export the same public union
for TypeScript. Internal transforms generated by composite actions, including
box-plot and final-mark filtering provenance, are intentionally not part of
this direct-authoring union. The public tuple contains exactly one transform;
multi-transform pipelines are rejected. Built-in value materializers each own
and normalize that single transform.