Transforms

A transform reshapes the data before it is charted: pivoting columns into rows, filtering, sorting, aggregating, or adding a constant column. Transforms run before mappings are read, so a mapping can reference a column a transform produced.

import { transform } from '@graphysdk/react';

pipe(
  createSpec(),
  transform.reshape({
    reshape: ['revenue', 'profit'],
    keyName: 'metric',
    valueName: 'amount',
  }),
  mapping({ x: 'month', y: 'amount', color: 'metric' }),
  geom.line(),
  scale.x(),
  scale.y(),
  scale.color.discrete()
);

Reshape: wide to long

The most common transform. Many datasets are wide, with one column per group:

{ month: 'Jan', revenue: 12000, profit: 3000 }

A mapping wants a long shape: one row per group, with a column naming the group to split on:

{ month: 'Jan', metric: 'revenue', amount: 12000 }
{ month: 'Jan', metric: 'profit',  amount: 3000 }

transform.reshape pivots wide to long so you can map the new column to color:

string[]

The numeric columns to collapse into rows. Defaults to all numeric columns.

string[]

Columns to carry through unchanged. Defaults to all categorical/temporal columns.

string

default:"key"

Name of the output column holding the original column names.

string

default:"value"

Name of the output column holding the values.

Other transforms

Transform	Purpose
`transform.filter({ variableName, operator, value })`	Keep only rows matching a comparison
`transform.sort({ variableName, direction })`	Order rows by a column
`transform.aggregate({ groupby, operations })`	Group and summarize (sum, mean, …) into new columns
`transform.constant({ variableName, type, value })`	Add a column with the same value on every row

transform.filter({ variableName: 'revenue', operator: 'gt', value: 0 });
transform.sort({ variableName: 'revenue', direction: 'desc' });
transform.aggregate({
  groupby: ['region'],
  operations: [{ op: 'sum', variableName: 'revenue', as: 'total' }],
});

operator is one of 'eq', 'neq', 'gt', 'gte', 'lt', 'lte'. neq belongs to this comparison vocabulary only: the highlight predicate language has no neq and writes the same idea as { not: … }. direction is 'asc' or 'desc', defaulting to 'asc'. op is one of 'count', 'sum', 'mean', 'median', 'mode', 'min', 'max'. The first four always produce a numeric output column; mode, min and max keep the source column’s type, which decides whether the result can be mapped to a continuous scale. transform.constant’s type is a DataType: 'numeric', 'categorical' or 'temporal'.

Custom transforms

A plugin can contribute its own transform: a TransformStrategy object with a transformType name and an apply(data, transform) that returns a new Dataset. It goes into plugins and gets a typed builder, kit.transform.<transformType>({ options? }); the options bag arrives on the transform argument of apply. See Extending for registration.

Spec-level vs layer-level

Piping a transform into the spec applies it to all layers. To reshape the data for a single geom, such as a line overlay that needs a different shape than the bars beneath it, pass transforms on that geom:

geom.line({
  transforms: [
    transform.aggregate({
      groupby: ['month'],
      operations: [{ op: 'sum', variableName: 'revenue', as: 'total' }],
    }),
  ],
  aes: { y: 'total' },
});

Statistics — per-layer summaries that run after transforms
Mappings & aesthetics — reference the columns a transform produces

Get Started

Core concepts

Chart types

Themes

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Reshape: wide to long

Other transforms

Custom transforms

Spec-level vs layer-level

Next

​Reshape: wide to long

​Other transforms

​Custom transforms

​Spec-level vs layer-level

​Next

Reshape: wide to long

Other transforms

Custom transforms

Spec-level vs layer-level

Next