Parallel Timelines Chart With JavaScript And SVG

Preview:

Description:

A JavaScript & SVG based charting library to create a Gantt Chart style segmented timelines for representing the state of time-series over time.

More Features:

• Custom date format.
• Data sorting.
• Data zooming.
• Custom tick labels.
• Apply colors to segments according to their data values.

How to use it:

1. Install the package.

# NPM
$ npm install timelines-chart --save

2. Import the Timelines Chart as a module.

import TimelinesChart from 'timelines-chart';

3. Or load the UMD version from a CDN.

<script src="https://unpkg.com/timelines-chart"></script>

4. Prepare your data as follows:

myData = [
  {
    group: "group1",
    data: [
      {
        label: "label1",
        data: [
          {
            timeRange: [<date>, <date>],
            val: <val: number (continuous dataScale) or string (ordinal dataScale)> 
          },
          {
            timeRange: [<date>, <date>],
            val: <val>
          },
          (...)
        ]
      },
      {
        label: "label2",
        data: [...]
      },
      (...)
    ],
  },
  {
    group: "group2",
    data: [...]
  },
]

5. Render a basic timelines chart on an element you specify.

TimelinesChart()(element)
.data(myData);

6. Customize the timelines chart with the following API.

const myChart = TimelinesChart();
// get/set data
myChart.data([array]);
// get/set chart width
myChart.width([number]);
// get/set the max height of the chart
// defaults to 640
myChart.maxHeight([number]);
// get/set the max height of the timeline
// defaults to 12
myChart.maxLineHeight([number]);
// get/set the left margin of the timeline
// defaults to 90
myChart.leftMargin([number]);
// get/set the right margin of the timeline
// defaults to 100
myChart.rightMargin([number]);
// get/set the top margin of the timeline
// defaults to 26
myChart.topMargin([number]);
// get/set the bottom margin of the timeline
// defaults to 30
myChart.bottomMargin([number]);
// determine whether to display time in the local time zone (false) or in UTC (true)
// defaults to false
myChart.useUtc([boolean]);
// time format to use in tooltips
// defaults to %Y-%m-%d %-I:%M:%S %p
myChart.timeFormat([string]);
// X axis tick label formatter function
myChart.xTickFormat([function]);
// get/set the date marker to show as a vertical line
// defaults to null
myChart.dateMarker([date object]);
// get/set the minimum time duration (in msecs) of a segment
// defaults to 0
myChart.minSegmentDuration([number]);
// return the number of timelines currently visible in the chart
myChart.getNLines();
// return the total number of timelines currently visible in the chart
myChart.getTotalNLines();
// determine whether the segment data color values are categorical (true) or quantitative (false)
// defaults to false
myChart.zQualitative([boolean]);
// get/set the color scale to be used for coloring the segments according to their data values
// this object should be a D3 color scale object
myChart.zColorScale([d3 scale object]);
// get/set the units of z data (tooltip descriptions)
myChart.zDataLabel([string]);
// get/set the color scale label
myChart.zScaleLabel([string]);
// data sorting function
// function(labelCmpFn, groupCompFn). 
// each comparison function should follow the signature function(nameA, nameB) and return a numeric value.
myChart.sort([[function, function]]);
// sort the timelines and groups in alpha-numeric order
// defaults to true
myChart.sortAlpha([[boolean]]);
// sort the timelines and groups in  chronological order of their most recent data point
// defaults to true
myChart.sortChrono([[boolean]]);
// set/get chart zoom
// defaults to null
myChart.zoomX([[startDate, endDate]]);
myChart.zoomY([[number, number]]);
// set/get chart's vertical zoom in terms of timeline labels
myChart.zoomYLabels([[number, number]]);
// callback
myChart.onZoom(([startDate, endDate], [startY, endY]); 
// determine whether to show an interactive timeline overview below the chart
// defaults to true
myChart.enableOverview([boolean]);
// get/set the time extent shown in the overview section below the chart
myChart.overviewDomain([[startDate, endDate]]);
// return data representation of timelines currently visible in the chart
myChart.getVisibleStructure();
// returns graphic (SVG) representation of currently visible chart
myChart.getSvg();
// determine whether to animate transitions
// defaults to true
myChart.enableAnimations([boolean]);
// callback
// callback will include the clicked label (if applicable) and group parameter: onLabelClick(<string>, <string>)
myChart.onLabelClick([function]);
// callback
// callback will return a segment object: onSegmentClick(segment)
myChart.onSegmentClick([function]);
// refresh the chart
myChart.refresh();