d3-line-chunked

d3-line-chunked

A d3 plugin that renders a line with potential gaps in the data by styling the gaps differently from the defined areas. Single points are rendered as circles. Transitions are supported.

Demo: http://peterbeshai.com/vis/d3-line-chunked/

Example Usage

var lineChunked = d3.lineChunked()
  .x(function (d) { return xScale(d.x); })
  .y(function (d) { return yScale(d.y); })
  .curve(d3.curveLinear)
  .defined(function (d) { return d.y != null; })
  .lineStyles({
    stroke: '#0bb',
  });

d3.select('svg')
  .append('g')
    .datum(lineData)
    .transition()
    .duration(1000)
    .call(lineChunked);

Example with multiple lines

var lineChunked = d3.lineChunked()
  .x(function (d) { return xScale(d.x); })
  .y(function (d) { return yScale(d.y); })
  .defined(function (d) { return d.y != null; })
  .lineStyles({
    stroke: (d, i) => colorScale(i),
  });

var data = [
  [{ 'x': 0, 'y': 42 }, { 'x': 1, 'y': 76 }, { 'x': 2, 'y': 54 }],
  [{ 'x': 0, 'y': 386 }, { 'x': 1 }, { 'x': 2, 'y': 38 }, { 'x': 3, 'y': 192 }],
  [{ 'x': 0, 'y': 325 }, { 'x': 1, 'y': 132 }, { 'x': 2 }, { 'x': 3, 'y': 180 }]
];

// bind data
var binding = d3.select('svg').selectAll('g').data(data);

// append a `<g>` for each line
var entering = binding.enter().append('g');

// call lineChunked on enter + update
binding.merge(entering)
  .transition()
  .duration(transitionDuration / 3)
  .call(lineChunked);

// remove `<g>` when exiting
binding.exit().remove();

Development

Get rollup watching for changes and rebuilding

npm run watch

Run a web server in the example directory

cd example
php -S localhost:8000

Go to http://localhost:8000

Installing

If you use NPM, npm install d3-line-chunked. Otherwise, download the latest release.

Note that this project relies on the following d3 features and plugins:

• d3-array
• d3-selection
• d3-shape

If you are using transitions, you will also need:

• d3-interpolate
• d3-interpolate-path (plugin)

The only thing not included in the default d3 v4 build is the plugin d3-interpolate-path. You'll need to get that separately.

API Reference

# d3.lineChunked()

Constructs a new generator for chunked lines with the default settings.

# lineChunked(context)

Render the chunked line to the given context, which may be either a d3 selection of SVG containers (either SVG or G elements) or a corresponding d3 transition. Reads the data for the line from the datum property on the container.

# lineChunked.x([x])

Define an accessor for getting the x value for a data point. See d3 line.x for details.

# lineChunked.y([y])

Define an accessor for getting the y value for a data point. See d3 line.y for details.

# lineChunked.curve([curve])

Get or set the d3 curve factory for the line. See d3 line.curve for details. Define an accessor for getting the curve value for a data point. See d3 line.curve for details.

# lineChunked.defined([defined])

Get or set defined, a function that given a data point (d) returns true if the data is defined for that point and false otherwise. This function is important for determining where gaps are in the data when your data includes points without data in them.

For example, if your data contains attributes x and y, but no y when there is no data available, you might set defined as follows:

// sample data
var data = [{ x: 1, y: 10 }, { x: 2 }, { x: 3 }, { x: 4, y: 15 }, { x: 5, y: 12 }];

// returns true if d has a y value set
function defined(d) {
  return d.y != null;
}

It is only necessary to define this if your dataset includes entries for points without data.

The default returns true for all points.

# lineChunked.isNext([isNext])

Get or set isNext, a function to determine if a data point follows the previous. This function enables detecting gaps in the data when there is an unexpected jump.

For example, if your data contains attributes x and y, and does not include points with missing data, you might set isNext as follows:

// sample data
var data = [{ x: 1, y: 10 }, { x: 4, y: 15 }, { x: 5, y: 12 }];

// returns true if current datum is 1 `x` ahead of previous datum
function isNext(previousDatum, currentDatum) {
  var expectedDelta = 1;
  return (currentDatum.x - previousDatum.x) === expectedDelta;
}

It is only necessary to define this if your data doesn't explicitly include gaps in it.

The default returns true for all points.

# lineChunked.transitionInitial([transitionInitial])

Get or set transitionInitial, a boolean flag that indicates whether to perform a transition on initial render or not. If true and the context that lineChunked is called in is a transition, then the line will animate its y value on initial render. If false, the line will appear rendered immediately with no animation on initial render. This does not affect any subsequent renders and their respective transitions.

The default value is true.

# lineChunked.extendEnds([[xMin, xMax]])

Get or set extendEnds, an array [xMin, xMax] specifying the minimum and maximum x pixel values (e.g., xScale.range()). If defined, the undefined line will extend to the values provided, otherwise it will end at the last defined points.

# lineChunked.accessData([accessData])

Get or set accessData, a function that specifies how to map from a dataset entry to the array of line data. This is only useful if your input data doesn't use the standard form of [point1, point2, point3, ...]. For example, if you pass in your data as { results: [point1, point2, point3, ...] }, you would want to set accessData to data => data.results. For convenience, if your accessData function simply accesses a key of an object, you can pass it in directly: accessData('results') is equivalent to accessData(data => data.results).

The default value is the identity function data => data.

# lineChunked.lineStyles([lineStyles])

Get or set lineStyles, an object mapping style keys to style values to be applied to both defined and undefined lines. Uses syntax similar to d3-selection-multi.

# lineChunked.lineAttrs([lineAttrs])

Get or set lineAttrs, an object mapping attribute keys to attribute values to be applied to both defined and undefined lines. The passed in lineAttrs are merged with the defaults. Uses syntax similar to d3-selection-multi.

The default attrs are:

{
  fill: 'none',
  stroke: '#222',
  'stroke-width': 1.5,
  'stroke-opacity': 1,
}

# lineChunked.gapStyles([gapStyles])

Get or set gapStyles, an object mapping style keys to style values to be applied only to undefined lines. It overrides values provided in lineStyles. Uses syntax similar to d3-selection-multi.

# lineChunked.gapAttrs([gapAttrs])

Get or set gapAttrs, an object mapping attribute keys to attribute values to be applied only to undefined lines. It overrides values provided in lineAttrs. The passed in gapAttrs are merged with the defaults. Uses syntax similar to d3-selection-multi.

The default attrs are:

{
  'stroke-dasharray': '2 2',
  'stroke-opacity': 0.2,
}

# lineChunked.pointStyles([pointStyles])

Get or set pointStyles, an object mapping style keys to style values to be applied to points. Uses syntax similar to d3-selection-multi.

# lineChunked.pointAttrs([pointAttrs])

Get or set pointAttrs, an object mapping attr keys to attr values to be applied to points (circles). Note that if fill is not defined in pointStyles or pointAttrs, it will be read from the stroke color on the line itself. Uses syntax similar to d3-selection-multi.