plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/genome/sources.py

@@ -0,0 +1,459 @@
+"""Reading genome data from readers, without importing any reader library: the calls
+plot_io makes, as the protocols of :mod:`plot_io.genome.readers` describe them.
+
+With ``bin_size``, a signal row grows to the grid of the size and its bounds come from
+``resolve_regions`` (same arguments) when the reader has it; the bins are then cut to the
+region.  A contact read checks ``normalization`` against the reader's ``normalizations``
+first.  Results are read as buffers (numpy arrays included) without importing numpy.
+"""
+
+import math
+from array import array
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from vec_io.arrays import doubles
+
+from .. import kernels
+from .regions import Region
+
+__all__ = ["kind_of", "check_reader", "read_signal", "read_entries", "read_models",
+           "read_contacts", "bin_size_for", "entry_columns", "pair_columns", "read_pairs", "even_edges", "matrix", "ints",
+           "BED_COLUMNS", "BEDPE_COLUMNS"]
+
+#: The BED columns the interval tracks use, by their names in autoSql and in BED files.
+BED_COLUMNS = ("chr", "start", "end", "name", "score", "strand", "thickStart", "thickEnd",
+               "itemRgb", "blockCount", "blockSizes", "blockStarts")
+#: The BEDPE columns links use, in BEDPE order.
+BEDPE_COLUMNS = ("chr1", "start1", "end1", "chr2", "start2", "end2", "name", "score")
+_PAIR_ALIASES = {"chrom1": "chr1", "chromosome1": "chr1", "chr": "chr1", "chrom": "chr1",
+                 "chromosome": "chr1", "start": "start1", "end": "end1", "chrom2": "chr2",
+                 "chromosome2": "chr2"}
+_TYPES = {"bigwig": "signal", "bigbed": "intervals", "bed": "intervals", "peaks": "intervals",
+          "hic": "contacts", "bam": "alignments", "cram": "alignments", "gtf": "annotation",
+          "gff3": "annotation"}
+_ALIASES = {"chrom": "chr", "chromosome": "chr", "chromStart": "start", "chromEnd": "end",
+            "chrom_start": "start", "chrom_end": "end", "reserved": "itemRgb",
+            "item_rgb": "itemRgb",
+            "thick_start": "thickStart", "thick_end": "thickEnd",
+            "block_count": "blockCount", "block_sizes": "blockSizes",
+            "block_starts": "blockStarts", "chromStarts": "blockStarts",
+            "chrom_starts": "blockStarts", "exonCount": "blockCount",
+            "exonSizes": "blockSizes", "exonStarts": "blockStarts"}
+
+
+def kind_of(reader: Any) -> str | None:
+    """``"signal"``, ``"intervals"``, ``"annotation"``, ``"contacts"``, ``"alignments"`` or
+    ``None`` (not a reader)."""
+    t = getattr(reader, "type", None)
+    if isinstance(t, str) and t.lower() in _TYPES:
+        return _TYPES[t.lower()]
+    if hasattr(reader, "read_sparse_values") or hasattr(reader, "bin_sizes"):
+        return "contacts"
+    if hasattr(reader, "tss"):
+        return "annotation"
+    if hasattr(reader, "read_entries"):
+        return "intervals"
+    if hasattr(reader, "read_values"):
+        return "signal"
+    if hasattr(reader, "read_alignments"):
+        return "alignments"
+    return None
+
+
+def check_reader(reader: Any, want: tuple[str, ...], what: str) -> str:
+    """The kind of ``reader``, which must be one of ``want``."""
+    kind = kind_of(reader)
+    if kind == "alignments":
+        raise TypeError(f"{what} does not read alignments: pile the reads up into a bigWig "
+                        f"first (gwseq_io.pileup_reads)")
+    if kind == "annotation" and kind not in want:
+        raise TypeError(f"{what} does not read gene annotations: draw a GTF or GFF3 reader "
+                        f"with gtf()")
+    if kind not in want:
+        raise TypeError(f"{what} needs a reader with "
+                        + {"signal": "read_values (a bigWig)",
+                           "intervals": "read_entries (a bigBed, BED or peaks file)",
+                           "annotation": "read_entries(model=) and tss (a GTF or GFF3 file)",
+                           "contacts": "bin_sizes and read_values (a Hi-C file)"}[want[0]]
+                        + f", got {type(reader).__name__}")
+    return kind
+
+
+def _first(v: Any) -> Any:
+    """Row 0 of a result with one row per region."""
+    rows = None
+    shape = getattr(v, "shape", None)
+    if shape is not None and len(shape) == 2:
+        rows = shape[0]
+        if rows != 1:
+            raise ValueError(f"expected one row of values, got {rows}")
+        return v[0]
+    if isinstance(v, Sequence) and v and isinstance(v[0], (Sequence, array)) \
+            and not isinstance(v[0], str):
+        return v[0]
+    return v
+
+
+def _bounds(reader: Any, region: Region, kw: dict[str, Any], hic: bool) -> tuple[int, int]:
+    """The start and end of the row a binned read gives, from ``resolve_regions``."""
+    target = (region.chr, region.start, region.end)
+    r = reader.resolve_regions(target if hic else [target], **kw)
+    if hic:
+        r = r["rows"]
+    return int(r["start"][0]), int(r["end"][0])
+
+
+def even_edges(start: float, end: float, n: int) -> array:
+    """``n + 1`` evenly spaced edges from ``start`` to ``end`` (no edges for no bins)."""
+    if n <= 0:
+        return array("d")
+    span = end - start
+    edges = array("d", [start + span * i / n for i in range(n + 1)])
+    edges[-1] = float(end)
+    return edges
+
+
+def matrix(m: Any) -> tuple[int, int, int, array]:
+    """``(height, width, k, values)`` of a 2-D buffer or a sequence of rows."""
+    g = kernels.grid(m)
+    if g is not None:
+        return g
+    rows = [list(r) for r in m]
+    return (len(rows), len(rows[0]) if rows else 0, 1,
+            doubles([v for r in rows for v in r]))
+
+
+def ints(v: Any) -> list[int]:
+    """Whole numbers of a column or a BED list (``"10,20,"``): ``[]`` for ``None``."""
+    if v is None:
+        return []
+    if isinstance(v, str):
+        return [int(p) for p in v.replace(" ", "").split(",") if p]
+    if isinstance(v, (int, float)):
+        return [int(v)]
+    return [int(x) for x in (v.tolist() if hasattr(v, "tolist") else v)]
+
+
+def read_signal(reader: Any, region: Region, bins: int | None, bin_size: int | None,
+                bin_mode: str, def_value: float) -> tuple[array, array]:
+    """``(edges, values)``: n + 1 bin edges (bp) and n values of ``region``, in ``bins``
+    bins or bins of ``bin_size``."""
+    target = (region.chr, region.start, region.end)
+    if bin_size is None:
+        n = max(1, int(bins or 1))
+        v = reader.read_values([target], bin_count=n, bin_mode=bin_mode, def_value=def_value,
+                               zoom="auto")
+        values = doubles(_first(v))
+        return even_edges(region.start, region.end, len(values)), values
+    kw: dict[str, Any] = {"bin_size": int(bin_size)}
+    if hasattr(reader, "resolve_regions"):
+        kw["snap_to_grid"] = "expand"
+        start, end = _bounds(reader, region, dict(kw), False)
+    else:
+        kw.update(snap_to_grid=False, full_bin=True)
+        start, end = region.start, region.end
+    v = reader.read_values([target], bin_mode=bin_mode, def_value=def_value, zoom="auto",
+                           **kw)
+    values = doubles(_first(v))
+    n = len(values)
+    edges = array("d", [float(start + i * bin_size) for i in range(n + 1)])
+    edges[-1] = float(min(end, start + n * bin_size))     # a last partial bin ends there
+    lo, hi = float(region.start), float(region.end)       # bins cut to the region
+    return array("d", [min(max(e, lo), hi) for e in edges]), values
+
+
+_LOWER = {k.lower(): v for k, v in _ALIASES.items()}
+
+
+def _column(cols: Mapping[str, Any], name: str) -> Any:
+    """The column ``name`` or an alias of it; then the same without case (``Start``)."""
+    for k, v in cols.items():
+        if k == name or _ALIASES.get(k) == name:
+            return v
+    low = name.lower()
+    for k, v in cols.items():
+        if isinstance(k, str) and (k.lower() == low or _LOWER.get(k.lower()) == name):
+            return v
+    return None
+
+
+def _position(v: Any, i: int, name: str) -> int:
+    try:
+        return int(v)
+    except (TypeError, ValueError, OverflowError):
+        raise ValueError(f"interval {i + 1}: {name} {v!r} is not a position") from None
+
+
+def _score(v: Any) -> float | None:
+    """A BED score as a number; ``None`` when missing or not a number (``"."``)."""
+    if v is None or isinstance(v, bool):
+        return None
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return None
+    return f if math.isfinite(f) else None
+
+
+def entry_columns(cols: Any) -> dict[str, list[Any]]:
+    """The BED columns of a dict of columns, a DataFrame, or rows (dicts, or tuples in BED
+    order, ``chr`` first): ``chr`` as strings, ``start`` and ``end`` as ints, ``score`` as
+    numbers (``None`` where missing or not a number), ``blockSizes`` and ``blockStarts`` as
+    lists of ints, the others as given (missing ones left out).  Reversed intervals and
+    blocks not matching ``blockCount`` (or several blocks without ``blockStarts``) are refused."""
+    if hasattr(cols, "to_dict") and hasattr(cols, "columns"):           # a DataFrame
+        cols = {str(c): list(cols[c]) for c in cols.columns}
+    elif not isinstance(cols, Mapping):
+        rows = list(cols)
+        if not rows:
+            return {"start": [], "end": []}
+        if isinstance(rows[0], Mapping) or hasattr(rows[0], "keys"):
+            keys = list(rows[0].keys())
+            cols = {k: [r[k] for r in rows] for k in keys}
+        else:
+            order = BED_COLUMNS
+            width = max(len(r) for r in rows)
+            cols = {order[i]: [r[i] if i < len(r) else None for r in rows]
+                    for i in range(min(width, len(order)))}
+    out: dict[str, list[Any]] = {}
+    for name in BED_COLUMNS:
+        v = _column(cols, name)
+        if v is None:
+            continue
+        out[name] = list(v.tolist() if hasattr(v, "tolist") else v)
+    if "start" not in out or "end" not in out:
+        raise ValueError("intervals need start and end columns")
+    if len(out["start"]) != len(out["end"]):
+        raise ValueError("start and end have different lengths")
+    if "chr" in out:
+        out["chr"] = [str(c) for c in out["chr"]]
+    out["start"] = [_position(s, i, "start") for i, s in enumerate(out["start"])]
+    out["end"] = [_position(e, i, "end") for i, e in enumerate(out["end"])]
+    for i, (s, e) in enumerate(zip(out["start"], out["end"])):
+        if e < s:
+            raise ValueError(f"interval {i + 1} ends before it starts ({s}-{e})")
+    if "score" in out:
+        out["score"] = [_score(v) for v in out["score"]]
+    for name in ("blockSizes", "blockStarts"):
+        if name in out:
+            out[name] = [None if v is None else ints(v) for v in out[name]]
+    counts = out.get("blockCount")
+    if counts is not None:
+        for i, c in enumerate(counts):
+            if c is None:
+                continue
+            starts = out.get("blockStarts")
+            if int(c) > 1 and (starts is None or starts[i] is None):
+                raise ValueError(f"interval {i + 1}: blockCount {int(c)} without blockStarts")
+            for name in ("blockSizes", "blockStarts"):
+                got = out.get(name)
+                if got is not None and got[i] is not None and len(got[i]) != int(c):
+                    raise ValueError(f"interval {i + 1}: blockCount {int(c)} with "
+                                     f"{len(got[i])} {name}")
+    return out
+
+
+def read_entries(reader: Any, region: Region) -> dict[str, list[Any]]:
+    """The entries of ``region``, as BED columns (see :func:`entry_columns`)."""
+    sql = getattr(reader, "auto_sql", None)
+    kw: dict[str, Any] = {}
+    if isinstance(sql, Mapping) and sql:
+        names = list(sql)
+        wanted = [i for i, k in enumerate(names) if (_ALIASES.get(k, k) in BED_COLUMNS)]
+        kw["columns"] = max(3, max(wanted, default=2) + 1)
+    return entry_columns(reader.read_entries([(region.chr, region.start, region.end)], **kw))
+
+
+def pair_columns(cols: Any) -> dict[str, list[Any]]:
+    """The BEDPE columns of a dict of columns, a DataFrame, or rows (dicts, or tuples in
+    BEDPE order): chromosomes as strings, positions as ints, ``score`` as numbers
+    (``None`` where missing); ``name`` and ``score`` optional.  Strand columns are left
+    out.  Reversed anchors are refused."""
+    if hasattr(cols, "to_dict") and hasattr(cols, "columns"):           # a DataFrame
+        cols = {str(c): list(cols[c]) for c in cols.columns}
+    elif not isinstance(cols, Mapping):
+        rows = list(cols)
+        if not rows:
+            return {k: [] for k in BEDPE_COLUMNS[:6]}
+        if isinstance(rows[0], Mapping) or hasattr(rows[0], "keys"):
+            cols = {k: [r[k] for r in rows] for k in rows[0].keys()}
+        else:
+            width = max(len(r) for r in rows)
+            if width < 6:
+                raise ValueError(f"links need 6 BEDPE columns (chr1 start1 end1 chr2 start2 "
+                                 f"end2), got {width}")
+            cols = {BEDPE_COLUMNS[i]: [r[i] if i < len(r) else None for r in rows]
+                    for i in range(min(width, len(BEDPE_COLUMNS)))}
+    named: dict[str, Any] = {}
+    for k, v in cols.items():
+        key = str(k)
+        name = key if key in BEDPE_COLUMNS else _PAIR_ALIASES.get(key) \
+            or _PAIR_ALIASES.get(key.lower()) or key.lower()
+        if name in BEDPE_COLUMNS and name not in named:
+            named[name] = v
+    missing = [k for k in BEDPE_COLUMNS[:6] if k not in named]
+    if missing:
+        raise ValueError(f"links need the BEDPE columns {', '.join(missing)}")
+    out = {k: list(v.tolist() if hasattr(v, "tolist") else v) for k, v in named.items()}
+    n = len(out["start1"])
+    if any(len(v) != n for v in out.values()):
+        raise ValueError("the BEDPE columns have different lengths")
+    for k in ("chr1", "chr2"):
+        out[k] = [str(c) for c in out[k]]
+    for k in ("start1", "end1", "start2", "end2"):
+        out[k] = [_position(v, i, k) for i, v in enumerate(out[k])]
+    for i in range(n):
+        for a in ("1", "2"):
+            if out["end" + a][i] < out["start" + a][i]:
+                raise ValueError(f"link {i + 1}: anchor {a} ends before it starts "
+                                 f"({out['start' + a][i]}-{out['end' + a][i]})")
+    if "score" in out:
+        out["score"] = [_score(v) for v in out["score"]]
+    return out
+
+
+def read_pairs(reader: Any, regions: Sequence[Region]) -> dict[str, list[Any]]:
+    """The pairs the reader gives for ``regions`` (those with an anchor in them; for
+    gwseq_io's peaks readers, those whose first anchor is), as BEDPE columns (see
+    :func:`pair_columns`)."""
+    return pair_columns(reader.read_entries([(r.chr, r.start, r.end) for r in regions]))
+
+
+def read_models(reader: Any, region: Region, model: str, gene_type: Any,
+                transcript_type: Any) -> dict[str, list[Any]]:
+    """The gene models overlapping ``region`` as BED12 columns: one per transcript
+    (``model="transcript"``, named by ``transcript_name``), or one per gene (named by
+    ``gene_name``): its transcripts' exons merged, the coding part from the first coding
+    start to the last coding end.  Ids name what has no name."""
+    cols = reader.read_entries([(region.chr, region.start, region.end)], model="transcript",
+                               gene_type=gene_type, transcript_type=transcript_type)
+    starts, ends = ints(cols["start"]), ints(cols["end"])
+    cds0, cds1 = ints(cols["cds_start"]), ints(cols["cds_end"])
+    exons = cols.nested["exons"]
+    ex0, ex1 = ints(exons["start"]), ints(exons["end"])
+    offs = ints(exons.groups)
+    strands = list(cols["strand"])
+    level = "transcript" if model == "transcript" else "gene"
+    ids = list(cols[f"{level}_id"])
+    names = list(cols.get(f"{level}_name") or [None] * len(ids))
+    models: dict[Any, dict[str, Any]] = {}
+    for i, key in enumerate(ids):
+        m = models.setdefault(key, {"start": starts[i], "end": ends[i], "strand": strands[i],
+                                    "name": names[i] or key, "exons": [], "cds": []})
+        m["start"], m["end"] = min(m["start"], starts[i]), max(m["end"], ends[i])
+        m["exons"].extend(zip(ex0[offs[i]:offs[i + 1]], ex1[offs[i]:offs[i + 1]]))
+        if cds0[i] >= 0:
+            m["cds"].append((cds0[i], cds1[i]))
+    out: dict[str, list[Any]] = {k: [] for k in (
+        "chr", "start", "end", "name", "strand", "thickStart", "thickEnd", "blockCount",
+        "blockSizes", "blockStarts")}
+    for m in models.values():
+        merged: list[list[int]] = []
+        for a, b in sorted(m["exons"]):
+            if merged and a <= merged[-1][1]:
+                merged[-1][1] = max(merged[-1][1], b)
+            else:
+                merged.append([a, b])
+        s, e = m["start"], m["end"]
+        cds = m["cds"]
+        out["chr"].append(region.chr)
+        out["start"].append(s)
+        out["end"].append(e)
+        out["name"].append(str(m["name"]))
+        out["strand"].append(m["strand"])
+        out["thickStart"].append(min(a for a, _ in cds) if cds else e)
+        out["thickEnd"].append(max(b for _, b in cds) if cds else e)
+        out["blockCount"].append(len(merged))
+        out["blockSizes"].append([b - a for a, b in merged])
+        out["blockStarts"].append([a - s for a, _ in merged])
+    return out
+
+
+def read_contacts(reader: Any, region: Region, bin_size: int | None, normalization: str,
+                  matrix_type: str, depth: int | None,
+                  bin_count: int | None = None) -> tuple[Any, float]:
+    """``(matrix, start)``: the contact matrix of ``region`` at ``bin_size`` (rows and
+    columns from ``start``, the row grown to the grid of ``bin_size``), or in ``bin_count``
+    bins over the region, and where its first bin starts."""
+    normalization = _normalization(reader, normalization)
+    target = (region.chr, region.start, region.end)
+    kw: dict[str, Any]
+    start: float = region.start
+    if bin_count is not None:
+        kw = {"bin_count": int(bin_count)}
+    elif hasattr(reader, "resolve_regions"):
+        kw = {"bin_size": _bin_size(reader, bin_size), "snap_to_grid": "expand"}
+        start = _bounds(reader, region, dict(kw), True)[0]
+    else:
+        kw = {"bin_size": _bin_size(reader, bin_size), "snap_to_grid": False,
+              "full_bin": True}
+    extra: dict[str, Any] = {"normalization": normalization, "matrix_type": matrix_type}
+    if depth is not None:
+        extra["max_distance"] = int(depth)
+    m = reader.read_values(target, **kw, **extra)
+    return m, start
+
+
+def _bin_size(reader: Any, bin_size: int | None) -> int:
+    """``bin_size`` as an int, which must be one of ``reader.bin_sizes`` when it has them."""
+    n = int(bin_size or 0)
+    sizes = sorted(int(b) for b in getattr(reader, "bin_sizes", None) or ())
+    if sizes and n not in sizes:
+        def bp(b: int) -> str:
+            unit, f = next(((u, f) for u, f in (("Mb", 1_000_000), ("kb", 1_000))
+                            if b >= f and b % f == 0), ("bp", 1))
+            return f"{b // f:,} {unit}"
+        raise ValueError(f"the Hi-C file has no matrix in bins of {bp(n)} (it has "
+                         f"{', '.join(bp(b) for b in sizes)})")
+    return n
+
+
+def _normalization(reader: Any, name: str) -> str:
+    """``name`` as the reader spells it (``KR``, ``kr``); ``ValueError`` when it has none
+    such."""
+    norms = getattr(reader, "normalizations", None)
+    if norms is not None and name not in norms and name != "none":
+        same = [n for n in norms if str(n).lower() == name.lower()]
+        if not same:
+            raise ValueError(f"normalization {name!r} is not in the file (it has "
+                             f"{', '.join(map(repr, norms))})")
+        return same[0]
+    return name
+
+
+def read_square(reader: Any, region: Region, region2: Region, bin_size: int | None,
+                normalization: str, matrix_type: str,
+                bin_count: tuple[int, int] | None = None) -> tuple[Any, float, float]:
+    """``(matrix, start, start2)``: the contact matrix of ``region`` (rows) against
+    ``region2`` (columns) at ``bin_size`` (each grown to its grid) or in ``bin_count``
+    ``(rows, columns)`` bins, and where its first row and first column start."""
+    t1 = (region.chr, region.start, region.end)
+    t2 = (region2.chr, region2.start, region2.end)
+    kw: dict[str, Any]
+    start, start2 = float(region.start), float(region2.start)
+    if bin_count is not None:
+        kw = {"bin_count": (int(bin_count[0]), int(bin_count[1]))}
+    elif hasattr(reader, "resolve_regions"):
+        kw = {"bin_size": _bin_size(reader, bin_size), "snap_to_grid": "expand"}
+        r = reader.resolve_regions(t1, t2, **kw)
+        start, start2 = float(r["rows"]["start"][0]), float(r["cols"]["start"][0])
+    else:
+        kw = {"bin_size": _bin_size(reader, bin_size), "snap_to_grid": False,
+              "full_bin": True}
+    m = reader.read_values(t1, t2, **kw, normalization=_normalization(reader, normalization),
+                           matrix_type=matrix_type)
+    return m, start, start2
+
+
+def bin_size_for(reader: Any, span: int, cells: float) -> int:
+    """The finest of ``reader.bin_sizes`` giving at most ``cells`` cells across ``span``;
+    the coarsest when none does."""
+    sizes = sorted(int(b) for b in getattr(reader, "bin_sizes", []) or [])
+    if not sizes:
+        raise ValueError("the Hi-C reader has no bin_sizes; give bin_size")
+    for b in sizes:
+        if span / b <= max(1.0, cells):
+            return b
+    return sizes[-1]
+

plot_io/genome/testing.py

@@ -0,0 +1,161 @@
+"""A conformance check of readers: :func:`check` calls a reader as plot_io does and says
+what it gives that plot_io cannot draw.
+
+    >>> from plot_io.genome.testing import check
+    >>> check(gwseq_io.open("atac.bw"), "signal", "chr2:30,000,001-31,000,000")
+    []
+"""
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+from . import readers, sources
+from .regions import Region, parse_region
+
+__all__ = ["check", "KINDS"]
+
+#: The reader roles :func:`check` knows (as :func:`plot_io.genome.readers.adapt` takes them).
+KINDS = tuple(readers.WANTS)
+
+
+def _rows(v: Any) -> list[list[Any]]:
+    """The rows of a 2-D result (a buffer or a sequence of rows)."""
+    if hasattr(v, "tolist"):
+        v = v.tolist()
+    rows = list(v)
+    if not all(hasattr(r, "__len__") and not isinstance(r, (str, bytes)) for r in rows):
+        raise ValueError("expected one row per region, got a flat sequence")
+    return [list(r.tolist() if hasattr(r, "tolist") else r) for r in rows]
+
+
+def _number(v: Any) -> bool:
+    try:
+        float(v)
+    except (TypeError, ValueError):
+        return False
+    return not isinstance(v, (str, bytes, bool))
+
+
+def check(reader: Any, kind: str, region: Any) -> list[str]:
+    """The problems plot_io meets reading ``reader`` as a ``kind`` reader (``"signal"``,
+    ``"intervals"``, ``"annotation"``, ``"pairs"``, ``"contacts"``) over ``region`` (a
+    region with data, as ``region=`` takes it); ``[]``: none.  Each protocol member is
+    called with the arguments plot_io passes (:mod:`plot_io.genome.readers`), and the
+    results checked: rows per region and bins per row, numbers, the columns needed,
+    entries in the region, a square matrix, ``resolve_regions`` bounds against the read,
+    ``chr_sizes`` a mapping of whole numbers."""
+    if kind not in readers.WANTS:
+        raise ValueError(f"kind must be one of {', '.join(KINDS)}, got {kind!r}")
+    r = parse_region(region)
+    problems: list[str] = []
+    got = sources.kind_of(reader)
+    if got not in readers.WANTS[kind]:
+        return [f"recognised as {got or 'no reader'}, not as a {kind} reader: give it a "
+                f"type attribute or the members of its protocol"]
+    for name, test in (("chr_sizes", _sized), (kind, _CHECKS[kind])):
+        if name == "chr_sizes" and not hasattr(reader, "chr_sizes"):
+            continue
+        try:
+            test(reader, r, problems)
+        except Exception as e:
+            problems.append(f"{name}: {type(e).__name__}: {e}")
+    return problems
+
+
+def _sized(reader: Any, r: Region, out: list[str]) -> None:
+    sizes = reader.chr_sizes
+    if not isinstance(sizes, Mapping):
+        out.append(f"chr_sizes is a {type(sizes).__name__}, not a mapping")
+        return
+    for k, v in sizes.items():
+        if not isinstance(k, str) or not isinstance(v, int) or isinstance(v, bool) or v <= 0:
+            out.append(f"chr_sizes: {k!r}: {v!r} is not a name and a positive whole number")
+            return
+
+
+def _signal(reader: Any, r: Region, out: list[str]) -> None:
+    t = (r.chr, r.start, r.end)
+    half = (r.chr, r.start, r.start + max(1, r.span // 2))
+    for regions, n in (([t], 7), ([t, half], 3)):
+        rows = _rows(reader.read_values(regions, bin_count=n, bin_mode="mean", def_value=0.0,
+                                        zoom="auto"))
+        if len(rows) != len(regions):
+            out.append(f"read_values of {len(regions)} region(s): {len(rows)} rows")
+        for row in rows:
+            if len(row) != n:
+                out.append(f"read_values(bin_count={n}): {len(row)} bins in a row")
+            if not all(_number(v) for v in row):
+                out.append("read_values: values that are not numbers")
+                break
+    size = max(1, r.span // 5)
+    edges, values = sources.read_signal(reader, r, None, size, "mean", 0.0)
+    if len(values) < r.span // size or len(edges) != len(values) + 1:
+        out.append(f"read_values(bin_size={size}): {len(values)} bins over {r.span} bp")
+    if hasattr(reader, "resolve_regions"):
+        got = reader.resolve_regions([t], bin_size=size, snap_to_grid="expand")
+        a, b = int(got["start"][0]), int(got["end"][0])
+        if a > r.start or b < r.end or (b - a) != len(values) * size:
+            out.append(f"resolve_regions gives {a}-{b} for {len(values)} bins of {size} bp "
+                       f"over {r.start}-{r.end}")
+
+
+def _in(s: Any, e: Any, r: Region) -> bool:
+    return int(e) > r.start and int(s) < r.end
+
+
+def _intervals(reader: Any, r: Region, out: list[str]) -> None:
+    cols = sources.read_entries(reader, r)
+    chrs = cols.get("chr")
+    for i, (s, e) in enumerate(zip(cols["start"], cols["end"])):
+        if not _in(s, e, r) or (chrs is not None and chrs[i] != r.chr):
+            out.append(f"read_entries: entry {i + 1} ({s}-{e}) is not in the region")
+            return
+
+
+def _annotation(reader: Any, r: Region, out: list[str]) -> None:
+    for model in ("transcript", "gene"):
+        cols = sources.read_models(reader, r, model, None, None)
+        for i, (s, e) in enumerate(zip(cols["start"], cols["end"])):
+            if not _in(s, e, r):
+                out.append(f"read_entries(model=): model {i + 1} ({s}-{e}) is not in the "
+                           f"region")
+                return
+
+
+def _pairs(reader: Any, r: Region, out: list[str]) -> None:
+    cols = sources.read_pairs(reader, [r])
+    for i in range(len(cols["start1"])):
+        if not any(cols["chr" + a][i] == r.chr and _in(cols["start" + a][i],
+                                                       cols["end" + a][i], r)
+                   for a in "12"):
+            out.append(f"read_entries: pair {i + 1} has no anchor in the region")
+            return
+
+
+def _contacts(reader: Any, r: Region, out: list[str]) -> None:
+    sizes = list(getattr(reader, "bin_sizes", None) or [])
+    if not sizes or not all(isinstance(b, int) and b > 0 for b in sizes):
+        out.append(f"bin_sizes {sizes!r}: expected positive whole numbers")
+        return
+    norms = getattr(reader, "normalizations", None)
+    if norms is None or not all(isinstance(n, str) for n in norms):
+        out.append(f"normalizations {norms!r}: expected names")
+    b = sources.bin_size_for(reader, r.span, 50)
+    m, start = sources.read_contacts(reader, r, b, "none", "observed", None)
+    h, w, k, flat = sources.matrix(m)
+    if h != w or k != 1:
+        out.append(f"read_values(bin_size={b}): a {h} × {w} matrix for one region")
+    elif start > r.start or start + h * b < r.end:
+        out.append(f"read_values(bin_size={b}): {h} bins from {start} do not cover "
+                   f"{r.start}-{r.end}")
+    if not all(_number(v) and not math.isinf(float(v)) for v in flat):
+        out.append("read_values: values that are not finite numbers or NaN")
+    m, _ = sources.read_contacts(reader, r, None, "none", "observed", None, bin_count=4)
+    h, w, _, _ = sources.matrix(m)
+    if (h, w) != (4, 4):
+        out.append(f"read_values(bin_count=4): a {h} × {w} matrix")
+
+
+_CHECKS = {"signal": _signal, "intervals": _intervals, "annotation": _annotation,
+           "pairs": _pairs, "contacts": _contacts}