Cornelius can draw a Cohort Chart like this for you:

Only with this code:

<script type="text/javascript">
  var data = [
    [1973,1000,750,300,400,70,20],
    [1268,549,336,221,122,115],
    [1892,1282,250,32,18],
    [1832,379,254,314],
    [1171,256,120],
    [2533,340]
  ],
  // The initial date is the date displayed
  // in the first column of the first row
  initialDate = new Date(2012, 0),

  // DOM Element where the Cohort Chart will be inserted
  container = document.getElementById('main-example');

  Cornelius.draw({
    initialDate: initialDate,
    container: container,
    cohort: data,
    title: 'Cornelius Demo'
  });
</script>

Installation

Just include the javascript and stylesheet files and you are ready to go. No jQuery needed, dependency free.

<link rel="stylesheet" type="text/css" href="cornelius.css" />
<script type="text/javascript" src="cornelius.js"></script>

API

There is only one method you can use:

Cornelius.draw({

  // required params

  initialDate: new Date(2013, 03),

  container: document.getElementById('my-container'),

  cohort: [
    [1973,1000,750,300,400,70,20],
    [1268,549,336,221,122,115],
    [1892,1282,250,32,18],
    [1832,379,254,314],
    [1171,256,120],
    [2533,340]
  ],

  /* any other options */

  timeInterval: 'weekly'
});

The initialDate property is a Date object that will be used as the initial date to compute the following dates that will be shown in the chart.

This Date object should have the date part of the object set as the beginning of the month (day 1), and must have the time set to ‘00:00’.

var date = new Date(2012, 6); // Sun Jul 01 2012 00:00:00

Be careful with the month argument you pass since the Date object considers January as month 0.

Data Format

The cohort property must be an array of arrays whose values will be mapped to the cohort table cells in the same order as provided. Given the distinctive triangle shape of the chart, each array should either have a value less than the previous one, or it should be filled with null, undefined, or false values.

Options

Cornelius accepts any of these option values passed to the constructor:

timeInterval

Cornelius accepts 4 time intervals that are used to compute the date labels: daily, weekly, monthly, yearly.

Example: <div id="time-interval-example"></div>

Cornelius.draw({
  timeInterval: 'weekly',

  initialDate: initialDate,
  cohort: data,
  container: document.getElementById('time-interval-example')
});

Default: 'monthly'

repeatLevels

It is possible to customize the colours of the cells depending on the percentage each of them have. You will have to specify the class names and the percentage ranges the library will use in order to decide which class will be assigned to each cell.

Below are the default css classes and ranges the library uses.

var repeatLevels = {
  'low': [0, 10],
  'medium-low': [10, 20],
  'medium': [20, 30],
  'medium-high': [30, 40],
  'high': [40, 60],
  'hot': [60, 70],
  'extra-hot': [70, 100]
}

Cornelius.draw({
  repeatLevels: repeatLevels,

  initialDate: new Date(2012, 3),
  cohort: data,
  container: document.getElementById('container')
});

In this example, Cornelius will assign the cornelius-low class to each cell with a value between 0% and 10%, cornelius-medium-low to each cell between 10% and 20%, and so on.

You can specify as many ranges and class names as you want, but don’t forget to add those classes to your stylesheets.

drawEmptyCells

Setting this property to true will display a white empty cell for those cells that are “outside” of the main triangle.

Example:

Cornelius.draw({
  drawEmptyCells: false,

  initialDate: initialDate,
  timeInterval: 'daily',
  cohort: data,
  container: document.getElementById('empty-cells-example')
});

Default: true

rawNumberOnHover

If rawNumberOnHover is set to true, it will display the raw number while leaving the mouse on top of the cell.

Default: true

displayAbsoluteValues

If displayAbsoluteValues is set to true, absolute values will be displayed instead of the percentage value.

Default: false

initialIntervalNumber

This property will allow you to specify the initial number that will be displayed in the first column header.

Default: 1

I18n

The library uses only 3 strings for the labels that can be specified in the options object:

Cornelius.draw({
  labels: {
    time: 'Zeit', // Time
    people: 'Menschen', // People
    weekOf: 'Woche Vom' // Week Of
  },

  initialDate: new Date(2011, 6),
  cohort: data,
  container: document.getElementById('container')
});

The long and short month names can also be customized:

Cornelius.draw({
  monthNames: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio',
               'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'],

  shortMonthNames: ['Ene', 'Feb', 'Mar', 'Abr', 'Mar', 'Jun', 'Jul',
                    'Ago', 'Sep', 'Oct', 'Nov', 'Dic'],

  initialDate: initialDate,
  cohort: data,
  container: document.getElementById('container')
});

Alternatively you can specify the functions that will be called to return the Strings for the header and date labels:

formatHeaderLabel(index)

If setting the initialIntervalNumber and labels doesn’t fullfill your needs, you can format the header label using a lower level API. You can pass a function that will be called for every column header that is being drawn, and its return value will be used as the header label. The only parameter it receives is the index of the column that will be drawn (zero index).

Example:

Cornelius.draw({
  formatHeaderLabel: function(i) {
    return i * 2;
  },

  initialDate: initialDate,
  cohort: data,
  container: document.getElementById('format-header-example')
});

Formatting the dates

There are 4 optional parameters that Cornelius can use to format the date labels. Depending on the time interval you use, you can pass a formatDailyLabel, formatWeeklyLabel, formatMonthlyLabel and formatYearlyLabel function to format a daily, weekly, monthly and yearly cohort chart respectively.

These functions takes 2 parameters: the date object corresponding to the initial date, and the column index.

Example:

Cornelius.draw({
  formatMonthlyLabel: function(date, i) {
    date.setDate(date.getDate() + i); // update the date object to the corresponding month
    return "Month " + (i + 1) + " - " + this.monthNames[i];
  },

  initialDate: initialDate,
  cohort: data,
  container:document.getElementById('format-date-example')
});

Trimming the table

If your cohort data is too large and want only to display the first N columns or the last M rows, you can use the maxRows and maxColumns properties.

Example:

Cornelius.draw({
  maxRows: 4,
  maxColumns: 3,

  initialDate: initialDate,
  cohort: data,
  container: document.getElementById('trimming-example')
});

Chart Title

To display a title above the chart, use the title option:

Cornelius.draw({
  title: 'My Chart Title',

  initialDate: new Date(2011, 6),
  cohort: data,
  container: document.getElementById('container')
});

Default options

One instance of Cornelius can be used to draw multiple charts using the same options. You can also set the global defaults that will be used in any Cornelius instance.

Example:

Cornelius.getDefaults(); // { ..., initialIntervalNumber: 1, timeInterval: 'monthly', ... }

Cornelius.setDefaults({initialIntervalNumber: 0, timeInterval: 'weekly'});

Cornelius.getDefaults(); // { ..., initialIntervalNumber: 0, timeInterval: 'weekly', ... }

Cornelius.resetDefaults();

Cornelius.getDefaults(); // { ..., initialIntervalNumber: 1, timeInterval: 'monthly', ... }

jQuery plugin

Cornelius doesn’t have jQuery as a dependency. But if you have it already, you can use the jQuery helper:

$("#container").cornelius({
  initialDate: new Date(2013, 1),
  // cohort data
  cohort: [
    [100, 30, 23, 10],
    [399, 23, 10, 40]
  ],
  timeInterval: 'daily',
  /* ... other options ... */
});

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.