Skip to content

line ​

Draws a path. It has two forms. The shape form, line(x=..., y=...), draws one path per group through its rows. The connector form draws through a set of points another chart placed, so it is often paired with select_all(). select_all hands line an array of refs, and the line reads placed geometry off them.

python
from gofish import layer, chart, scatter, blank, select_all, line

layer([
    chart(catch_locations)
        .flow(scatter(by="lake", x="x", y="y"))
        .mark(blank().name("points")),
    chart(select_all("points")).mark(line()),
]).render(w=500, h=300, axes=True)

Signature ​

python
# Shape form
line(x=..., y=..., stroke=None, stroke_width=None, stroke_dasharray=None, opacity=None, curve=None) -> Mark

# Connector form
line(stroke=None, stroke_width=None, stroke_dasharray=None, opacity=None, curve=None, along=None, w=None, h=None, em_x=None, em_y=None) -> Mark

Parameters ​

A path. Given x and y, the shape form: the mark owns its rows and draws one path per group through them, sorted by x. Without them, the connector form: the path between the centers of consecutive marks another flow placed, in bag form over a ref array, or pairwise {from, to} form over rows with two ref columns.

OptionTypeDefaultDescription
filterFilter | strA filter over this whole drawing: a Filter strategy (Filter.grayscale(), Filter.luminanceToAlpha()) or a raw CSS filter string ("blur(2px)", "url(#shadow)").
fillstrA line's path is never filled. fill is the channel the shared color scale reads: a field name or an accessor colors each line by group (it must be constant within the line), and it is the line color when stroke is omitted.
strokestrLine color, or a field name or accessor for a color scale (constant within the line). Defaults to fill.
stroke_widthfloat1Line thickness in pixels.
stroke_dasharraystrRaw SVG stroke-dasharray (e.g. "12") for a dashed line.
opacityfloatOpacity, 0 to 1.
blend_modestr"normal"How connectors mix where they overlap (CSS mix-blend-mode).
curveCurveScreen-space path shape, made by a call in the Curve family: Curve.linear(), Curve.step(), Curve.monotone(), Curve.smooth(), Curve.catmullRom(), Curve.bezier(), Curve.orthogonal({bend}), Curve.arc({direction}) or Curve.perfectArrows({bow, ...}). Curve.step(), Curve.linear(), Curve.monotone() and Curve.smooth() are read over the parameter of the run, from the least to the most smooth. Curve.step() holds every value that depends on the ordering field until the next point, then jumps: a staircase when the ordering field is an axis (a line chart over years), and straight jumps between the points when it is not (a connected scatter plot). Curve.monotone() is piecewise monotone: between two neighboring points each coordinate only rises or only falls, so the curve never goes past either point. It does not make the whole line monotone: the line still turns where the data turns, and the turn sits exactly on the data point. For a path in x and y (a connected scatter plot) this holds for x and y separately, over the ordering field. It is the same curve as d3 curveMonotoneX and Vega-Lite interpolate "monotone". Curve.smooth() rounds a peak a little past its point, but keeps a run of equal values flat. Curve.catmullRom() is a centripetal Catmull-Rom through the points on screen. It can overshoot between points, and it is not used when reading values over time (a mark moving along the run follows a data-space curve). Omitted, it is Curve.monotone() on a homogeneous continuous connection axis, else Curve.linear(). The shape form reads its curve over x, so it takes Curve.linear(), Curve.step(), Curve.monotone() or Curve.smooth(), and Curve.monotone() when omitted.
dirstrConnection axis.
sourceAnyAnchor-mode start point: a normalized [fx, fy] on the mark's bbox, or a start/middle/end keyword.
targetAnyAnchor-mode end point; see source.
from_strPairwise form: column holding the source ref.
tostrPairwise form: column holding the target ref.
alongstrNames a flow tier by its by field: that tier becomes the path tier (threading its groups in order) and every OTHER grouping tier splits. Omitted: the path tier is inferred from the flow shape. Naming a field that matches no tier, or using along where the mark doesn't fuse over this chart's own flow (a refs bag, or the pairwise from/to form), is an error.
em_xboolBlank-fusion anchor key: placed directly in .mark() position, line(opts) elaborates to an invisible anchor tier (a blank() carrying just {w, h, emX, emY}) plus this connector — see the mark construct's doc. Ignored by line itself.
em_yboolBlank-fusion anchor key — see emX. Ignored by line itself.
wint | float | strBlank-fusion anchor key — see emX. Ignored by line itself.
hint | float | strBlank-fusion anchor key — see emX. Ignored by line itself.
xint | float | strShape form: each row's x, a numeric or time column, a field expression, or an accessor. The path runs through the rows sorted by x, read between them as curve says; two rows of one group at one x are an error. Needs y.
yint | float | strShape form: each row's y, a position on the y axis. Needs x.

Returns a Mark for use in .mark().

Curve ​

curve takes a member of the Curve family, such as Curve.monotone() or Curve.orthogonal(bend="auto"). When curve is left out, a line over a continuous axis uses Curve.monotone(), and any other line uses Curve.linear(). The Curve page compares the curves.

Shape form ​

Given x and y, the line draws one path per group through its rows, sorted by x. x must be a numeric or time column. Two rows of one group at the same x are an error: split them with group first. The curve defaults to Curve.monotone() and takes Curve.linear(), Curve.step(), Curve.monotone() or Curve.smooth().

python
(
    chart(prices, schema={"date": Unit.time()})
    .flow(group(by="symbol"))
    .mark(line(x="date", y="price", stroke="symbol"))
)

Function channels ​

In JavaScript, the shape form reads a function value made with fun in place of a column. Python does not support function values yet: fun raises. Give the function's values at sample points as rows instead.

The line pattern ​

A line needs points to connect. The idiomatic recipe:

  1. One chart positions invisible blank marks and names the layer with .name("points").
  2. A second chart selects that layer — chart(select_all("points")) — and draws a line() through it.
  3. layer([...]) composes the two.

This separation lets the same positioned points back both a line and, say, circles drawn on top.

Default grouping ​

A line fused into a flow — in .mark() position or as .layer() sugar over the previous tier's marks — splits at the flow's own grouping by default: one tier lays the line's path, and every other grouping in the flow splits it into separate lines. You don't restate the split — the flow one line up already declared it, and line has no option that spells the split directly.

When you need a different path tier than the one inference would pick, name it with along: along="year" finds the flow tier whose by is "year", makes it the path, and splits by every other grouping tier instead. Naming a field no tier groups by is an error. This doesn't apply to a line drawn over an explicit refs bag (chart(select_all(...))) or the pairwise from/to form — along is only meaningful when the line fuses into a chart's own flow, and throws if used on either of those. A refs bag spells its split structurally instead, with an upstream flow(group(by="species")).

A slope chart is a good example of why the default matters: ten barley varieties across six field sites, one short line per site-variety pair from 1931 to 1932, with no line crossing a site boundary.

python
from gofish import chart, spread, scatter, line

chart(barley, axes=True).flow(
    spread(by="site", dir="x", spacing=110),
    spread(by="year", dir="x", spacing=36),
    scatter(by="variety", y="yield"),
).mark(line(stroke="variety", stroke_width=2))

No option at all: the innermost tier that lays out the travel axis (the year spread) becomes the path, and every other grouping — site and variety — splits, giving one line per site-variety pair. Writing the same split by hand would take a composite key over both fields; naming it explicitly would be line(along="year", stroke="variety", stroke_width=2), which picks the same path tier the default already infers.

Sugar: .layer(line(...)) ​

When the line connects a chart's own marks, skip the two-chart select_all recipe and chain .layer() on the builder with a bare line(...):

python
from gofish import chart, scatter, circle, line

chart(driving_shifts, axes=True).flow(
    scatter(by="year", x="miles", y="gas")
).mark(circle(r=4, fill="white", stroke="black", stroke_width=2)).layer(
    line(stroke="black", stroke_width=2)
).render(w=500, h=300)

See .layer() for the full semantics, including the zBelow-by-default paint order and the desugaring to the explicit layer([...]) + select_all form (which is still what you want to connect another chart's marks).

Sugar: .mark(line(...)) (blank-fusion) ​

When there's no earlier tier at all — just raw data that needs both fresh anchors and a connector — place line(...) directly in .mark() position and skip .layer() too:

python
chart(catch_locations).flow(
    scatter(by="lake", x="x", y="y")
).mark(line())

# ...is sugar for the explicit two-tier form:
chart(catch_locations).flow(
    scatter(by="lake", x="x", y="y")
).mark(blank()).layer(line())

See .layer()'s blank-fusion section for the full desugaring rule (the w/h/em_x/em_y anchor/connector key split, .name() chaining, and when the rule doesn't fire).

The w/h/em_x/em_y anchor channels are only meaningful when line gets to synthesize its own anchors this way; passing them to a line that instead connects already-drawn marks (an empty-scope chart() tier inside .layer(), or chart(select_all(...))/chart(ref(...))) is an error, since there's nothing left for them to anchor.

Examples ​

python
# Styled line
chart(select_all("points")).mark(line(stroke="black", stroke_width=2))