@wq/chart is a @wq/app plugin providing reusable charts powered by the excellent d3.js library. Some basic chart types (scatter, timeSeries, boxplot) are included, as well as the ability to create new chart types. Any data source can be used, as long as enough information is provided to understand the structure of the data.

Installation

wq.app for PyPI

python3 -m venv venv      # create virtual env (if needed)
. venv/bin/activate       # activate virtual env
python3 -m pip install wq # install wq framework (wq.app, wq.db, etc.)
# pip install wq.app      # install wq.app only

@wq/app for npm

npm install @wq/chart

API

When used as a @wq/app plugin, @wq/chart detects <svg>s containing data-wq-* attributes and automatically generates appropriate charts. Alternatively, the @wq/chart API can also be used directly, by specifying a dataset object and a d3 selection. Note that the import path is slighly different in each case.

wq.app for PyPI

// @wq/app plugin
define(['wq/app', 'wq/chartapp'], function(app, chartapp) {
    app.use(chartapp);
    app.init(...);
});

// direct API
define(['wq/chart', 'd3', ...], function(chart, d3, ...) {
    var dataset = { ... }; // See below
    var svg = d3.select('svg#chart');
    var plot = chart.timeSeries()
        .width(800)
        .height(300);
    svg.datum([dataset]).call(plot);
});

@wq/app for npm

// @wq/app plugin
import chartapp from '@wq/chart';
app.use(chartapp);
app.init(...);

// direct API
import { chart } from '@wq/chart';
import * as d3 from 'd3';

const dataset = { ... }; // See below
const svg = d3.select('svg#chart');
const plot = chart.timeSeries()
                .width(800)
                .height(300);
svg.datum([dataset]).call(plot);

The direct API functions each return a configurable function that can be called on a d3 selection that already has data bound to it. By convention, this generated chart function is referred to as plot to differentiate it from the chart module. However, any variable name can be used.

The dataset in the example above would typically be a JavaScript object of the form:

{
  'id': 'temp-data',
  'label': 'Temperature',
  'units': 'C'
  'list': [
    {'date': '2013-09-26', 'value': 26},
    {'date': '2013-09-27', 'value': 23},
    // ...
  ]
}

When used as a @wq/app plugin, @wq/chart automatically loads objects in this format via CSV files generated by Django REST Pandas. To use the plugin, the URL and other chart options should be specified on an otherwise empty <svg> in the page template.

<svg data-wq-url="/api/data/timeseries.csv"
     data-wq-type="timeSeries"
     data-wq-point-cutoff="100"
     data-wq-time-format="%Y-%m-%d"
     data-wq-width="800"
     data-wq-height="600"
     data-wq-x="date"
     data-wq-y="value"
     data-wq-label-template=""
     data-wq-point-label-template="Value on " >
</svg>

Chart Options

The core chart generator (chart.base()) includes a number of setup routines that are utilized by each of the built-in chart types. All chart types inherit the base chart options, and some include additional options unique to each chart. All options have reasonable defaults, most of which can be re-configured using d3-style getter/setter functions.

Options

These options control basic chart formatting and layout.

Margins

There is also a special method, plot.setMargin(name, margin), that can be used to “reserve” named spaces at the margins of the chart. Unlike other options, setMargin is not a getter/setter function. Instead, it takes two arguments: a unique margin name, and a margin object which should have at least one of left, right, top, or bottom set. The values should be distances measured in pixels. All of the set margins are aggregated by plot.getMargins() to determine the final margins for the chart.

// Reserve 30px at the top for a custom header
plot.setMargin("myheader", {'top': 30});

var allMargins = plot.getMargins();
// allMargins.top == 5 + 30 == 35

Margins for the legend and axes are set automatically using the setMargin() mechanism. The margin names padding, xaxis, yaxis, and legend are reserved for this purpose.

Accessors

Accessors control how the data object is parsed, i.e. how data properties are accessed. Accessors are simple functions that take an object and return a value. Overriding the default accessor makes it possible to chart data structures that are not of the format shown above.

Dataset Accessors

Legend Accessors

Accessors for Individual Values

Scatter plots

chart.scatter() returns a function useful for drawing basic x-y scatter plots and line charts. One or more datasets containing x and y values should be provided. All datasets should have the same units for x values, but can can have different y units if needed. Alternating left and right-side y axes will be created for each unique y unit (so it’s best to have no more than two).

chart.scatter() can be used with Django REST Pandas’ PandasScatterSerializer.

Default Overrides

chart.scatter() overrides the following base chart defaults:

Additional Options

chart.scatter() defines these additional options:

Time series plots

chart.timeSeries() is a simple extension to chart.scatter() that assumes the x values are times or dates.

chart.timeSeries() can be used with Django REST Pandas’ PandasUnstackedSerializer.

Default Overrides

chart.timeSeries() overrides the following scatter chart defaults:

Additional Options

chart.timeSeries() defines one additional option:

Box & Whisker plots

chart.boxplot() returns a function useful for rendering simple box-and-whisker plots. The quartile data for each box should be precomputed.

The default implementation of chart.boxplot() assumes a dataset with roughly the following structure:

{
  'id': 'temp-data',
  'label': 'Temperature',
  'units': 'C'
  'list': [
    {
      'year': "2013",
      'value-whislo': 3,
      'value-q1', 8
      'value-median': 17,
      'value-q3': 20,
      'value-whishi': 25
    }
    // ...
  ]
}

The x value (year in the above example) is used to define an ordinal scale where each item on the x axis corresponds to a box. Thus, any text or numeric attribute can be defined as the x value, provided that the xvalue accessor is defined.

var plot = chart.boxplot().xvalue(function(d) { return d.year });

chart.boxplot() can be customized by overriding the following accessor methods:

Accessors for Individual Values

chart.boxplot() can be used with Django REST Pandas’ PandasBoxplotSerializer.

Custom Charts

The base chart provides “hooks” that allow for specifying the chart rendering process before, during, and after each dataset is rendered. Each of the chart types above defines one or more of these functions. They can also be used if you want to define a new chart type or significantly alter the behavior of one of the existing types.

To define your own chart function generator, you could do something like the following:

function myChart() {
    var plot = chart.base()
        .render(render);

    function render(dataset) {
        var items = plot.items()(dataset);
        d3.select(this)
           .selectAll('g.data')
           .data(items)
           .append('g').attr('class', 'data')
           /* do something cool with d3 */
    }

    return plot;
}

var plot = myChart();
svg.datum([dataset]).call(plot);