plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/genome/regions.py

@@ -0,0 +1,228 @@
+"""Genomic regions: parsing what ``region=`` takes, and the unit of coordinate labels."""
+
+import math
+import re
+from collections.abc import Mapping
+from decimal import Decimal, InvalidOperation
+from typing import Any, NamedTuple
+
+__all__ = ["Region", "Regions", "Chromosome", "parse_region", "parse_regions", "parse_bp",
+           "auto_unit", "whole", "pending", "UNITS"]
+
+#: Coordinate units and their size in bp.
+UNITS = {"bp": 1, "kb": 1_000, "Mb": 1_000_000, "Gb": 1_000_000_000}
+
+_POS = r"[\d.,_]+(?:[eE]\d+)?\s*(?:[kKmMgG][bB]?|[bB][pP])?"
+_STRING = re.compile(rf"^\s*([^:\s]+)\s*:\s*({_POS})\s*-\s*({_POS})\s*$")
+_SIZE = re.compile(r"^([\d.,_]+(?:[eE]\d+)?)\s*([kKmMgG][bB]?|[bB][pP])?$")
+_SUFFIX = {"": 1, "bp": 1, "k": 1_000, "kb": 1_000, "m": 1_000_000, "mb": 1_000_000,
+           "g": 1_000_000_000, "gb": 1_000_000_000}
+_NAME = re.compile(r"^[^:\s,]+$")
+_THOUSANDS = re.compile(r"^\d{1,3}(?:,\d{3})+$")
+_CHR_KEYS = ("chr", "chrom", "chromosome", "chr_id", "seqname")
+_START_KEYS = ("start", "chromStart", "chrom_start")
+_END_KEYS = ("end", "chromEnd", "chrom_end")
+
+
+class Region(NamedTuple):
+    """A region: 0-based, half-open."""
+
+    chr: str
+    start: int
+    end: int
+
+    @property
+    def span(self) -> int:
+        return self.end - self.start
+
+    def __str__(self) -> str:
+        return f"{self.chr}:{self.start + 1:,}-{self.end:,}"
+
+
+class Chromosome(NamedTuple):
+    """A whole chromosome (``"chr1"``): a region whose end, the chromosome's size, is known
+    once the figure is drawn (see :func:`whole`)."""
+
+    chr: str
+
+    def __str__(self) -> str:
+        return self.chr
+
+
+def parse_bp(v: Any, what: str = "position", positive: bool = False) -> int:
+    """A position or length in bp: a whole number, or a string with digit separators
+    (``"1,200,000"``, ``"1_200_000"``) and an optional unit (``"1.2M"``, ``"1.2Mb"``,
+    ``"500k"``, ``"500kb"``, ``"1200bp"``; ``k``, ``M``, ``G``, case-insensitive)."""
+    if isinstance(v, str):
+        m = _SIZE.match(v.strip())
+        if m is None:
+            raise ValueError(f"{what} must be a number of bp (\"1,200,000\", \"1.2M\", "
+                             f"\"500kb\"), got {v!r}")
+        digits, unit = m.group(1), (m.group(2) or "").lower()
+        if "." in digits and "," in digits:
+            raise ValueError(f"{what}: write {v!r} without thousands separators")
+        if "," in digits and not _THOUSANDS.match(digits.split("e")[0].split("E")[0]):
+            raise ValueError(f"{what}: the commas of {v!r} are not thousands separators "
+                             f"(\"1,500,000\"); a decimal is written with a point "
+                             f"(\"1.5M\")")
+        try:
+            d = Decimal(digits.replace(",", "").replace("_", "")) * _SUFFIX[unit]
+        except InvalidOperation:
+            raise ValueError(f"{what} must be a number of bp, got {v!r}") from None
+        if d != d.to_integral_value():
+            raise ValueError(f"{what} must be a whole number of bp, got {v!r}")
+        n = int(d)
+    else:
+        try:
+            f = float(v)
+        except (TypeError, ValueError):
+            raise ValueError(f"{what} must be a number, got {v!r}") from None
+        if not math.isfinite(f) or f != int(f):
+            raise ValueError(f"{what} must be a whole number, got {v!r}")
+        n = int(f)
+    if positive and n <= 0:
+        raise ValueError(f"{what} must be positive, got {v!r}")
+    return n
+
+
+def _int(v: Any, what: str) -> int:
+    return parse_bp(v, f"region {what}")
+
+
+def _pick(m: Mapping[str, Any], keys: tuple[str, ...]) -> Any:
+    for k in keys:
+        if k in m:
+            v = m[k]
+            if not isinstance(v, (str, int, float)) and hasattr(v, "__len__"):
+                if len(v) != 1:
+                    raise ValueError("a region mapping holds one region")
+                v = v[0]
+            return v
+    raise ValueError(f"a region mapping needs one of {', '.join(map(repr, keys))}")
+
+
+def parse_region(v: Any, whole: bool = False) -> Region:
+    """A region from a string, 1-based and inclusive (``"chr2:143,120,001-143,780,000"``;
+    positions with units: ``"chr1:1.2M-1.5M"``, ``"chr1:500kb-2Mb"``, see
+    :func:`parse_bp`), a ``(chr, start, end)`` tuple or list, 0-based and half-open, or a
+    mapping with ``chr``, ``start`` and ``end``.  A region has no strand: one given (a
+    fourth element, a ``strand`` key) is an error.  ``whole``: a chromosome name alone
+    (``"chr1"``) is the whole chromosome, a :class:`Chromosome`."""
+    if isinstance(v, Region):
+        return v
+    if whole and isinstance(v, Chromosome):
+        return v  # type: ignore[return-value]
+    if whole and isinstance(v, str) and _NAME.match(v.strip()):
+        return Chromosome(v.strip())  # type: ignore[return-value]
+    if isinstance(v, str):
+        m = _STRING.match(v)
+        if m is None:
+            raise ValueError(f"expected 'chr:start-end' (1-based, inclusive), got {v!r}")
+        chr_, start, end = m.group(1), _int(m.group(2), "start") - 1, _int(m.group(3), "end")
+        if start < 0 or end <= start:
+            raise ValueError(f"a region needs 1 <= start <= end (1-based, inclusive), got "
+                             f"{start + 1:,}-{end:,} in {v!r}")
+    elif isinstance(v, Mapping):
+        if "strand" in v:
+            raise ValueError(f"a region has no strand (drawn the same either way), got {v!r}")
+        chr_ = str(_pick(v, _CHR_KEYS))
+        start, end = _int(_pick(v, _START_KEYS), "start"), _int(_pick(v, _END_KEYS), "end")
+    elif isinstance(v, (tuple, list)) and len(v) == 4:
+        raise ValueError(f"a region has no strand (drawn the same either way): give "
+                         f"(chr, start, end), got {v!r}")
+    elif isinstance(v, (tuple, list)) and len(v) == 3:
+        chr_, start, end = str(v[0]), _int(v[1], "start"), _int(v[2], "end")
+    else:
+        raise ValueError(f"expected 'chr:start-end', (chr, start, end) or a mapping, "
+                         f"got {v!r}")
+    if start < 0 or end <= start:
+        raise ValueError(f"a region needs 0 <= start < end, got {start}-{end}")
+    return Region(chr_, start, end)
+
+
+class Regions(tuple):
+    """Several regions drawn side by side (``region=[r1, r2]``), in order."""
+
+    def __str__(self) -> str:
+        return ", ".join(str(r) for r in self)
+
+    def __repr__(self) -> str:
+        return f"Regions({', '.join(repr(str(r)) for r in self)})"
+
+
+def _one(v: Any) -> bool:
+    """Whether an element of a list can only be a region of its own (not a field of one)."""
+    return isinstance(v, (Region, Chromosome, Mapping, tuple, list)) or (
+        isinstance(v, str) and _STRING.match(v) is not None)
+
+
+def _names(v: Any) -> bool:
+    """Whether a list is of chromosome names (``["chr1", "chr2"]``), not ``(chr, start,
+    end)`` with positions as strings."""
+    if not all(isinstance(e, str) and _NAME.match(e.strip()) for e in v):
+        return False
+    for e in v[1:]:
+        try:
+            parse_bp(e)
+        except ValueError:
+            continue
+        return False
+    return True
+
+
+def parse_regions(v: Any) -> Region | Regions:
+    """A region (as :func:`parse_region` takes it, a chromosome name included) or several,
+    a list of regions or chromosome names (as :class:`Regions`; a list of one is that
+    region)."""
+    if isinstance(v, Regions):
+        return v
+    if isinstance(v, (tuple, list)) and not isinstance(v, (Region, Chromosome)) and v \
+            and (all(_one(e) for e in v) or _names(v)):
+        got = [parse_region(e, whole=True) for e in v]
+        return got[0] if len(got) == 1 else Regions(got)
+    return parse_region(v, whole=True)
+
+
+def pending(v: Any) -> bool:
+    """Whether a region value (a region, several, ``None``) holds a whole chromosome whose
+    size is not known yet."""
+    return isinstance(v, Chromosome) or (isinstance(v, Regions) and
+                                         any(isinstance(r, Chromosome) for r in v))
+
+
+def whole(v: Any, sizes: Any) -> Any:
+    """``v`` (a region value) with each :class:`Chromosome` made the region of the whole
+    chromosome; ``sizes()`` gives the chromosome sizes known (a mapping), called once and
+    only when needed.  A chromosome without a size raises naming ``chr_sizes``."""
+    if not pending(v):
+        return v
+    known = sizes()
+
+    def one(r: Any) -> Region:
+        if not isinstance(r, Chromosome):
+            return r
+        n = known.get(r.chr)
+        if n is None:
+            raise ValueError(f"the size of {r.chr!r} is unknown: give the x axis chr_sizes "
+                             f"(a mapping of chromosome sizes, gwseq_io.get_chr_sizes(…)) or "
+                             f"draw a reader that has it")
+        return Region(r.chr, 0, int(n))
+    return Regions(one(r) for r in v) if isinstance(v, Regions) else one(v)
+
+
+def auto_unit(lo: float, hi: float) -> str:
+    """The unit coordinate labels from ``lo`` to ``hi`` (bp, drawn values) are written in:
+    with the ticks about a fifth of the span apart, the largest unit in which they are at
+    least 1 apart and at most 1000; else the largest in which they are at most 1000 and
+    need at most 3 decimals; else bp."""
+    step = (hi - lo) / 5 or 1.0
+    big = max(abs(lo), abs(hi))
+    for name in ("Gb", "Mb", "kb", "bp"):
+        u = UNITS[name]
+        if step >= u and big <= 1000 * u:
+            return name
+    for name in ("Gb", "Mb", "kb"):
+        u = UNITS[name]
+        if big <= 1000 * u and step >= 0.001 * u:
+            return name
+    return "bp"

plot_io/genome/scale.py

@@ -0,0 +1,349 @@
+"""The genome scale of an axis (``scale="genome"``): linear in bp, its limits the axis'
+``region`` less its ``origin``, without padding, tick labels in bp, kb or Mb (``unit``,
+``unit_in``) or as ``chr:pos`` (``tick_format="chr:pos"``), and the chromosome as the
+automatic label.  Genome series set it on their x
+axis when it has no scale of its own.
+
+An axis over several regions (``region=[r1, r2]``) draws them side by side as segments
+(:class:`Segments`): each ``region_widths="span"`` wide (its share of the bp) or
+``"equal"``, ``region_gap`` apart, with its own ticks and chromosome label.  Its drawn
+units run from 0 at the first segment's start; a segment draws its region's positions
+through :meth:`Segment.u`.
+
+With ``scale_bar``, an x genome axis draws a scale bar in place of its ticks and tick
+labels: a bar at its right end (at each segment's, over several regions) with its length
+written left of it (``10 kb``); the label is the chromosome without a unit."""
+
+import copy
+from typing import Any, NamedTuple
+
+from ..numbers import NumberStyle, _decimals, _fixed
+from .regions import UNITS, Region, Regions, auto_unit, parse_bp
+
+__all__ = ["GenomeFormat", "CHR_POS", "check_tick_format", "origin_of", "axis_unit",
+           "axis_label", "Segment", "Segments", "segments_of", "segment_ticks",
+           "segment_labels", "check_scale_bar", "scale_bar_on", "bar_length", "bar_text",
+           "scale_bars"]
+
+#: The ``tick_format`` writing genome positions as ``chr2:143,250,000``.
+CHR_POS = "chr:pos"
+
+
+def check_tick_format(v: Any) -> Any:
+    """An axis ``tick_format``: a number format, or ``"chr:pos"`` (genome axes)."""
+    if isinstance(v, str) and v.strip().lower() == CHR_POS:
+        return CHR_POS
+    from ..numbers import check_format
+    return check_format(v)
+
+
+class GenomeFormat:
+    """Tick labels of genome coordinates (drawn bp) in ``unit``: numbers alone
+    (``unit_in="label"``) or with the unit (``"ticks"``: ``500kb``; 0 stays ``0``); bp
+    with ``,`` between thousands unless the style has its own separator.  With
+    ``chr``, positions as ``chr:pos``: the chromosome, then the position (the drawn value
+    plus ``origin``) in bp with ``,`` between thousands (``chr2:143,250,000``), or in kb
+    or Mb with the unit (``chr2:143.25Mb``)."""
+
+    def __init__(self, unit: str, unit_in: str, chr: str | None = None,
+                 origin: float = 0.0) -> None:
+        self.unit = unit
+        self.unit_in = unit_in
+        self.chr = chr
+        self.origin = origin
+
+    def format_all(self, values: list[float], style: NumberStyle) -> list[Any]:
+        u = UNITS[self.unit]
+        if self.chr is not None:
+            return self._positions(values, u, style)
+        if u == 1 and not style.thousands:          # bp: "," between thousands
+            style = copy.copy(style)
+            style.thousands = ","
+        scaled = [v / u for v in values]
+        d = _decimals(scaled, None, cap=6)
+        out = []
+        for v in scaled:
+            text = _fixed(v, d)
+            if self.unit_in == "ticks" and float(text) == 0:
+                s = "0"
+            else:
+                s = style.digits(text) + (self.unit if self.unit_in == "ticks" else "")
+            out.append(style.wrap(s))
+        return out
+
+    def _positions(self, values: list[float], u: int, style: NumberStyle) -> list[Any]:
+        scaled = [(v + self.origin) / u for v in values]
+        d = _decimals(scaled, None, cap=6)
+        out = []
+        for v in scaled:
+            text = _fixed(v, d)
+            if u == 1:
+                whole, _, frac = text.partition(".")
+                sign = "-" if whole.startswith("-") else ""
+                whole = f"{int(whole.lstrip('-')):,}"
+                text = sign + whole + ("." + frac if frac else "")
+                out.append(f"{self.chr}:{text}")
+            else:
+                out.append(f"{self.chr}:{style.digits(text)}{self.unit}")
+        return out
+
+    def __call__(self, v: float) -> Any:
+        return self.format_all([v], NumberStyle())[0]
+
+    def _key(self) -> tuple[Any, ...]:
+        return (self.unit, self.unit_in, self.chr, self.origin)
+
+    def __eq__(self, other: Any) -> bool:
+        return isinstance(other, GenomeFormat) and self._key() == other._key()
+
+    def __hash__(self) -> int:
+        return hash(self._key())
+
+
+def origin_of(origin: Any, region: Region | None) -> float | None:
+    """The position an axis ``origin`` names on a genome axis over ``region`` (``center``,
+    ``start``, ``end`` of the region, or a position); ``None`` for an anchor without a
+    region."""
+    if origin is None:
+        return 0.0
+    if isinstance(origin, str):
+        if region is None:
+            return None
+        return {"center": (region.start + region.end) / 2, "start": float(region.start),
+                "end": float(region.end)}[origin]
+    return float(origin)
+
+
+def axis_unit(axis: Any, lo: float, hi: float) -> str:
+    """The axis' ``unit``; ``auto``: from its limits (drawn bp), bp for ``chr:pos``
+    labels."""
+    u = axis.resolve("unit")
+    if u != "auto":
+        return u
+    return "bp" if axis.resolve("tick_format") == CHR_POS else auto_unit(lo, hi)
+
+
+def tick_format(state: Any) -> Any:
+    """The ``GenomeFormat`` of a genome axis whose ``tick_format`` is ``auto`` or
+    ``chr:pos``; ``None`` for other formats."""
+    axis = state.axis
+    fmt = axis.resolve("tick_format")
+    if fmt not in ("auto", CHR_POS):
+        return None
+    unit = axis_unit(axis, state.lo, state.hi)
+    if fmt == CHR_POS:
+        if state.region is None:
+            raise ValueError("tick_format=\"chr:pos\" needs the axis' region")
+        return GenomeFormat(unit, "ticks", state.region.chr, state.origin)
+    return GenomeFormat(unit, axis.resolve("unit_in"))
+
+
+def axis_label(state: Any, given: Any) -> Any:
+    """The label of a genome axis: ``given`` (a string's ``{chr}``, ``{unit}``,
+    ``{start}``, ``{end}`` filled in), else the chromosome, with the unit unless the tick
+    labels show it; ``None`` without a region."""
+    region = state.region
+    axis = state.axis
+    unit = axis_unit(axis, state.lo, state.hi)
+    if given is None:
+        if region is None or axis.resolve("tick_format") == CHR_POS:
+            return None
+        given = "{chr} ({unit})" if axis.resolve("unit_in") == "label" \
+            and not scale_bar_on(state) else "{chr}"
+    if not isinstance(given, str) or "{" not in given:
+        return given
+    if region is None:
+        return given
+    return given.format(chr=region.chr, unit=unit, start=region.start + 1, end=region.end)
+
+
+class Segment(NamedTuple):
+    """A region of an axis over several: drawn from ``u0`` (drawn units), ``k`` drawn units
+    per bp, ``px`` wide on axes as wide as the segments were made for, its ``number`` (from 0)."""
+
+    region: Region
+    u0: float
+    k: float
+    px: float
+    number: int
+
+    @property
+    def u1(self) -> float:
+        return self.u0 + self.region.span * self.k
+
+    def u(self, pos: float) -> float:
+        """Drawn position of ``pos`` (bp)."""
+        return self.u0 + (pos - self.region.start) * self.k
+
+    def holds(self, chr: str, pos: float) -> bool:
+        return chr == self.region.chr and self.region.start <= pos <= self.region.end
+
+
+class Segments(tuple):
+    """The segments of an axis over several regions, in order; ``total``: the drawn units
+    from the first segment's start to the last's end."""
+
+    total: float
+
+    def __new__(cls, regions: Regions, widths: str, gap: float, width: float) -> "Segments":
+        spans = [float(r.span) for r in regions]
+        drawn = spans if widths == "span" else [sum(spans) / len(spans)] * len(spans)
+        n = len(regions)
+        room = max(width - gap * (n - 1), 1.0)            # px of the segments
+        per_px = sum(drawn) / room                        # drawn units per px
+        gap_u = gap * per_px
+        out, u = [], 0.0
+        for i, (r, d) in enumerate(zip(regions, drawn)):
+            out.append(Segment(r, u, d / r.span, d / per_px, i))
+            u += d + gap_u
+        self = super().__new__(cls, out)
+        self.total = u - gap_u
+        return self
+
+    def at(self, chr: str, pos: float) -> Segment | None:
+        """The segment holding ``chr:pos`` (the first, where regions overlap)."""
+        return next((s for s in self if s.holds(chr, pos)), None)
+
+
+def segments_of(plot: Any, width: float | None = None) -> Segments | None:
+    """The segments of ``plot``'s x axis for axes ``width`` px wide (default: the width its
+    genome data are binned for), or ``None``: the axis has one region or none."""
+    from .series import axis_region
+    axis = plot.x_axis
+    r = axis_region(axis)
+    if not isinstance(r, Regions):
+        return None
+    if width is None:
+        from .series import axes_width
+        width = axes_width(plot)
+    return Segments(r, axis.resolve("region_widths"), float(axis.resolve("region_gap")),
+                    width)
+
+
+def _segment_state(state: Any, seg: Segment) -> Any:
+    """An axis state over one segment's region, in bp (its ticks and label)."""
+    st = copy.copy(state)
+    st.segments = None
+    st.shared = None
+    st.call_ticks = None
+    st.region, st.origin = seg.region, 0.0
+    st.lo = st.flo = float(seg.region.start)
+    st.hi = st.fhi = float(seg.region.end)
+    return st
+
+
+def segment_ticks(state: Any, fonts: Any, length: float, horizontal: bool) -> None:
+    """The ticks of an axis over several regions ``length`` px long: each segment's, as an
+    axis over its region as wide as the segment, at their drawn positions."""
+    from ..text import lines_box
+    from ..ticks import Tick
+    segs = state.segments
+    per_px = length / (segs.total or 1.0)
+    font = state.tick_font()
+    gap = state.axis.resolve("tick_label_gap")
+    ticks: list[Any] = []
+    rotation = 0.0
+    for seg in segs:
+        st = _segment_state(state, seg)
+        st._compute_ticks(fonts, (seg.u1 - seg.u0) * per_px, horizontal)
+        mine = [Tick(seg.u(t.value), t.label, t.major) for t in st.ticks]
+        if horizontal and ticks:          # labels meeting across the gap: the earlier goes
+            last = max((i for i, t in enumerate(ticks) if t.label is not None), default=None,
+                       key=lambda i: ticks[i].value)
+            first = min((t for t in mine if t.label is not None), default=None,
+                        key=lambda t: t.value)
+            if last is not None and first is not None:
+                t = ticks[last]
+                a = (t.value * per_px + lines_box(fonts, t.label, font)[0] / 2)
+                b = (first.value * per_px - lines_box(fonts, first.label, font)[0] / 2)
+                if a + gap > b:
+                    ticks[last] = Tick(t.value, None, t.major)
+        ticks += mine
+        rotation = st.rotation
+    state.ticks, state.length = ticks, length
+    state.offset_label, state.rotation = None, rotation
+
+
+def segment_labels(state: Any) -> list[tuple[Any, Segment]]:
+    """The label of each segment of an axis over several regions (as :func:`axis_label`
+    over its region; ``None`` left out) and the segment."""
+    from ..states import label_content
+    out = []
+    for seg in state.segments:
+        content = label_content(_segment_state(state, seg))
+        if content is not None:
+            out.append((content, seg))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Scale bar
+# ---------------------------------------------------------------------------
+
+def check_scale_bar(v: Any) -> Any:
+    """An axis ``scale_bar``: ``False``, ``True`` (an automatic length) or a length in bp
+    (``"10kb"``, ``5000``)."""
+    if v is None or v is False:
+        return False
+    if v is True:
+        return True
+    return parse_bp(v, "scale bar length", positive=True)
+
+
+def scale_bar_on(state: Any) -> bool:
+    """Whether an axis state draws a scale bar: an x genome axis with ``scale_bar``."""
+    return bool(state.genome and state.axis.role == "x"
+                and state.axis.resolve("scale_bar") is not False)
+
+
+def bar_length(span: float) -> int:
+    """The automatic scale bar length over ``span`` bp: the largest 1, 2 or 5 × 10ᵏ bp at
+    most a fifth of it (at least 1 bp)."""
+    best = 1
+    k = 1
+    while k <= span / 5:
+        for m in (1, 2, 5):
+            if m * k <= span / 5:
+                best = m * k
+        k *= 10
+    return best
+
+
+def bar_text(n: int) -> str:
+    """A scale bar length written in the largest unit it is at least one of
+    (``200 kb``, ``1.5 Mb``, ``50 bp``)."""
+    unit = max((u for u, f in UNITS.items() if n >= f), key=lambda u: UNITS[u], default="bp")
+    v = n / UNITS[unit]
+    text = f"{v:.3f}".rstrip("0").rstrip(".")
+    return f"{text} {unit}"
+
+
+def scale_bars(state: Any, mapper: Any, room: Any = None) -> list[tuple[float, float, str]]:
+    """The scale bars of an axis state drawing them (:func:`scale_bar_on`): ``(left,
+    right, text)`` in page units through ``mapper``, one per region, each at its right
+    end; a bar longer than its region spans it.  ``room(text)``: the px its text takes
+    left of the bar; an automatic length is shortened (2, 1, 0.5 × …) until bar and
+    text fit in the region."""
+    given = state.axis.resolve("scale_bar")
+    if state.segments is not None:
+        parts = [(seg.u0, seg.u1, float(seg.region.span)) for seg in state.segments]
+    else:
+        parts = [(state.lo, state.hi, abs(state.hi - state.lo))]
+    out = []
+    for u0, u1, span in parts:
+        a, b = sorted((mapper(u0), mapper(u1)))
+        if not span > 0 or not b > a:
+            continue
+        n = bar_length(span) if given is True else int(given)
+        while given is True and room is not None and n > 1 \
+                and b - (b - a) * n / span - room(bar_text(n)) < a:
+            n = _shorter(n)
+        out.append((max(a, b - (b - a) * n / span), b, bar_text(n)))
+    return out
+
+
+def _shorter(n: int) -> int:
+    """The 1, 2 or 5 × 10ᵏ length below ``n`` (one of them)."""
+    k = 10 ** (len(str(n)) - 1)
+    m = n // k
+    return 2 * k if m == 5 else k if m == 2 else max(1, k // 2)