ggaction 0.0.5

Source and Derived Data

Cars scatterplot of horsepower and fuel economy
Quantitative positions with nominal color.

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
"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
"interval" { type, field, groupBy, center, extent, level?, as } createIntervalData
"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.

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. Multiple public transforms may be recorded in the ordered array, but built-in value materializers each require the single transform owned by their corresponding higher-level action.

Data overview · Chart API · Action reference