plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/formatters.py

@@ -0,0 +1,97 @@
+"""Tick label formatters, one per axis kind: numbers, times and categories.
+
+A formatter gives the labels of tick values and the offset content written at the end of
+the axis (the common ×10ᵏ factor and additive offset of numbers, ``+1×10⁹``; the date
+part common to time ticks, ``Mar 2026``), or ``None`` when there is none.  Axes and
+colorbars label their ticks through the formatter of their axis
+(:meth:`plot_io.axis.AxisState.formatter`).
+"""
+
+import math
+from typing import Any, NamedTuple
+
+from .numbers import NumberStyle, additive_offset, apply_format, format_axis, offset_label
+from .text import superscript
+from .times import time_labels, time_ticks
+
+__all__ = ["Formatted", "NumberFormatter", "TimeFormatter", "CategoryFormatter",
+           "number_offset"]
+
+
+class Formatted(NamedTuple):
+    labels: list[Any]
+    offset: Any = None          # content written at the end of the axis, or None
+
+
+def number_offset(factor: int, shift: float, style: NumberStyle) -> Any:
+    """The offset content of numeric labels: ``×10ᵏ`` and the value added (``+1×10⁹``);
+    ``None`` for neither."""
+    if not factor and not shift:
+        return None
+    out: list[Any] = []
+    if factor:
+        out += ["×10", superscript(style.exponent(factor))]
+    if shift:
+        out += offset_label(shift, style)
+    return out
+
+
+class NumberFormatter:
+    """Labels of numbers formatted together (shared decimals) in ``fmt``; ``"auto"``
+    writes a common part of four digits or more as an additive offset and large or small
+    values as mantissas of a common ×10ᵏ factor."""
+
+    def __init__(self, fmt: Any, style: NumberStyle, sci_limits: tuple[int, int]) -> None:
+        self.fmt, self.style, self.sci_limits = fmt, style, sci_limits
+
+    def __call__(self, values: list[float]) -> Formatted:
+        shift = additive_offset(values) if self.fmt == "auto" else 0.0
+        if shift:            # the differences, rounded relative to the tick spacing
+            step = min((abs(b - a) for a, b in zip(values, values[1:]) if b != a),
+                       default=abs(shift))
+            digits = 2 - math.floor(math.log10(step))
+            values = [round(v - shift, digits) + 0.0 for v in values]
+        labels, factor = format_axis(values, self.fmt, self.style, self.sci_limits)
+        return Formatted(labels, number_offset(factor, shift, self.style))
+
+    def offset(self, factor: int) -> Any:
+        """The offset content of labels written as mantissas of ×10^``factor``."""
+        return number_offset(factor, 0.0, self.style)
+
+
+class TimeFormatter:
+    """Concise labels of times (seconds since the epoch) in the finest calendar unit the
+    ticks need, with the date part common to them as the offset; ``fmt``: strftime codes
+    or a function of a ``datetime`` (no offset)."""
+
+    def __init__(self, fmt: Any, tz: Any) -> None:
+        self.fmt, self.tz = fmt, tz
+
+    def __call__(self, values: list[float]) -> Formatted:
+        labels, offset = time_labels(values, self.tz, self.fmt)
+        return Formatted(labels, offset)
+
+    def ticks(self, lo: float, hi: float, most: int) -> tuple[list[tuple[float, Any]], Any]:
+        """Automatic ticks between ``lo`` and ``hi``: ``[(value, label)]`` and the offset."""
+        return time_ticks(lo, hi, most, self.tz, self.fmt)
+
+
+class CategoryFormatter:
+    """Labels of categories (by index): their names (a list is a name of several lines),
+    or numeric categories in ``fmt``, or each name through ``fmt``."""
+
+    def __init__(self, categories: list[Any], fmt: Any, style: NumberStyle) -> None:
+        self.categories, self.fmt, self.style = categories, fmt, style
+
+    def __call__(self, index: list[int]) -> Formatted:
+        cats = [self.categories[i] for i in index]
+        fmt = self.fmt
+        if fmt != "auto":
+            if all(isinstance(c, (int, float)) and not isinstance(c, bool) for c in cats):
+                return Formatted(format_axis([float(c) for c in cats], fmt, self.style,
+                                             None)[0])
+            if callable(fmt):
+                return Formatted([fmt(c) for c in cats])
+            if fmt not in ("percent", "sci", "eng", "si", "int"):
+                return Formatted([apply_format(fmt, c) for c in cats])
+        return Formatted([str(c) if not isinstance(c, (list, str)) else c for c in cats])

plot_io/genome/__init__.py

@@ -0,0 +1,17 @@
+"""Genome tracks: signals, intervals, gene models, links and Hi-C triangles over a
+region, and site matrices (a signal around many sites), read from gwseq_io's readers (or
+any object with their methods) without depending on them; drawn on a genome x axis
+(:mod:`~plot_io.genome.scale`), in a tracks figure (:func:`~plot_io.genome.layout.Tracks`)
+or in any plot."""
+
+from .signal import BigWig
+from .combine import combine
+from .intervals import Bed, Genes, Gtf
+from .contacts import HiC
+from .links import Links
+from .layout import Track, Tracks
+from .regions import Region, parse_region
+from .sites import SignalMatrix, SiteHeatmap, SiteProfile
+
+__all__ = ["Tracks", "Track", "BigWig", "combine", "Bed", "Genes", "Gtf", "HiC", "Links",
+           "SiteHeatmap", "SiteProfile", "SignalMatrix", "Region", "parse_region"]

plot_io/genome/adapters.py

@@ -0,0 +1,356 @@
+"""Readers for what is not one: paths, opened with gwseq_io, and plain data, read from
+memory.  Each meets its protocol (:mod:`plot_io.genome.readers`).
+
+* paths: ``.bed`` (``.bed12``, …), ``.narrowPeak``, ``.broadPeak`` (gzipped too) through
+  ``gwseq_io.open_bed``; ``.tsv``, ``.csv``, ``.xlsx`` through ``gwseq_io.open_peaks``;
+  anything else through ``gwseq_io.open``, which tells the format by its bytes.  The
+  formats gwseq_io has no reader for (bedGraph, BEDPE) are refused;
+* :class:`Intervals`: BED columns (a gene table: BED12);
+* :class:`Pairs`: BEDPE columns, the pairs with an anchor in the region;
+* :class:`Signal`: ``chr``, ``start``, ``end``, ``value`` records, binned here;
+* :class:`Matrix`: a square matrix over the region drawn, whatever it is.
+"""
+
+import bisect
+import importlib
+import math
+import os
+import re
+import weakref
+from array import array
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from . import sources
+
+__all__ = ["check_path", "open_path", "close", "Deferred", "from_data", "Intervals", "Pairs",
+           "Signal", "Matrix", "REDUCTIONS"]
+
+_BED = re.compile(r"\.(bed\d*|narrowpeak|broadpeak)(\.b?gz)?$", re.IGNORECASE)
+_PEAKS = re.compile(r"\.(tsv|csv|xlsx)$", re.IGNORECASE)
+#: Formats gwseq_io has no reader for, by suffix: their name and what to do instead.
+_UNREAD = {
+    "bedgraph": ("bedGraph", "convert it to a bigWig (gwseq_io.convert_to_bigwig) or pass "
+                             "its chr, start, end, value columns"),
+    "bdg": ("bedGraph", "convert it to a bigWig (gwseq_io.convert_to_bigwig) or pass its "
+                        "chr, start, end, value columns"),
+    "bedpe": ("BEDPE", "pass its columns (chr1, start1, end1, chr2, start2, end2) as data"),
+}
+
+
+def _gwseq_io(path: str, what: str) -> Any:
+    try:
+        return importlib.import_module("gwseq_io")
+    except ImportError:
+        raise TypeError(f"{what}: reading the file {path!r} needs gwseq_io, which is not "
+                        f"installed; or pass an open reader or plain data") from None
+
+
+def check_path(path: Any, what: str) -> None:
+    """Refuse a path of a format gwseq_io has no reader for (by its suffix)."""
+    p = os.fsdecode(path)
+    name = p.lower()
+    for ext in (".gz", ".bgz"):
+        if name.endswith(ext):
+            name = name[:-len(ext)]
+    suffix = name.rsplit(".", 1)[-1] if "." in os.path.basename(name) else ""
+    if suffix in _UNREAD:
+        fmt, instead = _UNREAD[suffix]
+        raise TypeError(f"{what}: gwseq_io, which plot_io reads files with, has no {fmt} "
+                        f"reader ({p!r}): {instead}")
+
+
+def open_path(path: Any, what: str) -> Any:
+    """The gwseq_io reader of the file at ``path`` (see the module)."""
+    check_path(path, what)
+    p = os.fsdecode(path)
+    g = _gwseq_io(p, what)
+    if _BED.search(p):
+        return g.open_bed(p)
+    if _PEAKS.search(p):
+        return g.open_peaks(p)
+    try:
+        return g.open(p)
+    except g.InvalidFile as e:
+        raise TypeError(f"{what}: gwseq_io cannot read {p!r} ({e}); a BED or peaks file "
+                        f"needs its suffix (.bed, .narrowPeak, .tsv, …)") from e
+
+
+def close(reader: Any) -> None:
+    """Close a reader plot_io opened (errors ignored: it is being let go)."""
+    f = getattr(reader, "close", None)
+    if f is not None:
+        try:
+            f()
+        except Exception:
+            pass
+
+
+class Deferred:
+    """A path's reader, opened when first used (at draw): once per figure, shared by the
+    series of the figure that read the same path, closed when the figure is collected (a
+    series without a figure: when this is).  Every member is the reader's."""
+
+    def __init__(self, path: Any, kinds: tuple[str, ...], what: str, owner: Any) -> None:
+        self._path, self._kinds, self._what = os.fsdecode(path), kinds, what
+        self._owner = None if owner is None else weakref.ref(owner)
+        self._reader: Any = None
+
+    def _figure(self) -> Any:
+        owner = None if self._owner is None else self._owner()
+        return getattr(getattr(owner, "plot", None), "figure", None)
+
+    def opened(self) -> Any:
+        """The reader (opened now when it is not yet)."""
+        fig = self._figure()
+        cache = None if fig is None else fig.__dict__.setdefault("_genome_readers", {})
+        reader = self._reader if cache is None else cache.get(self._path)
+        if reader is None:
+            reader = open_path(self._path, self._what)
+            try:
+                sources.check_reader(reader, self._kinds, self._what)
+            except BaseException:
+                close(reader)
+                raise
+            if cache is None:
+                weakref.finalize(self, close, reader)
+            else:
+                cache[self._path] = reader
+                weakref.finalize(fig, close, reader)
+        else:
+            sources.check_reader(reader, self._kinds, self._what)
+        self._reader = reader
+        return reader
+
+    def __getattr__(self, name: str) -> Any:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(self.opened(), name)
+
+    def __repr__(self) -> str:
+        return f"<reader of {self._path!r}>"
+
+
+def from_data(value: Any, want: str, what: str) -> Any:
+    """An in-memory reader of plain data for role ``want`` (see
+    :func:`plot_io.genome.readers.adapt`)."""
+    if want == "signal":
+        if callable(value):                    # f(chr, start, end, bins): values over the region
+            return value
+        return Signal(value, what)
+    if want in ("intervals", "annotation"):
+        return Intervals(value)
+    if want == "pairs":
+        return Pairs(value)
+    if want == "contacts":
+        return Matrix(value)
+    raise ValueError(f"unknown reader role {want!r}")
+
+
+def _regions(regions: Any) -> list[tuple[str, int, int]]:
+    if isinstance(regions, tuple) and len(regions) == 3 and isinstance(regions[0], str):
+        regions = [regions]
+    return [(str(c), int(s), int(e)) for c, s, e in regions]
+
+
+class Intervals:
+    """BED columns in memory (see :func:`~plot_io.genome.sources.entry_columns`): the
+    entries overlapping a region, on its chromosome when the data name one."""
+
+    def __init__(self, data: Any) -> None:
+        self.columns = sources.entry_columns(data)
+        chrs = self.columns.get("chr")
+        #: the chromosomes the data name (``None``: any)
+        self.chr_names = None if chrs is None else frozenset(chrs)
+
+    def read_entries(self, regions: Any, columns: Any = None, **kw: Any) -> dict[str, list]:
+        cols = self.columns
+        chrs = cols.get("chr")
+        starts, ends = cols["start"], cols["end"]
+        keep: list[int] = []
+        for c, lo, hi in _regions(regions):
+            keep += [i for i in range(len(starts)) if ends[i] > lo and starts[i] < hi
+                     and (chrs is None or chrs[i] == c)]
+        return {k: [v[i] for i in keep] for k, v in cols.items()}
+
+
+class Pairs:
+    """BEDPE columns in memory (see :func:`~plot_io.genome.sources.pair_columns`): the
+    pairs with either anchor overlapping a region, each once, in the given order."""
+
+    def __init__(self, data: Any) -> None:
+        self.columns = sources.pair_columns(data)
+
+    def read_entries(self, regions: Any, **kw: Any) -> dict[str, list]:
+        cols = self.columns
+        want = _regions(regions)
+        keep = []
+        for i in range(len(cols["start1"])):
+            for c, lo, hi in want:
+                if (cols["chr1"][i] == c and cols["end1"][i] > lo and cols["start1"][i] < hi) \
+                        or (cols["chr2"][i] == c and cols["end2"][i] > lo
+                            and cols["start2"][i] < hi):
+                    keep.append(i)
+                    break
+        return {k: [v[i] for i in keep] for k, v in cols.items()}
+
+
+#: The reductions :class:`Signal` computes.
+REDUCTIONS = ("mean", "min", "max", "sum", "count")
+_SIGNAL_KEYS = {"chr": ("chr", "chrom", "chromosome", "seqname"),
+                "start": ("start", "chromstart", "chrom_start"),
+                "end": ("end", "chromend", "chrom_end"),
+                "value": ("value", "score", "signal", "dataValue")}
+
+
+def _signal_columns(data: Any, what: str) -> dict[str, list]:
+    if hasattr(data, "to_dict") and hasattr(data, "columns"):          # a DataFrame
+        data = {str(c): list(data[c]) for c in data.columns}
+    if isinstance(data, Mapping):
+        low = {str(k).lower(): v for k, v in data.items()}
+        cols = {}
+        for name, keys in _SIGNAL_KEYS.items():
+            got = next((low[k.lower()] for k in keys if k.lower() in low), None)
+            if got is None:
+                raise ValueError(f"{what}: a signal table needs chr, start, end and value "
+                                 f"columns; {name} is missing")
+            cols[name] = list(got.tolist() if hasattr(got, "tolist") else got)
+        return cols
+    if isinstance(data, (str, bytes)) or not isinstance(data, Sequence) and \
+            not hasattr(data, "__iter__"):
+        raise TypeError(f"{what} takes a signal reader, a path, a function f(chr, start, "
+                        f"end, bins) or chr, start, end, value records; got "
+                        f"{type(data).__name__}")
+    rows = list(data)
+    if rows and isinstance(rows[0], Mapping):
+        return _signal_columns({k: [r[k] for r in rows] for k in rows[0]}, what)
+    if any(isinstance(r, (str, bytes)) or not isinstance(r, Sequence) or len(r) != 4
+           for r in rows):
+        raise TypeError(f"{what} takes a signal reader, a path, a function f(chr, start, "
+                        f"end, bins) or chr, start, end, value records (rows of 4); got "
+                        f"{type(data).__name__}")
+    return {k: [r[i] for r in rows] for i, k in enumerate(("chr", "start", "end", "value"))}
+
+
+class Signal:
+    """``chr``, ``start``, ``end``, ``value`` records in memory (columns, a DataFrame, or
+    rows), binned here as gwseq_io bins a bigWig: each bin the reduction (:data:`REDUCTIONS`)
+    of its bases, weighted by overlap, bases no record covers counting as ``def_value``
+    (left out when NaN)."""
+
+    def __init__(self, data: Any, what: str = "BigWig") -> None:
+        cols = _signal_columns(data, what)
+        n = len(cols["chr"])
+        if any(len(v) != n for v in cols.values()):
+            raise ValueError(f"{what}: the signal columns have different lengths")
+        by: dict[str, list[tuple[int, int, float]]] = {}
+        for i in range(n):
+            s = sources._position(cols["start"][i], i, "start")
+            e = sources._position(cols["end"][i], i, "end")
+            if e < s:
+                raise ValueError(f"record {i + 1} ends before it starts ({s}-{e})")
+            v = cols["value"][i]
+            by.setdefault(str(cols["chr"][i]), []).append(
+                (s, e, math.nan if v is None else float(v)))
+        self._chrs: dict[str, tuple[array, array, array, int]] = {}
+        for c, recs in by.items():
+            recs.sort()
+            self._chrs[c] = (array("q", [r[0] for r in recs]), array("q", [r[1] for r in recs]),
+                             array("d", [r[2] for r in recs]),
+                             max((r[1] - r[0] for r in recs), default=0))
+        #: the chromosomes the records name
+        self.chr_names = frozenset(self._chrs)
+
+    def read_values(self, regions: Any, *, bin_count: int | None = None,
+                    bin_size: int | None = None, bin_mode: str = "mean",
+                    def_value: float = 0.0, full_bin: bool = False, **kw: Any) -> list[array]:
+        if bin_mode not in REDUCTIONS:
+            raise ValueError(f"bin_mode {bin_mode!r}: plain signal data are reduced by "
+                             f"{', '.join(REDUCTIONS)}")
+        if kw.get("snap_to_grid") not in (None, False, "auto"):
+            raise ValueError("plain signal data are binned from the region's start "
+                             "(snap_to_grid=False)")
+        out = []
+        for c, lo, hi in _regions(regions):
+            if bin_count is not None:
+                n = max(1, int(bin_count))
+                edges = [lo + (hi - lo) * i / n for i in range(n + 1)]
+                edges[-1] = float(hi)
+            else:
+                size = int(bin_size or 1)
+                n = (hi - lo) // size if not full_bin else -(-(hi - lo) // size)
+                edges = [float(lo + i * size) for i in range(n + 1)]
+            out.append(self._bin(c, edges, bin_mode, float(def_value)))
+        return out
+
+    def _bin(self, chr: str, edges: list[float], mode: str, def_value: float) -> array:
+        n = len(edges) - 1
+        total = [0.0] * n          # value × bases covered
+        covered = [0.0] * n        # bases covered
+        lo_v = [math.inf] * n
+        hi_v = [-math.inf] * n
+        got = self._chrs.get(chr)
+        if got is not None and n > 0:
+            starts, ends, values, longest = got
+            a, b = edges[0], edges[-1]
+            i = bisect.bisect_left(starts, int(a) - longest)
+            j = bisect.bisect_left(starts, b)
+            for k in range(i, j):
+                s, e, v = starts[k], ends[k], values[k]
+                if e <= a or math.isnan(v):
+                    continue
+                s0, e0 = max(float(s), a), min(float(e), b)
+                if e0 <= s0:
+                    continue
+                first = max(0, bisect.bisect_right(edges, s0) - 1)
+                for m in range(first, n):
+                    x0, x1 = max(s0, edges[m]), min(e0, edges[m + 1])
+                    if x1 <= x0:
+                        if edges[m] >= e0:
+                            break
+                        continue
+                    total[m] += v * (x1 - x0)
+                    covered[m] += x1 - x0
+                    lo_v[m] = min(lo_v[m], v)
+                    hi_v[m] = max(hi_v[m], v)
+        fill = not math.isnan(def_value)
+        out = array("d")
+        for m in range(n):
+            width = edges[m + 1] - edges[m]
+            gap = max(0.0, width - covered[m])
+            if mode == "count":
+                out.append(covered[m])
+                continue
+            if fill and gap > 1e-9:
+                total[m] += def_value * gap
+                lo_v[m], hi_v[m] = min(lo_v[m], def_value), max(hi_v[m], def_value)
+                weight = width
+            else:
+                weight = covered[m]
+            if weight <= 0:
+                out.append(math.nan)
+            elif mode == "mean":
+                out.append(total[m] / weight)
+            elif mode == "sum":
+                out.append(total[m])
+            else:
+                out.append(lo_v[m] if mode == "min" else hi_v[m])
+        return out
+
+
+class Matrix:
+    """A square matrix of values over the region drawn (bins of ``span / n``): it has no
+    coordinates of its own, so it is the same whatever the region."""
+
+    bin_sizes: tuple[int, ...] = ()
+    normalizations = ("none",)
+
+    def __init__(self, data: Any) -> None:
+        h, w, k, flat = sources.matrix(data)
+        if h != w or k != 1 or not h:
+            raise ValueError(f"HiC needs a square matrix of values, got {h} × {w}")
+        self.n, self.values = h, flat
+
+    def read_values(self, region1: Any, region2: Any = None, **kw: Any) -> list[array]:
+        n, v = self.n, self.values
+        return [v[i * n:(i + 1) * n] for i in range(n)]

plot_io/genome/combine.py

@@ -0,0 +1,123 @@
+"""Two signals as one: :func:`combine` gives a signal reader whose values are those of two
+readers read with the same arguments, combined bin by bin (a difference, a ratio, a log2
+ratio or a function)."""
+
+import math
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from vec_io.arrays import doubles
+
+from ..validators import real
+from . import adapters, readers
+
+__all__ = ["combine", "Combined", "OPS"]
+
+
+def _ratio(a: float, b: float) -> float:
+    return a / b if b else math.nan
+
+
+def _log2ratio(p: float) -> Callable[[float, float], float]:
+    def f(a: float, b: float) -> float:
+        a, b = a + p, b + p
+        return math.log2(a / b) if a > 0 and b > 0 else math.nan
+    return f
+
+
+#: The operations by name: ``a - b``, ``a / b``, ``log2((a + p) / (b + p))``.
+OPS = ("difference", "ratio", "log2ratio")
+
+
+def _rows(v: Any) -> list[Any]:
+    """The rows of a read (a 2-D buffer or a sequence of rows), as doubles."""
+    shape = getattr(v, "shape", None)
+    if shape is not None and len(shape) == 2:
+        return [doubles(v[i]) for i in range(shape[0])]
+    return [doubles(r) for r in v]
+
+
+class Combined:
+    """A signal reader of two (see :func:`combine`)."""
+
+    def __init__(self, a: Any, b: Any, op: Any, pseudo_count: Any) -> None:
+        self.a = self._signal(a)
+        self.b = self._signal(b)
+        p = real(pseudo_count)
+        if p is None or not math.isfinite(p) or p < 0:
+            raise ValueError(f"combine: pseudo_count must be a number ≥ 0, got "
+                             f"{pseudo_count!r}")
+        if isinstance(op, str):
+            if op not in OPS:
+                raise ValueError(f"combine: op must be one of {', '.join(OPS)} or a "
+                                 f"function, got {op!r}")
+            f: Callable[[float, float], float] = (
+                (lambda x, y: x - y) if op == "difference" else
+                (lambda x, y: _ratio(x + p, y + p)) if op == "ratio" else _log2ratio(p))
+        elif callable(op):
+            f = op
+        else:
+            raise TypeError(f"combine: op must be one of {', '.join(OPS)} or a function, "
+                            f"got {op!r}")
+        self.op, self.pseudo_count, self._f = op, p, f
+
+    def __getattr__(self, name: str) -> Any:
+        """``resolve_regions``: the first reader's, when both give it (read at draw)."""
+        if name == "resolve_regions" and "b" in self.__dict__ \
+                and hasattr(self.a, name) and hasattr(self.b, name):
+            return self.a.resolve_regions
+        raise AttributeError(name)
+
+    def _signal(self, v: Any) -> Any:
+        reader = readers.adapt(v, "signal", "combine", owner=self)
+        if not isinstance(reader, adapters.Deferred) and not hasattr(reader, "read_values"):
+            raise TypeError(f"combine needs signal readers or signal data, got {v!r}")
+        return reader
+
+    def __repr__(self) -> str:
+        op = self.op if isinstance(self.op, str) else getattr(self.op, "__name__", "op")
+        return f"combine({self.a!r}, {self.b!r}, {op!r})"
+
+    @property
+    def chr_sizes(self) -> Mapping[str, int]:
+        """The sizes either reader gives (the larger)."""
+        sizes: dict[str, int] = {}
+        for r in (self.a, self.b):
+            got = getattr(r, "chr_sizes", None)
+            if isinstance(got, Mapping):
+                for k, n in got.items():
+                    sizes[str(k)] = max(sizes.get(str(k), 0), int(n))
+        if not sizes:
+            raise AttributeError("neither reader gives chr_sizes")
+        return sizes
+
+    def read_values(self, regions: Any, **kw: Any) -> list[Any]:
+        """Both readers read with these arguments, combined bin by bin: NaN where either
+        is NaN or the result is undefined (a ratio over 0, the log of a value ≤ 0)."""
+        ra, rb = _rows(self.a.read_values(regions, **kw)), _rows(self.b.read_values(regions, **kw))
+        if len(ra) != len(rb):
+            raise ValueError(f"combine: the readers gave {len(ra)} and {len(rb)} rows")
+        f = self._f
+        out = []
+        for x, y in zip(ra, rb):
+            if len(x) != len(y):
+                raise ValueError(f"combine: the readers gave rows of {len(x)} and {len(y)} "
+                                 f"bins (give both the same grid)")
+            row = [math.nan if math.isnan(a) or math.isnan(b) else float(f(a, b))
+                   for a, b in zip(x, y)]
+            out.append(doubles(row))
+        return out
+
+
+def combine(a: Any, b: Any, op: Any = "log2ratio", pseudo_count: Any = 0) -> Combined:
+    """A signal reader of ``a`` and ``b`` (readers, paths or signal data, as ``bigwig``
+    takes them) read with the same arguments and combined bin by bin: ``"difference"``
+    (``a - b``), ``"ratio"`` (``a / b``), ``"log2ratio"`` (``log2((a + p) / (b + p))``,
+    ``p`` the ``pseudo_count``; a ratio adds it too) or a function ``op(a, b)`` of two
+    numbers; NaN where either is NaN or the result is undefined.  It is drawn wherever a
+    signal reader is: ``bigwig``, heat strips, the site matrix.
+
+        >>> fig.bigwig(plt.genome.combine("treat.bw", "input.bw", "log2ratio",
+        ...                              pseudo_count=1))
+    """
+    return Combined(a, b, op, pseudo_count)