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 x(d.x); })
.y(function (d) { return y(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);
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:
If you are using transitions, you will also need:
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:
var data = [{ x: 1, y: 10 }, { x: 2 }, { x: 3 }, { x: 4, y: 15 }, { x: 5, y: 12 }];
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:
var data = [{ x: 1, y: 10 }, { x: 4, y: 15 }, { x: 5, y: 12 }];
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.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.