charts.ticks

import math
from typing import Tuple


def tick_step(start: float, stop: float, count: int) -> float:
    """The tick step for about count ticks: 1, 2 or 5 times a power of ten,
    as d3-array's tickIncrement chooses it, found without log10 and returned
    as one correctly rounded division so 0.2 is exactly the double 0.2."""
    mul, div = tick_spec(start, stop, count)
    return mul / div


# Exported for nice_ticks, which needs the step as a multiplier or a divisor.


def tick_spec(start: float, stop: float, count: int) -> Tuple[float, float]:
    """The step as (multiplier, divisor), one of which is 1; (0, 1) when start equals stop."""
    for v in (start, stop):
        if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v):
            raise ValueError(f"start and stop must be finite numbers; got {start} and {stop}")
    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}")
    raw = abs(float(stop) - float(start)) / count
    if raw == 0:
        return 0.0, 1.0
    if raw >= 1:
        power = 1.0
        while power * 10 <= raw:
            power *= 10
        return _nice_factor(raw / power) * power, 1.0
    inverse = 1.0
    while raw * inverse < 1:
        inverse *= 10
    factor = _nice_factor(raw * inverse)
    return (1.0, 1.0) if factor == inverse else (1.0, inverse / factor)


def _nice_factor(error: float) -> float:
    if error >= math.sqrt(50):
        return 10.0
    if error >= math.sqrt(10):
        return 5.0
    if error >= math.sqrt(2):
        return 2.0
    return 1.0

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

from .charts_ticks_tick_step import tick_spec  ← tickStep, 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 nice_ticks(start: float, stop: float, count: int) -> List[float]:
    """Ticks at round values between start and stop, as d3.ticks, each one
    exact operation on a whole number (i * step or i / divisor), so 0.1 steps
    give 0.3 and not 0.30000000000000004."""
    mul, div = tick_spec(start, stop, count)
    if start == stop:
        return [float(start) + 0.0]
    reverse = stop < start
    lo = float(stop if reverse else start)
    hi = float(start if reverse else stop)
    i1, i2 = _indexes(lo, hi, mul, div)
    if i2 < i1 and count == 1:
        # No multiple of the step for one tick falls inside; d3 retries with two.
        mul, div = tick_spec(start, stop, 2)
        i1, i2 = _indexes(lo, hi, mul, div)
    ticks = []
    i = i1
    while i <= i2:
        ticks.append((i / div if div > 1 else i * mul) + 0.0)
        i += 1
    if reverse:
        ticks.reverse()
    return ticks


def _indexes(lo: float, hi: float, mul: float, div: float) -> Tuple[float, float]:
    if div > 1:
        i1 = round_float(lo * div, 0)
        i2 = round_float(hi * div, 0)
        if i1 / div < lo:
            i1 += 1
        if i2 / div > hi:
            i2 -= 1
        return i1, i2
    i1 = round_float(lo / mul, 0)
    i2 = round_float(hi / mul, 0)
    if i1 * mul < lo:
        i1 += 1
    if i2 * mul > hi:
        i2 -= 1
    return i1, i2

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

from .charts_ticks_tick_step import tick_step  ← tickStep, another function of this group · built into the same file, even by a slim install
from .charts_ticks_types import TimeTickInterval
from .dates_add_days import epoch_day_from_iso  ← from dates.add-days ^1.0.0 · built alongside by fune

# d3-scale's calendar ladder, from a day up, with the lengths in days it
# compares against: a month counts as 30, a quarter as 90, a year as 365.
_LADDER = [
    ("day", 1, 1),
    ("day", 2, 2),
    ("week", 1, 7),
    ("month", 1, 30),
    ("quarter", 1, 90),
    ("year", 1, 365),
]


def time_tick_interval(start: str, stop: str, count: int) -> TimeTickInterval:
    """The calendar interval for about count ticks between two dates, as d3's
    time scale picks it: the nearest rung of the ladder by ratio, or whole
    years in steps of 1, 2 or 5 x 10^k beyond a year."""
    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}")
    span = abs(epoch_day_from_iso(stop) - epoch_day_from_iso(start))
    target = span / count
    i = 0
    while i < len(_LADDER) and _LADDER[i][2] <= target:
        i += 1
    if i == len(_LADDER):
        return TimeTickInterval(interval="year", step=max(1, int(tick_step(0, span / 365, count))))
    if i == 0:
        return TimeTickInterval(interval="day", step=1)
    pick = _LADDER[i - 1] if target / _LADDER[i - 1][2] < _LADDER[i][2] / target else _LADDER[i]
    return TimeTickInterval(interval=pick[0], step=pick[1])

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 List

from .charts_ticks_types import TimeInterval
from .dates_add_days import civil_from_days, days_from_civil, epoch_day_from_iso, iso_from_epoch_day  ← from dates.add-days ^1.0.0 · built alongside by fune

# 1970-01-05, the first Monday on or after the epoch, as a day number.
_FIRST_MONDAY = 4
_MAX_TICKS = 10000


def _ceil_div(a: int, b: int) -> int:
    return -((-a) // b)


def time_ticks(start: str, stop: str, interval: TimeInterval, step: int) -> List[str]:
    """Calendar boundaries between two dates, inclusive, anchored to the
    calendar rather than to start so that panning does not move them: days by
    (day - 1) % step, weeks since 1970-01-05, months by (month - 1) % step,
    quarters by quarter of the year, years by year % step."""
    if isinstance(step, bool) or not isinstance(step, int) or step < 1:
        raise ValueError(f"step must be a whole number of at least 1, got {step}")
    a = epoch_day_from_iso(start)
    b = epoch_day_from_iso(stop)
    reverse = b < a
    lo, hi = (b, a) if reverse else (a, b)
    days: List[int] = []

    def add(day: int) -> None:
        if len(days) >= _MAX_TICKS:
            raise ValueError(f"too many ticks: more than {_MAX_TICKS}; use a longer interval or step")
        days.append(day)

    if interval == "day":
        for d in range(lo, hi + 1):
            if (civil_from_days(d).day - 1) % step == 0:
                add(d)
    elif interval == "week":
        k = _ceil_div(lo - _FIRST_MONDAY, 7)
        k = _ceil_div(k, step) * step
        d = _FIRST_MONDAY + 7 * k
        while d <= hi:
            add(d)
            d += 7 * step
    elif interval in ("month", "quarter", "year"):
        months = step if interval == "month" else 3 * step if interval == "quarter" else 12
        first = civil_from_days(lo)
        year, month = first.year, first.month
        while True:
            d = days_from_civil(year, month, 1)
            if d > hi:
                break
            on_step = (month == 1 and year % step == 0) if interval == "year" else (month - 1) % months == 0
            if d >= lo and on_step:
                add(d)
            month += 1
            if month > 12:
                month = 1
                year += 1
    else:
        raise ValueError(f'unknown time interval "{interval}"')
    ticks = [iso_from_epoch_day(d) for d in days]
    if reverse:
        ticks.reverse()
    return ticks