Tutorial

This tutorial will explain each step required to make basic use of crosscompare. Further information on options and available functions can be found in the API reference. A more in-depth use case can be found as the air traffic delay example.

Preview

This will be the outcome of this tutorial. Try it out! Filters can be applied via dragging or selection within these charts. Then press Add to Cache below the respective chart. Change some filter and press the same button again. Repeat if you like. Press Render if you want to see the comparison. You can then continue adding and re-render the comparison.

Please be aware that the cache will be reset whenever you try to cache data from different charts.

You will get the best results by filtering one chart, but caching the other.

Cache either chart...

Render
Reset

Row Chart

Add to Cache

Bar Chart

Add to Cache

Instructions

For your convenience you can download all necessary files and the end result bundled here: download tutorial bundle.

1. Establishing the framework

Use an existing or create a new HTML page and include the .js-files of dc.js, crossfilter, c3.js, d3.js, and jQuery; by downloading and extracting them into the same folder, where the HTML file is stored. crosscompare.js itself must also be included and can be downloaded here. Also include dc.js' and c3.js' own .css-files. Within the body, create three div-containers (two containers for the dc-charts, one container for the comparison chart). Additionally, give each of the div-containers a unique id (e.g. '#crosscompare' for the comparison chart, and '#row-chart' and '#bar-chart' for the dc-charts). For clarity, let each container be preceded by a heading. Now, the page could look something like this:

<!DOCTYPE html>
<html>
  <link href="dc.css" rel="stylesheet" type="text/css">
  <link href="c3.css" rel="stylesheet" type="text/css">
  <body>
 
    <h1>Comparison Chart</h1>
    <div id="crosscompare"></div>
 
    <h1>Row Chart</h1>
    <div id="row-chart">Row Chart</div>
 
    <h1>Bar Chart</h1>
    <div id="bar-chart">Bar Chart</div>
 
    <script src="jquery-2.1.4.min.js" type="text/javascript"></script>
    <script src="d3.js" type="text/javascript"></script>
    <script src="crossfilter.js" type="text/javascript"></script>
    <script src="dc.js" type="text/javascript"></script>
    <script src="c3.js" type="text/javascript"></script>
    <script src="crosscompare.js" type="text/javascript"></script>
  </body>
</html>

2. Setting up Crossfilter

Create a new script section below the included .js-files. This is where the page-specific logic will be placed. Create a crossfilter instance and pass it some sample data (excerpt shown below, download full sample here). From the sample data, create two dimensions and two groups (for the samlpe data's keys and values repectively).

<script type="text/javascript">
  // Set up crossfilter
  var ndx = crossfilter([
    {key: 'C', value: '6'},	{key: 'B', value: '5'},
    {key: 'B', value: '0'},	{key: 'C', value: '3'},
    // ... more sample data via link above
    {key: 'B', value: '7'},	{key: 'C', value: '7'},
    {key: 'A', value: '7'},	{key: 'A', value: '7'}
  ]);
 
  // Define dimensions
  var key = ndx.dimension(function(d) { return d.key; }),
      value = ndx.dimension(function(d) { return d.value; });
 
  // Define groups
  var keyGroup = key.group(),
      valueGroup = value.group();
</script>

3. Setting up dc.js

Create, define, and render dc.js charts via adding the following within the page specific script section below the code for crossfilter.

  // Create dc.js charts
  var keyChart = dc.rowChart('#row-chart'),
      valueChart = dc.barChart('#bar-chart');
 
  // Define each chart's dimension and group
  keyChart
  .dimension(key)
  .group(keyGroup);
  
  valueChart
  .dimension(value)
  .group(valueGroup)
  // A bar chart additionally requires x-axis settings
  .x(d3.scale.linear().domain([0, 10]));
  
  // Render and display charts
  dc.renderAll();

4. Setting up Crosscompare

Below the div-containers, add four links which will be used to control the behaviour of crosscompare. One link to activate crosscompare's .render() function, one to .reset() crosscompare, and one link for each dc.js chart to cache them (i.e. take a snapshot of their current data and filters). For the latter, crosscompare listens to the dc.js chart's anchors with '-cross' appended (by default). Additonally, to be displayed information messages from crosscompare, add another heading below the links with the id 'crosscompare-info' (by default).

    <a href='javascript:crosscompare.render();'>Render</a></br>
    <a href='javascript:crosscompare.reset();'>Reset</a></br>
    <a href='#' id='row-chart-cross'>Cache Row Chart</a></br>
    <a href='#' id='bar-chart-cross'>Cache Bar Chart</a></br>
 
    <h2 id='crosscompare-info'>-</h2>

Finally, define the charts that should be comparable via crosscompare. Add the following within our page specific script section below the code for dc.js. When compared, the keyChart should be represented using a bar chart and should be sorted in descending order. These settings are being provided in the .add() function, together with the according chart. The valueChart should be represented using a line chart (which is the default), so no additional options have to be provided.

  // Register the dc.js charts with crosscompare
  crosscompare
  .addLegend(keyChart)  // optional
  .addLegend(valueChart)  // optional
  .add(keyChart, { type: 'bar', order: 'desc' })
  .add(valueChart);

That's it! Open the HTML file in a browser and start comparing!