data$

The API data$ is one of the essential APIs for drawing charts, used to add the data required for drawing charts.

The syntax for creating data is the same for chart objects of 6 data formats, but the data formats are different. The explanation will be longer, so the following will introduce each category separately. Readers can also refer to their own needs.

TIP

The example JSON data in this section can be directly copied and pasted into the Playground page, and the results can be displayed immediately by modifying the data directly on it.

Syntax

The syntax for creating data is chart.data$.next(Data)

Example:

chart.data$.next([
  [80,120,45],
  [50,30,15,28],
  [55,13,38,10,5]
])

Series

• Type: (DataSeriesDatum | DataSeriesValue)[][] | (DataSeriesDatum | DataSeriesValue)[]

Detailed Type

type DataSeriesValue = number | null

interface DataSeriesDatum {
  id?: string
  label?: string
  data?: any
  value: number | null
}

• Description:

The format of Series is a two-dimensional array of data, and the second-dimensional array data is called "Series Data".

For example, the following example has two sets of series data:

[ 
  [ 65, 70, 50, 12, 50 ],
  [ 35, 40, 15, 65 ]
]

In some cases, there is only one piece of data in the "Series Data". In this case, it can be written as a number[] or directly as a number. For example, the original format is:

[ 
  [55],
  [80],
  [50],
  [11],
  [150]
]

It can be equivalent to this format, which is a convenient shorthand, but in OrbCharts, we still consider it as five sets of series data (five colors of graphics will be drawn).

[ 55, 80, 50, 11, 150 ]

The two formats can be mixed together:

[ 
  35,
  [ 65, 70, 50, 12, 50 ],
  [ 35, 40, 15, 65 ]
]

Each individual data can be a number or an {} object, mainly for two purposes:

• label is used to label the data, which can be displayed on specific Plugins.
• data can contain more custom data, used for extracting related data in event$ events.

[
  [
    {
      label: 'Taipei',
      value: 50000
    },
    {
      label: 'Taichung',
      value: 40000
    },
    {
      label: 'Kaohsiung',
      value: 30000
    }
  ]
]

Grid

• Type: (DataGridDatum | DataGridValue)[][]

Detailed Type

type DataGridValue = number | null

interface DataGridDatum {
  id?: string
  label?: string
  data?: any
  value: number | null
}

• Description:

The data of Grid is a two-dimensional array of data:

[
  [ 55, 80, 50, 11 ],
  [ 35, 40, 15, 65 ]
]

In the Grid data format, there is a concept of "columns" and "rows". We arrange the data into a matrix shape, which can be converted into the following hypothetical format. In this data set, we can say it has two rows and four columns:

     Col1  Col2  Col3  Col4
Row1 | 55 | 80 | 50 | 11 
Row2 | 35 | 40 | 15 | 65 

In the default settings, "rows" are also equivalent to "series data" (series), and "columns" are also called "group data" (group). Understanding this concept is not necessary, but it will be used in some advanced usages when other APIs such as chartParams$ and dataFormatter$ perform further operations on the data.

TIP

Examples of operating series and group in other APIs:

1. The highlightTarget of chartParams$ can set the highlight target to series or group, etc.
2. The seriesDirection in dataFormatter$ can set "rows" or "columns" as series, and the other will be group. The main purpose is to control the mapping rules of drawing through the setting of seriesDirection.

The Grid format has a rule that the length of the array data in each column and each row must be consistent. If there is no data (also presented in the drawing), null values need to be added:

[
  [ 55, 80, 50, 11 ],
  [ 35, 40, 15, null ]
]

Each individual data can be a number or an {} object, mainly for two purposes:

• label is used to label the data, which can be displayed on specific Plugins.
• data can contain more custom data, used for extracting related data in event$ events.

[
  [
    {
      label: 'Import-Q1',
      value: 55
    },
    {
      label: 'Import-Q2',
      value: 80
    },
    {
      label: 'Import-Q3',
      value: 50
    },
    {
      label: 'Import-Q4',
      value: 11
    }
  ],
  [
    {
      label: 'Export-Q1',
      value: 35
    },
    {
      label: 'Export-Q2',
      value: 40
    },
    {
      label: 'Export-Q3',
      value: 15
    },
    {
      label: 'Export-Q4',
      value: 65
    }
  ],
]

MultiGrid

• Type: DataGrid[]

Detailed Type

type DataGrid = (DataGridDatum | DataGridValue)[][]

type DataGridValue = number | null

interface DataGridDatum {
  id?: string
  label?: string
  data?: any
  value: number | null
}

• Description:

The difference between MultiGrid and Grid is that MultiGrid has multiple sets of Grid data. From the data structure, it can be said that an additional array structure is added to the Grid structure:

[
  // First set of Grid data
  [
    [ 55, 80, 50, 11, 150 ],
    [ 35, 40, 15, 65, 120 ]
  ],
  // Second set of Grid data
  [
    [ 65, 70, 90, 110, 80 ],
    [ 25, 40, 25, 75, 90 ]
  ]
]

Other rules are the same as Grid, please refer to the previous section for explanation.

MultiValue

• Type: (DataMultiValueDatum | DataMultiValueValue[])[]

Detailed Type

type DataMultiValueValue = number

interface DataMultiValueDatum {
  id?: string
  label?: string
  data?: any
  categoryLabel?: string
  value: number[]
}

• Description:

The biggest feature of MultiValue is that each piece of data is a fixed-length array of data, and the length of this array is determined by the Plugin used (e.g., ScatterBubbles is designed as [x-coordinate, y-coordinate, value] - length 3).

For example:

[
  [ 25, 30, 15 ],
  [ 55, 60, 40 ],
  [ 45, 55, 30 ],
  [ 75, 35, 30 ],
  [ 65, 25, 5 ],
]

Each individual data can be a number or an {} object, mainly for:

• label is used to label the data, which can be displayed on specific Plugins.
• categoryLabel is used to label category data, which can correspond to colors and legend text.
• data can contain more custom data, used for extracting related data in event$ events.

Example:

[
  [ 10, 25, 5 ],
  [ 5, 10, 5 ],
  [ 30, 45, 20 ],
  [ 35, 40, 25 ],
  [ 25, 30, 15 ],
  [ 55, 60, 40 ],
  {
    value: [
      45,
      55,
      30
    ],
    categoryLabel: "category1"
  },
  {
    value: [
      75,
      35,
      30
    ],
    categoryLabel: "category2"
  },
  {
    value: [
      65,
      25,
      5
    ],
    categoryLabel: "category2"
  },
  [ 50, 65, 35 ],
  [ 20, 30, 15 ],
  [ 15, 25, 10 ],
  [ 70, 80, 60 ],
  [ 60, 70, 50 ],
  [ 55, 65, 45 ],
  [ 25, 35, 20 ]
]

Relationship

• Type: DataRelationshipObj | DataRelationshipList

Detailed Type

interface DataRelationshipObj {
  nodes: Node[]
  edges: Edge[]
}

// Array data
type DataRelationshipList = [
  Node[],
  Edge[]
]

interface Node extends DatumBase {
  id: string
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}

interface Edge extends DatumBase {
  id: string
  start: string
  end: string
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}

• Description:

There are two data structures that can be used, the first is the "object structure" and the second is the "array structure". In general, it is recommended to use the "object structure" directly:

// Object structure
{
  nodes: Node[]
  edges: Edge[]
}
// Array structure
[
  Node[],
  Edge[]
]

Required fields for Node:

• id is used for identifying data and must be unique.

Required fields for Edge:

• id is used for identifying data and must be unique.
• start is the id of the starting Node of the edge.
• end is the id of the ending Node of the edge.

Optional fields for Node and Edge:

• label is used to label the data, which can be displayed on specific Plugins.
• categoryLabel is used to label category data, which can correspond to colors and legend text.
• data can contain more custom data, used for extracting related data in event$ events.
• value is used to annotate quantity data, which can be displayed on specific Plugins.

Example:

{
  nodes: [
    {
      id: "id0",
      label: "label0",
      value: 19800000,
      categoryLabel: "category1"
    },
    {
      id: "id3",
      label: "label1",
      value: 5114269,
      categoryLabel: "category1"
    },
    {
      id: "id4",
      label: "label2",
      value: 1093200,
      categoryLabel: "category1"
    },
    {
      id: "id5",
      label: "label3",
      value: 32007217,
      categoryLabel: "category1"
    }
  ],
  edges: [
    {
      id: "id14",
      label: "label8",
      categoryLabel: "category2",
      start: "id5",
      end: "id0",
      value: 100
    },
    {
      id: "id15",
      label: "",
      categoryLabel: "category2",
      start: "id5",
      end: "id3",
      value: 100
    },
    {
      id: "id16",
      label: "",
      categoryLabel: "category2",
      start: "id5",
      end: "id4",
      value: 50
    }
  ]
}

Tree

• Type: DataTreeObj | DataTreeDatum[]

Detailed Type

// Tree structure
interface DataTreeObj {
  id: string
  children?: DataTreeObj[]
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}

// Array data
interface DataTreeDatum {
  id: string
  parent?: string
  label?: string
  data?: any
  categoryLabel?: string
  value?: number
}

• Description:

There are two data structures that can be used, the first is the "object structure" and the second is the "array structure". In general, it is recommended to use the "object structure" directly.

For example, the "object structure" (tree structure) has a characteristic that there is a starting data called the "root node", and each "root node" corresponds to multiple "child nodes".

Example of "object structure":

{
  id: 'root',
  value: 10,
  categoryLabel: 'Root Node',
  children: [
    {
      id: 'child1',
      value: 5,
      categoryLabel: 'Child Node 1',
    },
    {
      id: 'child2',
      value: 30,
      categoryLabel: 'Child Node 2',
      children: [
        {
          id: 'child3',
          value: 20,
          categoryLabel: 'Child Node 3'
        }
      ]
    }
  ]
}

The main difference between the "array structure" and the former is that the child nodes use the parent field to correspond to the unique parent node. Although both data structures are common (the "array structure" can also be converted to the same tree structure data after conversion), this writing method may cause problems in debugging, making it difficult to determine from the data whether a legal tree structure data can be calculated.

The following example of the "array structure" is the same as the previous one and can draw exactly the same graphics:

[
  {
    id: 'root',
    value: 10,
    categoryLabel: 'Root Node'
  },
  {
    id: 'child1',
    value: 5,
    categoryLabel: 'Child Node 1',
    parent: 'root'
  },
  {
    id: 'child2',
    value: 30,
    categoryLabel: 'Child Node 2',
    parent: 'root'
  },
  {
    id: 'child3',
    value: 20,
    categoryLabel: 'Child Node 3',
    parent: 'child2'
  }
]

Field description:

• id is used for identifying data and must be unique.

• value, categoryLabel, children, parent are optional fields.