timelines-chart

Timelines Chart ============== [![NPM package][npm-img]][npm-url] [![Build Size][build-size-img]][build-size-url] [![NPM Downloads][npm-downloads-img]][npm-downloads-url] <a href="//vasturiano.github.io/timelines-chart/example/categorical/"><img width="80%" src="https://vasturiano.github.io/timelines-chart/example/preview.png"></a> A parallel timelines layout (swimlanes) for representing state of time-series over time. Each timeline segment can be assigned a value on a color scale, either continuous (heatmap mode) or ordinal (for categorical representation). Time-series can be grouped into logical groups, represented as distinct sections. Allows for exploration using drag-to-zoom or a timeline brush. Check out the examples: * [Categorical](https://vasturiano.github.io/timelines-chart/example/categorical/) * [Continuous (Heatmap)](https://vasturiano.github.io/timelines-chart/example/heatmap/) * [Custom Time Format](https://vasturiano.github.io/timelines-chart/example/custom-time-format/) ## Quick start ```js import TimelinesChart from 'timelines-chart'; ``` or using a *script* tag ```html <script src="//unpkg.com/timelines-chart"></script> ``` then ```js const myChart = new TimelinesChart(<myDOMElement>) .data(<myData>); ``` ## API reference | Method | Description | Default | | --- | --- | --- | | data([array]) | Getter/setter for chart data (see below for syntax details). | `[]` | | width([number]) | Getter/setter for the chart width in px. | *<window width>* | | maxHeight([number]) | Getter/setter for the chart's maximum height in px. | 640 | | maxLineHeight([number]) | Getter/setter for the maximum height of each line, in px. | 12 | | leftMargin([number]) | Getter/setter for the chart's left margin, which contains the left-side group axis labels. | 90 | | rightMargin([number]) | Getter/setter for the chart's right margin, which contains the right-side series axis labels. | 100 | | topMargin([number]) | Getter/setter for the chart's top margin, which contains the color legend. | 26 | | bottomMargin([number]) | Getter/setter for the chart's bottom margin, which contains the time axis labels. | 30 | | useUtc([boolean]) | Getter/setter for whether to display time in the local time zone (`false`) or in UTC (`true`). | false | | timeFormat([string]) | Getter/setter for the time format to use in tooltips. See [d3-time-format](https://github.com/d3/d3-time-format#locale_format) for available options. | `%Y-%m-%d %-I:%M:%S %p` | | xTickFormat([function]) | X axis tick label formatter function, as pass-through to [d3-axis](https://github.com/d3/d3-axis#axis_tickFormat). By default, it uses a [multi-scale time format](https://bl.ocks.org/mbostock/4149176). | | | dateMarker([date object]) | Getter/setter for the date marker to show as a vertical line. If a falsy value is used, no marker is shown. | `null` | | minSegmentDuration([number]) | Getter/setter for the minimum time duration (in msecs) of a segment in order for it to be shown. | 0 | | minSegmentWidth([number]) | Getter/setter for the minimum displayed px width of a segment. | 1 | | getNLines() | Returns number of timelines currently visible in the chart. | - | | getTotalNLines() | Returns total number of timelines in the chart. | - | | zQualitative([boolean]) | Getter/setter for whether the segment data color values are categorical (true) or quantitative (false). This will affect how the color legend is presented, and changing it will automatically toggle the `zColorScale` between defaults. | false | | zColorScale([d3 scale object]) | Getter/setter for the color scale to be used for coloring the segments according to their data values. This object should be a D3 color scale object. | qualitative: `d3.scaleOrdinal(<color-list>)` quantitative: `d3.scaleSequential(<color-interpolator>)` | | zDataLabel([string]) | Getter/setter for the units of z data. Used in the tooltip descriptions. | | | zScaleLabel([string]) | Getter/setter for the color scale label. Only applicable to quantitative z scales. | | | sort([[function, function]]) | Sorts the timelines and groups according to two name comparison functions: `function(labelCmpFn, groupCompFn)`. Each comparison function should follow the signature `function(nameA, nameB)` and return a numeric value. | `(<alpha-numeric-cmp>, <alpha-numeric-cmp>)` | | sortAlpha([[boolean]]) | Sorts the timelines and groups in alpha-numeric order. The boolean parameter indicates whether the order should be ascending (`true`) or descending (`false`). | true | | sortChrono([[boolean]]) | Sorts the timelines and groups in chronological order of their most recent data point. The boolean parameter indicates whether the order should be ascending (`true`) or descending (`false`). | true | | zoomX([[startDate, endDate]]) | Getter/setter for the chart's time (horizontal) zoom. A null value indicates a zoom reset to full extent. | `null` | | zoomY([[number, number]]) | Getter/setter for the chart's vertical zoom. The parameter should follow the syntax `[<start row index>, <end row index>]`. A null value indicates a zoom reset to full extent. | `null` | | zoomYLabels([[number, number]]) | Getter/setter for the chart's vertical zoom in terms of timeline labels. The parameter should follow the syntax `[<start label>, <end label>]`. A null value indicates a zoom reset to full extent. | `null` | | onZoom([function]) | Getter/setter for the callback function for user initiated zoom (incl. zoom resets). Callback will have two parameters: `onZoom([startDate, endDate], [startY, endY])`. | `null` | | enableOverview([boolean]) | Getter/setter for whether to show an interactive timeline overview below the chart. | true | | overviewDomain([[startDate, endDate]]) | Getter/setter for the time extent shown in the overview section below the chart. | *<auto-derived from data: `[minTs, maxTs]`>* | | getVisibleStructure() | Returns data representation of timelines currently visible in the chart. | - | | getSvg() | Returns graphic (SVG) representation of currently visible chart. | - | | enableAnimations([boolean]) | Getter/setter for whether to animate transitions. | true | | onLabelClick([function]) | Getter/setter for the callback function for clicking on the Y axis labels. Callback will include the clicked label (if applicable) and group parameter: `onLabelClick(<string>, <string>)`. | `null` | | onSegmentClick([function]) | Getter/setter for the callback function for clicking on a segment. Callback will return a segment object: `onSegmentClick(segment)`. | `null` | | segmentTooltipContent([function]) | Getter/setter for the callback function to populate a custom tooltip for segments. The segment data point is provided as sole argument: `segmentTooltipContent(d)`. Supports plain text or HTML content. | `null` | | refresh() | Rerenders chart. | - | ## Data syntax ``` [ { group: "group1name", data: [ { label: "label1name", data: [ { timeRange: [<date>, <date>], val: <val: number (continuous dataScale) or string (ordinal dataScale)> }, { timeRange: [<date>, <date>], val: <val> }, ... ] }, { label: "label2name", data: [...] }, ... ], }, { group: "group2name", data: [...] }, ... ] ``` ## Giving Back [![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=L398E7PKP47E8&currency_code=USD&source=url) If this project has helped you and you'd like to contribute back, you can always [buy me a ☕](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=L398E7PKP47E8&currency_code=USD&source=url)! [npm-img]: https://img.shields.io/npm/v/timelines-chart [npm-url]: https://npmjs.org/package/timelines-chart [build-size-img]: https://img.shields.io/bundlephobia/minzip/timelines-chart [build-size-url]: https://bundlephobia.com/result?p=timelines-chart [npm-downloads-img]: https://img.shields.io/npm/dt/timelines-chart [npm-downloads-url]: https://www.npmtrends.com/timelines-chart