transform.filter type property
The type property for a filter transform must be set to the string value 'filter'.
data-transforms
65 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
transform.filter config property
The config property on a filter transform contains the condition used to filter data. It accepts any value type (*).
filter transform overview
The transform.filter() method is a data transform component that allows filtering data based on specified conditions. It is configured with a type property set to 'filter' and a config property containing the filter condition.
datasetIndex option default and behavior
The datasetIndex option has a default value of 0. When series.data is not specified and dataset exists, datasetIndex specifies which dataset will be used by the series.
datasetId option type and behavior
The datasetId option accepts type string or number. When series.data is not specified and dataset exists, datasetId specifies which dataset will be used by matching the id of the dataset.
Series data default behavior with dataset
If no data is specified in series and dataset exists in the option, the series will use the first dataset as its datasource. If data has been specified in series, dataset will not be used.
transform.print property for debugging data transforms
The transform.print property is a boolean option that defaults to false and is only available in development environments. When set to true, it causes the result of a data transform to be printed to the browser console using console.log, which helps debug data transform configurations when the chart does not display correctly. The print property is applied as a configuration option within the transform object in the dataset configuration.
Example of using transform.print for debugging
```ts option = { dataset: [{ source: [ ... ] }, { transform: { type: 'filter', config: { ... } // The result of this transform will be printed // in dev tool via `console.log`. print: true } }], ... } ``` This example shows how to enable transform.print on a filter-type transform to output the transformation result to the console for debugging purposes.
Accessing y-axis value with encode in array-based dataset
When using an array-based dataset without explicit dimensions, access the y-axis value using params.value[params.encode.y[0]]. The encode.y array contains the dimension index for the y-axis coordinate.
Accessing y-axis value with dimensionNames in object-based dataset
When using an object-based dataset with explicit dimensions property, access the y-axis value using params.value[params.dimensionNames[params.encode.y[0]]]. The dimensionNames array maps dimension indices to their string names.
Data transform definition and purpose
Data transform in Apache ECharts generates new data from user-provided source data and transform functions using the formula outData = f(inputData). It enables users to process data in a declarative way. Common transform functions include filter, sort, regression, boxplot, and cluster. Data transform has been supported since Apache ECharts 5.
Dataset-based data transform configuration
Data transform is implemented based on the concept of dataset. A dataset.transform property can be configured in a dataset instance to indicate that the dataset should be generated from that transform. The dataset containing the transform function will use transformed data, while series reference these transformed datasets to display the result.
Dataset transform source specification
When configuring a dataset with a transform, optional properties fromDatasetIndex or fromDatasetId indicate where the input data of the transform comes from. If both fromDatasetIndex and fromDatasetId are omitted, fromDatasetIndex: 0 is used by default.
Piped transforms
Multiple transforms can be declared in an array to pipe them, making them execute one by one where the output of the previous transform becomes the input of the next transform. When transforms are piped, each transform (except the first) can only take one input and (except the last) produce one output.
Transform output multiple data
Transform functions can produce multiple output data using the dataset.fromTransformResult property. For example, boxplot transform produces both boxplot data (result[0]) and outlier data (result[1]). By default only result[0] is accessible when series reference the dataset. To access other results, create an additional dataset with fromDatasetIndex, fromTransformResult: n to retrieve result[n].
Transform.print debug property
The transform.print property is available in development environment only. When set to true, the result of the transform will be printed in the dev tool via console.log, helping debug data transform configurations.
Filter transform basic usage
The filter transform is a built-in transform that provides data filtering according to specified conditions. It traverses source data and retrieves all items matching the condition in config.
Filter transform dimension specification
In filter transform config, the dimension property can be either a dimension name declared in the dataset (like 'Year') or a dimension index starting from 0 (like 3). Dimension name declaration is optional.
Filter transform relational operators
Filter transform supports relational operators: > (gt), >= (gte), < (lt), <= (lte), = (eq), != (ne, <>), and reg (regular expression). Multiple operators can appear in one config item representing logical AND, such as { dimension: 'Price', '>=': 20, '<': 30 }.
Filter transform numeric string handling
Data values in filter transform can be numeric strings (strings convertible to numbers, like '123' with whitespace). White spaces and line breaks are automatically trimmed in the conversion process.
Filter transform time comparison
To compare JS Date instances or date strings (like '2012-05-12'), the parser: 'time' must be specified manually in the config. Example: { dimension: 3, lt: '2012-05-12', parser: 'time' }. The parser follows the same rule as echarts.time.parse.
Filter transform string comparison
Pure string comparison is supported only with = and != operators. The operators >, >=, <, <= do not support pure string comparison (their right values cannot be strings).
Filter transform regular expression operator
The reg operator can be used for regular expression testing. Example: { dimension: 'Name', reg: /\s+Müller\s*$/ } selects all data items where the Name dimension contains the family name Müller.
Filter transform logical operators
Logical operators and, or, and not can be used in filter transform config to express logical relationships. These can be nested. The not operator should be followed with a {...} rather than [...].
Filter transform parser options
Filter transform supports three parsers: parser: 'time' (parse to date time before comparing), parser: 'trim' (trim string before comparison, return original for non-string), parser: 'number' (force convert to number with loose strategy, useful for values with unit suffixes like '33%' or '12px').
Filter transform TypeScript definition
type FilterTransform = { type: 'filter'; config: ConditionalExpressionOption; }; type RelationalExpressionOption = { dimension: DimensionName | DimensionIndex; parser?: 'time' | 'trim' | 'number'; lt?: DataValue; lte?: DataValue; gt?: DataValue; gte?: DataValue; eq?: DataValue; ne?: DataValue; '<'?: DataValue; '<='?: DataValue; '>'?: DataValue; '>='?: DataValue; '='?: DataValue; '!='?: DataValue; '<>'?: DataValue; reg?: RegExp | string; }; type LogicalExpressionOption = { and?: ConditionalExpressionOption[]; or?: ConditionalExpressionOption[]; not?: ConditionalExpressionOption; };
Sort transform basic usage
The sort transform is a built-in transform that sorts data by one or more dimensions. Example: { type: 'sort', config: { dimension: 'score', order: 'asc' } }.
Sort transform multiple dimensions
Sort transform supports ordering by multiple dimensions. Pass an array of config objects: config: [{ dimension: 'profession', order: 'desc' }, { dimension: 'score', order: 'desc' }].
Sort transform numeric vs non-numeric ordering
By default numeric values (numbers and numeric-strings like ' 123 ') are sorted by numeric order. Non-numeric-strings are ordered among themselves. When numeric and non-numeric-string are compared, or either is compared with other types, they are incomparable and treated as min or max value according to the incomparable property.
Sort transform incomparable handling
The incomparable property in sort transform config can be 'min' or 'max', determining whether incomparable or empty values (null, undefined, NaN, '', '-') are placed at the head or tail of sorted results.
Sort transform parser options
Sort transform supports parser property with same options as filter: 'time' | 'trim' | 'number'. For time values use parser: 'time'. For values with unit suffix (like '33%', '16px') use parser: 'number'.
Sort transform TypeScript definition
type SortTransform = { type: 'filter'; config: OrderExpression | OrderExpression[]; }; type OrderExpression = { dimension: DimensionName | DimensionIndex; order: 'asc' | 'desc'; incomparable?: 'min' | 'max'; parser?: 'time' | 'trim' | 'number'; };
External transform registration and usage
External transforms (besides built-in 'filter' and 'sort') can be registered and used. They are referenced with a namespace prefix like 'ecStat:regression'. Built-in transforms have no namespace. Example: echarts.registerTransform(ecStatTransform(ecStat).regression); then use type: 'ecStat:regression' in transform config.
External transform ecStat example
The third-party library ecStat provides transforms like regression, clustering, and histogram. After registering ecStatTransform(ecStat).regression, use { type: 'ecStat:regression', config: { method: 'exponential' } } in dataset transform. Available methods include linear, exponential, logarithmic, and polynomial regression.
Data transform use cases
Data transforms enable: partitioning data into multiple series, making statistics and visualizing results, adapting visualization algorithms to data, sorting data, removing or selecting empty or special data items.
dataset component introduced in ECharts 4
The dataset component was introduced in Apache ECharts 4. It separates data management from styling and enables data reuse by different series. It also enables data encoding from data to visual representation.
Benefits of dataset component
Dataset provides four main benefits: (1) It allows following common data visualization methodology by specifying mapping from data to visual via series.encode option. (2) Data can be managed and configured separately from other configurations. (3) Data can be reused by different series and components. (4) It supports more common data formats like 2d-array and object-array to avoid extra data transform work for users.
dataset.source formats supported
dataset.source supports multiple formats: 2d-array format where each row is a data item and each column is a dimension, object-array format where each object is a data item with named properties, and column-based key-value format where properties are arrays of values.
dataset.sourceHeader option
The dataset.sourceHeader option controls whether the first row/column of dataset.source contains dimension names or data. When set to true, it mandatorily specifies the first row/column is dimension names. When set to false, it indicates data starts from the first row/column. By default, ECharts auto-detects whether the first row/column contains dimension names.
series.seriesLayoutBy option values
series.seriesLayoutBy configures whether columns or rows of a dataset map to series. The optional values are: 'column' (series are positioned on each column of the dataset, default value) and 'row' (series are positioned on each row of the dataset).
Dimension concept in dataset
A dimension in dataset means a column or row (depending on seriesLayoutBy setting). When seriesLayoutBy is 'column', each column is a dimension and each row is a data item. When seriesLayoutBy is 'row', each row is a dimension and each column is a data item. Dimensions can have names defined in the first row/column of dataset.source.
dataset.dimensions configuration
dataset.dimensions can separately define dimension names and types. Each item can be a string (indicating dimension name) or an object with name and type properties. Dimension type can also be specified in series.dimensions with higher priority. Dimensions declared in series.dimensions will override those in dataset.dimensions.
Dimension type options
Dimension types in ECharts are: 'number' (normal data, default value), 'ordinal' (string/category/text data, auto-detected by default), 'time' (time data supporting parsing time strings to timestamps), 'float' (stored in TypedArray for performance), and 'int' (stored in TypedArray for performance). Generally dimension types are auto-detected based on data.
series.encode option structure
series.encode maps data dimensions to visual channels. The basic structure uses axis names like 'x', 'y', 'radius', 'angle' or special reserved names like 'tooltip', 'itemName' on the left of a colon, and dimension names or dimension indices (0-based) on the right. One or more dimensions can be specified. Usually not all mappings need to be specified, only specify needed ones.
encode common properties
The encode object supports these properties in any coordinate system: tooltip (array of dimension names/indices to display in tooltip), seriesName (array of dimension indices to concatenate for series name), itemId (dimension index/name as id for each data item for dynamic updates), itemName (dimension index/name as name for each data item, useful for pie/funnel charts).
encode cartesian coordinate properties
In cartesian (grid) coordinate system, encode supports: x (map dimensions to X axis), y (map dimensions to Y axis). These properties accept dimension indices or dimension names.
encode polar coordinate properties
In polar coordinate system, encode supports: radius (map dimension to radius), angle (map dimension to angle). These properties accept dimension indices or dimension names.
encode geo coordinate properties
In geo coordinate system, encode supports: lng (map dimension to longitude), lat (map dimension to latitude). These properties accept dimension indices or dimension names.
encode for non-coordinate system series
For series types not in any coordinate system like pie and funnel, encode supports: value (map dimension to data value). This property accepts dimension index or dimension name.
visualMap for visual encoding
The visualMap component is used to map data to visual channels like color and symbol size. It works together with dataset to encode dimensions to visual properties.
Default encoding rules for common charts
ECharts provides default encoding for common chart types (line, bar, scatter, candlestick, pie, funnel, etc.) when no encode option is specified. For coordinate systems: if a category axis exists, map the first column/row to it and each series uses following columns/rows; if no category axis exists with two axes, each series uses two columns/rows. For non-coordinate charts: use first column/row as item name and second column/row as item value.
series.datasetIndex option
Multiple datasets can be defined in the option, and series can reference them using series.datasetIndex property to specify which dataset index (0-based) the series should use.
Data transform feature in ECharts 5
Data transform feature has been supported since Apache ECharts 5. Data transform means generating new data from user-provided source data and transform functions. This enables users to process data in a declarative way with common transform functions provided by ECharts.
Legacy series.data approach still supported
The data setting approach from ECharts 3 using series.data directly is still supported and can be used normally. If a series has series.data declared, it will be used instead of dataset. This approach is still useful for some chart types and scenarios like incremental data loading.
Series types supporting dataset
The following series types currently support dataset: line, bar, pie, scatter, effectScatter, parallel, candlestick, map, funnel, and custom. Series types that do not support dataset include treemap, graph, and lines, which do not apply table data.
label.formatter dimension reference syntax
In series.label.formatter, dimension values can be referenced using the syntax '{@dimensionName}' for dimension names or '{@[index]}' for dimension indices (0-based). For example: '{@product}' references the dimension named 'product', and '{@[4]}' references the fifth dimension.
Example: Simple dataset with 2d-array
option = { legend: {}, tooltip: {}, dataset: { source: [ ['product', '2015', '2016', '2017'], ['Matcha Latte', 43.3, 85.8, 93.7], ['Milk Tea', 83.1, 73.4, 55.1], ['Cheese Cocoa', 86.4, 65.2, 82.5], ['Walnut Brownie', 72.4, 53.9, 39.1] ] }, xAxis: {type: 'category'}, yAxis: {}, series: [ {type: 'bar'}, {type: 'bar'}, {type: 'bar'} ] }
Example: Dataset with object-array and dimensions
option = { legend: {}, tooltip: {}, 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}, {product: 'Cheese Cocoa', '2015': 86.4, '2016': 65.2, '2017': 82.5}, {product: 'Walnut Brownie', '2015': 72.4, '2016': 53.9, '2017': 39.1} ] }, xAxis: {type: 'category'}, yAxis: {}, series: [ {type: 'bar'}, {type: 'bar'}, {type: 'bar'} ] }
Example: Using encode to map dimensions to axes
var option = { dataset: { source: [ ['score', 'amount', 'product'], [89.3, 58212, 'Matcha Latte'], [57.1, 78254, 'Milk Tea'], [74.4, 41032, 'Cheese Cocoa'], [50.1, 12755, 'Cheese Brownie'], [89.7, 20145, 'Matcha Cocoa'], [68.1, 79146, 'Tea'], [19.6, 91852, 'Orange Juice'], [10.6, 101852, 'Lemon Juice'], [32.7, 20112, 'Walnut Brownie'] ] }, xAxis: {}, yAxis: {type: 'category'}, series: [ { type: 'bar', encode: { x: 'amount', y: 'product' } } ] }
Example: Using visualMap to encode dimension to bubble size
var option = { dataset: { source: [ [12, 323, 11.2], [23, 167, 8.3], [81, 284, 12], [91, 413, 4.1], [13, 287, 13.5] ] }, visualMap: { show: false, dimension: 2, min: 2, max: 15, inRange: { symbolSize: [5, 60] } }, xAxis: {}, yAxis: {}, series: { type: 'scatter' } }