polyphys 1.0.0__py3-none-any.whl

polyphys/tests/viz/conftest.py

@@ -0,0 +1,32 @@
+"""
+Fixtures for the tests of :mod:`polyphys.viz`.
+
+The viz layer needs matplotlib, which the ``viz`` extra installs. The test
+modules of the matplotlib-backed modules call
+``pytest.importorskip("matplotlib")`` first, and the fixtures here do the
+same, so ``test_colors.py``, whose module imports no plotting library,
+runs without the extra. Every figure is drawn with the Agg backend, which
+needs no display, and closed by the fixture that made it. All data is tier
+A: a few hand-written points.
+"""
+from typing import Any, Iterator
+
+import pytest
+
+
+@pytest.fixture
+def figure() -> Iterator[Any]:
+    """An empty Agg figure, closed after the test."""
+    matplotlib = pytest.importorskip("matplotlib")
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    fig = plt.figure()
+    yield fig
+    plt.close(fig)
+
+
+@pytest.fixture
+def ax(figure: Any) -> Any:
+    """One empty axes on the test's figure."""
+    return figure.add_subplot()

polyphys/tests/viz/test_colors.py

@@ -0,0 +1,113 @@
+"""Tests for :mod:`polyphys.viz.colors`.
+
+The expected colors of the three Tol palettes are read from Figures 1, 3,
+and 4 of Paul Tol, *Colour Schemes*, SRON/EPS/TN/09-002, issue 3.2
+(18 August 2021), in the fixed-sequence order its page 6 gives; those of
+``DUTCH_FIELD`` from the wpDataTables article the module docstring cites,
+read on 2026-11-06. The form test states a property of every palette. The
+expected endpoints of a truncated map are the parent map's own values at
+the cut points, a reproducible computation on the parent; the count and
+name follow from the arguments.
+"""
+import re
+
+import pytest
+
+from polyphys.viz.colors import (
+    DUTCH_FIELD,
+    STUDY_COLORS,
+    TOL_BRIGHT,
+    TOL_MUTED,
+    TOL_VIBRANT,
+    truncate_colormap,
+)
+
+
+@pytest.fixture
+def viridis():
+    """matplotlib's registered viridis map, the parent of every cut."""
+    matplotlib = pytest.importorskip("matplotlib")
+    return matplotlib.colormaps["viridis"]
+
+
+@pytest.mark.parametrize("palette, expected", [
+    pytest.param(
+        TOL_BRIGHT,
+        ("#4477AA", "#EE6677", "#228833", "#CCBB44", "#66CCEE", "#AA3377",
+         "#BBBBBB"),
+        id="tol-bright-fig1"),
+    pytest.param(
+        TOL_VIBRANT,
+        ("#EE7733", "#0077BB", "#33BBEE", "#EE3377", "#CC3311", "#009988",
+         "#BBBBBB"),
+        id="tol-vibrant-fig3"),
+    pytest.param(
+        TOL_MUTED,
+        ("#CC6677", "#332288", "#DDCC77", "#117733", "#88CCEE", "#882255",
+         "#44AA99", "#999933", "#AA4499", "#DDDDDD"),
+        id="tol-muted-fig4"),
+    pytest.param(
+        DUTCH_FIELD,
+        ("#e60049", "#0bb4ff", "#50e991", "#e6d800", "#9b19f5", "#ffa300",
+         "#dc0ab4", "#b3d4ff", "#00bfa0"),
+        id="dutch-field-wpdatatables"),
+])
+def test_palette_matches_its_source(palette, expected):
+    """Each cited palette holds its source's colors in the source's order."""
+    assert palette == expected
+
+
+@pytest.mark.parametrize("palette", [
+    pytest.param(TOL_BRIGHT, id="tol-bright"),
+    pytest.param(TOL_VIBRANT, id="tol-vibrant"),
+    pytest.param(TOL_MUTED, id="tol-muted"),
+    pytest.param(DUTCH_FIELD, id="dutch-field"),
+    pytest.param(STUDY_COLORS, id="study-colors"),
+])
+def test_palette_entries_are_distinct_hex_colors(palette):
+    """Every palette entry is a #RRGGBB string, and no color repeats."""
+    hex_color = re.compile(r"^#[0-9A-Fa-f]{6}$")
+
+    assert all(hex_color.match(color) for color in palette)
+    assert len(set(color.lower() for color in palette)) == len(palette)
+
+
+def test_truncate_colormap_endpoints_are_the_parent_values(viridis):
+    """The cut map starts at cmap(lower) and ends at cmap(upper)."""
+    np = pytest.importorskip("numpy")
+
+    cut = truncate_colormap(viridis, 0.2, 0.8, n=5)
+
+    # Exact: the endpoint colors are copied from the parent's lookup table.
+    np.testing.assert_array_equal(cut(0.0), viridis(0.2))
+    np.testing.assert_array_equal(cut(1.0), viridis(0.8))
+
+
+def test_truncate_colormap_has_n_colors_and_a_named_range(viridis):
+    """The cut map samples n colors and is named trunc(<name>,lower,upper)."""
+    cut = truncate_colormap(viridis, 0.2, 0.8, n=5)
+
+    assert cut.N == 5
+    assert cut.name == "trunc(viridis,0.2,0.8)"
+
+
+def test_truncate_colormap_accepts_a_registered_name(viridis):
+    """A color map name is looked up in matplotlib's registry."""
+    np = pytest.importorskip("numpy")
+
+    cut = truncate_colormap("viridis", 0.2, 0.8, n=5)
+
+    np.testing.assert_array_equal(cut(0.0), viridis(0.2))
+
+
+@pytest.mark.parametrize("lower, upper, n", [
+    pytest.param(0.8, 0.2, 5, id="lower-above-upper"),
+    pytest.param(-0.1, 1.0, 5, id="lower-below-zero"),
+    pytest.param(0.0, 1.1, 5, id="upper-above-one"),
+    pytest.param(0.0, 1.0, 1, id="one-color"),
+])
+def test_truncate_colormap_rejects_a_bad_range_or_count(viridis, lower,
+                                                        upper, n):
+    """A range outside 0 <= lower < upper <= 1, or n below 2, is refused."""
+    with pytest.raises(ValueError, match="lower|n must"):
+        truncate_colormap(viridis, lower, upper, n=n)

polyphys/tests/viz/test_helpers.py

@@ -0,0 +1,292 @@
+"""Tests for :mod:`polyphys.viz.helpers`.
+
+Every expected tick value is hand arithmetic on the module's rule: ticks
+every `step` from `lower` to `upper`, limits widened by ``step / 10``
+rounded down to its first non-zero digit (``0.025 -> 0.02``,
+``0.05 -> 0.05``), labels rounded to `decimals`. Every expected legend value
+is the input the handle or legend was built from: the labels, colors,
+styles, and titles given, read back from the artists.
+"""
+import importlib
+import sys
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("matplotlib")
+
+import matplotlib  # noqa: E402
+import numpy as np  # noqa: E402
+from matplotlib.colors import to_rgba  # noqa: E402
+from matplotlib.lines import Line2D  # noqa: E402
+from matplotlib.patches import Patch  # noqa: E402
+
+from polyphys.viz.helpers import (  # noqa: E402
+    band_under_lines,
+    color_handles,
+    line_handles,
+    move_legend_to_axes,
+    set_xticks,
+    set_yticks,
+)
+
+
+@pytest.fixture
+def two_panels(figure):
+    """Two side-by-side axes; the left one holds two labeled lines and the
+    figure a legend of them titled 'curves'."""
+    left, right = figure.subplots(ncols=2)
+    left.plot([0, 1], [0, 1], label="rise")
+    left.plot([0, 1], [1, 0], label="fall")
+    legend = figure.legend(title="curves")
+    return left, right, legend
+
+
+def test_set_xticks_places_ticks_every_step_to_upper(ax):
+    """Ticks run from lower to upper in steps of step, upper included."""
+    ticks = set_xticks(ax, 0.0, 1.0, 0.25)
+
+    # Exact: the positions are lower + k * step for a step with a short
+    # binary expansion.
+    np.testing.assert_array_equal(ticks, [0.0, 0.25, 0.5, 0.75, 1.0])
+    np.testing.assert_array_equal(ax.get_xticks(), ticks)
+
+
+def test_set_xticks_widens_the_limits_by_the_tolerance(ax):
+    """The limits sit one rounded-down tenth of a step beyond the ticks."""
+    set_xticks(ax, 0.0, 1.0, 0.25)
+
+    # 0.25 / 10 = 0.025 rounds down to 0.02; float64 round-off tolerance.
+    assert ax.get_xlim() == pytest.approx((-0.02, 1.02), abs=1e-12)
+
+
+def test_set_xticks_writes_a_near_zero_tick_as_exactly_zero(ax):
+    """A tick that float arithmetic puts near zero is exactly 0.0."""
+    # -0.3 + 3 * 0.1 is 5.55e-17 in float64, not 0.0.
+    ticks = set_xticks(ax, -0.3, 0.3, 0.1)
+
+    assert ticks[3] == 0.0
+    assert ax.get_xticklabels()[3].get_text() == "0.0"
+
+
+def test_set_xticks_hides_labels_on_request(ax):
+    """labels=False leaves every tick label empty."""
+    set_xticks(ax, 0.0, 1.0, 0.25, labels=False)
+
+    assert [label.get_text() for label in ax.get_xticklabels()] == [""] * 5
+
+
+def test_set_xticks_rounds_labels_to_decimals(ax):
+    """Labels are the ticks rounded to `decimals` places."""
+    set_xticks(ax, 0.0, 0.9, 0.3, decimals=1)
+
+    assert ([label.get_text() for label in ax.get_xticklabels()]
+            == ["0.0", "0.3", "0.6", "0.9"])
+
+
+def test_set_xticks_forwards_text_kwargs_to_the_labels(ax):
+    """Keyword arguments such as fontsize reach every tick label."""
+    set_xticks(ax, 0.0, 1.0, 0.5, fontsize=7)
+
+    assert all(label.get_fontsize() == 7 for label in ax.get_xticklabels())
+
+
+@pytest.mark.parametrize("lower, upper, step", [
+    pytest.param(0.0, 1.0, 0.0, id="zero-step"),
+    pytest.param(0.0, 1.0, -0.1, id="negative-step"),
+    pytest.param(0.0, 1.0, 1.0, id="step-equals-span"),
+    pytest.param(1.0, 0.0, 0.1, id="lower-above-upper"),
+])
+def test_set_xticks_rejects_a_bad_step_or_order(ax, lower, upper, step):
+    """A step that is not positive and below the span, or lower >= upper,
+    is refused."""
+    with pytest.raises(ValueError, match="step must|lower must"):
+        set_xticks(ax, lower, upper, step)
+
+
+def test_set_yticks_applies_the_same_rule_on_the_y_axis(ax):
+    """set_yticks places the ticks and widens the limits of the y axis."""
+    ticks = set_yticks(ax, 0.0, 1.0, 0.5)
+
+    np.testing.assert_array_equal(ticks, [0.0, 0.5, 1.0])
+    np.testing.assert_array_equal(ax.get_yticks(), ticks)
+    # 0.5 / 10 = 0.05 is already one significant digit.
+    assert ax.get_ylim() == pytest.approx((-0.05, 1.05), abs=1e-12)
+
+
+def test_color_handles_make_one_patch_per_label_in_order():
+    """Each label gets a Patch of its color, in the order given."""
+    handles = color_handles(["a", "b"], ["#ff0000", "#0000ff"])
+
+    assert all(isinstance(handle, Patch) for handle in handles)
+    assert [handle.get_label() for handle in handles] == ["a", "b"]
+    assert [handle.get_facecolor() for handle in handles] == [
+        to_rgba("#ff0000"), to_rgba("#0000ff")]
+
+
+@pytest.mark.parametrize("labels, color", [
+    pytest.param(["a", "b", "c"], (0.1, 0.2, 0.3), id="rgb-tuple"),
+    pytest.param(["a", "b"], (0.1, 0.2, 0.3, 0.5), id="rgba-tuple"),
+    pytest.param(["a", "b"], "red", id="name"),
+])
+def test_color_handles_repeat_one_color_for_every_label(labels, color):
+    """One color, a name or an RGB(A) tuple, is given to every label."""
+    handles = color_handles(labels, color)
+
+    assert [handle.get_facecolor() for handle in handles] == \
+        [to_rgba(color)] * len(labels)
+
+
+def test_color_handles_reject_a_list_of_the_wrong_length():
+    """A list of colors must have one entry per label."""
+    with pytest.raises(ValueError, match="colors has 3 entries"):
+        color_handles(["a", "b"], ["red", "green", "blue"])
+
+
+def test_line_handles_repeat_a_numpy_integer_width():
+    """A NumPy integer width is one value, given to every label."""
+    handles = line_handles(["a", "b"], linewidths=np.int64(2))
+
+    assert [h.get_linewidth() for h in handles] == [2, 2]
+
+
+def test_line_handles_repeat_a_dash_tuple_for_every_label():
+    """An (offset, on-off sequence) dash tuple is one line style."""
+    handles = line_handles(["a", "b"], linestyles=(0, (5, 2)))
+
+    assert [h.get_linestyle() for h in handles] == ["--", "--"]
+
+
+def test_line_handles_carry_the_style_marker_and_color_given():
+    """Each label gets a Line2D with its own style and marker and the shared
+    color and width."""
+    handles = line_handles(["a", "b"], linestyles=["-", "--"],
+                           markers=["o", "^"], linewidths=2, color="red")
+
+    assert all(isinstance(handle, Line2D) for handle in handles)
+    assert [(h.get_label(), h.get_linestyle(), h.get_marker())
+            for h in handles] == [("a", "-", "o"), ("b", "--", "^")]
+    assert [h.get_linewidth() for h in handles] == [2, 2]
+    assert [h.get_color() for h in handles] == ["red", "red"]
+
+
+def test_line_handles_reject_a_sequence_of_the_wrong_length():
+    """A per-label sequence must have one entry per label."""
+    with pytest.raises(ValueError, match="markers has 3 entries"):
+        line_handles(["a", "b"], markers=["o", "^", "s"])
+
+
+def test_move_legend_to_axes_moves_entries_and_title_into_the_axes(
+        two_panels):
+    """The figure legend disappears and each target axes gets a legend with
+    the same labels and title."""
+    left, right, legend = two_panels
+
+    new = move_legend_to_axes(legend, [left, right],
+                              ["upper left", "lower right"])
+
+    assert left.figure.legends == []
+    assert [leg.axes for leg in new] == [left, right]
+    for panel in (left, right):
+        texts = [t.get_text() for t in panel.get_legend().get_texts()]
+        assert texts == ["rise", "fall"]
+        assert panel.get_legend().get_title().get_text() == "curves"
+
+
+def test_move_legend_to_axes_takes_a_new_title(two_panels):
+    """A title argument replaces the moved legend's title."""
+    left, right, legend = two_panels
+
+    move_legend_to_axes(legend, [right], ["upper left"], title="new")
+
+    assert right.get_legend().get_title().get_text() == "new"
+
+
+def test_move_legend_to_axes_rejects_mismatched_locations(two_panels):
+    """One location per target axes is required."""
+    left, right, legend = two_panels
+
+    with pytest.raises(ValueError, match="locs has 1 entries for 2 axes"):
+        move_legend_to_axes(legend, [left, right], ["upper left"])
+
+
+def test_band_under_lines_shades_each_band_in_its_line_color(ax):
+    """One band per line is filled between the given edges, over the line's
+    x data, in the line's color."""
+    ax.plot([0, 1, 2], [0.5, 0.5, 0.5], color="#ff0000")
+    ax.plot([0, 1, 2], [1.5, 1.5, 1.5], color="#0000ff")
+
+    bands = band_under_lines(
+        ax, [([0, 0, 0], [1, 1, 1]), ([1, 1, 1], [2, 2, 2])], alpha=0.5)
+
+    assert len(bands) == 2
+    assert [tuple(b.get_facecolor()[0]) for b in bands] == [
+        to_rgba("#ff0000", 0.5), to_rgba("#0000ff", 0.5)]
+    for band, (lower, upper) in zip(bands, [(0, 1), (1, 2)]):
+        vertices = band.get_paths()[0].vertices
+        # Exact: the polygon vertices are the integer edges given.
+        assert vertices[:, 1].min() == lower
+        assert vertices[:, 1].max() == upper
+        np.testing.assert_array_equal(np.unique(vertices[:, 0]), [0, 1, 2])
+
+
+@pytest.mark.parametrize("bands, message", [
+    pytest.param([([0], [1]), ([0], [1])], "2 bands were given for 1 lines",
+                 id="more-bands-than-lines"),
+    pytest.param([([0, 0], [1, 1])], "a band has edges of shape",
+                 id="edge-length-differs-from-line"),
+])
+def test_band_under_lines_rejects_a_band_that_does_not_fit(ax, bands,
+                                                           message):
+    """More bands than lines, or an edge of the wrong length, is refused."""
+    ax.plot([0, 1, 2], [0, 0, 0])
+
+    with pytest.raises(ValueError, match=message):
+        band_under_lines(ax, bands)
+
+
+# On the research code's space table (tier C)
+
+
+def _plot_state_points(ax, table, colors):  # pragma: no cover - tier C
+    """One line per state point of a space table, ``gyrTMon-mean`` against
+    ``time``, in the given colors; returns the labels, the rounded crowder
+    volume fractions."""
+    labels = []
+    for (phi, rows), color in zip(table.groupby("phi_bulk_c_round"), colors):
+        ax.plot(rows["time"], rows["gyrTMon-mean"], color=color)
+        labels.append(f"{phi:g}")
+    return labels
+
+
+@pytest.mark.private_data
+def test_helpers_draw_the_research_space_table(  # pragma: no cover
+        ax, private_data_dir):
+    """A figure of the research code's TransFociCub gyration space table has
+    one line per state point, one legend handle per line in its color from
+    ``color_handles``, and x ticks from ``set_xticks`` whose first and last
+    frame the time axis. A property check: there is no research figure to
+    compare with."""
+    from polyphys.analyze.pipeline import space_tseries_from_spec
+
+    sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+    spec = importlib.import_module("projects.trans_foci_cub.spec").SPEC
+    parent = private_data_dir / "TransFociCub" / "analysis"
+    folders = sorted(parent.glob("*-bug-ensAvg"))
+    if len(folders) != 1:
+        pytest.skip(f"no single *-bug-ensAvg folder under {parent}")
+    table = space_tseries_from_spec(folders[0], spec, "gyrTMon")
+    n_states = table["ensemble_long"].nunique()
+    colors = [tuple(color) for color in matplotlib.colormaps["viridis"](
+        np.linspace(0.0, 1.0, n_states))]
+    t_max = float(table["time"].max())
+
+    labels = _plot_state_points(ax, table, colors)
+    handles = color_handles(labels, colors)
+    ticks = set_xticks(ax, 0.0, t_max, t_max / 5)
+
+    assert len(ax.lines) == n_states == len(handles)
+    assert [to_rgba(handle.get_facecolor()) for handle in handles] == [
+        to_rgba(line.get_color()) for line in ax.lines]
+    assert ticks[0] <= table["time"].min() and ticks[-1] >= t_max
+    assert ax.get_xlim()[0] <= 0.0 and ax.get_xlim()[1] >= t_max

polyphys/viz/__init__.py

@@ -0,0 +1,15 @@
+"""
+The viz layer: color lists and small matplotlib helpers for the studies'
+figures, which the ``viz`` extra makes usable
+(``python -m pip install 'polyphys[viz]'``).
+
+:mod:`polyphys.viz.colors` holds the color lists, which need no plotting
+library, and :func:`~polyphys.viz.colors.truncate_colormap`, which imports
+matplotlib when called. :mod:`polyphys.viz.helpers` needs matplotlib at
+import and raises :exc:`ImportError` with that hint when it is missing. This
+package imports neither module on its own; import the one you need.
+
+.. versionadded:: 0.8.0
+"""
+
+__all__ = ["colors", "helpers"]

polyphys/viz/colors.py

@@ -0,0 +1,204 @@
+"""
+==========================================================
+:mod:`polyphys.viz.colors`
+==========================================================
+
+The :mod:`polyphys.viz.colors` module holds the qualitative color lists the
+studies' figures use, as tuples of ``#RRGGBB`` strings, and
+:func:`truncate_colormap`, which cuts a matplotlib color map down to a
+sub-range of its domain so that, for instance, the pale end of a sequential
+map does not vanish against a white background.
+
+The module imports no plotting library at import time, so the color lists
+can be read without the ``viz`` extra and passed to any plotting call that
+accepts matplotlib color strings; :func:`truncate_colormap` imports
+matplotlib when called and raises :exc:`ImportError` with the install hint
+when it is missing.
+
+Sources
+=======
+
+``TOL_BRIGHT``, ``TOL_VIBRANT``, ``TOL_MUTED``
+    Paul Tol, *Colour Schemes*, SRON Technical Note SRON/EPS/TN/09-002,
+    issue 3.2, 18 August 2021, Figures 1, 3, and 4
+    (https://sronpersonalpages.nl/~pault/data/colourschemes.pdf). The
+    schemes are designed to be distinct for color-blind readers, distinct
+    from black and white, and distinct on screen and paper. Each tuple is
+    in the order the note gives for picking colors in a fixed sequence
+    (page 6), and ends with the scheme's gray, which the note reserves for
+    bad or missing data.
+``DUTCH_FIELD``
+    A nine-color palette named "Dutch Field" in a HEAVY.AI (formerly
+    OmniSci) blog post, "12 color palettes for telling better stories with
+    your data", which could not be opened when this module was written. The
+    values here are the ones listed, under the same name, by
+    M. Jovanovic, "12 Great Data Visualization Color Palettes to Use",
+    wpDataTables, 17 December 2023
+    (https://wpdatatables.com/data-visualization-color-palette/), read on
+    2026-11-06. Neither page states terms of reuse.
+``STUDY_COLORS``
+    The maintainer's own twelve-color list, assembled from the lists above
+    and CSS named colors for the published figures; its fifth entry is
+    matplotlib's ``gray``, ``#808080``.
+
+Examples
+========
+
+>>> from polyphys.viz.colors import TOL_BRIGHT, truncate_colormap
+>>> TOL_BRIGHT[0]
+'#4477AA'
+>>> len(TOL_BRIGHT)
+7
+>>> truncate_colormap("viridis", 0.2, 0.8, n=5).name
+'trunc(viridis,0.2,0.8)'
+"""
+from typing import TYPE_CHECKING, Union
+
+import numpy as np
+
+if TYPE_CHECKING:  # pragma: no cover - imported for the annotations only
+    from matplotlib.colors import Colormap, LinearSegmentedColormap
+
+__all__ = [
+    "DUTCH_FIELD",
+    "STUDY_COLORS",
+    "TOL_BRIGHT",
+    "TOL_MUTED",
+    "TOL_VIBRANT",
+    "truncate_colormap",
+]
+
+#: Tol's *bright* scheme, his default for lines and their labels: blue, red,
+#: green, yellow, cyan, purple, grey.
+TOL_BRIGHT: tuple[str, ...] = (
+    "#4477AA",
+    "#EE6677",
+    "#228833",
+    "#CCBB44",
+    "#66CCEE",
+    "#AA3377",
+    "#BBBBBB",
+)
+
+#: Tol's *vibrant* scheme, designed for TensorBoard: orange, blue, cyan,
+#: magenta, red, teal, grey.
+TOL_VIBRANT: tuple[str, ...] = (
+    "#EE7733",
+    "#0077BB",
+    "#33BBEE",
+    "#EE3377",
+    "#CC3311",
+    "#009988",
+    "#BBBBBB",
+)
+
+#: Tol's *muted* scheme, with more colors but no clear red or medium blue:
+#: rose, indigo, sand, green, cyan, wine, teal, olive, purple, pale grey.
+TOL_MUTED: tuple[str, ...] = (
+    "#CC6677",
+    "#332288",
+    "#DDCC77",
+    "#117733",
+    "#88CCEE",
+    "#882255",
+    "#44AA99",
+    "#999933",
+    "#AA4499",
+    "#DDDDDD",
+)
+
+#: The nine-color "Dutch Field" palette; see the module docstring for its
+#: provenance.
+DUTCH_FIELD: tuple[str, ...] = (
+    "#e60049",
+    "#0bb4ff",
+    "#50e991",
+    "#e6d800",
+    "#9b19f5",
+    "#ffa300",
+    "#dc0ab4",
+    "#b3d4ff",
+    "#00bfa0",
+)
+
+#: The maintainer's twelve-color list for the published figures.
+STUDY_COLORS: tuple[str, ...] = (
+    "#00008b",
+    "#e60049",
+    "#9b19f5",
+    "#228b22",
+    "#808080",
+    "#ffe119",
+    "#ff00ff",
+    "#00ffff",
+    "#ffa300",
+    "#00ff00",
+    "#8b4513",
+    "#000000",
+)
+
+
+def truncate_colormap(
+    cmap: "Union[str, Colormap]",
+    lower: float = 0.0,
+    upper: float = 1.0,
+    n: int = 256,
+) -> "LinearSegmentedColormap":
+    """
+    Cut `cmap` down to the sub-range ``[lower, upper]`` of its domain.
+
+    The result is a linear segmented color map through the `n` colors
+    that `cmap` takes at equally spaced points of ``[lower, upper]``, so its
+    value at 0 is ``cmap(lower)`` and its value at 1 is ``cmap(upper)``.
+    Time and space are :math:`O(n)`.
+
+    Parameters
+    ----------
+    cmap : str or matplotlib.colors.Colormap
+        The color map to cut, or the name of a registered one, such as
+        ``'viridis'``.
+    lower, upper : float, default 0.0 and 1.0
+        The sub-range of ``[0, 1]`` to keep; ``0 <= lower < upper <= 1``.
+    n : int, default 256
+        The number of colors sampled from `cmap`, at least 2.
+
+    Returns
+    -------
+    matplotlib.colors.LinearSegmentedColormap
+        The truncated map, named ``'trunc(<cmap.name>,<lower>,<upper>)'``.
+
+    Raises
+    ------
+    ImportError
+        If matplotlib is not installed; the ``viz`` extra installs it.
+    ValueError
+        If the range is not ``0 <= lower < upper <= 1`` or `n` is below 2.
+
+    Examples
+    --------
+    >>> import matplotlib
+    >>> dark = truncate_colormap("viridis", 0.5, 1.0, n=4)
+    >>> dark.name
+    'trunc(viridis,0.5,1.0)'
+    >>> dark(0.0) == matplotlib.colormaps["viridis"](0.5)
+    True
+    """
+    try:
+        import matplotlib
+        from matplotlib.colors import LinearSegmentedColormap
+    except ImportError as error:  # pragma: no cover - depends on the install
+        raise ImportError(
+            "polyphys.viz.colors.truncate_colormap needs matplotlib; "
+            "install it with python -m pip install 'polyphys[viz]'."
+        ) from error
+    if isinstance(cmap, str):
+        cmap = matplotlib.colormaps[cmap]
+    if not 0.0 <= lower < upper <= 1.0:
+        raise ValueError(
+            f"the range must satisfy 0 <= lower < upper <= 1, got "
+            f"lower={lower} and upper={upper}.")
+    if n < 2:
+        raise ValueError(f"n must be at least 2, got {n}.")
+    colors = cmap(np.linspace(lower, upper, n))
+    return LinearSegmentedColormap.from_list(
+        f"trunc({cmap.name},{lower},{upper})", colors, N=n)