Skip to content
API Reference
basic
continuous
line

line

Mojo function 🡭

line

fn def line(df: DataFrame, x: String, y: String, step: StepStyle = StepStyle.NONE, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", x_title: String = "", y_title: String = "") -> Chart[Line]

line() over named columns of a dataframe_mojo DataFrame (#364); the axis titles default to the column names.

Args:

  • df (DataFrame): The frame to read.
  • x (String): The numeric column for the x axis.
  • y (String): The numeric column for the y axis.
  • step (StepStyle): Step (stairs) interpolation; see the numeric overload.
  • theme (Theme): Full styling knobs beyond this function’s own parameters.
  • width (Int): Pixel width of the returned Plot (.size()).
  • height (Int): Pixel height of the returned Plot (.size()).
  • title (String): The chart’s title, shown above the plot.
  • x_title (String): The x-axis caption; defaults to x.
  • y_title (String): The y-axis caption; defaults to y.

Returns:

Chart[Line]: The finished chart – unrendered.

Raises:

Error: A named column is missing, is not numeric, or has missing values.

fn def line(x: List[Float64], y: List[Float64], step: StepStyle = StepStyle.NONE, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", x_title: String = "", y_title: String = "") -> Chart[Line]

A line chart: continuous x/y data connected in order, the standard choice for showing a trend over a continuous variable such as time.

Mark.LINE over continuous x/y, connected in data order.

Example:

from dataviz import line
from dataviz import save
from dataviz.core.colors import BROWN
from dataviz import Theme

def main() raises:
    # Illustrative monthly active users after a product launch:
    # sustained growth with a summer plateau and year-end lift.
    var month: List[Float64] = [
        1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,
        13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24,
    ]
    var active_users_k: List[Float64] = [
        18, 24, 31, 39, 48, 57, 63, 66, 68, 74, 83, 96,
        104, 113, 125, 138, 149, 156, 158, 164, 177, 193, 214, 238,
    ]

    var c = line(
        month,
        active_users_k,
        title="Illustrative Monthly Active Users After Launch",
        x_title="Month since launch",
        y_title="Active users (thousands)",
        theme=Theme(
            mark_color=BROWN,
            line_width=3.0,
            show_gridlines=False,
        ),
    )
    save(c, "docs/src/examples/out_line.svg")

Example (Slope Chart): ```mojo from dataviz import line from dataviz import save from dataviz import Theme from dataviz.core.colors import SEAGREEN

def main() raises:
    # x=0.0 ("2023"), x=1.0 ("2024") -- revenue, in millions.
    var x: List[Float64] = [0.0, 1.0]
    var revenue: List[Float64] = [42.0, 61.0]

    var c = line(
        x,
        revenue,
        title="Revenue, 2023 to 2024",
        x_title="Year",
        y_title="Revenue ($M)",
        theme=Theme(
            mark_color=SEAGREEN,
            line_width=3.0,
            show_gridlines=False,
        ),
        width=320,
        height=420,
    )
    save(c, "docs/src/examples/out_slope.svg")
```

Example (Step Chart): ```mojo from dataviz import StepStyle, line from dataviz import save from dataviz.core.colors import CRIMSON from dataviz import Theme

def main() raises:
    # A central bank's policy rate holds flat between meetings and
    # moves only at one, so the straight interpolation a plain line
    # draws would show months of gradual drift that never happened.
    # StepStyle.POST puts the riser at the later month: the rate set
    # at a meeting is the rate in force until the next one.
    var month: List[Float64] = [
        0.0, 3.0, 6.0, 9.0, 12.0, 15.0, 18.0, 21.0, 24.0, 27.0
    ]
    var rate: List[Float64] = [
        1.75, 2.5, 3.25, 4.0, 4.5, 5.0, 5.25, 5.25, 4.75, 4.75
    ]

    var c = line(
        month,
        rate,
        step=StepStyle.POST,
        title="Policy Rate Changes",
        theme=Theme(mark_color=CRIMSON, line_width=3.0),
        x_title="Months since first hike",
        y_title="Policy rate (%)",
    )
    save(c, "docs/src/examples/out_step.svg")
```

Args:

  • x (List[Float64]): The continuous x column, one entry per point.
  • y (List[Float64]): The continuous y column, one entry per point.
  • step (StepStyle): Step (stairs) interpolation – NONE (the default, straight segments), or PRE/MID/POST for a value that holds until it changes rather than moving gradually between samples. See StepStyle for which riser placement claims what.
  • theme (Theme): Full styling knobs beyond this function’s own parameters (colors, margins, fonts, gridlines, …) – see Theme’s docstring.
  • width (Int): Pixel width of the returned Plot (.size()).
  • height (Int): Pixel height of the returned Plot (.size()).
  • title (String): The chart’s title, shown above the plot.
  • x_title (String): The x-axis caption.
  • y_title (String): The y-axis caption.

Returns:

Chart[Line]: The finished chart – unrendered. Call save(plot, path) to write it (any of .svg/.png/.bmp), or render(plot)/render_svg(plot) for the explicit two-step.

Raises:

fn def line[x_dtype: DType, y_dtype: DType](x: List[Scalar[x_dtype]], y: List[Scalar[y_dtype]], step: StepStyle = StepStyle.NONE, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", x_title: String = "", y_title: String = "") -> Chart[Line]

line() generalized over numeric element type; see scatter()’s DType overload above. Delegates to the concrete overload above.

Parameters:

  • x_dtype (DType)
  • y_dtype (DType)

Args:

  • x (List[Scalar[x_dtype]])
  • y (List[Scalar[y_dtype]])
  • step (StepStyle)
  • theme (Theme)
  • width (Int)
  • height (Int)
  • title (String)
  • x_title (String)
  • y_title (String)

Returns:

Chart[Line]

Raises:

fn def line(x: List[Morrow], y: List[Float64], step: StepStyle = StepStyle.NONE, theme: Theme = Theme(WHITE, Color(UInt8(30), UInt8(100), UInt8(180), UInt8(255)), Color(UInt8(80), UInt8(80), UInt8(80), UInt8(255)), Color(UInt8(225), UInt8(225), UInt8(225), UInt8(255)), Color(UInt8(40), UInt8(40), UInt8(40), UInt8(255)), SIMD(12), SIMD(3.5), SIMD(2), Int(60), Int(20), Int(20), Int(50), True, False, False, Color(UInt8(240), UInt8(240), UInt8(240), UInt8(255)), Int(3), Color(UInt8(60), UInt8(110), UInt8(200), UInt8(255)), Color(UInt8(235), UInt8(235), UInt8(235), UInt8(255)), Color(UInt8(220), UInt8(90), UInt8(40), UInt8(255)), ColorRamp(), ColorPalette(), SIMD(3), SIMD(15), True, SIMD(1), Int(0), False, Color(UInt8(200), UInt8(60), UInt8(60), UInt8(255)), Color(UInt8(224), UInt8(224), UInt8(224), UInt8(255)), Color(UInt8(120), UInt8(120), UInt8(120), UInt8(255)), Color(UInt8(100), UInt8(100), UInt8(100), UInt8(255)), Color(UInt8(230), UInt8(230), UInt8(230), UInt8(255)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), UInt8(90), UInt8(160), False, False, SIMD(0), SIMD(18), SIMD(14), Color(UInt8(110), UInt8(110), UInt8(110), UInt8(255)), SIMD(14), Color(UInt8(150), UInt8(150), UInt8(150), UInt8(255)), Color(UInt8(224), UInt8(236), UInt8(246), UInt8(200)), Color(UInt8(255), UInt8(255), UInt8(255), UInt8(255)), True, False, False, True, AxisPosition.EDGE, AxisPosition.EDGE, String("sans-serif"), True, UInt8(90), Int(5), Int(4), Int(130), Int(14), Int(8), Int(14), Int(100), Int(8), SIMD(4), OutputFormat.SVG, Tooltips.AUTO, Missing.DRAW, String("(missing)"), Int(1000), False, LineStyle.SOLID, SIMD(1.5), LineStyle.SOLID, LegendPosition.RIGHT, XAxisLabelRotation.AUTO, TickFormat.AUTO, TickFormat.AUTO), width: Int = Int(640), height: Int = Int(420), title: String = "", x_title: String = "", y_title: String = "") -> Chart[Line]

line() over a time axis: x as dates or timestamps rather than bare numbers, so the axis reads “Mar 2026” instead of “20515”.

See Plot.encode_time() for how the axis is built and _time_ticks (scale.mojo) for where the ticks land. Everything else is the numeric overload above.

Example (Time Axis): ```mojo from morrow import Morrow

from dataviz import line, save
from dataviz import Theme
from dataviz.core.colors import STEELBLUE

def main() raises:
    # Six months of daily readings. Before #195 this axis read
    # 20454, 20504, 20554 -- epoch day counts -- because the
    # only way to plot a date was to convert it by hand. Now the
    # ticks land on month starts, which is where a reader of a
    # six-month series looks.
    var day = List[Morrow]()
    var latency_ms = List[Float64]()
    var start = Morrow.get(2026, 1, 1)
    for i in range(180):
        day.append(start.shift(days=i))
        # A slow upward drift with a weekly cycle on top.
        var weekday = Float64((i + 3) % 7)
        latency_ms.append(
            82.0 + Float64(i) * 0.06 + weekday * 1.8
        )
    var c = line(
        day,
        latency_ms,
        title="Illustrative Checkout Latency by Day",
        theme=Theme(mark_color=STEELBLUE),
        y_title="p50 latency (ms)",
    )
    save(c, "docs/src/examples/out_line_time.svg")
```

Args:

  • x (List[Morrow]): The timestamps, one per point.
  • y (List[Float64]): The continuous y column, one entry per point.
  • step (StepStyle): Step (stairs) interpolation; see the numeric overload.
  • theme (Theme): Visual theme.
  • width (Int): Canvas width in pixels.
  • height (Int): Canvas height in pixels.
  • title (String): Chart title.
  • x_title (String): The x-axis caption.
  • y_title (String): The y-axis caption.

Returns:

Chart[Line]: The finished chart – unrendered.

Raises:

Error: morrow could not convert a value to a timestamp.

areascatter