Charts

Axes, number lines, polar axes, plots and data charts.

Contents:

• k.PolarAxes: Polar axes (rings and spokes): r=(0, r_max, step), radius= in units, spokes=.
• k.Axes: Cartesian axes with ticks, labels and an optional grid: x=(min, max, step), y=(min, max), labels=("x", "y"), width=/height= in units.
• k.NumberLine: A horizontal number line: a k.Axes with only the x axis.
• Plot: A curve y = fn(x) of an axes.
• k.BarChart: Bar chart from a table: x= is the category column, y= the value column and key= identifies each bar.
• k.LineChart: A k.Axes with one line per y= column (one or several), connecting the table's points in x= order.
• k.Table: Table of k.Text with a highlighted header; columns= selects and orders the columns.

Methods in this area:

• ax.parametric: Parametric curve (fx(t), fy(t)) for t=(start, end); clipped to the visible ranges.
• ax.plot: Draws the curve y = fn(x) on the axes, with adaptive sampling.
• ax.area: Filled region under a curve (down to the x axis) or between two curves (between=).
• ax.vline: Vertical line on the axes at at= (accepts a signal: the line moves with it); style="dashed" makes it dashed.
• ax.hline: Horizontal line on the axes at at= (accepts a signal); style="dashed" makes it dashed.
• ax.scatter: Points (xs[i], ys[i]) on the axes, as a group of k.Dot.
• ax.zoom_to: Named transition: animates the visible ranges of the axes (x=(a, b), y=(c, d)).
• ax.point: Data point (x, y) in world coordinates, reactive when x or y are signals.
• curve.point_at: World position of the curve at x; reactive when x is a signal.
• curve.tangent_at: Tangent segment length units long, centered on the curve at x, reactive when x is a signal.
• curve.slope_at: Numerical derivative of the curve at x, reactive when x is a signal.

Back to the reference index.

k.PolarAxes (class)#

k.PolarAxes(
    r: tuple[float, ...] = (0, 1),
    *,
    radius: float = 3.0,
    spokes: int = 12,
    labels: bool = True,
    **props: Unpack[UnplacedKeywords],
)

Polar axes (rings and spokes): r=(0, r_max, step), radius= in units, spokes=. pa.plot(lambda a: r(a)) draws r = f(θ); pa.point(r, θ) gives the world position.

Parameters:

Props (animatable with .to(), settable with .set() or in the constructor):

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Example:

def petals(a: float) -> float:
    return abs(k.cos(3 * a))

@k.scene
def rose(s: k.Scene):
    pa = k.PolarAxes(r=(0, 1, 0.25), radius=3).place(at="center")
    curve = pa.plot(petals, color=k.PINK)
    s.add(pa)
    s.play(k.draw(curve), duration=2)

See also: k.Axes, ax.parametric.

Members:

• local_point: Point at radius r (data units) and angle theta (radians, from +x), in the axes' own coordinates.
• point: World position of (r, theta).
• plot: Curve r = fn(theta) (sampled at build, in the axes' coordinates).

Inherited from k.Group: children, to, swap, insert, pop, fit. Inherited from k.Node: set, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

k.PolarAxes.local_point (method)

polaraxes.local_point(r: FloatVal, theta: FloatVal) -> Expr[Vec]

Point at radius r (data units) and angle theta (radians, from +x), in the axes' own coordinates.

Parameters:

k.PolarAxes.point (method)

polaraxes.point(r: FloatVal, theta: FloatVal) -> Expr[Vec]

World position of (r, theta).

Parameters:

k.PolarAxes.plot (method)

polaraxes.plot(
    fn: Callable[[float], float],
    *,
    theta: tuple[float, float] = (0.0, 6.283185307179586),
    samples: int = 360,
    color: ColorLike | None = None,
    **style: Unpack[PlotStyleKeywords],
) -> Path

Curve r = fn(theta) (sampled at build, in the axes' coordinates).

Parameters:

k.Axes (class)#

k.Axes(
    x: Sequence[float] = (0, 10),
    y: Sequence[float] = (0, 5),
    *,
    labels: tuple[str, str] | None = None,
    grid: bool = False,
    width: float = 8.0,
    height: float = 4.5,
    tick_labels: bool = True,
    **props: Unpack[UnplacedKeywords],
)

Cartesian axes with ticks, labels and an optional grid: x=(min, max, step), y=(min, max), labels=("x", "y"), width=/height= in units. The visible ranges are signals: ax.zoom_to(...) animates them and everything on the axes follows.

Parameters:

Props (animatable with .to(), settable with .set() or in the constructor):

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Example:

@k.scene
def axes(s: k.Scene):
    ax = k.Axes(x=(0, 10, 2), y=(0, 5, 1), labels=("t", "v"), grid=True).place(at="center")
    s.play(k.draw(ax))
    s.wait(0.5)

See also: ax.plot, ax.zoom_to, k.NumberLine.

Members:

• map_x: Data x → x in the axes' own coordinates (reactive: follows zooms).
• map_y: Data y → y in the axes' own coordinates (reactive: follows zooms).
• local_point: Data point in the axes' own coordinates.
• point: Data point (x, y) in world coordinates, reactive when x or y are signals.
• plot: Draws the curve y = fn(x) on the axes, with adaptive sampling.
• area: Filled region under a curve (down to the x axis) or between two curves (between=).
• vline: Vertical line on the axes at at= (accepts a signal: the line moves with it); style="dashed" makes it dashed.
• hline: Horizontal line on the axes at at= (accepts a signal); style="dashed" makes it dashed.
• scatter: Points (xs[i], ys[i]) on the axes, as a group of k.Dot.
• parametric: Parametric curve (fx(t), fy(t)) for t=(start, end); clipped to the visible ranges.
• bars: Vertical bars at data xs with data heights (from the x axis); width is in data units.
• zoom_to: Named transition: animates the visible ranges of the axes (x=(a, b), y=(c, d)).

Inherited from k.Group: children, to, swap, insert, pop, fit. Inherited from k.Node: set, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

k.Axes.map_x (method)

ax.map_x(x: FloatVal) -> Expr[float]

Data x → x in the axes' own coordinates (reactive: follows zooms).

Parameters:

k.Axes.map_y (method)

ax.map_y(y: FloatVal) -> Expr[float]

Data y → y in the axes' own coordinates (reactive: follows zooms).

Parameters:

k.Axes.local_point (method)

ax.local_point(x: FloatVal, y: FloatVal) -> Expr[Vec]

Data point in the axes' own coordinates.

Parameters:

k.Axes.point (method)

ax.point(x: FloatVal, y: FloatVal) -> Expr[Vec]

Data point (x, y) in world coordinates, reactive when x or y are signals. It is the target of place(at=...) for markers on the axes.

Parameters:

Example:

@k.scene
def point(s: k.Scene):
    ax = k.Axes(x=(0, 10, 2), y=(0, 10, 2)).place(at="center")
    pin = k.Dot(r=0.12, fill=k.RED).place(at=ax.point(3, 9))
    label = k.Text("(3, 9)", size=0.35).place(right_of=pin, gap=0.2)
    s.play(k.draw(ax))
    s.play(k.fade_in(pin, label))

See also: curve.point_at, obj.place.

k.Axes.plot (method)

ax.plot(
    fn: PlotFunction,
    *,
    until: FloatExpr | None = None,
    from_: FloatExpr | None = None,
    domain: tuple[float, float] | None = None,
    color: ColorLike | None = None,
    label: str | None = None,
    samples: int = 160,
    **style: Unpack[PlotStyleKeywords],
) -> Plot

Draws the curve y = fn(x) on the axes, with adaptive sampling. fn uses k functions (k.sin, k.max...), so the same function works for floats and signals. until=/from_= accept signals: the curve grows as the signal moves. label= puts a label at the end of the curve.

Parameters:

Example:

def wave(x: float) -> float:
    return 2 + 1.5 * k.sin(x)

@k.scene
def wave_plot(s: k.Scene):
    ax = k.Axes(x=(0, 10, 2), y=(0, 4, 1)).place(at="center")
    t = k.signal(0.0)
    ax.plot(wave, until=t, color=k.YELLOW, label="wave")
    s.play(k.draw(ax))
    s.play(t.to(10), duration=3, ease=k.ease.linear)

See also: curve.point_at, ax.area, k.sin.

k.Axes.area (method)

ax.area(
    f: Plot | PlotFunction,
    *,
    between: Plot | PlotFunction | None = None,
    domain: tuple[float, float] | None = None,
    until: FloatExpr | None = None,
    samples: int = 200,
    **style: Unpack[StyleKeywords],
) -> Area

Filled region under a curve (down to the x axis) or between two curves (between=). Accepts a curve from ax.plot or a function, plus style (fill=, fill_opacity=).

Parameters:

Example:

def f(x: float) -> float:
    return 0.1 * x * x

@k.scene
def area(s: k.Scene):
    ax = k.Axes(x=(0, 6, 1), y=(0, 4, 1)).place(at="center")
    curve = ax.plot(f, color=k.BLUE)
    ax.area(curve, domain=(1, 5), fill=k.BLUE, fill_opacity=0.3)
    s.play(k.draw(ax))
    s.wait(0.5)

See also: ax.plot.

k.Axes.vline (method)

ax.vline(
    at: FloatVal,
    *,
    style: LineStyle = "solid",
    **props: Unpack[StyleKeywords],
) -> Line

Vertical line on the axes at at= (accepts a signal: the line moves with it); style="dashed" makes it dashed.

Parameters:

Example:

@k.scene
def marker(s: k.Scene):
    ax = k.Axes(x=(0, 24, 6), y=(0, 5)).place(at="center")
    hour = k.signal(6.0)
    ax.vline(at=hour, style="dashed", stroke=k.YELLOW)
    s.play(k.draw(ax))
    s.play(hour.to(18), duration=2)

See also: ax.hline, ax.plot.

k.Axes.hline (method)

ax.hline(
    at: FloatVal,
    *,
    style: LineStyle = "solid",
    **props: Unpack[StyleKeywords],
) -> Line

Horizontal line on the axes at at= (accepts a signal); style="dashed" makes it dashed. Good for limits and targets.

Parameters:

Example:

@k.scene
def limit(s: k.Scene):
    ax = k.Axes(x=(0, 10, 2), y=(0, 5, 1)).place(at="center")
    ax.hline(at=4, style="dashed", stroke=k.RED)
    s.play(k.draw(ax))
    s.wait(0.5)

See also: ax.vline.

k.Axes.scatter (method)

ax.scatter(
    xs: FloatColumn,
    ys: FloatColumn,
    *,
    radius: float = 0.06,
    **props: Unpack[UnplacedStyleKeywords],
) -> Group[Dot]

Points (xs[i], ys[i]) on the axes, as a group of k.Dot. Accepts lists, numpy arrays and Arrow columns (polars, pandas, pyarrow).

Parameters:

Example:

@k.scene
def scatter(s: k.Scene):
    ax = k.Axes(x=(0, 5, 1), y=(0, 5, 1)).place(at="center")
    pts = ax.scatter([1, 2, 3, 4], [1.5, 2.2, 3.1, 3.8], radius=0.1, fill=k.TEAL)
    s.play(k.draw(ax))
    s.play(k.indicate(pts))

See also: ax.plot, k.Dot.

k.Axes.parametric (method)

ax.parametric(
    fx: PlotFunction,
    fy: PlotFunction,
    *,
    t: tuple[float, float] = (0.0, 6.283185307179586),
    samples: int = 300,
    color: ColorLike | None = None,
    **style: Unpack[PlotStyleKeywords],
) -> ParametricPlot

Parametric curve (fx(t), fy(t)) for t=(start, end); clipped to the visible ranges. Siblings: ax.bars(xs, heights, width=) (bars in data units) and ax.scatter(xs, ys).

Parameters:

Example:

def fx(t: float) -> float:
    return k.sin(2 * t)

def fy(t: float) -> float:
    return k.sin(3 * t)

@k.scene
def loop(s: k.Scene):
    ax = k.Axes(x=(-1.5, 1.5), y=(-1.5, 1.5), width=5, height=5).place(at="center")
    curve = ax.parametric(fx, fy, color=k.TEAL)
    s.add(ax)
    s.play(k.draw(curve), duration=2)

See also: ax.plot, k.Axes.

k.Axes.bars (method)

ax.bars(
    xs: FloatColumn,
    heights: FloatColumn,
    *,
    width: float = 0.6,
    **props: Unpack[UnplacedStyleKeywords],
) -> Group[Node]

Vertical bars at data xs with data heights (from the x axis); width is in data units. Bars follow the axes when it zooms.

Parameters:

k.Axes.zoom_to (method)

ax.zoom_to(
    *,
    x: Sequence[float] | None = None,
    y: Sequence[float] | None = None,
    **kw: Unpack[AnimationTiming],
) -> Animation

Named transition: animates the visible ranges of the axes (x=(a, b), y=(c, d)). Curves, ticks and points follow. Equivalent to ax.to(x_range=..., y_range=...).

Parameters:

Example:

@k.scene
def zoom(s: k.Scene):
    ax = k.Axes(x=(-4, 4, 1), y=(-1, 9, 1)).place(at="center")
    ax.plot(lambda x: x * x, color=k.YELLOW)
    s.play(k.draw(ax))
    s.play(ax.zoom_to(x=(0, 2), y=(0, 4)), duration=1.5)

See also: k.Axes, ax.plot.

k.NumberLine (class)#

k.NumberLine(
    x: Sequence[float] = (0, 10, 1),
    *,
    width: float = 10.0,
    **props: Unpack[UnplacedKeywords],
)

A horizontal number line: a k.Axes with only the x axis. Use nl.point(x, 0) to position markers.

Parameters:

Props inherited from k.Axes: x_range, y_range, size.

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Example:

@k.scene
def number_line(s: k.Scene):
    nl = k.NumberLine(x=(-3, 3, 1), width=10).place(at="center")
    x = k.signal(-2.0)
    dot = k.Dot(r=0.15, fill=k.RED).place(at=nl.point(x, 0))
    s.play(k.draw(nl), k.fade_in(dot))
    s.play(x.to(2), duration=2)

See also: k.Axes, ax.point.

Inherited from k.Axes: map_x, map_y, local_point, point, plot, area, vline, hline, scatter, parametric, bars, zoom_to. Inherited from k.Group: children, to, swap, insert, pop, fit. Inherited from k.Node: set, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

Plot (class)#

Plot(
    axes: Axes,
    fn: PlotFunction,
    segments: list[list[tuple[float, float]]],
    clip: Vec | Expr[Vec],
    **props: Unpack[StyleKeywords],
)

A curve y = fn(x) of an axes. Grows with until=; follows the axes when it zooms.

Parameters:

Props (animatable with .to(), settable with .set() or in the constructor):

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Members:

• point_at: World position of the curve at x; reactive when x is a signal.
• value_at: Function value at x (an expression when x is a signal).
• slope_at: Numerical derivative of the curve at x, reactive when x is a signal.
• tangent_at: Tangent segment length units long, centered on the curve at x, reactive when x is a signal.

Inherited from k.Node: set, to, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

Plot.point_at (method)

curve.point_at(x: FloatExpr) -> Expr[Vec]

World position of the curve at x; reactive when x is a signal. With place(at=...) it makes a dot slide along the curve. curve.value_at(x) gives the y value.

Parameters:

Example:

def f(x: float) -> float:
    return 0.15 * x**3 - 0.9 * x + 1.5

@k.scene
def slide(s: k.Scene):
    ax = k.Axes(x=(-3, 3, 1), y=(-1, 5, 1)).place(at="center")
    curve = ax.plot(f, color=k.YELLOW)
    x = k.signal(-2.0)
    dot = k.Dot(r=0.1, fill=k.RED).place(at=curve.point_at(x))
    s.play(k.draw(ax), k.fade_in(dot))
    s.play(x.to(2.5), duration=3)

See also: curve.tangent_at, curve.slope_at, ax.point.

Plot.value_at (method)

curve.value_at(x: float) -> float
curve.value_at(x: Expr[float]) -> Expr[float]

Function value at x (an expression when x is a signal).

Parameters:

Plot.slope_at (method)

curve.slope_at(x: FloatExpr) -> Expr[float]

Numerical derivative of the curve at x, reactive when x is a signal. Use it inside lambdas with a tracked read: curve.slope_at(x)().

Parameters:

Example:

@k.scene
def slope(s: k.Scene):
    ax = k.Axes(x=(-3, 3, 1), y=(-1, 9, 1)).place(at="center")
    curve = ax.plot(lambda x: x * x, color=k.YELLOW)
    x = k.signal(-2.0)
    label = k.Text(lambda: f"f'({x():.1f}) = {curve.slope_at(x)():.1f}").place(at="top", margin=0.5)
    s.play(k.draw(ax), k.fade_in(label))
    s.play(x.to(2), duration=3)

See also: curve.tangent_at.

Plot.tangent_at (method)

curve.tangent_at(
    x: FloatExpr,
    length: float = 2.0,
    **style: Unpack[UnplacedStyleKeywords],
) -> Line

Tangent segment length units long, centered on the curve at x, reactive when x is a signal. It is added to the axes directly; accepts style (stroke=).

Parameters:

Example:

@k.scene
def tangent(s: k.Scene):
    ax = k.Axes(x=(-3, 3, 1), y=(-1, 9, 1)).place(at="center")
    curve = ax.plot(lambda x: x * x, color=k.YELLOW)
    x = k.signal(-2.0)
    curve.tangent_at(x, length=3, stroke=k.RED)
    s.play(k.draw(ax))
    s.play(x.to(2), duration=3)

See also: curve.slope_at, curve.point_at.

k.BarChart (class)#

k.BarChart(
    data: DataTable,
    x: str,
    y: str,
    *,
    key: str | None = None,
    width: float = 8.0,
    height: float = 4.5,
    color: ColorLike | Mapping[str, ColorLike] | None = None,
    labels: bool = True,
    grid: bool = False,
    bar_ratio: float = 0.7,
    label_size: float = 0.28,
    **props: Unpack[ChartKeywords],
)

Bar chart from a table: x= is the category column, y= the value column and key= identifies each bar. Accepts Arrow sources without copying (polars, pandas, pyarrow, duckdb), dicts of lists and lists of dicts. chart.to(data=df2) animates the change: bars grow, move, enter and leave by key; the value axis follows.

Parameters:

Props (animatable with .to(), settable with .set() or in the constructor):

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Example:

@k.scene
def energy(s: k.Scene):
    chart = k.BarChart({"country": ["PT", "ES"], "gwh": [50, 260]}, x="country", y="gwh").place(at="center")
    s.play(k.draw(chart))
    s.play(chart.to(data={"country": ["ES", "PT", "FR"], "gwh": [300, 80, 540]}), duration=2)

See also: k.LineChart, k.Table, k.Bar.

Members:

• keys: Keys of the bars, in slot order (as of the last scheduled transition).
• bar: The bar of key.
• enter: k.draw(chart): axes are drawn, then the bars grow from the baseline.
• to: chart.to(data=df2): animated change of data (plus any other props).

Inherited from k.Group: children, swap, insert, pop, fit. Inherited from k.Node: set, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

k.BarChart.keys (property)

barchart.keys: list[str]  # read-only

Keys of the bars, in slot order (as of the last scheduled transition).

k.BarChart.bar (method)

barchart.bar(key: object) -> ChartBar

The bar of key.

Parameters:

k.BarChart.enter (method)

barchart.enter() -> Animation

k.draw(chart): axes are drawn, then the bars grow from the baseline.

k.BarChart.to (method)

barchart.to(*, data: DataTable | None = None, **kw: Unpack[ChangeKeywords]) -> Animation

chart.to(data=df2): animated change of data (plus any other props).

Parameters:

k.LineChart (class)#

k.LineChart(
    data: DataTable,
    x: str,
    y: str | Sequence[str],
    *,
    x_range: Sequence[float] | None = None,
    y_range: Sequence[float] | None = None,
    width: float = 8.0,
    height: float = 4.5,
    colors: Sequence[ColorLike] | None = None,
    dots: bool = False,
    legend: bool = True,
    **props: Unpack[UnplacedKeywords],
)

A k.Axes with one line per y= column (one or several), connecting the table's points in x= order. chart.to(data=df2) morphs the lines point by point; the axis ranges stay fixed (use y_range= to cover all the data).

Parameters:

Props inherited from k.Axes: x_range, y_range, size.

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Example:

@k.scene
def lines(s: k.Scene):
    chart = k.LineChart({"h": [0, 12, 24], "kw": [0, 6, 0]}, x="h", y="kw", y_range=(0, 8)).place(at="center")
    s.play(k.draw(chart))
    s.play(chart.to(data={"h": [0, 6, 12, 18, 24], "kw": [0, 3, 7, 3, 0]}), duration=2)

See also: k.Axes, k.BarChart.

Members:

• to: chart.to(data=df2): the lines morph to the new values (plus any other props).

Inherited from k.Axes: map_x, map_y, local_point, point, plot, area, vline, hline, scatter, parametric, bars, zoom_to. Inherited from k.Group: children, swap, insert, pop, fit. Inherited from k.Node: set, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

k.LineChart.to (method)

linechart.to(
    *,
    data: DataTable | None = None,
    **kw: Unpack[ChangeKeywords],
) -> Animation

chart.to(data=df2): the lines morph to the new values (plus any other props).

Parameters:

k.Table (class)#

k.Table(
    data: DataTable,
    columns: Sequence[str] | None = None,
    *,
    size: float = 0.32,
    header_color: ColorLike | None = None,
    rule: bool = True,
    **props: Unpack[TransformKeywords],
)

Table of k.Text with a highlighted header; columns= selects and orders the columns. table.to(data=df2) updates the cells: changed texts flash with the new value, new rows appear and removed ones leave. table.cells[r][c] are the cells.

Parameters:

Props inherited from k.Node: x, y, rotate, scale, scale_x, scale_y, anchor, opacity, z, visible.

Example:

@k.scene
def table(s: k.Scene):
    t = k.Table({"country": ["PT", "ES"], "gwh": [50, 260]}).place(at="center")
    s.play(k.fade_in(t))
    s.play(t.to(data={"country": ["PT", "ES", "FR"], "gwh": [80, 260, 1200]}))

See also: k.BarChart, k.Text.

Members:

• to: table.to(data=df2): animated update of the cells (plus any other props).

Inherited from k.Group: children, swap, insert, pop, fit. Inherited from k.Node: set, unbind, edge, age, entered, exited, copy, place, to_place, unpin.

k.Table.to (method)

table.to(*, data: DataTable | None = None, **kw: Unpack[ChangeKeywords]) -> Animation

table.to(data=df2): animated update of the cells (plus any other props).

Parameters: