30:[] 2e:{"title":"d3.line","cells":[{"id":0,"value":"# d3.line\n\n[d3.line](https://d3js.org/d3-shape/line) creates a *shape* that follows a sequence of points. Its default curve interpolator connects the points with straight line segments, creating a polygonal chain or polyline:","pinned":false,"hidden":false,"mode":"md"},{"id":8,"value":"p = d3.line()([[10, 60], [40, 90], [60, 10], [190, 10]])","pinned":true,"hidden":false,"mode":"ojs"},{"id":114,"value":"The result is a SVG path string, that can be used inside a path _d_ attribute.","pinned":false,"hidden":false,"mode":"md"},{"id":20,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":17,"value":"## Context: SVG or Canvas?\n\n[*line*.context](https://d3js.org/d3-shape/line#line_context) sets the drawing context. Like all shapes, d3.line builds upon [d3-path](https://observablehq.com/@d3/d3-path) and can optionally create a series of moveTo/lineTo instructions for canvas instead of SVG. To switch from one mode to the other, use\n~~~{js}\nline.context(context); // for canvas\n~~~\nor conversely\n~~~{js}\nline.context(null); // for SVG\n~~~\n","pinned":false,"hidden":false,"mode":"md"},{"id":39,"value":"In canvas, the following are equivalent:\n\n~~~{js}\nconst line = d3.line().context(context);\nline([[1, 3], [2, 7], [3, 2], [5, 2]]);\n~~~\n\n_and_\n~~~{js}\n{\n context.moveTo(1, 3);\n context.lineTo(2, 7);\n context.lineTo(3, 2);\n context.lineTo(5, 2);\n}\n~~~","pinned":false,"hidden":false,"mode":"md"},{"id":59,"value":"Both in SVG and canvas, the shape describes the series of movements of the pen — but it does not _draw_ the path.\n\nTo actually draw a path, in SVG use:\n>

<path d=\"line(data)\" stroke=\"black\" fill=\"none\">

\n\nor, with d3-selection:\n>

d3.select(…)\n>   .append(\"path\")\n>   .attr(\"d\", line(data))\n>   .attr(\"stroke\", \"black\")\n>   …\n\nand, in canvas:\n> \nline.context(context);\ncontext.beginPath();\nline(data);\ncontext.fill();\ncontext.stroke();\n
\n\nIn the following examples we’ll use SVG or canvas indifferently.","pinned":false,"hidden":false,"mode":"md"},{"id":108,"value":"## Accessors\n\nTo draw a line chart with actual data, we will need to use [scales](https://observablehq.com/@d3/introduction-to-d3s-scales) to get the (x,y) coordinates of the points. Remember that SVG and canvas usually position (0,0) at the top-left corner, *x* increasing towards the right of the canvas, and *y* increasing in direction of the bottom.\n\n*line*.x() sets or reads the *x* accessor for the line, and *line*.y the *y* accessor. For example here is a random walk in one direction (which we will represent vertically), on a hundred successive steps (which we’ll represent with an horizontal scale).","pinned":false,"hidden":false,"mode":"md"},{"id":156,"value":"walk = {\n  replay;\n  const data = [];\n  for (let i = 0, v = 2; i < 50; ++i) {\n    v += Math.random() - 0.5;\n    v = Math.max(Math.min(v, 4), 0);\n    data.push({step: i, value: v});\n    yield data;\n  }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":163,"value":"walkX = d3.scaleLinear()\n    .domain([0, 49])\n    .range([10, width - 10])","pinned":true,"hidden":false,"mode":"ojs"},{"id":168,"value":"walkY = d3.scaleLinear()\n    .domain([0, 4])\n    .range([200 - 10, 10])","pinned":true,"hidden":false,"mode":"ojs"},{"id":174,"value":"line = d3.line()\n    .x(d => walkX(d.step))\n    .y(d => walkY(d.value))","pinned":true,"hidden":false,"mode":"ojs"},{"id":191,"value":"line(walk)","pinned":true,"hidden":false,"mode":"ojs"},{"id":172,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":184,"value":"viewof replay = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":141,"value":"For most line charts (see our [Line Chart](https://observablehq.com/@d3/line-chart) and [Multi-Line Chart](https://observablehq.com/@d3/multi-line-chart) notebooks), the data should be sorted before being passed to d3.line — unless, of course, we are plotting the actual path of a drunk mosquito that zigs-zags across a room.","pinned":false,"hidden":false,"mode":"md"},{"id":198,"value":"// Using d3.shuffle to simulate unordered data\nsvg``","pinned":true,"hidden":false,"mode":"ojs"},{"id":212,"value":"But *x* does not always have to be monotonous; for example, if we are plotting a ball’s trajectory on a football field:","pinned":false,"hidden":false,"mode":"md"},{"id":215,"value":"ball = {\n  replay2;\n  // Start at the center of the field.\n  let vx = width / 2, vy = 250;\n  const data = [];\n  for (let i = 0; i < 1000; i++) {\n    // Random walk with large or small steps.\n    const l = Math.random() < 0.05 ? 100 : 10;\n    data.push({\n      step: i,\n      x: vx += l * (Math.random() - 0.5),\n      y: vy += l * (Math.random() - 0.5)\n    });\n    yield data;\n  }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":220,"value":"// The x and y accessors retrieve the corresponding attributes\n// shorthand equivalent to d3.line().x(d => d.x).y(d => d.y)\nfootballLine = d3.line(d => d.x, d => d.y)","pinned":true,"hidden":false,"mode":"ojs"},{"id":242,"value":"footballLine(ball)","pinned":true,"hidden":false,"mode":"ojs"},{"id":219,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":231,"value":"viewof replay2 = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":315,"value":"By default the *x* and *y* accessors retrieve d[0] and d[1].","pinned":false,"hidden":false,"mode":"md"},{"id":329,"value":"### Unknown\n\nWhen confronted with data points that are not well-defined, the *line* must absolutely not break (because a value is NaN) nor jump to a fixed point such as [0,0]. It should either ignore the point, or stop before (and restart after) it.\n\nThe first strategy is to omit the undefined points, by applying *line* to a filtered dataset in which all data points are well-defined — and interpolate between them. This strategy might be valuable if the data represents a continuous process with poorly-collected measurements.\n\nThe second strategy is to use *line*.defined, which sets (or reads) a function that returns true when the data point should be drawn, and false when the line should stop. (The default value for this function is the constant *true*.) This reflects the underlying data quality better, at the expense of continuity.","pinned":false,"hidden":false,"mode":"md"},{"id":328,"value":"As an example, let’s consider our random walk and transform some measurements into nulls, at random.","pinned":false,"hidden":false,"mode":"md"},{"id":327,"value":"badwalk = walk.map(d => ({\n  step: d.step,\n  value: Math.random() < 0.2 ? null : d.value,\n  real: d.value\n}))","pinned":true,"hidden":false,"mode":"ojs"},{"id":326,"value":"On these points, a default call to *line* will call the y accessor on null, resulting in the same y as if the value were 0: in essence, all the missing points are replaced by zeros, resulting in incorrect visual artifacts:","pinned":false,"hidden":false,"mode":"md"},{"id":325,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":324,"value":"Showing only the defined points results in a continuous line, but does not show explicitly where the data was interpolated (figured by a gray layer):","pinned":false,"hidden":false,"mode":"md"},{"id":323,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":322,"value":"Using *line*.defined can show this much more explicitly:","pinned":false,"hidden":false,"mode":"md"},{"id":321,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":320,"value":"A combination of the two approaches might give a better sense of the missing data while still highlighting the continuity:","pinned":false,"hidden":false,"mode":"md"},{"id":319,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":349,"value":"See also this standalone example of [a line with missing data](/@d3/line-with-missing-data).","pinned":false,"hidden":false,"mode":"md"},{"id":244,"value":"## Curves\n\nMaking straight line segments from one point to the next is so easy a [turtle](https://en.wikipedia.org/wiki/Turtle_%28robot%29) can do it. But there are other ways a path can join the dots. d3-shape offers several [curve factories](https://d3js.org/d3-shape/curve) that will enable a host of possibilities.\n\n[*line*.curve](https://d3js.org/d3-shape/line#line_curve) sets or reads the [curve factory](https://d3js.org/d3-shape/curve). For example, here’s the previous chart with the [d3.${curve}](https://d3js.org/d3-shape/curve#${curve}) factory:","pinned":false,"hidden":false,"mode":"md"},{"id":279,"value":"lc = d3.line()\n    .curve(d3[curve])\n    .x(d => walkX(d.step))\n    .y(d => walkY(d.value))","pinned":true,"hidden":false,"mode":"ojs"},{"id":406,"value":"viewof curve = html``","pinned":false,"hidden":false,"mode":"ojs"},{"id":258,"value":"svg``","pinned":false,"hidden":false,"mode":"ojs"},{"id":286,"value":"The default curve factory is [d3.curveLinear](https://d3js.org/d3-shape/curve#curveLinear), which creates the polyline (aka straight segments). In [Mona Lisa Histogram](https://observablehq.com/@d3/mona-lisa-histogram), a custom curve is created to wrap the area a bit more generously than d3.curveStepAfter would.","pinned":false,"hidden":false,"mode":"md"},{"id":456,"value":"## Radial lines\n\nSee [d3.lineRadial](https://observablehq.com/@d3/d3-lineradial) for a line generator that, instead of cartesian coordinates (*x* and *y*), works with radial coordinates (*angle* and *radius*).","pinned":false,"hidden":false,"mode":"md"}],"files":"$W30","stdlib":"1","titling":"auto"}