charts.scale

import math
from typing import Sequence, Tuple


def linear_scale(domain: Sequence[float], range: Sequence[float], value: float, clamp: bool) -> float:
    """Where value lands on the range, as a straight-line map from the domain.

    Outside the domain the line carries on, unless clamp stops it at the
    range's ends.
    """
    d0, d1 = pair(domain, "domain")
    r0, r1 = pair(range, "range")
    t = normalise(d0, d1, value, "domain")
    if clamp:
        t = max(0.0, min(1.0, t))
    return round6(interpolate(r0, r1, t))


# The helpers below are shared with invert_linear, which is the same line read
# the other way; they are not part of the group's contract.


def pair(values: Sequence[float], what: str) -> Tuple[float, float]:
    if len(values) != 2:
        raise ValueError(f"{what} must have exactly 2 values, [from, to]; got {len(values)}")
    return float(values[0]), float(values[1])


def normalise(start: float, end: float, value: float, what: str) -> float:
    # Equal ends would divide by zero, which Python raises as a bare
    # ZeroDivisionError that does not say which end is wrong.
    if start == end:
        raise ValueError(f"{what} has no width: both ends are {start}")
    return (value - start) / (end - start)


def interpolate(start: float, end: float, t: float) -> float:
    return start + t * (end - start)


def round6(x: float) -> float:
    """Half up to 6 decimal places, the same way in every language."""
    return math.floor(x * 1e6 + 0.5) / 1e6

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_scale_linear_scale import interpolate, normalise, pair, round6  ← linearScale, another function of this group · built into the same file, even by a slim install


def invert_linear(domain: Sequence[float], range: Sequence[float], value: float) -> float:
    """The domain value at a position in the range: linear_scale read backwards.

    Never clamped; a position past the end of the axis is a value past the end
    of the data.
    """
    d0, d1 = pair(domain, "domain")
    r0, r1 = pair(range, "range")
    return round6(interpolate(d0, d1, normalise(r0, r1, value, "range")))

import math
from typing import Sequence

from .charts_scale_types import NiceDomain


def nice_domain(domain: Sequence[float], count: int) -> NiceDomain:
    """Widen a domain to multiples of a round tick step chosen for about count ticks.

    Widening can change the best step, so it repeats until the step settles,
    as d3's nice() does.
    """
    if len(domain) != 2:
        raise ValueError(f"domain must have exactly 2 values, [from, to]; got {len(domain)}")
    if isinstance(count, bool) or not isinstance(count, int) or count < 1:
        raise ValueError(f"count must be a whole number of at least 1, got {count}")
    reversed_ = domain[1] < domain[0]
    lo = float(domain[1] if reversed_ else domain[0])
    hi = float(domain[0] if reversed_ else domain[1])
    if lo == hi:
        return NiceDomain(domain=[float(domain[0]), float(domain[1])], step=0.0)

    step = 0.0
    for _ in range(10):
        nxt = _tick_step(lo, hi, count)
        if nxt == step:
            break
        step = nxt
        if step >= 1:
            lo = math.floor(lo / step) * step
            hi = math.ceil(hi / step) * step
        else:
            # A fractional step divides badly (0.3 / 0.1 is 2.9999999999999996),
            # so multiply by its whole-number inverse instead.
            inverse = math.floor(1 / step + 0.5)
            lo = math.floor(lo * inverse) / inverse
            hi = math.ceil(hi * inverse) / inverse
    ends = [_round6(hi), _round6(lo)] if reversed_ else [_round6(lo), _round6(hi)]
    return NiceDomain(domain=ends, step=_round6(step))


def _tick_step(lo: float, hi: float, count: int) -> float:
    raw = (hi - lo) / count
    # Powers of ten by repeated multiplication rather than log10, whose last
    # digit is not guaranteed to agree between languages.
    power = 1.0
    while power * 10 <= raw:
        power *= 10
    while power > raw:
        power /= 10
    error = raw / power
    if error >= math.sqrt(50):
        factor = 10
    elif error >= math.sqrt(10):
        factor = 5
    elif error >= math.sqrt(2):
        factor = 2
    else:
        factor = 1
    return factor * power


def _round6(x: float) -> float:
    return math.floor(x * 1e6 + 0.5) / 1e6

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_scale_linear_scale import interpolate, pair  ← linearScale, another function of this group · built into the same file, even by a slim install
from .math_ln import ln  ← from math.ln ^1.0.0 · built alongside by fune
from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune


def log_scale(domain: Sequence[float], range: Sequence[float], value: float, clamp: bool) -> float:
    """Where value lands on a logarithmic axis: equal ratios take equal lengths.

    The base cancels out, so there is none to pass. ln is math.ln, not
    math.log, so every language lands on the same double.
    """
    d0, d1 = pair(domain, "domain")
    r0, r1 = pair(range, "range")
    if not (d0 > 0) or not (d1 > 0):
        raise ValueError(f"log scale domain must be positive; got [{d0}, {d1}]")
    if d0 == d1:
        raise ValueError(f"domain has no width: both ends are {d0}")
    if not (value > 0):
        raise ValueError(f"value must be positive for a log scale; got {value}")
    l0 = ln(d0)
    t = (ln(value) - l0) / (ln(d1) - l0)
    if clamp:
        t = max(0.0, min(1.0, t))
    return round_float(interpolate(r0, r1, t), 6)

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_scale_linear_scale import interpolate, pair  ← linearScale, another function of this group · built into the same file, even by a slim install
from .dates_days_between import days_between  ← from dates.days-between ^1.0.0 · built alongside by fune
from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune


def time_scale(domain: Sequence[str], range: Sequence[float], value: str, clamp: bool) -> float:
    """Where an ISO date lands on the range, linearly by calendar days.

    Days are counted with dates.days-between, never through datetime, so no
    time zone can move a point by a day.
    """
    if len(domain) != 2:
        raise ValueError(f"domain must have exactly 2 values, [from, to]; got {len(domain)}")
    r0, r1 = pair(range, "range")
    span = days_between(domain[0], domain[1])
    if span == 0:
        raise ValueError(f"domain has no width: both ends are {domain[0]}")
    t = days_between(domain[0], value) / span
    if clamp:
        t = max(0.0, min(1.0, t))
    return round_float(interpolate(r0, r1, t), 6)

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, Tuple

from .charts_scale_linear_scale import pair  ← linearScale, another function of this group · built into the same file, even by a slim install
from .charts_scale_types import Band
from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune


def band_scale(
    domain: Sequence[str],
    range: Sequence[float],
    value: str,
    padding_inner: float,
    padding_outer: float,
    align: float,
) -> Band:
    """The band a category occupies, as d3.scaleBand lays it out (without
    rounding to whole pixels). A reversed range reverses the order of the
    bands, not their direction, so start is always the lower coordinate."""
    if not (0 <= padding_inner <= 1):
        raise ValueError(f"paddingInner must be between 0 and 1; got {padding_inner}")
    check_outer(padding_outer, "paddingOuter")
    check_align(align)
    start, width = band_position(domain, range, value, padding_inner, padding_outer, align)
    return Band(start=round_float(start, 6), center=round_float(start + width / 2, 6), width=round_float(width, 6))


# Exported for point_scale, which is a band scale whose bands have no width.


def check_outer(padding: float, what: str) -> None:
    if not (padding >= 0):
        raise ValueError(f"{what} must be 0 or more; got {padding}")


def check_align(align: float) -> None:
    if not (0 <= align <= 1):
        raise ValueError(f"align must be between 0 and 1; got {align}")


def band_position(
    domain: Sequence[str],
    extent: Sequence[float],
    value: str,
    padding_inner: float,
    padding_outer: float,
    align: float,
) -> Tuple[float, float]:
    """The unrounded lower coordinate of value's band, and the band width."""
    r0, r1 = pair(extent, "range")
    n = len(domain)
    if n == 0:
        raise ValueError("domain must not be empty")
    index = -1
    for i in range(n):
        for j in range(i):
            if domain[j] == domain[i]:
                raise ValueError(f'domain has a repeated value: "{domain[i]}"')
        if domain[i] == value:
            index = i
    if index < 0:
        raise ValueError(f'value is not in the domain: "{value}"')
    reverse = r1 < r0
    start = r1 if reverse else r0
    stop = r0 if reverse else r1
    step = (stop - start) / max(1.0, n - float(padding_inner) + float(padding_outer) * 2)
    start += (stop - start - step * (n - float(padding_inner))) * float(align)
    slot = n - 1 - index if reverse else index
    return start + step * slot, step * (1 - float(padding_inner))

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_scale_band_scale import band_position, check_align, check_outer  ← bandScale, another function of this group · built into the same file, even by a slim install
from .math_round_float import round_float  ← from math.round-float ^1.0.0 · built alongside by fune


def point_scale(domain: Sequence[str], range: Sequence[float], value: str, padding: float, align: float) -> float:
    """The position of a category on an axis of evenly spaced points, as
    d3.scalePoint: a band scale with inner padding 1, so bands have no width."""
    check_outer(padding, "padding")
    check_align(align)
    return round_float(band_position(domain, range, value, 1, padding, align)[0], 6)