Charts

It is recommended to read the documentation about Data beforehand.

The API at a Glance #

Let’s look at two examples of the Chart API usage with static data and data coming from a MDX query.

Static data #

If there is a div with the id charts in your page, you can add a chart displaying your static data in it with:

import ActiveUI from 'activeui';

export default ActiveUI.initialize();

import activeUI from './activeui';

// Define data headers and tuples
const dataHeaders = [
  {value: 'x', caption: 'X', numeric: true},
  {value: 'y', caption: 'Y', numeric: true},
  {value: 'count', caption: 'Count', numeric: true},
  {value: 'category', caption: 'Category', numeric: false},
];
const tuples = [[20, 3, 10, 'A'], [30, 1, 20, 'A'], [18, 5, 13, 'B'], [40, 2, 6, 'B'], [14, 3, 18, 'B']];
// Convert to a Table:
const table = activeUI.data.toTable(dataHeaders, tuples);
// Create a query object from it:
const staticDataQuery = activeUI.data.createStaticDataQuery().setTable(table);
// Define the chart configuration
const configuration = {
  type: 'scatter',
  mapping: {
    x: {from: 'x'},
    y: {from: 'y'},
    color: {from: ['category']},
    r: {from: 'count'},
  },
  handlers: {},
};

// Display in a chart:
activeUI.widgets
  .createChart()
  .addLayer(staticDataQuery, configuration)
  .within('chart');

<div id="chart" class="chart"></div>

Another example displaying in a Gantt chart:

import ActiveUI from 'activeui';

export default ActiveUI.initialize();

import activeUI from './activeui';

const getCell = date => ({value: date, caption: date.toLocaleDateString()});
// Data used for gantt chart
const tuples = [
  [getCell(new Date(2015, 5, 15)), getCell(new Date(2015, 5, 20)), 'Sprint 1'],
  [getCell(new Date(2015, 5, 20)), getCell(new Date(2015, 6, 5)), 'Sprint 2'],
  [getCell(new Date(2015, 6, 0)), getCell(new Date(2015, 6, 10)), 'Sprint 3'],
  [getCell(new Date(2015, 6, 10)), getCell(new Date(2015, 6, 21)), 'Sprint 4'],
  [getCell(new Date(2015, 6, 21)), getCell(new Date(2015, 7, 21)), 'UAT'],
  [getCell(new Date(2015, 6, 21)), getCell(new Date(2015, 7, 5)), 'Testing'],
];

// Define data headers for gantt chart
const dataHeaders = [
  {value: 'from', caption: 'From', numeric: true},
  {value: 'to', caption: 'To', numeric: true},
  {value: 'name', caption: 'Name', numeric: false},
];

// Gantt chart configuration
const configuration = {
  type: 'gantt',
  mapping: {
    start: {from: 'from', scaleType: 'time'},
    end: {from: 'to', scaleType: 'time', grid: true},
    y: {from: ['name']},
    color: {from: ['name']},
  },
  handlers: {},
  leftMargin: 10,
  rightMargin: 0,
  bottomMargin: 15,
  topMargin: 0,
};

const table = activeUI.data.toTable(dataHeaders, tuples);
const staticDataQuery = activeUI.data.createStaticDataQuery().setTable(table);

// Create chart & attach to DOM
activeUI.widgets
  .createChart()
  .addLayer(staticDataQuery, configuration)
  .within('chart');

<div id="chart" class="chart"></div>

This will create a scatter plot chart with five points, the coordinates of each point will be mapped to the first two columns of the data, the size to the third and they will have one of two colors, one for the points having A as category, the other one for the points having B.

As one can see we need to give two inputs to the chart, its data and its configuration. The configuration will be explained here.

You can look at the Gant sample for a live example.

From a MDX query #

Creating a chart from a MDX query is quite similar, and for example on the Sandbox one can do:

import ActiveUI from 'activeui';

const activeUI = ActiveUI.initialize();
const servers = activeUI.queries.serversPool;
servers.addActivePivotServer({url: 'http://url/of/your/activepivot/server'});

export default activeUI;

import activeUI from './activeui';

const mdx = `
  SELECT NON EMPTY {
    [Measures].[contributors.COUNT],
    [Measures].[pnl.SUM],
    [Measures].[pv.SUM]
  } ON COLUMNS,
  NON EMPTY CrossJoin(
    Hierarchize(DrilldownLevel([Booking].[Desk].[ALL].[AllMember])),
    Hierarchize(DrilldownLevel([Currency].[Currency].[ALL].[AllMember]))
  ) ON ROWS FROM [EquityDerivativesCube]`;

const config = {
  type: 'scatter',
  mapping: {
    x: {from: '[Measures].[pnl.SUM]'},
    y: {from: '[Measures].[contributors.COUNT]'},
    row: {from: ['[Booking].[Desk].[Desk]']},
    color: {from: ['[Currency].[Currency].[Currency]']},
    text: {from: '[Measures].[pv.SUM]'},
  },
  handlers: {},
};

activeUI.widgets
  .createChart()
  .addLayer({mdx}, config)
  .within('chart');

<div id="chart" class="chart"></div>

The main difference with the static data example is that the mapping given in the configuration of the chart must refer to the unique names of the level or measures contained in the query result (see TableFromCellSet).

Configuration #

Let’s dive more into the configuration of the chart itself.

In ActivePivot Live 3, the charts had no intrinsic configuration, they were entirely configured from the MDX query, trying to map the COLUMNS axis to some attribute and the ROWS axis to other ones. Now this mapping between data columns and attribute mapping is done in the configuration of the chart, which is a separate object stored along the MDX in the bookmarks. In addition to the mapping multiple other parameters of the chart rendering are stored in this configuration object.

Attribute Mapping #

All chart types display a graphical element per tuple in the Table they receive. Each type of chart has its own list of graphical properties that can be configured, they are called chart attributes. The main goal of the configuration is to map columns of the input Table to the graphical properties of the displayed elements. So for instance on a Scatter Plot chart that displays a circle per Tuple in the data, the list of attributes that can be mapped is:

To map any of these attributes to a column of the table, one just has to add an entry in configuration.mapping with the name of the attribute as key. So mapping x to a Table column whose header value is v is made with:

{
  mapping: {
    x: {
      from: 'v';
    }
  }
}

Attribute type #

As you could see in the table listing the attributes of the Scatter Plot, attributes have different types. This type is here to constrain the mapping between the data and the chart attributes to be meaningful. For instance the goal of a Scatter Plot is to compare two measures by putting them on the X and Y axes to visually detect correlation clustering and so on… So it makes no sense to put on these axes a currency information for instance. If one wants to plot a measure against a currency then a Line Chart or a Histogram will be more suited. This is why the X attribute of these two chart types is of type ordinal instead of numeric.

The chart library will read the isNumeric information of the header to decide if it can be mapped to an attribute. Columns with isNumeric set to true are called numeric columns, the other ones are called ordinal columns (in reference to the same d3 naming).

There are four types of attributes, each one of them can or not be mapped to numeric columns or ordinal columns.

Attributes of type numeric can only be mapped to a single numeric column: it doesn’t make sense to map the radius of the scatter plot circle to contributors.COUNT and pnl.SUM, we can use only one of the two values. On the other hand, ordinal attributes can be mapped to multiple columns. This will be converted to a cartesian product in the charts library. So for instance we can map the scatter plot circle color to a first column with 3 distinct values and a second column with 4 distinct values. The charts library will create a color scale with 12 different colors for all the possible combinations.

Mapping value #

The mapping part of the configuration of a chart is a map whose keys are attribute names and the values are called mapping value.

There are two possible types of mapping values: constant and dynamic. The constant type should be used when all elements in the charts have the same value for this attribute, otherwise the dynamic type should be used.

To define a constant mapping, we use the key value instead of from in the mapping value. So for instance to have all circles of a scatter plot pink one can write:

{
  mapping: {
    color: {
      value: 'pink';
    }
  }
}

In opposition, the dynamic mapping uses the from key. Its value depends on the type of the attribute, since numeric attributes can only be mapped to a single column the value of the mapping value will directly be the value of the header of the Table column that we want to map to. When mapping to ordinal value, we will by contrast use an array because in this situation we can map to multiple columns.

If we look back at the configuration of the scatter plot on a MDX query:

 mapping: {
    x: {from: '[Measures].[pnl.SUM]'},
    y: {from: '[Measures].[contributors.COUNT]'},
    row: {from: ['[Booking].[Desk].[Desk]']},
    color: {from: ['[Currency].[Currency].[Currency]']},
  }

This is the reason why the mapping values of row and color use arrays and the mapping values of x and y use directly a string, even if the arrays contain only one element.

Mandatory attributes #

As you could see in the table listing the attributes of the Scatter Plot, X and Y are mandatory. This means a chart will refuse to render if any of them is not mapped to a data column. An explicit error message will be rendered instead. Each chart type has its own list of mandatory attributes.

Common attributes #

All chart types have different attributes, but there are a few attributes that are common to all charts:

• rows and columns: these two ordinal attributes can be used to display multiple charts (called sub-charts) side by side in multiple rows and columns. The only chart types that do not work with them are Geographical ones.
• cardinality: this attribute doesn’t map to any visual property of any chart. It can be used when connecting a Chart to a MDX query, mapping a new level to this attribute will make the UI add this level in the MDX query, crossJoining it on the ROWS axis thus multiplying the number of displayed points (the cardinality of the chart) by the number of members of this level.

Automatic mapping #

In addition to the mapping declared in the configuration given to the charts library, each type of chart contains rules on how to map additional attributes automatically based on the currently mapped ones. This is called configuration post-processing. This is this mechanism that will map for instance the lineColor attribute of a Line Chart to be the same as line. Each chart type has different rules per attributes that are triggered if no mapping is given and if the rule can be applied. So the later rule will not apply if lineColor is already mapped (even on a constant color), or if line is not mapped.

Mapping options #

The dynamic mapping object can have more keys than just from, the other keys are options that control the way the mapping is performed. Here is the list of options that one can use:

Integer means a natural number (1,2,3,…).

Number means a real number (1.2, 1.3,…).

Axes attributes are x and y.

Type #

In the configurations object, the type attributes define the type of chart to use. The core implementations are:

• scatter
• line
• lineArea
• histogram
• horizontalHistogram
• gantt
• pie
• gauge
• treeMap
• pointMap
• vectorMap
• histogramMap

Other configuration properties #

The configuration can take other parameters outside of the mapping. These parameters change the rendering of the non data-related items of the chart. We list here the properties read by all types of chart, some chart types read additional ones.