Data format specifications and requirements

Data Format Specifications and Requirements

ECharts, as a powerful data visualization library, has strict requirements for data formats. Correct data formats ensure proper chart rendering, while incorrect formats may cause charts to fail to display or display abnormally. The standardization of data formats is closely related to chart types, with different chart types having varying requirements for data structure, field naming, value types, etc.

Basic Data Structures

ECharts supports two basic data structures: arrays and objects. Arrays are suitable for simple datasets, while objects are suitable for complex data structures. For example, line charts commonly use array formats:

// Simple array format
const data = [10, 20, 30, 40, 50];

// Array of objects format
const data = [
  { value: 10, name: 'A' },
  { value: 20, name: 'B' },
  { value: 30, name: 'C' }
];

Object formats are typically used for data containing additional properties:

const data = {
  categories: ['A', 'B', 'C'],
  values: [10, 20, 30],
  units: 'kg'
};

Common Chart Data Formats

Line Chart/Bar Chart

Line charts and bar charts typically require x-axis and y-axis data. ECharts supports two formats:

// Format 1: Separate xAxis and series data
option = {
  xAxis: {
    data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri']
  },
  series: [{
    data: [120, 200, 150, 80, 70]
  }]
};

// Format 2: Dataset form
option = {
  dataset: {
    source: [
      ['product', 'sales'],
      ['Mon', 120],
      ['Tue', 200],
      ['Wed', 150]
    ]
  }
};

Pie Chart/Doughnut Chart

Pie charts require name-value pair data formats:

option = {
  series: [{
    type: 'pie',
    data: [
      { value: 335, name: 'Direct Access' },
      { value: 310, name: 'Email Marketing' },
      { value: 234, name: 'Affiliate Advertising' }
    ]
  }]
};

Scatter Plot

Scatter plots require two-dimensional or three-dimensional coordinate data:

option = {
  xAxis: {},
  yAxis: {},
  series: [{
    type: 'scatter',
    data: [
      [10, 5],
      [0, 8],
      [6, 10]
    ]
  }]
};

// 3D scatter plot
option = {
  grid3D: {},
  xAxis3D: {},
  yAxis3D: {},
  zAxis3D: {},
  series: [{
    type: 'scatter3D',
    data: [
      [10, 5, 3],
      [0, 8, 1],
      [6, 10, 5]
    ]
  }]
};

Using Dataset

ECharts 4.0+ recommends using datasets to manage data, which offers more flexibility and facilitates data reuse:

option = {
  dataset: {
    // 2D array form
    source: [
      ['product', '2015', '2016', '2017'],
      ['Matcha Latte', 43.3, 85.8, 93.7],
      ['Milk Tea', 83.1, 73.4, 55.1]
    ]
  },
  xAxis: { type: 'category' },
  yAxis: {},
  series: [
    { type: 'bar' },
    { type: 'bar' },
    { type: 'bar' }
  ]
};

Datasets also support object array formats:

option = {
  dataset: {
    dimensions: ['product', '2015', '2016', '2017'],
    source: [
      { product: 'Matcha Latte', '2015': 43.3, '2016': 85.8, '2017': 93.7 },
      { product: 'Milk Tea', '2015': 83.1, '2016': 73.4, '2017': 55.1 }
    ]
  }
};

Special Data Format Requirements

Tree Data

Tree charts require a specific hierarchical structure:

option = {
  series: [{
    type: 'tree',
    data: [{
      name: 'Node A',
      children: [{
        name: 'Node A1',
        children: [{ name: 'Node A11' }]
      }]
    }]
  }]
};

Graph Data

Graphs require two arrays: nodes and links:

option = {
  series: [{
    type: 'graph',
    data: [{
      name: 'Node 1',
      category: 0
    }, {
      name: 'Node 2',
      category: 1
    }],
    links: [{
      source: 'Node 1',
      target: 'Node 2'
    }]
  }]
};

Data Transformation

ECharts provides transform functionality for data processing:

option = {
  dataset: [{
    source: [
      ['Product', 'Sales', 'Price', 'Year'],
      ['Cake', 123, 32, 2011],
      ['Cereal', 231, 14, 2011]
    ]
  }, {
    transform: {
      type: 'filter',
      config: { dimension: 'Year', value: 2011 }
    }
  }],
  series: {
    type: 'pie',
    datasetIndex: 1
  }
};

Large Data Optimization

For handling large datasets, the following formats can optimize performance:

// Use flat arrays instead of object arrays
const largeData = new Float64Array(1000000);
for (let i = 0; i < largeData.length; i++) {
  largeData[i] = Math.random() * 100;
}

option = {
  series: [{
    type: 'line',
    data: largeData
  }]
};

Asynchronous Data Loading

ECharts supports asynchronous data loading in common formats:

// Using Promise
fetch('data.json')
  .then(response => response.json())
  .then(data => {
    myChart.setOption({
      series: [{
        type: 'line',
        data: data.values
      }]
    });
  });

// Using callback function
$.get('data.json', function(data) {
  myChart.setOption({
    dataset: {
      source: data
    }
  });
});

Data Error Handling

When data formats do not meet requirements, ECharts will throw warnings or errors. Common issues include:

1. Missing required fields in data items
2. Incorrect value types (e.g., strings instead of numbers)
3. Data structures not matching chart type requirements
4. Mismatched data dimensions

// Error example: Pie chart data missing name field
option = {
  series: [{
    type: 'pie',
    data: [
      { value: 335 },  // Missing name field
      { value: 310, name: 'Email Marketing' }
    ]
  }]
};

Custom Data Parsing

For special data formats, field mapping can be specified via the encode property:

option = {
  dataset: {
    source: [
      { month: 'Jan', temperature: 2.3, rainfall: 45 },
      { month: 'Feb', temperature: 4.5, rainfall: 30 }
    ]
  },
  series: [{
    type: 'line',
    encode: {
      x: 'month',  // Specify x-axis data field
      y: 'temperature'  // Specify y-axis data field
    }
  }]
};

Time Data Processing

Special attention is required for time data formats:

option = {
  xAxis: {
    type: 'time',
    data: [
      '2023-01-01',
      '2023-01-02',
      '2023-01-03'
    ]
  },
  series: [{
    data: [
      ['2023-01-01', 100],
      ['2023-01-02', 200],
      ['2023-01-03', 150]
    ]
  }]
};

// Or using timestamps
option = {
  xAxis: {
    type: 'time'
  },
  series: [{
    data: [
      [1672531200000, 100],  // 2023-01-01
      [1672617600000, 200]   // 2023-01-02
    ]
  }]
};

Multidimensional Data Analysis

ECharts supports multidimensional data analysis via the dataset's dimensions property:

option = {
  dataset: {
    dimensions: ['date', 'open', 'close', 'highest', 'lowest'],
    source: [
      ['2023-01-01', 120, 220, 240, 110],
      ['2023-01-02', 150, 250, 270, 130]
    ]
  },
  series: [{
    type: 'candlestick',
    encode: {
      x: 'date',
      y: ['open', 'close', 'lowest', 'highest']
    }
  }]
};

Geographic Data Formats

Map data has special format requirements:

// GeoJSON format
option = {
  series: [{
    type: 'map',
    data: [
      { name: 'Beijing', value: 100 },
      { name: 'Shanghai', value: 200 }
    ],
    geoJSON: geoJsonData  // Externally loaded GeoJSON data
  }]
};

// Simple format
option = {
  series: [{
    type: 'map',
    map: 'china',
    data: [
      { name: 'Guangdong', value: 500 },
      { name: 'Zhejiang', value: 300 }
    ]
  }]
};

Dynamic Data Updates

ECharts supports dynamic data updates but requires consistent data structures:

// Initial data
option = {
  series: [{
    type: 'line',
    data: [10, 20, 30]
  }]
};

// Update data
setInterval(() => {
  const newData = option.series[0].data.map(v => v + Math.random() * 10 - 5);
  myChart.setOption({
    series: [{
      data: newData
    }]
  });
}, 1000);