dataFormatter$

The dataFormatter$ API is a shared chart parameter setting for all plugins. Each data type chart object has its own parameter format, mainly used to set data mapping and filtering rules.
All parameters are optional. If this API is not used, all parameter settings are default values.

Syntax

The syntax for setting parameters is chart.dataFormatter$.next(DataFormatter)

Example:

chart.dataFormatter$.next([
  // Params
])

Series

Type: DataFormatterSeriesPartial

Fields:

Name	Description	Type
visibleFilter	Data filtering function	`(datum: ComputedDatumSeries, context: DataFormatterContext<'series'>) => boolean \| null`
sort	Sorting function	`((a: ComputedDatumSeries, b: ComputedDatumSeries) => number) \| null`
seriesLabels	Series labels	`string[]`
sumSeries	Merge data by series	`boolean`
container	Multi-chart container layout	`DataFormatterContainer`
separateSeries	Display separately by series (placed according to the layout set by the `container` field)	`boolean`
separateLabel	Display separately by label (placed according to the layout set by the `container` field)	`boolean`

Detailed Types

interface ComputedDatumSeries {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  value: number | null
  color: string
  seriesIndex: number
  seriesLabel: string
  seq: number
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

dataFormatter.container
Name Description Type
columnAmount Number of columns number
rowAmount Number of rows number
columnGap Gap of columns number
rowGap Gap of rows number
Default values:

Name	Description	Type
columnAmount	Number of columns	`number`
rowAmount	Number of rows	`number`
columnGap	Gap of columns	`number`
rowGap	Gap of rows	`number`

const DEFAULT_DATA_FORMATTER_SERIES: DataFormatterSeries = {
  type: 'series',
  visibleFilter: (datum, context) => true,
  sort: null,
  seriesLabels: [],
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  },
  separateSeries: false,
  separateLabel: false,
  sumSeries: false
}

Grid

Type: DataFormatterGridPartial

Fields:

Name	Description	Type
visibleFilter	Data filtering function	`(datum: ComputedDatumGrid, context: DataFormatterContext<'grid'>) => boolean \| null`
seriesDirection	Define whether the `data$` data's "row" or "column" is the series	`boolean`
rowLabels	Labels for the "rows" in the `data$` data	`boolean`
columnLabels	Labels for the "columns" in the `data$` data	`boolean`
valueAxis	Value axis (default is Y axis) settings	`DataFormatterValueAxis`
groupAxis	Group axis (default is X axis) settings	`DataFormatterGroupAxis`
container	Multi-chart container layout	`DataFormatterContainer`
separateSeries	Display separately by series (placed according to the layout set by the `container` field)	`boolean`

Detailed Types

interface ComputedDatumGrid {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  value: number | null
  color: string
  gridIndex: number
  seriesIndex: number
  seriesLabel: string
  groupIndex: number
  groupLabel: string
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

dataFormatter.valueAxis

Name	Description	Type
position	Position of the axis. Note that this field must be set perpendicular to the `position` set by `groupAxis` (e.g., if `groupAxis` is `bottom`, then `valueAxis` must be `left` or `right`)	`'top' \| 'bottom' \| 'left' \| 'right'`
scaleDomain	Range settings for the data's minimum and maximum values: [0] => `'min'`: minimum value, `'auto'`: take the minimum value, but if greater than 0, keep it as 0 [1] => `'max'`: maximum value, `'auto'`: take the maximum value, but if less than 0, keep it as 0	`[number \| 'min' \| 'auto', number \| 'max' \| 'auto']`
scaleRange	Range settings mapped to the axis (0 ~ 1)	`[number, number]`
label	Axis label	`string`

TIP

The parameter settings for the axis are relatively complex concepts. The scaleDomain and scaleRange fields need to be used together, which is the setting for mapping "data" => "axis".

General case (default value) - The data range is from 0 to the maximum value (automatically determines the positive and negative values of the data)

{
  scaleDomain: ['auto', 'auto'],
  scaleRange: [0, 0.9]
}

Display the area from the minimum to the maximum value. When you only want to display a specific data range on the chart, you can set it like this

{
  scaleDomain: ['min', 'max'],
  scaleRange: [0.1, 0.9]
}

Specify the range

{
  scaleDomain: [100, 300],
  scaleRange: [0.1, 0.9]
}

dataFormatter.groupAxis

Name	Description	Type
position	Position of the axis. Note that this field must be set perpendicular to the `position` set by `valueAxis` (e.g., if `groupAxis` is `bottom`, then `valueAxis` must be `left` or `right`)	`'top' \| 'bottom' \| 'left' \| 'right'`
scaleDomain	Range settings for the data's minimum and maximum values, using the Group data in the `data$` data (default is the "column" direction) as the unit	`[number, number \| 'max']`
scalePadding	Padding on both sides of the axis, in axis scale units	`number`
label	Axis label	`string`

dataFormatter.container
Name Description Type
columnAmount Number of columns number
rowAmount Number of rows number
columnGap Gap of columns number
rowGap Gap of rows number
Default values:

Name	Description	Type
columnAmount	Number of columns	`number`
rowAmount	Number of rows	`number`
columnGap	Gap of columns	`number`
rowGap	Gap of rows	`number`

const DEFAULT_DATA_FORMATTER_GRID: DataFormatterGrid = {
  type: 'grid',
  visibleFilter: (datum, context) => true,
  seriesDirection: 'row',
  rowLabels: [],
  columnLabels: [],
  valueAxis: { 
    position: 'left',
    scaleDomain: ['auto', 'auto'],
    scaleRange: [0, 0.9],
    label: '',
  },
  groupAxis: {
    position: 'bottom',
    scaleDomain: [0, 'max'],
    scalePadding: 0.5,
    label: ''
  },
  separateSeries: false,
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  }
}

MultiGrid

Type: DataFormatterMultiGridPartial

Fields:

Name	Description	Type
visibleFilter	Data filtering function	`(datum: ComputedDatumGrid, context: DataFormatterContext<'grid'>) => boolean \| null`
gridList	Settings for mapping data for each grid, with the same format as the DataFormatter for the `Grid` data type	`Array<DataFormatterGridGrid>`
container	Multi-chart container layout	`DataFormatterContainer`
separateGrid	Display separately by grid (placed according to the layout set by the `container` field)	`boolean`

dataFormatter.gridList[]

Name	Description	Type
seriesDirection	Define whether the `data$` data's "row" or "column" is the series	`boolean`
rowLabels	Labels for the "rows" in the `data$` data	`boolean`
columnLabels	Labels for the "columns" in the `data$` data	`boolean`
valueAxis	Value axis (default is Y axis) settings	`DataFormatterValueAxis`
groupAxis	Group axis (default is X axis) settings	`DataFormatterGroupAxis`
container	Multi-chart container layout	`DataFormatterContainer`
separateSeries	Display separately by series (placed according to the layout set by the `container` field)	`boolean`

TIP

The fields in gridList[] have the same format as the DataFormatter for the Grid data type, so the detailed field descriptions are not repeated.
When the number of arrays in gridList[] is inconsistent with the number of Grid data (arrays) in data$, gridList[0] (if not set, the default value) will be used as the main one.

dataFormatter.container
Name Description Type
columnAmount Number of columns number
rowAmount Number of rows number
columnGap Gap of columns number
rowGap Gap of rows number
Default values:

Name	Description	Type
columnAmount	Number of columns	`number`
rowAmount	Number of rows	`number`
columnGap	Gap of columns	`number`
rowGap	Gap of rows	`number`

const DEFAULT_DATA_FORMATTER_MULTI_GRID: DataFormatterMultiGrid = {
  type: 'multiGrid',
  visibleFilter: (datum, context) => true,
  gridList: [
    {
      seriesDirection: 'row',
      rowLabels: [],
      columnLabels: [],
      valueAxis: { 
        position: 'left',
        scaleDomain: ['auto', 'auto'],
        scaleRange: [0, 0.9],
        label: '',
      },
      groupAxis: {
        position: 'bottom',
        scaleDomain: [0, 'max'],
        scalePadding: 0.5,
        label: ''
      },
      separateSeries: false,
    },
  ],
  separateGrid: false,
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  }
}

MultiValue

Type: DataFormatterMultiValuePartial

Fields:

Name	Description	Type
visibleFilter	Data filtering function	`(datum: ComputedDatumMultiValue, context: DataFormatterContext<'multiValue'>) => boolean \| null`
categoryLabels	Category labels	`string[]`
xAxis	X axis settings	`DataFormatterAxis`
yAxis	Y axis settings	`DataFormatterAxis`
container	Multi-chart container layout	`DataFormatterContainer`
separateCategory	Display separately by category (placed according to the layout set by the `container` field)	`boolean`

Detailed Types

interface ComputedDatumMultiValue {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  datumIndex: number
  value: number[]
  color: string
  categoryIndex: number
  categoryLabel: string
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

dataFormatter.xAxis and dataFormatter.yAxis

Name	Description	Type
scaleDomain	Range settings for the data's minimum and maximum values: [0] => `'min'`: minimum value, `'auto'`: take the minimum value, but if greater than 0, keep it as 0 [1] => `'max'`: maximum value, `'auto'`: take the maximum value, but if less than 0, keep it as 0	`[number \| 'min' \| 'auto', number \| 'max' \| 'auto']`
scaleRange	Range settings mapped to the axis (0 ~ 1)	`[number, number]`
label	Axis label	`string`

TIP

The parameter settings for the axis are relatively complex concepts. The scaleDomain and scaleRange fields need to be used together, which is the setting for mapping "data" => "axis".

General case (default value) - The data range is from 0 to the maximum value (automatically determines the positive and negative values of the data)

{
  scaleDomain: ['auto', 'auto'],
  scaleRange: [0, 0.9]
}

Display the area from the minimum to the maximum value. When you only want to display a specific data range on the chart, you can set it like this

{
  scaleDomain: ['min', 'max'],
  scaleRange: [0.1, 0.9]
}

Specify the range

{
  scaleDomain: [100, 300],
  scaleRange: [0.1, 0.9]
}

dataFormatter.container
Name Description Type
columnAmount Number of columns number
rowAmount Number of rows number
columnGap Gap of columns number
rowGap Gap of rows number
Default values:

Name	Description	Type
columnAmount	Number of columns	`number`
rowAmount	Number of rows	`number`
columnGap	Gap of columns	`number`
rowGap	Gap of rows	`number`

const DEFAULT_DATA_FORMATTER_MULTI_VALUE: DataFormatterMultiValue = {
  type: 'multiValue',
  visibleFilter: (datum, context) => true,
  categoryLabels: [],
  xAxis: {
    scaleDomain: ['auto', 'auto'],
    scaleRange: [0, 0.9],
    label: '',
  },
  yAxis: {
    scaleDomain: ['auto', 'auto'],
    scaleRange: [0, 0.9],
    label: '',
  },
  container: {
    columnAmount: 1,
    rowAmount: 1,
    columnGap: 'auto',
    rowGap: 'auto'
  },
  separateCategory: false
}

Relationship

Type: DataFormatterRelationshipPartial
Fields:
Name Description Type
visibleFilter Data filtering function (datum: ComputedNode, context: DataFormatterContext<'relationship'>) => boolean | null
categoryLabels Category labels string[]

Name	Description	Type
visibleFilter	Data filtering function	`(datum: ComputedNode, context: DataFormatterContext<'relationship'>) => boolean \| null`
categoryLabels	Category labels	`string[]`

Detailed Types

interface ComputedNode {
  id: string
  index: number
  label: string
  visible: boolean
  data: any
  value: number | null
  color: string
  categoryIndex: number
  categoryLabel: string
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

Default values:

const DEFAULT_DATA_FORMATTER_RELATIONSHIP: DataFormatterRelationship = {
  type: 'relationship',
  visibleFilter: (datum, context) => true,
  categoryLabels: []
}

Tree

Type: DataFormatterTreePartial
Fields:
Name Description Type
visibleFilter Data filtering function (datum: ComputedDataTree, context: DataFormatterContext<'tree'>) => boolean | null
categoryLabels Category labels string[]

Name	Description	Type
visibleFilter	Data filtering function	`(datum: ComputedDataTree, context: DataFormatterContext<'tree'>) => boolean \| null`
categoryLabels	Category labels	`string[]`

Detailed Types

interface ComputedDataTree {
  level: number
  seq: number
  children?: ComputedDataTree[]
}

interface DataFormatterContext<T extends ChartType> {
  data: DataTypeMap<T>
  dataFormatter: DataFormatterTypeMap<T>
  chartParams: ChartParams
}

Default values:

const DEFAULT_DATA_FORMATTER_TREE: DataFormatterTree = {
  type: 'tree',
  visibleFilter: (datum, context) => true,
  categoryLabels: []
}