Transformations for Zeppelin Visualization

Overview

Transformations

  • renders setting which allows users to set columns and
  • transforms table rows according to the configured columns.

Zeppelin provides 4 types of transformations.

1. PassthroughTransformation

PassthroughTransformation is the simple transformation which does not convert original tabledata at all.

See passthrough.js

2. ColumnselectorTransformation

ColumnselectorTransformation is uses when you need N axes but do not need aggregation.

See columnselector.js

3. PivotTransformation

PivotTransformation provides group by and aggregation. Every chart using PivotTransformation has 3 axes. Keys, Groups and Values.

See pivot.js

4. AdvancedTransformation

AdvancedTransformation has more detailed options while providing existing features of PivotTransformation and ColumnselectorTransformation

  • multiple sub charts
  • configurable chart axes
  • parameter widgets: input, checkbox, option, textarea
  • parsing parameters automatically based on their types
  • expand / fold axis and parameter panels
  • multiple transformation methods while supporting lazy converting
  • re-initialize the whole configuration based on spec hash.

Spec

AdvancedTransformation requires spec which includes axis and parameter details for charts.

Let's create 2 sub-charts called line and no-group. Each sub chart can have different axis and parameter depending on their requirements.


class AwesomeVisualization extends Visualization {
  constructor(targetEl, config) {
    super(targetEl, config)

    const spec = {
      charts: {
        'line': {
          transform: { method: 'object', },
          sharedAxis: false, /** set if you want to share axes between sub charts, default is `false` */
          axis: {
            'xAxis': { dimension: 'multiple', axisType: 'key', description: 'serial', },
            'yAxis': { dimension: 'multiple', axisType: 'aggregator', description: 'serial', },
            'category': { dimension: 'multiple', axisType: 'group', description: 'categorical', },
          },
          parameter: {
            'xAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of xAxis', },
            'yAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of yAxis', },
            'lineWidth': { valueType: 'int', defaultValue: 0, description: 'width of line', },
          },
        },

        'no-group': {
          transform: { method: 'object', },
          sharedAxis: false,
          axis: {
            'xAxis': { dimension: 'single', axisType: 'key', },
            'yAxis': { dimension: 'multiple', axisType: 'value', },
          },
          parameter: {
            'xAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of xAxis', },
            'yAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of yAxis', },
        },
      },
    }

    this.transformation = new AdvancedTransformation(config, spec)
  }

  ...

  // `render` will be called whenever `axis` or `parameter` is changed 
  render(data) {
    const { chart, parameter, column, transformer, } = data

    if (chart === 'line') {
      const transformed = transformer()
      // draw line chart 
    } else if (chart === 'no-group') {
      const transformed = transformer()
      // draw no-group chart 
    }
  }
}


Spec: axis

Field Name Available Values (type) Description
dimension single Axis can contains only 1 column
dimension multiple Axis can contains multiple columns
axisType key Column(s) in this axis will be used as key like in PivotTransformation. These columns will be served in column.key
axisType aggregator Column(s) in this axis will be used as value like in PivotTransformation. These columns will be served in column.aggregator
axisType group Column(s) in this axis will be used as group like in PivotTransformation. These columns will be served in column.group
axisType (string) Any string value can be used here. These columns will be served in column.custom
maxAxisCount (optional) (int) The max number of columns that this axis can contain. (unlimited if undefined)
minAxisCount (optional) (int) The min number of columns that this axis should contain to draw chart. (1 in case of single dimension)
description (optional) (string) Description for the axis.


Here is an example.

axis: {
  'xAxis': { dimension: 'multiple', axisType: 'key',  },
  'yAxis': { dimension: 'multiple', axisType: 'aggregator'},
  'category': { dimension: 'multiple', axisType: 'group', maxAxisCount: 2, valueType: 'string', },
},


Spec: sharedAxis

If you set sharedAxis: false for sub charts, then their axes are persisted in global space (shared). It's useful for when you creating multiple sub charts sharing their axes but have different parameters. For example,

  • basic-column, stacked-column, percent-column
  • pie and donut


Here is an example.

    const spec = {
      charts: {
        'column': {
          transform: { method: 'array', },
          sharedAxis: true,
          axis: { ... },
          parameter: { ... },
        },

        'stacked': {
          transform: { method: 'array', },
          sharedAxis: true,
          axis: { ... }
          parameter: { ... },
        },


Spec: parameter

Field Name Available Values (type) Description
valueType string Parameter which has string value
valueType int Parameter which has int value
valueType float Parameter which has float value
valueType boolean Parameter which has boolean value used with checkbox widget usually
valueType JSON Parameter which has JSON value used with textarea widget usually. defaultValue should be "" (empty string). This
description (string) Description of this parameter. This value will be parsed as HTML for pretty output
widget input Use input widget. This is the default widget (if widget is undefined)
widget checkbox Use checkbox widget.
widget textarea Use textarea widget.
widget option Use select + option widget. This parameter should have optionValues field as well.
optionValues (Array) Available option values used with the option widget


Here is an example.

parameter: {
  // string type, input widget
  'xAxisUnit': { valueType: 'string', defaultValue: '', description: 'unit of xAxis', },

  // boolean type, checkbox widget
  'inverted': { widget: 'checkbox', valueType: 'boolean', defaultValue: false, description: 'invert x and y axes', },

  // string type, option widget with `optionValues`
  'graphType': { widget: 'option', valueType: 'string', defaultValue: 'line', description: 'graph type', optionValues: [ 'line', 'smoothedLine', 'step', ], },

  // HTML in `description`
  'dateFormat': { valueType: 'string', defaultValue: '', description: 'format of date (<a href="https://docs.amcharts.com/3/javascriptcharts/AmGraph#dateFormat">doc</a>) (e.g YYYY-MM-DD)', },

  // JSON type, textarea widget
  'yAxisGuides': { widget: 'textarea', valueType: 'JSON', defaultValue: '', description: 'guides of yAxis ', },


Spec: transform

Field Name Available Values (type) Description
method object designed for rows requiring object manipulation
method array designed for rows requiring array manipulation
method array:2-key designed for xyz charts (e.g bubble chart)
method drill-down designed for drill-down charts
method raw will return the original tableData.rows


Whatever you specified as transform.method, the transformer value will be always function for lazy computation. 

// advanced-transformation.util#getTransformer

if (transformSpec.method === 'raw') {
  transformer = () => { return rows; }
} else if (transformSpec.method === 'array') {
  transformer = () => {
    ...
    return { ... }
  }
}

Here is actual usage.

class AwesomeVisualization extends Visualization {
  constructor(...) { /** setup your spec */ }

  ... 

  // `render` will be called whenever `axis` or `parameter` are changed
  render(data) {
    const { chart, parameter, column, transformer, } = data

    if (chart === 'line') {
      const transformed = transformer()
      // draw line chart 
    } else if (chart === 'no-group') {
      const transformed = transformer()
      // draw no-group chart 
    }
  }

  ...
}