plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/rows.py

@@ -0,0 +1,491 @@
+"""Rows of a figure: row labels in a band left of the plots, groups of rows, and lines and
+bands drawn through several rows.
+
+* A plot's y axis ``label`` with ``label_position`` ``band`` or ``left`` sits in a band left
+  of the y axis: the band is as wide as the widest label of the plots starting in the same
+  grid column, and the labels line up at the widest y axis margin of that column
+  (``inside``: top left inside the axes).  On a plot whose class sets ``BAND_FITS`` (genome
+  tracks), a ``band`` label longer than the axes are high is drawn as ``left``.
+* ``figure.group(first, last)`` (:class:`FigureGroup`): consecutive plots with a panel
+  ``letter`` in a band left of the row labels, a ``label`` as a left figure title over them
+  (:meth:`FigureGroup.title`, in the lanes left of their column); the group's last plot
+  shows the tick labels of a shared x axis.
+* ``figure.vline(x, rows=…)`` (:class:`FigureVLine`) and ``figure.vspan(x0, x1, rows=…)``
+  (:class:`FigureVSpan`): from the top of the first plot's axes to the bottom of the last
+  one's, the gaps included, at x positions of the plots' x axis (drawn units); bands under
+  the plots, lines over them.
+"""
+
+from typing import Any
+
+from ._methods import FigureGroupMixin, FigureVLineMixin, FigureVSpanMixin
+from . import groups
+from .color.values import color
+from .settings import Setting, Settings, family, number, table, text
+from .text import Font, font_of, line_pitch, measure, plain, rich, run
+from .times import axis_value
+from .titles import CREATED
+from .validators import length
+
+__all__ = ["FigureVLine", "FigureVSpan", "FigureGroup", "lines", "label_text", "label_extent", "bands",
+           "with_bands", "place_label", "occupy_label", "place_figure"]
+
+
+def lines(content: Any, font: Font | None = None) -> list[Any]:
+    """Content split at ``\\n``: a list of lines (strings, or lists of runs); with
+    ``font``, its markup read first (see :func:`~plot_io.text.rich`), so tags may span
+    lines."""
+    if content is None:
+        return []
+    if font is not None:
+        content = rich(content, font)
+    if isinstance(content, str):
+        return content.split("\n")
+    out: list[list[Any]] = [[]]
+    for item in content:
+        if isinstance(item, str):
+            parts = item.split("\n")
+        elif "\n" in item.text:
+            parts = [item.with_text(p) for p in item.text.split("\n")]
+        else:
+            parts = [item]
+        out[-1].append(parts[0])
+        for p in parts[1:]:
+            out.append([p])
+    return [ln if len(ln) != 1 or not isinstance(ln[0], str) else ln[0] for ln in out]
+
+
+def _plot_of(v: Any) -> Any:
+    from .plot import Plot
+    p = getattr(v, "plot", v)
+    if not isinstance(p, Plot):
+        raise ValueError(f"expected a plot or one of its series, got {v!r}")
+    return p
+
+
+def plots_of(rows: Any) -> list[Any] | None:
+    """The plots a ``rows=`` value names (plots or series, one or a list); ``None``: all."""
+    if rows is None:
+        return None
+    items = rows if isinstance(rows, (list, tuple)) else [rows]
+    return [_plot_of(v) for v in items]
+
+
+# ---------------------------------------------------------------------------
+# Row labels
+# ---------------------------------------------------------------------------
+
+def _axis(plot: Any) -> Any:
+    return plot.y_axis
+
+
+def label_text(plot: Any) -> Any:
+    """The row label of a plot: its y axis' ``label`` when its ``label_position`` puts it
+    in the row band or inside the axes (``band``, ``left``, ``inside``), else ``None``."""
+    a = _axis(plot)
+    if a.resolve("label_position") == "axis":
+        return None
+    content = a.resolve("label")
+    return None if content == "" else content
+
+
+def label_font(plot: Any) -> Font:
+    a = _axis(plot)
+    return font_of(a, a.resolve("label_font_size"), a.resolve("label_weight"),
+                   a.resolve("label_style"), a.resolve("label_color"))
+
+
+def _label_position(plot: Any, fonts: Any, content: Any) -> str:
+    """The label's ``label_position``; ``left`` for a ``band`` label longer than the axes
+    are high on a plot whose class sets ``BAND_FITS``."""
+    pos = _axis(plot).resolve("label_position")
+    if pos != "band" or content is None or not getattr(plot, "BAND_FITS", False):
+        return pos
+    from .spec import current
+    r = current()
+    h = None if r is None else r.boxes.get(id(plot), {}).get("axes_height")
+    if h is None:
+        return pos
+    font = label_font(plot)
+    if max(measure(fonts, ln, font)[0] for ln in lines(content, font)) > h:
+        return "left"
+    return pos
+
+
+def label_extent(plot: Any, fonts: Any) -> float:
+    """Width the plot's row label takes left of its y axis (with its pad); 0 inside."""
+    content = label_text(plot)
+    pos = _label_position(plot, fonts, content)
+    if content is None or pos == "inside":
+        return 0.0
+    font = label_font(plot)
+    ls = lines(content, font)
+    if pos == "left":
+        w = max(measure(fonts, ln, font)[0] for ln in ls)
+    else:
+        w = len(ls) * line_pitch(fonts, font)
+    return w + float(_axis(plot).resolve("label_pad"))
+
+
+def with_bands(b: Any, extra: tuple[Any, ...]) -> Any:
+    """Bands ``b`` with the row label and group bands ``extra`` outermost on the left (the
+    left margin reaches past them: from the first one's offset, when it takes room)."""
+    import dataclasses
+    left, right, top, bottom = b.margins
+    if extra and extra[0].size:
+        left = max(left, extra[0].offset)
+    for k in extra:
+        left += k.size
+    return dataclasses.replace(b, left=b.left + extra, margins=(left, right, top, bottom))
+
+
+def bands(fig: Any, areas: list[Any], fonts: Any) -> None:
+    """Add the row label band and the group band of their grid column to the bands of the
+    plots of ``areas``, outermost on the left: the labels line up at the widest y axis
+    margin of the column (the bands' offset), the band as wide as the column's widest
+    label, the group band as its widest group."""
+    from .geometry import Band
+    plots = [a for a in areas if not a.is_bar and a.is_plot]
+    columns: dict[int, list[Any]] = {}
+    for a in plots:
+        columns.setdefault(a.c0, []).append(a)
+    for col in columns.values():
+        base = max(a.margins[0] for a in col)
+        labels = max(label_extent(a.obj, fonts) for a in col)
+        members = {id(a.obj) for a in col}
+        width = max((g.extent(fonts) for g in fig.groups
+                     if any(id(p) in members for p in g.members())), default=0.0)
+        extra = (Band("row_label", base, labels), Band("group", base + labels, width))
+        for a in col:
+            a.bands = with_bands(a.bands, extra)
+            a.state.bands = a.bands
+            a.margins = a.bands.margins
+
+
+def _row_band(b: Any, kind: str) -> Any:
+    return next((k for k in b.left if k.kind == kind), None)
+
+
+def place_label(state: Any, fonts: Any, rect: tuple[float, float, float, float],
+                b: Any, reach: float) -> tuple[Any, ...]:
+    """The runs of the plot's row label, lined up at its band's offset, and never within
+    ``reach`` (px left of the axes that the plot's own bands take there)."""
+    plot = state.plot
+    content = label_text(plot)
+    if content is None:
+        return ()
+    x0, y0, x1, y1 = rect
+    font = label_font(plot)
+    lh = line_pitch(fonts, font)
+    pad = float(_axis(plot).resolve("label_pad"))
+    band = _row_band(b, "row_label")
+    base = band.offset if band is not None else reach
+    if reach > base + 0.01:                 # bands re-measured past the column's
+        base = reach
+    right = x0 - base - pad
+    pos = _label_position(plot, fonts, content)
+    ls = lines(content, font)
+    out = []
+    if pos == "inside":
+        y = y0 + pad * 0.5
+        for ln in ls:
+            out.append(run(fonts, ln, x0 + pad, y, font, "left", "top"))
+            y += lh
+        return tuple(out)
+    lo, hi = getattr(getattr(state, "y", None), "span", (0.0, 0.0))
+    mid = (y0 + hi + y1 - lo) / 2                # the value lane's middle (genome lanes)
+    if pos == "left":
+        y = mid - lh * (len(ls) - 1) / 2
+        for ln in ls:
+            out.append(run(fonts, ln, right, y, font, "right", "center"))
+            y += lh
+        return tuple(out)
+    x = right
+    for ln in reversed(ls):
+        out.append(run(fonts, ln, x, mid, font, "center", "bottom", 90.0))
+        x -= lh
+    return tuple(out)
+
+
+def occupy_label(plot: Any, ctx: Any, occ: Any) -> None:
+    """Marks a row label inside the axes for legend placement (its width estimated)."""
+    content = label_text(plot)
+    if content is None or _axis(plot).resolve("label_position") != "inside":
+        return
+    size = float(_axis(plot).resolve("label_font_size"))
+    ls = lines(content, label_font(plot))
+    pad = float(_axis(plot).resolve("label_pad"))
+    x0, y0 = ctx.rect[0] + pad, ctx.rect[1]
+    w = max(0.6 * size * len(plain(ln)) for ln in ls)
+    lh = _axis(plot).resolve("line_height")
+    lh = 1.2 if lh == "normal" else lh
+    occ.rects([x0], [y0], [x0 + w], [y0 + pad * 0.5 + lh * size * len(ls)], solid=True)
+
+
+# ---------------------------------------------------------------------------
+# Figure decorations
+# ---------------------------------------------------------------------------
+
+class FigureVLine(FigureVLineMixin, Settings):
+    """A vertical line through plots of a figure (``figure.vline``).
+
+    It runs from the top of the first of the plots ``rows`` to the bottom of the last, gaps
+    included, in each grid column; ``x`` is a value of the first plot's x axis in its drawn
+    units (a number, a date, ISO 8601 text, a category).  The plots of a column it crosses
+    must share x (``ValueError`` otherwise).  Lines are drawn over the plots, bands
+    (:class:`FigureVSpan`) under them.
+    """
+
+    SETTINGS = table(
+        **groups.Stroke.embed(only=("color", "line_width", "line_style"),
+                              inherited=("line_width",)),
+        opacity=Setting(number(0, 1), doc="Opacity."),
+    )
+
+    def __init__(self, figure: Any, x: float, rows: Any = None, **settings: Any) -> None:
+        self._figure = figure
+        self.x = _position(x, "vline")
+        self.rows = plots_of(rows)
+        super().__init__(**settings)
+
+    def _parent(self) -> Settings:
+        return self._figure
+
+
+def _position(v: Any, what: str) -> Any:
+    """A position along x: a number or a date (as a number), or text (a category or ISO
+    8601 text, read by the axis)."""
+    if isinstance(v, str):
+        return v
+    try:
+        return axis_value(v)
+    except ValueError:
+        raise ValueError(f"fig.{what}: expected a number, a date or text, got {v!r}") from None
+
+
+def _region_like(v: Any) -> bool:
+    if isinstance(v, str):
+        return True
+    if isinstance(v, (tuple, list)):
+        return len(v) == 3
+    return hasattr(v, "keys") or hasattr(v, "chr")
+
+
+class FigureVSpan(FigureVSpanMixin, Settings):
+    """A vertical band through plots of a figure (``figure.vspan``): from ``x0`` to ``x1``,
+    or over a genome region (``x0`` a region, ``x1`` unset: its positions less the x
+    axis' origin)."""
+
+    SETTINGS = table(
+        color=Setting(color, doc="Fill color."),
+        opacity=Setting(number(0, 1), doc="Opacity."),
+    )
+
+    def __init__(self, figure: Any, x0: Any, x1: Any = None, rows: Any = None,
+                 **settings: Any) -> None:
+        self._figure = figure
+        self.region: Any = None
+        if x1 is None:
+            if not _region_like(x0):
+                raise ValueError("vspan takes x0 and x1, or a region")
+            from .genome.regions import parse_region
+            self.region = parse_region(x0)
+            self.x0, self.x1 = float(self.region.start), float(self.region.end)
+        else:
+            self.x0, self.x1 = _position(x0, "vspan"), _position(x1, "vspan")
+        self.rows = plots_of(rows)
+        super().__init__(**settings)
+
+    def _parent(self) -> Settings:
+        return self._figure
+
+    def span(self, state: Any) -> tuple[float, float]:
+        """``(x0, x1)`` in the drawn units of an x axis state (over several regions: in the
+        first that the band's region overlaps; ``(-1, -1)`` in none)."""
+        if state.segments is not None:
+            if self.region is None:
+                raise ValueError("fig.vspan(x0, x1) on an x axis over several regions: give "
+                                 "a region (fig.vspan(\"chr1:1,000-2,000\"))")
+            r = self.region
+            for seg in state.segments:
+                g = seg.region
+                if g.chr == r.chr and r.start < g.end and r.end > g.start:
+                    return seg.u(max(r.start, g.start)), seg.u(min(r.end, g.end))
+            return -1.0, -1.0
+        if self.region is None:
+            return state.value(self.x0), state.value(self.x1)
+        o = state.origin if state.genome else 0.0
+        return self.x0 - o, self.x1 - o
+
+
+class FigureGroup(FigureGroupMixin, Settings):
+    """Consecutive plots with a common label (a left figure title over them) and letter
+    (left of their row labels), and the tick labels of a shared x axis under the last one
+    (``figure.group``).
+
+    Row labels: a y axis ``label`` with ``label_position`` ``"band"`` (rotated) or ``"left"``
+    (horizontal) sits in a band left of the plot, as wide as the widest label of the plots
+    starting in the same grid column, lined up at that column's widest y axis margin;
+    ``"inside"`` puts it inside the axes at the top left.  The group's ``label`` is a left
+    figure title over its plots (normal weight, the group's font settings, ``pad`` from the
+    plots), made at each layout and not in ``figure.titles``; the plots must fill the grid
+    rectangle they span.  The bold ``letter`` sits left of the row labels, level with the
+    top of the first plot's axes.  With a shared x axis and ``label_outer``, the last plot
+    of the group shows tick labels too.  ``plot.save()`` leaves the label out.
+    """
+
+    SETTINGS = table(
+        label=Setting(text, doc="Group label: a left figure title over the group's plots, "
+                                "reading upward, centered on their axes."),
+        letter=Setting(text, doc="Panel letter at the group's top left, left of the row "
+                                 "labels."),
+        font_size=Setting(length(positive=True, font=True, percent="em"), doc="Font size "
+                                                                              "of the label."),
+        **groups.TextStyle.embed("letter_",
+                                 only=("font_size", "font_weight"),
+                                 docs={"font_size": "Font size of the letter.",
+                                       "font_weight": "Weight of the letter."}),
+        pad=Setting(length(lo=0, percent="em"), doc="Gap right of the letter, and the label's "
+                                                    "`pad` (its gap to the plots)."),
+        font_family=Setting(family, inherited=True, doc="Font family."),
+        text_color=Setting(color, inherited=True, doc="Text color."),
+        **groups.Font.embed(only=("markup",)),
+    )
+
+    def __init__(self, figure: Any, first: Any, last: Any, **settings: Any) -> None:
+        self._figure = figure
+        self.first, self.last = first, last
+        self._made = next(CREATED)
+        super().__init__(**settings)
+
+    def _parent(self) -> Settings:
+        return self._figure
+
+    def members(self) -> list[Any]:
+        plots = self._figure.plots
+        i, j = plots.index(self.first), plots.index(self.last)
+        return plots[min(i, j):max(i, j) + 1]
+
+    def end(self) -> Any:
+        """The plot under which the group's x tick labels are drawn."""
+        return self.members()[-1]
+
+    def _font(self, size: str, weight: Any = "normal") -> Font:
+        f = font_of(self._figure, self.resolve(size), weight, color=self.resolve("text_color"),
+                    markup=self.resolve("markup"))
+        f.family = self.resolve("font_family")
+        return f
+
+    def title(self) -> Any:
+        """The group's label as a figure title (``None`` without a label): on the left of
+        its plots, rotated 90 (reading upward), centered on their axes, in the label's font
+        (``font_size``, ``font_family``, ``text_color``, ``markup``, normal weight), ``pad``
+        from the plots; made for each layout, in the group's creation order among the
+        figure's titles."""
+        label = self.resolve("label")
+        if label is None:
+            return None
+        from .figure import FigureTitle
+        t = FigureTitle(self._figure, self.members(), text=label, side="left",
+                        align="center", over="axes", rotation="auto", rule=False,
+                        font_size=self.resolve("font_size"), font_weight="normal",
+                        font_style="normal", color=self.resolve("text_color"),
+                        font_family=self.resolve("font_family"),
+                        markup=self.resolve("markup"), pad=self.resolve("pad"))
+        t._made = self._made
+        return t
+
+    def extent(self, fonts: Any) -> float:
+        """Width of the group band: the letter and ``pad`` (0 without a letter)."""
+        letter = self.resolve("letter")
+        if letter is None:
+            return 0.0
+        w = measure(fonts, letter, self._font("letter_font_size",
+                                               self.resolve("letter_weight")))[0]
+        return w + self.resolve("pad") if w else 0.0
+
+
+def _columns(fig: Any, areas: Any, rows: Any) -> list[list[Any]]:
+    """The placed areas of the plots ``rows`` (``None``: all), by grid column."""
+    from .plot import Plot
+    chosen = fig.plots if rows is None else rows
+    ids = {id(p) for p in chosen}
+    out: dict[tuple[int, int], list[Any]] = {}
+    for a in areas:
+        if isinstance(a.obj, Plot) and id(a.obj) in ids:
+            out.setdefault((a.c0, a.c1), []).append(a)
+    return list(out.values())
+
+
+def _one_x(col: list[Any], what: str) -> None:
+    """Refuse a column whose plots do not share x: one page x means nothing across them."""
+    if len({id(b.state.x.shared or b.state.x) for b in col}) > 1:
+        raise ValueError(f"fig.{what}: the plots of a grid column it crosses do not share x "
+                         "(share x, or pass rows=)")
+
+
+def _x_page(area: Any, x: Any) -> float:
+    x0, _, x1, _ = area.axes
+    state = area.state.x
+    return state.mapper(x0, x1)(state.value(x))
+
+
+def place_figure(fig: Any, fonts: Any, areas: Any) -> tuple[tuple[Any, ...], tuple[Any, ...],
+                                                             tuple[Any, ...]]:
+    """The figure's bands under the plots ``(span, rect)``, its lines over them ``(line,
+    segment)`` (each per grid column, from the top of the first plot's axes to the bottom of
+    the last one's) and its groups' runs."""
+    spans = []
+    for d in fig.decorations:
+        if not isinstance(d, FigureVSpan):
+            continue
+        for col in _columns(fig, areas, d.rows):
+            _one_x(col, "vspan")
+            a = col[0]
+            s0, s1 = d.span(a.state.x)
+            p0, p1 = sorted((_x_page(a, s0), _x_page(a, s1)))
+            x0, _, x1, _ = a.axes
+            p0, p1 = max(p0, x0), min(p1, x1)
+            if p1 <= p0:
+                continue
+            top = min(b.axes[1] for b in col)
+            bot = max(b.axes[3] for b in col)
+            spans.append((d, (p0, top, p1 - p0, bot - top)))
+    out = []
+    for d in fig.decorations:
+        if not isinstance(d, FigureVLine):
+            continue
+        for col in _columns(fig, areas, d.rows):
+            _one_x(col, "vline")
+            a = col[0]
+            if a.state.x.segments is not None:
+                raise ValueError("fig.vline on an x axis over several regions: mark a "
+                                 "position with fig.vspan(region)")
+            p = _x_page(a, d.x)
+            if not a.axes[0] - 0.01 <= p <= a.axes[2] + 0.01:
+                continue
+            top = min(b.axes[1] for b in col)
+            bot = max(b.axes[3] for b in col)
+            out.append((d, (p, top, p, bot)))
+    return tuple(spans), tuple(out), _place_groups(fig, fonts, areas)
+
+
+def _place_groups(fig: Any, fonts: Any, areas: Any) -> tuple[Any, ...]:
+    """The groups' letters: each at the left of its group band, level with the top of its
+    first plot's axes."""
+    runs: list[Any] = []
+    for g in fig.groups:
+        letter = g.resolve("letter")
+        if letter is None:
+            continue
+        members = {id(p) for p in g.members()}
+        col = [a for a in areas if id(a.obj) in members]
+        if not col:
+            continue
+        b = col[0].bands
+        label_band, group_band = _row_band(b, "row_label"), _row_band(b, "group")
+        col_right = col[0].axes[0] - label_band.offset - label_band.size
+        top = min(a.axes[1] for a in col)
+        font = g._font("letter_font_size", g.resolve("letter_weight"))
+        runs.append(run(fonts, letter, col_right - group_band.size, top, font, "left", "top"))
+    return tuple(runs)

plot_io/scales.py

@@ -0,0 +1,103 @@
+"""Scales: a monotone function from data to a position line.
+
+A numeric scale maps a value ``v`` to ``f(v)``; an axis maps ``f(lo)…f(hi)`` linearly onto
+its length.  ``f`` is one of the functions :func:`plot_io.kernels.scaled` applies in C, so
+bulk data never goes through a Python loop.
+"""
+
+import math
+from collections.abc import Callable
+
+__all__ = ["Scale", "SCALES", "get_scale", "NUMERIC_SCALES", "AXIS_SCALES"]
+
+
+class Scale:
+    """``forward``/``inverse`` on single values; ``function`` is the kernels' name for it;
+    ``base`` the base of a logarithmic scale (``None`` on the others)."""
+
+    __slots__ = ("name", "function", "forward", "inverse", "lo", "hi", "options", "base")
+
+    def __init__(self, name: str, function: str | None, forward: Callable[[float], float],
+                 inverse: Callable[[float], float], lo: float = -math.inf,
+                 hi: float = math.inf, options: dict | None = None,
+                 base: float | None = None) -> None:
+        self.name = name
+        self.function = function
+        self.forward = forward
+        self.inverse = inverse
+        self.base = base
+        self.lo = lo            # open domain bounds for log, closed for sqrt (see contains)
+        self.hi = hi
+        self.options = options or {}    # extra arguments of kernels.scaled (linthresh)
+
+    def contains(self, v: float) -> bool:
+        if not math.isfinite(v):
+            return False
+        if self.base is not None:
+            return v > 0
+        if self.name == "sqrt":
+            return v >= 0
+        if self.name == "exp":
+            return v < 709.78
+        if self.name == "logit":
+            return 0.0 < v < 1.0
+        return True
+
+    def f(self, v: float) -> float:
+        return self.forward(v) if self.contains(v) else math.nan
+
+    def __repr__(self) -> str:
+        return f"Scale({self.name})"
+
+
+def _safe_exp(t: float) -> float:
+    return math.exp(t) if t < 709.78 else math.inf
+
+
+def _exp10(t: float) -> float:
+    return 10.0 ** t if t < 308 else math.inf
+
+
+SCALES = {
+    "linear": Scale("linear", None, lambda v: v, lambda t: t),
+    "log": Scale("log", "log10", math.log10, _exp10, base=10.0),
+    "ln": Scale("ln", "log", math.log, _safe_exp, base=math.e),
+    "log2": Scale("log2", "log2", math.log2, lambda t: 2.0 ** t if t < 1024 else math.inf,
+                  base=2.0),
+    "log10": Scale("log10", "log10", math.log10, _exp10, base=10.0),
+    "sqrt": Scale("sqrt", "sqrt", math.sqrt, lambda t: t * t),
+    "exp": Scale("exp", "exp", _safe_exp, lambda t: math.log(t) if t > 0 else -math.inf),
+}
+
+def _symlog(c: float) -> Scale:
+    def f(v: float) -> float:
+        return math.copysign(math.log10(1.0 + abs(v) / c), v)
+
+    def inv(t: float) -> float:
+        return math.copysign(c * (10.0 ** abs(t) - 1.0), t) if abs(t) < 308 else \
+            math.copysign(math.inf, t)
+    return Scale("symlog", "symlog", f, inv, options={"linthresh": c})
+
+
+def _logit_inverse(t: float) -> float:
+    if t > 300:
+        return 1.0
+    return 1.0 / (1.0 + 10.0 ** -t)
+
+
+SCALES["symlog"] = _symlog(1.0)
+SCALES["logit"] = Scale("logit", "logit", lambda p: math.log10(p / (1.0 - p)), _logit_inverse)
+
+NUMERIC_SCALES = tuple(SCALES)
+#: Scales an axis takes: the numeric ones, ``time`` (set by date data), ``category`` and
+#: ``genome`` (linear in bp, set by genome series; see :mod:`plot_io.genome.scale`).
+AXIS_SCALES = NUMERIC_SCALES + ("time", "category", "genome")
+
+SCALES["time"] = Scale("time", None, lambda v: v, lambda t: t)
+
+
+def get_scale(name: str, linthresh: float | None = None) -> Scale:
+    """The scale ``name`` (``linthresh``: the linear region of ``symlog``)."""
+    if name == "symlog" and linthresh is not None and linthresh != 1.0:
+        return _symlog(float(linthresh))
+    return SCALES[name]