charts.axis

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from typing import Sequence

from .charts_axis_types import Axis, AxisOrient, AxisTick, Line
from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune

# d3-axis's default gap between the end of a tick mark and its label.
_LABEL_PADDING = 3


def axis_pixel(value: float) -> float:
    """A pixel coordinate rounded to 2 places, the precision every axis output uses."""
    return round_float(value, 2)


def axis_line(x1: float, y1: float, x2: float, y2: float) -> Line:
    return Line(x1=axis_pixel(x1), y1=axis_pixel(y1), x2=axis_pixel(x2), y2=axis_pixel(y2))


def check_orient(orient: str) -> None:
    if orient not in ("bottom", "top", "left", "right"):
        raise ValueError('orient must be bottom, top, left or right, received "%s"' % (orient,))


def axis_from_ticks(
    positions: Sequence[float],
    labels: Sequence[str],
    range: Sequence[float],  # noqa: A002 - the manifest names it range
    orient: AxisOrient,
    position: float,
    tick_size: float,
) -> Axis:
    """Axis geometry from tick positions and labels, for any scale (d3-axis layout)."""
    check_orient(orient)
    if len(positions) != len(labels):
        raise ValueError(
            "positions and labels must be the same length, received %d and %d" % (len(positions), len(labels))
        )
    if len(range) != 2:
        raise ValueError("range must have exactly 2 values, [from, to]; got %d" % len(range))
    horizontal = orient in ("bottom", "top")
    sign = 1 if orient in ("bottom", "right") else -1
    mark_end = position + sign * tick_size
    label_at = position + sign * (tick_size + _LABEL_PADDING)
    ticks = []
    for p, label in zip(positions, labels):
        if horizontal:
            ticks.append(
                AxisTick(
                    position=axis_pixel(p),
                    label=label,
                    tick=axis_line(p, position, p, mark_end),
                    label_x=axis_pixel(p),
                    label_y=axis_pixel(label_at),
                    anchor="middle",
                    baseline="hanging" if orient == "bottom" else "alphabetic",
                )
            )
        else:
            ticks.append(
                AxisTick(
                    position=axis_pixel(p),
                    label=label,
                    tick=axis_line(position, p, mark_end, p),
                    label_x=axis_pixel(label_at),
                    label_y=axis_pixel(p),
                    anchor="end" if orient == "left" else "start",
                    baseline="middle",
                )
            )
    if horizontal:
        line = axis_line(range[0], position, range[1], position)
    else:
        line = axis_line(position, range[0], position, range[1])
    return Axis(orient=orient, position=axis_pixel(position), line=line, ticks=ticks)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from typing import Sequence

from .charts_axis_axis_from_ticks import axis_from_ticks  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
from .charts_axis_types import Axis, AxisOrient
from .charts_format_format_tick import format_tick
from .charts_scale_linear_scale import linear_scale
from .charts_ticks_nice_ticks import nice_ticks
from .charts_ticks_tick_step import tick_step


def number_axis(
    domain: Sequence[float],
    range: Sequence[float],  # noqa: A002 - the manifest names it range
    count: int,
    orient: AxisOrient,
    position: float,
    tick_size: float,
) -> Axis:
    """A linear number axis: nice ticks, placed by linear_scale, labelled for the step."""
    if len(domain) != 2:
        raise ValueError("domain must have exactly 2 values, [from, to]; got %d" % len(domain))
    lo = min(domain[0], domain[1])
    hi = max(domain[0], domain[1])
    values = nice_ticks(domain[0], domain[1], count)
    step = tick_step(lo, hi, count)
    positions = [linear_scale(domain, range, v, False) for v in values]
    labels = [format_tick(v, step) for v in values]
    return axis_from_ticks(positions, labels, range, orient, position, tick_size)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from typing import Sequence

from .charts_axis_axis_from_ticks import axis_from_ticks  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
from .charts_axis_types import Axis, AxisOrient
from .charts_format_format_date import format_date
from .charts_scale_time_scale import time_scale
from .charts_ticks_time_tick_interval import time_tick_interval
from .charts_ticks_time_ticks import time_ticks


def time_axis(
    domain: Sequence[str],
    range: Sequence[float],  # noqa: A002 - the manifest names it range
    count: int,
    orient: AxisOrient,
    position: float,
    tick_size: float,
) -> Axis:
    """A date axis: a calendar interval for about count ticks, labelled for that interval."""
    if len(domain) != 2:
        raise ValueError("domain must have exactly 2 values, [from, to]; got %d" % len(domain))
    lo = min(domain[0], domain[1])
    hi = max(domain[0], domain[1])
    chosen = time_tick_interval(lo, hi, count)
    values = time_ticks(lo, hi, chosen.interval, chosen.step)
    positions = [time_scale(domain, range, v, False) for v in values]
    labels = [format_date(v, chosen.interval) for v in values]
    return axis_from_ticks(positions, labels, range, orient, position, tick_size)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

from typing import Sequence

from .charts_axis_axis_from_ticks import axis_from_ticks  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
from .charts_axis_types import Axis, AxisOrient
from .charts_scale_band_scale import band_scale


def band_axis(
    domain: Sequence[str],
    range: Sequence[float],  # noqa: A002 - the manifest names it range
    padding_inner: float,
    padding_outer: float,
    orient: AxisOrient,
    position: float,
    tick_size: float,
) -> Axis:
    """A category axis: one tick at the centre of each band, labelled with the category."""
    positions = [band_scale(domain, range, v, padding_inner, padding_outer, 0.5).center for v in domain]
    return axis_from_ticks(positions, list(domain), range, orient, position, tick_size)

Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.

import math
from typing import List

from .charts_axis_axis_from_ticks import axis_line, check_orient  ← axisFromTicks, another function of this group · built into the same file, even by a slim install
from .charts_axis_types import Axis, Line


def grid_lines(axis: Axis, length: float) -> List[Line]:
    """One gridline per tick, from the axis line across the plot."""
    check_orient(axis.orient)
    if isinstance(length, bool) or not isinstance(length, (int, float)) or not math.isfinite(length) or length < 0:
        raise ValueError("length must be a finite number of zero or more, received %r" % (length,))
    pos = axis.position
    out = []
    for t in axis.ticks:
        p = t.position
        if axis.orient == "bottom":
            out.append(axis_line(p, pos, p, pos - length))
        elif axis.orient == "top":
            out.append(axis_line(p, pos, p, pos + length))
        elif axis.orient == "left":
            out.append(axis_line(pos, p, pos + length, p))
        else:
            out.append(axis_line(pos, p, pos - length, p))
    return out