plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/ticks.py

@@ -0,0 +1,400 @@
+"""Tick choice and tick labels.
+
+Every function works on data values and returns :class:`Tick` lists; positions on the
+page are the axis's business.  Labels are strings or rich content (exponents).
+"""
+
+import math
+from collections.abc import Callable, Sequence
+from typing import Any, NamedTuple
+
+from .numbers import NumberStyle, format_axis
+from .scales import Scale
+
+__all__ = ["Tick", "linear_ticks", "nice_step", "numeric_ticks", "power_labels",
+           "step_values", "thin_by_position", "minor_linear", "exponent_label", "Every",
+           "every", "LOG_BASES"]
+
+_MANTISSAS = (1.0, 2.0, 2.5, 5.0)
+
+
+class Tick(NamedTuple):
+    value: float
+    label: Any          # str, rich content, or None (unlabelled)
+    major: bool = True
+
+
+def nice_step(raw: float) -> float:
+    """The smallest step 1, 2, 2.5 or 5 × 10^k that is at least ``raw``."""
+    if not raw > 0 or not math.isfinite(raw):
+        return 1.0
+    k = math.floor(math.log10(raw))
+    for m in _MANTISSAS + (10.0,):
+        s = m * 10.0 ** k
+        if s >= raw * (1 - 1e-9):
+            return s
+    return 10.0 ** (k + 1)
+
+
+def _next_step(step: float) -> float:
+    k = math.floor(math.log10(step) + 1e-9)
+    m = step / 10.0 ** k
+    for c in _MANTISSAS + (10.0,):
+        if c > m * (1 + 1e-9):
+            return c * 10.0 ** k
+    return 2.0 * 10.0 ** (k + 1)
+
+
+#: The most tick values one call makes.
+MAX_TICKS = 100_000
+
+
+def _values(lo: float, hi: float, step: float) -> list[float]:
+    eps = step * 1e-9
+    a, b = (lo - eps) / step, (hi + eps) / step
+    if not (math.isfinite(a) and math.isfinite(b)) or b - a > MAX_TICKS:
+        raise ValueError(f"ticks every {step:g} from {lo:g} to {hi:g}: more than "
+                         f"{MAX_TICKS} ticks")
+    start = math.ceil(a)
+    end = math.floor(b)
+    digits = 2 - math.floor(math.log10(step))     # rounded relative to the step
+    return [round(i * step, digits) + 0.0 for i in range(start, end + 1)]
+
+
+def linear_ticks(lo: float, hi: float, max_ticks: int,
+                 fits: Callable[[list[float], float], bool] | None = None,
+                 min_step: float = 0.0) -> tuple[list[float], float]:
+    """Tick values in [lo, hi]: the smallest nice step giving at most ``max_ticks``
+    ticks (and for which ``fits(values, step)`` holds); with ``min_step``, a whole multiple
+    of it (``1``: integers only).  Returns ``(values, step)``."""
+    if hi < lo:
+        lo, hi = hi, lo
+    if hi == lo:
+        return [lo], 1.0
+    n = max(2, int(max_ticks))
+    step = max(nice_step((hi - lo) / n), min_step)
+    for _ in range(60):
+        whole = not min_step or abs(step / min_step - round(step / min_step)) < 1e-9
+        if whole:
+            vals = _values(lo, hi, step)
+            if len(vals) <= n and (fits is None or fits(vals, step)):
+                return vals, step
+        step = _next_step(step)
+    return _values(lo, hi, step), step
+
+
+def minor_linear(lo: float, hi: float, step: float) -> list[float]:
+    k = math.floor(math.log10(step) + 1e-9)
+    m = round(step / 10.0 ** k, 6)
+    sub = step / (4 if m == 2.0 else 5)
+    return _values(lo, hi, sub)
+
+
+# ---------------------------------------------------------------------------
+# Ticks per scale
+# ---------------------------------------------------------------------------
+
+def exponent_label(base: str, k: int, style: NumberStyle | None = None) -> Any:
+    from .text import superscript
+    style = style or NumberStyle()
+    return style.wrap([base, superscript(style.exponent(k))])
+
+
+def _int_powers(flo: float, fhi: float) -> list[int]:
+    return list(range(math.ceil(flo - 1e-9), math.floor(fhi + 1e-9) + 1))
+
+
+def _thin_powers(ks: list[int], max_ticks: int, base: int = 1) -> tuple[list[int], int]:
+    """Every k-th power so that at most ``max_ticks`` remain (k a power of two when
+    ``base`` is 2, else any integer)."""
+    every = 1
+    while len([k for k in ks if k % every == 0]) > max(2, max_ticks):
+        every = every * 2 if base == 2 else every + 1
+    return [k for k in ks if k % every == 0], every
+
+
+def _each(values: list[float], fmt: Any, style: NumberStyle) -> list[Any]:
+    """Labels formatted one by one (log and other non-linear ticks)."""
+    if fmt != "auto":
+        return format_axis(values, fmt, style, None)[0]
+    return [format_axis([v], "auto", style, None)[0][0] for v in values]
+
+
+#: The label of each logarithmic base in power labels.
+LOG_BASES = {math.e: "e", 2.0: "2", 10.0: "10"}
+
+
+def power_labels(base: float, ks: list[int], fmt: Any = "auto",
+                 style: NumberStyle | None = None) -> list[Any]:
+    """Labels of the powers ``base**k`` of a log scale: ``10ᵏ``; in base 2 the numbers up
+    to 2¹⁰, else ``2ᵏ``; ``eᵏ`` (``1`` at 0); in ``fmt`` when it is set."""
+    style = style or NumberStyle()
+    if fmt != "auto":
+        return _each([base ** k for k in ks], fmt, style)
+    out: list[Any] = []
+    for k in ks:
+        if base == 10.0:
+            out.append(exponent_label("10", k, style))
+        elif base == 2.0:
+            out.append(_each([base ** k], "auto", style)[0] if -10 <= k <= 10
+                       else exponent_label("2", k, style))
+        else:
+            out.append(style.wrap("1") if k == 0
+                       else exponent_label(LOG_BASES[base], k, style))
+    return out
+
+
+def step_values(lo: float, hi: float, step: float) -> list[float]:
+    """The multiples of ``step`` from ``lo`` to ``hi`` (rounded relative to the step)."""
+    if not (step > 0 and math.isfinite(step)):
+        raise ValueError(f"expected a positive step, got {step!r}")
+    return _values(min(lo, hi), max(lo, hi), step)
+
+
+class Every:
+    """Ticks every ``step`` (:func:`every`)."""
+
+    __slots__ = ("step", "unit")
+
+    def __init__(self, step: float, unit: str | None) -> None:
+        self.step, self.unit = step, unit
+
+    def __repr__(self) -> str:
+        if self.unit is None:
+            return f"every({self.step:g})"
+        return f"every({str(int(self.step)) + ' ' + self.unit + 's'!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Every) and (self.step, self.unit) == (other.step, other.unit)
+
+    def __hash__(self) -> int:
+        return hash((self.step, self.unit))
+
+
+#: Calendar units of :func:`every` and their size in the units of the time locator.
+_UNITS = {"microsecond": ("microsecond", 1), "millisecond": ("microsecond", 1000),
+          "second": ("second", 1), "minute": ("minute", 1), "hour": ("hour", 1),
+          "day": ("day", 1), "week": ("day", 7), "month": ("month", 1), "year": ("year", 1)}
+
+
+def every(step: Any) -> Every:
+    """Ticks every ``step`` for ``ticks=`` and ``minor_ticks=``: a number in axis units
+    (on a log axis in powers of its base: ``every(1)`` is every decade; on a category axis
+    every n-th category; on a time axis seconds, or a ``timedelta``), or a calendar step
+    on a time axis: ``"2 months"``, ``"week"``, ``"15 minutes"`` (units ``microsecond``,
+    ``millisecond``, ``second``, ``minute``, ``hour``, ``day``, ``week``, ``month``,
+    ``year``)."""
+    import datetime as dt
+    from .validators import real
+    if isinstance(step, dt.timedelta):
+        step = step.total_seconds()
+    if isinstance(step, str):
+        parts = step.split()
+        if len(parts) in (1, 2):
+            count = parts[0] if len(parts) == 2 else "1"
+            unit = parts[-1].lower()
+            unit = unit[:-1] if unit.endswith("s") and unit[:-1] in _UNITS else unit
+            if unit in _UNITS and count.isdigit() and int(count) > 0:
+                return Every(float(count), unit)
+        raise ValueError(f"every: expected a number or a calendar step such as "
+                         f"'2 months' (units {', '.join(_UNITS)}), got {step!r}")
+    x = real(step)
+    if x is None or not (x > 0 and math.isfinite(x)):
+        raise ValueError(f"every: expected a positive number, got {step!r}")
+    return Every(x, None)
+
+
+def _no_quarters(fits: Callable[[list[float], float], bool] | None
+                 ) -> Callable[[list[float], float], bool]:
+    """``fits`` refusing steps of 2.5 × 10^k (labels with a set precision round them)."""
+    def out(vals: list[float], step: float) -> bool:
+        m = step / 10.0 ** math.floor(math.log10(step) + 1e-9)
+        return abs(m - 2.5) > 1e-6 and (fits is None or fits(vals, step))
+    return out
+
+
+def numeric_ticks(scale: Scale, lo: float, hi: float, max_ticks: int, fmt: Any = "auto",
+                  style: NumberStyle | None = None, sci_limits: tuple[int, int] = (-4, 5),
+                  minor: bool = True, length: float = 0.0,
+                  fits: Callable[[list[float], float], bool] | None = None,
+                  min_step: float = 0.0) -> tuple[list[Tick], int]:
+    """Ticks of a numeric scale between data limits ``lo`` < ``hi``, labelled with the
+    number format ``fmt``; a linear scale's step is a whole multiple of ``min_step``.
+    Returns the ticks and the exponent of a common ×10ᵏ factor (0: none)."""
+    style = style or NumberStyle()
+    if hi < lo:
+        lo, hi = hi, lo
+    name = scale.name
+    flo, fhi = scale.f(lo), scale.f(hi)
+    base_num = scale.base
+    if base_num is not None:
+        ks = _int_powers(flo, fhi)
+        if base_num == 10.0 and 1 <= len(ks) < 3:
+            values = [m * 10.0 ** k for k in range(min(ks, default=0) - 1, max(ks, default=0) + 1)
+                      for m in (1, 2, 5) if lo * (1 - 1e-9) <= m * 10.0 ** k <= hi * (1 + 1e-9)]
+            if len(values) >= 3 or len(values) > len(ks):
+                ticks = [Tick(v, s) for v, s in zip(values, _each(values, fmt, style))]
+                if minor:
+                    ticks += [Tick(m * 10.0 ** k, None, False)
+                              for k in range(min(ks) - 1, max(ks) + 1)
+                              for m in (3, 4, 6, 7, 8, 9)
+                              if lo <= m * 10.0 ** k <= hi]
+                return ticks, 0
+        if len(ks) >= 2:
+            kept, every = _thin_powers(ks, max_ticks, 2 if base_num == 2.0 else 1)
+            powers = dict(zip(kept, power_labels(base_num, kept, fmt, style)))
+            ticks = [Tick(base_num ** k, powers[k]) if k in powers
+                     else Tick(base_num ** k, None, False) for k in ks]
+            if base_num == 10.0 and minor and every == 1 and len(ks) <= 8:
+                ticks += [Tick(m * 10.0 ** k, None, False) for k in range(ks[0] - 1, ks[-1] + 1)
+                          for m in range(2, 10) if lo <= m * 10.0 ** k <= hi]
+            return ticks, 0
+        # Less than two powers in range: nice values in data space.
+    if name == "linear" or base_num is not None:
+        if style.precision is not None:          # 0.25 at one digit would read 0.3
+            fits = _no_quarters(fits)
+        values, step = linear_ticks(lo, hi, max_ticks, fits,
+                                    min_step if name == "linear" else 0.0)
+        values = [v for v in values if scale.contains(v)]
+        labels, exp = format_axis(values, fmt, style, sci_limits)
+        return [Tick(v, s) for v, s in zip(values, labels)], exp
+    if name == "symlog":
+        return _symlog_ticks(scale, lo, hi, max_ticks, fmt, style, minor, length)
+    if name == "logit":
+        return _logit_ticks(scale, lo, hi, max_ticks, fmt, style, length)
+    # sqrt, exp and other monotone scales: the smallest nice step whose ticks are at least
+    # `length / max_ticks` apart on the page.
+    spacing = length / max(max_ticks, 1)
+
+    def spaced(vals: list[float], step: float) -> bool:
+        vals = [v for v in vals if scale.contains(v)]
+        if length <= 0 or len(vals) < 2 or fhi == flo:
+            return True
+        pos = [(scale.f(v) - flo) / (fhi - flo) * length for v in vals]
+        return min(abs(b - a) for a, b in zip(pos, pos[1:])) >= spacing - 1e-9
+
+    values, step = linear_ticks(lo, hi, max(2 * max_ticks, 4), spaced)
+    values = [v for v in values if scale.contains(v)]
+    return [Tick(v, s) for v, s in zip(values, _each(values, fmt, style))], 0
+
+
+def thin_by_position(pos: Sequence[float], spacing: float) -> list[int]:
+    """Indices of increasing positions kept so that neighbours are at least ``spacing``
+    apart.  Walks from the end where the scale stretches the data most (the sparse end),
+    always keeping both ends."""
+    n = len(pos)
+    if n <= 2:
+        return list(range(n))
+    order = list(range(n))
+    if pos[-1] - pos[-2] > pos[1] - pos[0]:
+        order.reverse()        # sparse at the high end: walk from there
+    kept = [order[0]]
+    for i in order[1:-1]:
+        if abs(pos[i] - pos[kept[-1]]) >= spacing and abs(pos[order[-1]] - pos[i]) >= spacing:
+            kept.append(i)
+    kept.append(order[-1])
+    return sorted(kept)
+
+
+def _thin(scale: Scale, values: list[float], lo: float, hi: float, max_ticks: int,
+          length: float) -> list[float]:
+    flo, fhi = scale.f(lo), scale.f(hi)
+    if length > 0 and len(values) > 2 and fhi != flo:
+        pos = [(scale.f(v) - flo) / (fhi - flo) * length for v in values]
+        keep = thin_by_position(pos, length / max(max_ticks, 1))
+        values = [values[i] for i in keep]
+    return values
+
+
+def _thin_symlog(scale: Scale, values: list[float], lo: float, hi: float, max_ticks: int,
+                 length: float) -> list[float]:
+    """Symlog ticks kept from 0 outwards on each side (0 and the decades nearest to it
+    first), neighbours at least ``length / max_ticks`` apart, both ends kept."""
+    flo, fhi = scale.f(lo), scale.f(hi)
+    if length <= 0 or len(values) <= 2 or fhi == flo:
+        return values
+    spacing = length / max(max_ticks, 1)
+    pos = {v: (scale.f(v) - flo) / (fhi - flo) * length for v in values}
+    center = min(values, key=abs)
+    kept = [center]
+    for side in ([v for v in values if v > center], [v for v in reversed(values) if v < center]):
+        last = center
+        for i, v in enumerate(side):
+            end = side[-1]
+            if v is end or (abs(pos[v] - pos[last]) >= spacing
+                            and abs(pos[end] - pos[v]) >= spacing):
+                if v is end and abs(pos[v] - pos[last]) < spacing and last is not center:
+                    kept.remove(last)
+                kept.append(v)
+                last = v
+    return sorted(kept)
+
+
+def _symlog_ticks(scale: Scale, lo: float, hi: float, max_ticks: int, fmt: Any,
+                  style: NumberStyle, minor: bool, length: float) -> tuple[list[Tick], int]:
+    """0, ±linthresh, then decades beyond; linear minor ticks inside the linear region."""
+    c = scale.options.get("linthresh", 1.0)
+    eps = (hi - lo) * 1e-9 + 1e-300
+    majors = [0.0] if lo - eps <= 0.0 <= hi + eps else []
+    for sign in (1.0, -1.0):
+        k = 0
+        while k < 400:
+            v = sign * c * 10.0 ** k
+            if not lo - eps <= v <= hi + eps:
+                if (sign > 0 and v > hi) or (sign < 0 and v < lo):
+                    break
+            else:
+                majors.append(v)
+            k += 1
+    if len(majors) < 2:                    # inside the linear region: linear ticks
+        values, lin = linear_ticks(lo, hi, max_ticks)
+        labels = format_axis(values, fmt, style, None)[0]     # together: shared decimals
+        ticks = [Tick(v, s) for v, s in zip(values, labels)]
+        if minor and len(values) >= 2:
+            ticks += [Tick(v, None, False) for v in minor_linear(lo, hi, lin)
+                      if not any(abs(v - m) < lin * 1e-6 for m in values)]
+        return ticks, 0
+    majors = _thin_symlog(scale, sorted(set(majors)), lo, hi, max_ticks, length)
+    ticks = [Tick(v, s) for v, s in zip(majors, _each(majors, fmt, style))]
+    if minor:
+        have = set(majors)
+        step = _symlog_minor_step(scale, c)
+        if step is not None:
+            n = int(round(c / step))
+            for i in range(-n + 1, n):
+                v = i * step
+                if i and v not in have and lo <= v <= hi:
+                    ticks.append(Tick(v, None, False))
+    return ticks, 0
+
+
+#: Smallest gap between minor ticks in the linear region of a symlog axis, in scale units
+#: (decades): the gap between minor ticks 4 and 5 of a log decade.
+_SYMLOG_MINOR_GAP = math.log10(1.25)
+
+
+def _symlog_minor_step(scale: Scale, c: float) -> float | None:
+    """The finest nice step (c/10, c/5, c/4, c/2) whose ticks in (−c, c) stay at least
+    ``_SYMLOG_MINOR_GAP`` apart on the axis, or ``None`` when no step fits."""
+    if 2.0 * scale.f(c) < 2.0 * _SYMLOG_MINOR_GAP:
+        return None
+    for div in (10, 5, 4, 2):
+        step = c / div
+        pos = [scale.f(i * step) for i in range(0, div + 1)]
+        if min(b - a for a, b in zip(pos, pos[1:])) >= _SYMLOG_MINOR_GAP:
+            return step
+    return None
+
+
+def _logit_ticks(scale: Scale, lo: float, hi: float, max_ticks: int, fmt: Any,
+                 style: NumberStyle, length: float) -> tuple[list[Tick], int]:
+    """0.5, then 0.1/0.9, 0.01/0.99, … inside the limits."""
+    values = [0.5]
+    for k in range(1, 16):
+        values += [10.0 ** -k, 1.0 - 10.0 ** -k]
+    values = sorted(v for v in values if lo <= v <= hi)
+    if len(values) < 2:
+        values, _ = linear_ticks(lo, hi, max_ticks)
+        values = [v for v in values if 0 < v < 1]
+    values = _thin(scale, values, lo, hi, max_ticks, length)
+    return [Tick(v, s) for v, s in zip(values, _each(values, fmt, style))], 0

plot_io/times.py

@@ -0,0 +1,287 @@
+"""Dates and times on axes.
+
+Values (``datetime``, ``date``, numpy ``datetime64`` arrays, pandas timestamps) become
+float seconds since 1970-01-01 UTC, so scales, limits and the C mapping are unchanged; the
+axis (``scale="time"``, set by date data) chooses calendar-aware ticks and concise labels.
+"""
+
+import array
+import calendar
+import datetime as dt
+import math
+from typing import Any
+
+__all__ = ["is_time_like", "to_seconds", "seconds", "time_ticks", "time_labels", "time_unit",
+           "from_seconds", "axis_value", "calendar_ticks"]
+
+_UTC = dt.timezone.utc
+
+
+def _first(v: Any) -> Any:
+    for x in v:
+        if x is not None and not (isinstance(x, float) and math.isnan(x)):
+            return x
+    return None
+
+
+def is_time_like(v: Any) -> bool:
+    """Whether ``v`` is a date or time value, or a sequence or array of them."""
+    if isinstance(v, (dt.date, dt.datetime)):
+        return True
+    kind = getattr(getattr(v, "dtype", None), "kind", None)
+    if kind == "M":
+        return True
+    if isinstance(v, (list, tuple)) and v:
+        return isinstance(_first(v), (dt.date, dt.datetime))
+    return False
+
+
+def seconds(x: Any) -> float:
+    """Seconds since the epoch of one value (naive datetimes are UTC)."""
+    if x is None or (isinstance(x, float) and math.isnan(x)):
+        return math.nan
+    if isinstance(x, dt.datetime):
+        if x.tzinfo is not None:
+            return x.timestamp()
+        return calendar.timegm(x.timetuple()) + x.microsecond / 1e6
+    if isinstance(x, dt.date):
+        return float(calendar.timegm(x.timetuple()))
+    if hasattr(x, "astype") and getattr(getattr(x, "dtype", None), "kind", None) == "M":
+        n = int(x.astype("datetime64[ns]").astype("int64"))
+        return math.nan if n == -(2 ** 63) else n / 1e9
+    if isinstance(x, (int, float)):
+        return float(x)
+    raise ValueError(f"not a date or time: {x!r}")
+
+
+def axis_value(v: Any) -> float:
+    """A position on an axis as a float: a real number, a date or time (seconds since the
+    epoch), a numpy ``datetime64`` or ISO 8601 text."""
+    from .validators import real
+    x = real(v)
+    if x is not None:
+        return x
+    if isinstance(v, (dt.date, dt.datetime)) or getattr(
+            getattr(v, "dtype", None), "kind", None) == "M":
+        return seconds(v)
+    if isinstance(v, str):
+        try:
+            return seconds(dt.datetime.fromisoformat(v.strip()))
+        except ValueError:
+            pass
+    raise ValueError(f"expected a number, a date or ISO 8601 text, got {v!r}")
+
+
+def to_seconds(v: Any) -> tuple[array.array, Any]:
+    """Seconds since the epoch of every value, and the time zone of the first aware
+    value (``None``: naive, shown as UTC)."""
+    kind = getattr(getattr(v, "dtype", None), "kind", None)
+    if kind == "M":
+        ns = v.astype("datetime64[ns]").astype("int64").tolist()
+        nat = -(2 ** 63)
+        return array.array("d", (math.nan if n == nat else n / 1e9 for n in ns)), None
+    if isinstance(v, (dt.date, dt.datetime)):
+        v = [v]
+    first = _first(v)
+    tz = first.tzinfo if isinstance(first, dt.datetime) else None
+    return array.array("d", (seconds(x) for x in v)), tz
+
+
+#: The first and last times a ``datetime`` holds, in seconds.
+_FIRST = seconds(dt.datetime.min)
+_LAST = seconds(dt.datetime.max)
+
+
+def from_seconds(s: float, tz: Any) -> dt.datetime:
+    """The datetime of ``s`` seconds in zone ``tz`` (naive UTC when ``tz`` is ``None``);
+    times before year 1 or after 9999 are taken at those ends."""
+    s = min(max(s, _FIRST), _LAST)
+    try:
+        d = dt.datetime.fromtimestamp(s, tz or _UTC)
+    except (ValueError, OverflowError):     # the zone's offset passes an end
+        d = (dt.datetime.min if s < 0 else dt.datetime.max).replace(tzinfo=tz or _UTC)
+    return d if tz is not None else d.replace(tzinfo=None)
+
+
+def time_unit(s: float, tz: Any) -> float:
+    """The calendar unit of a time (s): a day at midnight in zone ``tz``, else an hour,
+    a minute or a second at a whole one, else a millisecond."""
+    d = from_seconds(s, tz)
+    if d.microsecond:
+        return 1e-3
+    if d.second:
+        return 1.0
+    if d.minute:
+        return 60.0
+    if d.hour:
+        return 3600.0
+    return 86400.0
+
+
+def _epoch(d: dt.datetime, tz: Any) -> float:
+    return d.timestamp() if tz is not None else seconds(d)
+
+
+#: (unit, step, approximate seconds) candidates, finest first.
+_STEPS = ([("microsecond", s, s * 1e-6) for s in (1, 2, 5, 10, 20, 50, 100, 200, 500, 1000,
+                                                 2000, 5000, 10000, 20000, 50000, 100000,
+                                                 200000, 500000)]
+          + [("second", s, s) for s in (1, 2, 5, 10, 15, 30)]
+          + [("minute", s, 60 * s) for s in (1, 2, 5, 10, 15, 30)]
+          + [("hour", s, 3600 * s) for s in (1, 2, 3, 6, 12)]
+          + [("day", s, 86400 * s) for s in (1, 2, 7, 14)]
+          + [("month", s, 2629746 * s) for s in (1, 2, 3, 6)]
+          + [("year", s, 31556952 * s) for s in (1, 2, 5, 10, 20, 25, 50, 100, 200, 250, 500,
+                                                 1000)])
+
+
+def _floor(d: dt.datetime, unit: str, step: int) -> dt.datetime:
+    if unit == "year":                      # year 0 does not exist: the first multiple
+        return d.replace(year=max(d.year - d.year % step, min(step, 9999)), month=1, day=1,
+                         hour=0, minute=0, second=0, microsecond=0)
+    if unit == "month":
+        m = (d.month - 1) - (d.month - 1) % step + 1
+        return d.replace(month=m, day=1, hour=0, minute=0, second=0, microsecond=0)
+    if unit == "day":
+        return d.replace(hour=0, minute=0, second=0, microsecond=0)
+    if unit == "hour":
+        return d.replace(hour=d.hour - d.hour % step, minute=0, second=0, microsecond=0)
+    if unit == "minute":
+        return d.replace(minute=d.minute - d.minute % step, second=0, microsecond=0)
+    if unit == "second":
+        return d.replace(second=d.second - d.second % step, microsecond=0)
+    return d.replace(microsecond=0)
+
+
+def _add(d: dt.datetime, unit: str, step: int) -> dt.datetime:
+    if unit == "year":
+        return d.replace(year=d.year + step)
+    if unit == "month":
+        m = d.month - 1 + step
+        return d.replace(year=d.year + m // 12, month=m % 12 + 1)
+    delta = {"hour": dt.timedelta(hours=step), "minute": dt.timedelta(minutes=step),
+             "second": dt.timedelta(seconds=step),
+             "microsecond": dt.timedelta(microseconds=step),
+             "day": dt.timedelta(days=1)}[unit]
+    return d + delta
+
+
+def _candidates(lo: float, hi: float, unit: str, step: int, tz: Any) -> list[float]:
+    start = _floor(from_seconds(lo, tz), unit, step)
+    out: list[float] = []
+    d = start
+    guard = 0
+    while guard < 100000:
+        guard += 1
+        s = _epoch(d, tz)
+        if s > hi + 1e-9:
+            break
+        keep = unit != "day" or (d.toordinal() - 1) % step == 0   # every step-th day
+        if keep and s >= lo - 1e-9:
+            out.append(s)
+        try:
+            d = _add(d, unit, step)
+        except (ValueError, OverflowError):     # past year 9999
+            break
+    return out
+
+
+def calendar_ticks(lo: float, hi: float, unit: str, step: int, tz: Any) -> list[float]:
+    """Times from ``lo`` to ``hi`` (seconds) every ``step`` calendar ``unit`` (``year``,
+    ``month``, ``day``, ``hour``, ``minute``, ``second``, ``microsecond``) in zone
+    ``tz``."""
+    from .ticks import MAX_TICKS
+    if hi < lo:
+        lo, hi = hi, lo
+    approx = next(a / s for u, s, a in _STEPS if u == unit) * step
+    if (hi - lo) / approx > MAX_TICKS:
+        raise ValueError(f"ticks every {step} {unit}s: more than {MAX_TICKS} ticks")
+    return _candidates(lo, hi, unit, step, tz)
+
+
+def time_ticks(lo: float, hi: float, max_ticks: int, tz: Any,
+               fmt: Any = "auto") -> tuple[list[tuple[float, str]], str | None]:
+    """Ticks between ``lo`` and ``hi`` seconds: ``[(value, label)]`` and the offset text
+    (the larger unit common to every tick: ``"Mar 2026"``)."""
+    if hi < lo:
+        lo, hi = hi, lo
+    span = max(hi - lo, 1e-6)
+    unit = "year"
+    ticks: list[float] = []
+    for u, s, approx in _STEPS:
+        if span / approx > max_ticks * 1.5:
+            continue
+        cand = _candidates(lo, hi, u, s, tz)
+        if 2 <= len(cand) <= max_ticks or (len(cand) <= max_ticks and u == "year"):
+            unit, ticks = u, cand
+            break
+    if not ticks:
+        ticks = [lo, hi]
+        unit = "second" if span < 86400 else "day"
+    dts = [from_seconds(t, tz) for t in ticks]
+    if isinstance(fmt, str) and "%" in fmt:
+        return [(t, d.strftime(fmt)) for t, d in zip(ticks, dts)], None
+    if callable(fmt):
+        return [(t, str(fmt(d))) for t, d in zip(ticks, dts)], None
+    return _concise(ticks, dts, unit, from_seconds((lo + hi) / 2, tz))
+
+
+def time_labels(values: list[float], tz: Any, fmt: Any = "auto"
+                ) -> tuple[list[str], str | None]:
+    """Labels of given tick times (seconds) and the offset text, as :func:`time_ticks`
+    writes them: concise labels in the finest calendar unit the ticks need."""
+    dts = [from_seconds(t, tz) for t in values]
+    if isinstance(fmt, str) and "%" in fmt:
+        return [d.strftime(fmt) for d in dts], None
+    if callable(fmt):
+        return [str(fmt(d)) for d in dts], None
+    if not dts:
+        return [], None
+    if any(d.microsecond for d in dts):
+        unit = "microsecond"
+    elif any(d.second for d in dts):
+        unit = "second"
+    elif any(d.hour or d.minute for d in dts):
+        unit = "minute"
+    elif any(d.day != 1 for d in dts):
+        unit = "day"
+    elif any(d.month != 1 for d in dts):
+        unit = "month"
+    else:
+        unit = "year"
+    pairs, offset = _concise(list(values), dts, unit, from_seconds(
+        (min(values) + max(values)) / 2, tz))
+    return [lab for _, lab in pairs], offset
+
+
+def _concise(ticks: list[float], dts: list[dt.datetime], unit: str, mid: dt.datetime
+             ) -> tuple[list[tuple[float, str]], str | None]:
+    """Concise labels of the ticks of ``unit`` and the offset text, the date part common
+    to the ticks written from the axis' middle (``mid``)."""
+    same_year = len({d.year for d in dts}) == 1
+    same_day = len({d.date() for d in dts}) == 1
+    if unit == "year":
+        return [(t, d.strftime("%Y")) for t, d in zip(ticks, dts)], None
+    if unit == "month":
+        labels = [d.strftime("%Y") if d.month == 1 and not same_year else d.strftime("%b")
+                  for d in dts]
+        return list(zip(ticks, labels)), (mid.strftime("%Y") if same_year else None)
+    if unit == "day":
+        labels = [d.strftime("%b %d").replace(" 0", " ") for d in dts]
+        return list(zip(ticks, labels)), (mid.strftime("%Y") if same_year else None)
+    if unit in ("hour", "minute"):
+        labels = [d.strftime("%H:%M") if (d.hour, d.minute) != (0, 0) or same_day
+                  else d.strftime("%b %d").replace(" 0", " ") for d in dts]
+        off = mid.strftime("%b %d, %Y").replace(" 0", " ") if same_day else (
+            mid.strftime("%Y") if same_year else None)
+        return list(zip(ticks, labels)), off
+    if unit == "second":
+        labels = [d.strftime("%H:%M:%S") for d in dts]
+        off = mid.strftime("%b %d, %Y").replace(" 0", " ") if same_day else None
+        return list(zip(ticks, labels)), off
+    digits = 6
+    while digits > 0 and all(d.microsecond % (10 ** (7 - digits)) == 0 for d in dts):
+        digits -= 1
+    labels = [d.strftime("%S") + ("." + f"{d.microsecond:06d}"[:digits] if digits else "")
+              for d in dts]
+    return list(zip(ticks, labels)), mid.strftime("%b %d, %Y %H:%M").replace(" 0", " ", 1)