Skip to content

Operations

Computation on already-open metacooler files: aggregation, re-binning, multi-resolution generation, visualisation, range parsing, contact QC and contact probability P(s). These act on files produced by the I/O functions.

aggregate, binnify, and zoomify are re-exported at the top level, so metacooler.binnify(...) and metacooler.ops.binnify.binnify(...) are equivalent.

Resolution constraints

binnify requires the target bin size to be an exact multiple of a fixed source bin size (or, for a variable-bin source, strictly larger than the median source bin width), and zoomify requires every requested resolution to be a multiple of the base bin size. Both raise ValueError otherwise; see the multi-resolution guide.

Aggregation

Aggregation operations for metacool files.

All aggregation shares two primitives:

  • :func:_bin_to_level_mapping maps each bin id to a contig or genome id;
  • :func:_write_aggregated_cool streams the aggregated pixels into a .cool.

_aggregate_sparse (dense/sparse, used by show) and the streaming aggregate / :meth:MetaCooler.to_cooler all build on these so the int-overflow handling and the bin→level mapping live in exactly one place.

aggregate

aggregate(
    uri: str | Path,
    output: str | Path,
    level: Literal["contig", "genome"] = "contig",
    count_col: str = "count",
    chunksize: int = DEFAULT_CHUNKSIZE,
) -> None

Aggregate a metacool file to contig or genome level.

The output is a standard .cool file where the "chromosomes" are either contigs or genomes. Pixels are streamed chunk-by-chunk; the full contact matrix is never materialised in memory.

Parameters:

Name Type Description Default
uri str | Path

Path to the source .metacool file.

required
output str | Path

Destination path for the output .cool file.

required
level Literal['contig', 'genome']

Aggregation level — "contig" or "genome".

'contig'
count_col str

Pixel column to use as contact count (default: "count").

'count'
chunksize int

Number of pixels to process per chunk.

DEFAULT_CHUNKSIZE
Source code in src/metacooler/ops/aggregate.py
def aggregate(
    uri: str | Path,
    output: str | Path,
    level: Literal["contig", "genome"] = "contig",
    count_col: str = "count",
    chunksize: int = DEFAULT_CHUNKSIZE,
) -> None:
    """Aggregate a metacool file to contig or genome level.

    The output is a standard ``.cool`` file where the "chromosomes" are
    either contigs or genomes.  Pixels are streamed chunk-by-chunk; the
    full contact matrix is never materialised in memory.

    Args:
        uri: Path to the source ``.metacool`` file.
        output: Destination path for the output ``.cool`` file.
        level: Aggregation level — ``"contig"`` or ``"genome"``.
        count_col: Pixel column to use as contact count (default: ``"count"``).
        chunksize: Number of pixels to process per chunk.
    """
    _write_aggregated_cool(
        MetaCooler(uri),
        output,
        level=level,
        count_col=count_col,
        chunksize=chunksize,
    )

Re-binning

Re-binning operation for metacool files.

binnify

binnify(
    uri: str | Path,
    output: str | Path,
    binsize: int,
    level: Literal["contig", "genome"] = "contig",
    chunksize: int = DEFAULT_CHUNKSIZE,
    force: bool = False,
) -> None

Re-bin a metacool file to a new, coarser fixed bin size.

The target binsize must be strictly coarser than the source binning:

  • for a fixed-bin source, binsize must be a strict, exact multiple of the source bin size. A non-multiple target is rejected: the midpoint rule would pack an oscillating number of source bins into each output bin (e.g. 1 kb → 3.5 kb alternates 3 and 4 source bins, a built-in ±14 % checkerboard) while the file would advertise a uniform bin size;
  • for a variable-bin source (fragment-level files, contig-level files) there is no exact multiple, so the median source bin width is used as the effective source resolution and binsize must be strictly larger than it. A target that is larger than the median but smaller than the widest source bin is accepted with a warning (those widest bins each collapse into a single output bin, so the local resolution is uneven).

Parameters:

Name Type Description Default
uri str | Path

Path to the source .metacool file.

required
output str | Path

Destination path for the output .metacool file.

required
binsize int

New bin size in base pairs.

required
level Literal['contig', 'genome']

Tiling level. contig (default) tiles each contig independently, preserving the contig hierarchy. genome artificially ligates each genome's contigs (ordered by decreasing length) into one sequence and tiles that uniformly; the output's contigs become the ligated genomes (one per genome), so bins may span the original contig boundaries.

'contig'
chunksize int

Number of source pixels loaded, remapped and aggregated per chunk. Pixels are never fully materialised in memory.

DEFAULT_CHUNKSIZE
force bool

Overwrite output if it already exists.

False

Raises:

Type Description
ValueError

If binsize is not strictly coarser than the source resolution, if it is not an exact multiple of a fixed source bin size, or if level is unknown.

FileExistsError

If output exists and force is False.

Source code in src/metacooler/ops/binnify.py
def binnify(
    uri: str | Path,
    output: str | Path,
    binsize: int,
    level: Literal["contig", "genome"] = "contig",
    chunksize: int = DEFAULT_CHUNKSIZE,
    force: bool = False,
) -> None:
    """Re-bin a metacool file to a new, coarser fixed bin size.

    The target *binsize* must be **strictly coarser** than the source binning:

    - for a fixed-bin source, *binsize* must be a strict, **exact multiple** of
      the source bin size.  A non-multiple target is rejected: the midpoint
      rule would pack an oscillating number of source bins into each output bin
      (e.g. 1 kb → 3.5 kb alternates 3 and 4 source bins, a built-in ±14 %
      checkerboard) while the file would advertise a uniform bin size;
    - for a variable-bin source (fragment-level files, contig-level files) there
      is no exact multiple, so the *median* source bin width is used as the
      effective source resolution and *binsize* must be strictly larger than it.
      A target that is larger than the median but smaller than the widest source
      bin is accepted with a warning (those widest bins each collapse into a
      single output bin, so the local resolution is uneven).

    Args:
        uri: Path to the source ``.metacool`` file.
        output: Destination path for the output ``.metacool`` file.
        binsize: New bin size in base pairs.
        level: Tiling level. ``contig`` (default) tiles each contig
            independently, preserving the contig hierarchy. ``genome``
            artificially ligates each genome's contigs (ordered by decreasing
            length) into one sequence and tiles that uniformly; the output's
            contigs become the ligated genomes (one per genome), so bins may
            span the original contig boundaries.
        chunksize: Number of source pixels loaded, remapped and aggregated per
            chunk.  Pixels are never fully materialised in memory.
        force: Overwrite *output* if it already exists.

    Raises:
        ValueError: If *binsize* is not strictly coarser than the source
            resolution, if it is not an exact multiple of a fixed source bin
            size, or if *level* is unknown.
        FileExistsError: If *output* exists and *force* is False.
    """
    from metacooler.api import MetaCooler

    output = Path(output)
    check_output_path(output, force=force, inputs=[uri])

    if binsize <= 0:
        raise ValueError(f"binsize must be a positive integer, got {binsize}.")

    mc = MetaCooler(uri)
    _binnify(
        mc,
        output,
        binsize,
        level=level,
        chunksize=chunksize,
        source_uri=uri,
        source_metadata=mc.metadata,
    )

Multi-resolution

Multi-resolution mmetacool generation.

zoomify

zoomify(
    uri: str | Path,
    output: str | Path,
    levels: int = 5,
    resolutions: str | None = None,
    temp_dir: str | Path | None = None,
    force: bool = False,
    nproc: int = 1,
) -> None

Create a multi-resolution .mmetacool file.

The input must be a fixed-bin metacooler. Each resolution is stored as an mmetacool entry named entries/<binsize> (open it as file.mmetacool::entries/<binsize>). The base resolution is streamed verbatim into the output; every coarser resolution is produced by re-binning, with :func:metacooler.ops.binnify.binnify, the coarsest level already written whose bin size divides it (10 kb from 5 kb, 2 kb and 5 kb from a 1 kb base), as cooler's zoomify does. Every bin size is a multiple of the base, so bins stay aligned to the base and each level holds exactly the counts re-binning the base would give, from far fewer pixels. A level is written into temp_dir, appended to the output and deleted right away — peak temporary disk use is one level, not a whole second pyramid. Its provenance names the base file, as if re-binned from it.

Resolutions are chosen one of two ways:

  • if resolutions is given, it is a cooler-style string ("1000,2000,5000", "1000N", "1000B", "4DN", …), expanded by :func:_parse_resolutions;
  • otherwise levels successive doublings of the base bin size are used.

The base resolution is always included and resolutions finer than the base are ignored. Every remaining resolution must be an exact multiple of the base bin size. Levels that would leave fewer than 2 bins, and levels that would be identical to an already-written one (once the bin size exceeds the longest contig, every contig collapses to a single bin), are skipped and reported in the log.

Parameters:

Name Type Description Default
uri str | Path

Path to the source .metacool file. Must be a standalone file; mmetacool entry URIs are not supported.

required
output str | Path

Destination path for the output .mmetacool file.

required
levels int

Number of doublings to use when resolutions is not given.

5
resolutions str | None

Optional cooler-style resolution string. Takes precedence over levels when provided.

None
temp_dir str | Path | None

Directory for the intermediate re-binned files. Defaults to the system temporary directory. Created if missing.

None
force bool

If True, overwrite output when it already exists.

False
nproc int

Levels built at once, each in its own process: with 1000,2000,5000,10000, 2 kb and 5 kb are built together, then 10 kb. Levels are appended in ladder order, so the output is that of nproc=1. A level's file is then kept in temp_dir until the levels coarsened from it are built.

1

Raises:

Type Description
FileExistsError

If output exists and force is False.

ValueError

If the input is not a fixed-bin metacooler, is an mmetacool entry URI, resolutions is malformed, or a requested resolution is not an exact multiple of the base bin size.

Source code in src/metacooler/ops/zoomify.py
def zoomify(
    uri: str | Path,
    output: str | Path,
    levels: int = 5,
    resolutions: str | None = None,
    temp_dir: str | Path | None = None,
    force: bool = False,
    nproc: int = 1,
) -> None:
    """Create a multi-resolution ``.mmetacool`` file.

    The input must be a fixed-bin metacooler.  Each resolution is stored as an
    mmetacool entry named ``entries/<binsize>`` (open it as
    ``file.mmetacool::entries/<binsize>``).  The base resolution is streamed
    verbatim into the output; every coarser resolution is produced by
    re-binning, with :func:`metacooler.ops.binnify.binnify`, the coarsest level
    already written whose bin size divides it (10 kb from 5 kb, 2 kb and 5 kb
    from a 1 kb base), as cooler's zoomify does.  Every bin size is a multiple
    of the base, so bins stay aligned to the base and each level holds exactly
    the counts re-binning the base would give, from far fewer pixels.  A level
    is written into *temp_dir*, appended to the output and deleted right away —
    peak temporary disk use is one level, not a whole second pyramid.  Its
    provenance names the base file, as if re-binned from it.

    Resolutions are chosen one of two ways:

    - if *resolutions* is given, it is a cooler-style string
      (``"1000,2000,5000"``, ``"1000N"``, ``"1000B"``, ``"4DN"``, …), expanded
      by :func:`_parse_resolutions`;
    - otherwise *levels* successive doublings of the base bin size are used.

    The base resolution is always included and resolutions finer than the base
    are ignored.  Every remaining resolution must be an exact multiple of the
    base bin size.  Levels that would leave fewer than 2 bins, and levels that
    would be identical to an already-written one (once the bin size exceeds the
    longest contig, every contig collapses to a single bin), are skipped and
    reported in the log.

    Args:
        uri: Path to the source ``.metacool`` file. Must be a standalone file;
            mmetacool entry URIs are not supported.
        output: Destination path for the output ``.mmetacool`` file.
        levels: Number of doublings to use when *resolutions* is not given.
        resolutions: Optional cooler-style resolution string. Takes precedence
            over *levels* when provided.
        temp_dir: Directory for the intermediate re-binned files. Defaults to
            the system temporary directory. Created if missing.
        force: If True, overwrite *output* when it already exists.
        nproc: Levels built at once, each in its own process: with
            ``1000,2000,5000,10000``, 2 kb and 5 kb are built together, then
            10 kb.  Levels are appended in ladder order, so the output is that
            of ``nproc=1``.  A level's file is then kept in *temp_dir* until
            the levels coarsened from it are built.

    Raises:
        FileExistsError: If *output* exists and *force* is False.
        ValueError: If the input is not a fixed-bin metacooler, is an
            mmetacool entry URI, *resolutions* is malformed, or a requested
            resolution is not an exact multiple of the base bin size.
    """
    from metacooler.api import MetaCooler
    from metacooler.io._utils import check_output_path
    from metacooler.io.mmetacool import add_entry, create_mmetacool
    from metacooler.ops.binnify import _binnify

    output = Path(output)
    check_output_path(output, force, inputs=[uri])

    mc = MetaCooler(uri)
    if mc._group_path not in ("/", ""):
        raise ValueError(
            "zoomify does not support mmetacool entry URIs (the base resolution is "
            "copied as a whole file). Extract the entry to a standalone .metacool "
            "first, then zoomify that file."
        )
    base_binsize = mc.binsize
    if base_binsize is None:
        raise ValueError(
            "Input must be a fixed-bin metacooler for zoomify. Got variable-bin input."
        )

    if mc.shape[0] < 2:
        raise ValueError("Input has fewer than 2 bins; cannot zoomify.")

    contig_lengths = mc.contigs["length"].to_numpy(dtype=np.int64)

    # Determine the target resolutions.
    if resolutions is not None:
        maxres = int(contig_lengths.max())
        requested = _parse_resolutions(resolutions, base_binsize, maxres)
    else:
        requested = [base_binsize * (2**i) for i in range(max(levels, 1))]

    below = sorted({r for r in requested if r < base_binsize})
    if below:
        logger.warning(
            "Ignoring resolutions finer than the base bin size %d: %s",
            base_binsize,
            below,
        )
    # Always include the base; keep only base-or-coarser; sort ascending.
    targets = sorted({base_binsize} | {r for r in requested if r >= base_binsize})
    _check_divisible(targets, base_binsize)

    # Predict the bin count of every level from the contig lengths, so that no
    # work is done for a level that is unusable or a duplicate of a coarser one.
    skipped: list[str] = []
    plan: list[int] = []
    collapsed_at: int | None = None
    for i, res in enumerate(targets):
        per_contig = _bins_per_contig(contig_lengths, res)
        if int(per_contig.sum()) < 2:
            skipped += [f"{r} (fewer than 2 bins)" for r in targets[i:]]
            break
        if collapsed_at is not None:
            skipped += [
                f"{r} (identical to resolution {collapsed_at}: one bin per contig)"
                for r in targets[i:]
            ]
            break
        plan.append(res)
        if bool((per_contig == 1).all()):
            collapsed_at = res
    if skipped:
        logger.warning("Skipping %d requested resolution(s): %s", len(skipped), skipped)

    if temp_dir is not None:
        temp_dir = Path(temp_dir)
        temp_dir.mkdir(parents=True, exist_ok=True)

    logger.info(
        "Creating mmetacool with %d resolution level(s): %s",
        len(plan),
        [str(r) for r in plan],
    )
    if nproc < 1:
        raise ValueError(f"nproc must be at least 1, got {nproc}")
    source_path = Path(mc._store)
    try:
        with tempfile.TemporaryDirectory(
            dir=None if temp_dir is None else str(temp_dir)
        ) as tmpdir:
            tmpdir_path = Path(tmpdir)
            if nproc > 1 and len(plan) > 2:
                _build_levels_in_parallel(
                    plan, source_path, mc.metadata, output, tmpdir_path, nproc, force
                )
                logger.info("Written multi-resolution mmetacool to %s", output)
                return
            built: list[int] = []
            for res in plan:
                if res == base_binsize:
                    # Base resolution: stream the source straight into the output.
                    create_mmetacool(output, {str(res): source_path}, force=force)
                    built.append(res)
                    continue
                # The coarsest level written so far that nests in this one; the
                # base always does (_check_divisible).
                parent = max(r for r in built if res % r == 0)
                parent_mc = (
                    mc
                    if parent == base_binsize
                    else MetaCooler(f"{output}::entries/{parent}")
                )
                res_path = tmpdir_path / f"res_{res}.metacool"
                logger.info("Coarsening %d -> %d", parent, res)
                _binnify(
                    parent_mc,
                    res_path,
                    res,
                    source_uri=source_path,
                    source_metadata=mc.metadata,
                )
                add_entry(output, str(res), res_path)
                built.append(res)
                # Reclaim the space before computing the next level.
                res_path.unlink(missing_ok=True)
    except Exception:
        # Never leave a half-built pyramid behind.
        if output.exists():
            output.unlink()
        raise

    logger.info("Written multi-resolution mmetacool to %s", output)

Visualisation

Visualization operations for metacool files.

show

show(
    uri: str | Path,
    level: Literal["bin", "contig", "genome"] = "genome",
    genomes: Sequence[str] | None = None,
    contigs: Sequence[str] | None = None,
    filters: Sequence[str] | None = None,
    range1: str | None = None,
    range2: str | None = None,
    transform: Literal["log1p", "log10", "none"] = "log1p",
    cmap: str = "afmhot_r",
    vmax: float | None = None,
    separators: bool = True,
    out: str | Path | None = None,
    dpi: int = 500,
    force: bool = False,
) -> None

Render a contact map heatmap.

There are two ways to choose what the axes show, and they cannot be combined:

  • genomes / contigs — a symmetric selection: every name goes on both axes, so the figure holds all the intra- and inter-block contacts between them, laid out in the order the names were given. This is uniform in the number of names: one name is that genome (or contig) against itself, and N names are all N against all N.
  • range1 / range2 — the asymmetric selection: a different region per axis, at bin level.

Both are honoured at every level: at level="genome" a genome is a single row/column, at "contig" it is its contigs, at "bin" its bins. A contigs selection has no meaning in genome id space, so it upgrades level="genome" to "contig"; likewise range1 implies level="bin".

Parameters:

Name Type Description Default
uri str | Path

Path to a .metacool file.

required
level Literal['bin', 'contig', 'genome']

Resolution level to display.

'genome'
genomes Sequence[str] | None

Genome names to put on both axes.

None
contigs Sequence[str] | None

Contig names to put on both axes.

None
filters Sequence[str] | None

--filter expressions (see :mod:metacooler.filters) that narrow genomes/contigs — or the whole file when neither is given. A contigs.* filter resolves the axes to contigs, just as contigs does. Cannot be combined with range1/range2.

None
range1 str | None

Row-dimension range: genome name, contig name, or contig:start-end. Implies level="bin" when set.

None
range2 str | None

Column-dimension range (defaults to range1 when omitted). Implies level="bin" when set.

None
transform Literal['log1p', 'log10', 'none']

Value transform (log1p, log10, or none).

'log1p'
cmap str

Matplotlib colormap name.

'afmhot_r'
vmax float | None

Upper bound for the colormap. Defaults to the 99th percentile of non-zero values in the (transformed) matrix.

None
separators bool

Draw lines at genome (or contig) boundaries.

True
out str | Path | None

Output file path (display interactively if None).

None
dpi int

DPI for the output image.

500
force bool

Overwrite out if it already exists.

False

Raises:

Type Description
ValueError

If level, transform or a name is unknown, if incompatible selection arguments are combined, or if the requested matrix is too large to materialise densely.

FileExistsError

If out exists and force is False.

Source code in src/metacooler/ops/show.py
def show(
    uri: str | Path,
    level: Literal["bin", "contig", "genome"] = "genome",
    genomes: Sequence[str] | None = None,
    contigs: Sequence[str] | None = None,
    filters: Sequence[str] | None = None,
    range1: str | None = None,
    range2: str | None = None,
    transform: Literal["log1p", "log10", "none"] = "log1p",
    cmap: str = "afmhot_r",
    vmax: float | None = None,
    separators: bool = True,
    out: str | Path | None = None,
    dpi: int = 500,
    force: bool = False,
) -> None:
    """Render a contact map heatmap.

    There are two ways to choose what the axes show, and they cannot be
    combined:

    * *genomes* / *contigs* — a **symmetric** selection: every name goes on
      **both** axes, so the figure holds all the intra- *and* inter-block
      contacts between them, laid out in the order the names were given.  This
      is uniform in the number of names: one name is that genome (or contig)
      against itself, and N names are all N against all N.
    * *range1* / *range2* — the **asymmetric** selection: a different region per
      axis, at bin level.

    Both are honoured at every *level*: at ``level="genome"`` a genome is a
    single row/column, at ``"contig"`` it is its contigs, at ``"bin"`` its bins.
    A *contigs* selection has no meaning in genome id space, so it upgrades
    ``level="genome"`` to ``"contig"``; likewise *range1* implies
    ``level="bin"``.

    Args:
        uri: Path to a ``.metacool`` file.
        level: Resolution level to display.
        genomes: Genome names to put on both axes.
        contigs: Contig names to put on both axes.
        filters: ``--filter`` expressions (see :mod:`metacooler.filters`) that
            narrow *genomes*/*contigs* — or the whole file when neither is
            given.  A ``contigs.*`` filter resolves the axes to contigs, just
            as *contigs* does.  Cannot be combined with *range1*/*range2*.
        range1: Row-dimension range: genome name, contig name, or
            ``contig:start-end``.  Implies ``level="bin"`` when set.
        range2: Column-dimension range (defaults to *range1* when omitted).
            Implies ``level="bin"`` when set.
        transform: Value transform (``log1p``, ``log10``, or ``none``).
        cmap: Matplotlib colormap name.
        vmax: Upper bound for the colormap. Defaults to the 99th percentile of
            non-zero values in the (transformed) matrix.
        separators: Draw lines at genome (or contig) boundaries.
        out: Output file path (display interactively if ``None``).
        dpi: DPI for the output image.
        force: Overwrite *out* if it already exists.

    Raises:
        ValueError: If *level*, *transform* or a name is unknown, if
            incompatible selection arguments are combined, or if the requested
            matrix is too large to materialise densely.
        FileExistsError: If *out* exists and *force* is False.
    """
    if level not in _LEVEL_NOUN:
        raise ValueError(f"Unknown level: {level!r}")
    if transform not in ("log1p", "log10", "none"):
        raise ValueError(f"Unknown transform: {transform!r}")

    mc = MetaCooler(uri)
    if (range1 is not None or range2 is not None) and (genomes or contigs or filters):
        raise ValueError(
            "--range/--range2 cannot be combined with --genomes, --contigs or "
            "--filter; they are two ways of selecting the same axes."
        )
    sel = _resolve_selection(mc, genomes, contigs, filters)

    # A selector that only makes sense at one level upgrades the level rather
    # than being silently dropped. Done here, not in the CLI, so the Python API
    # behaves identically.
    if range1 is not None and level != "bin":
        logger.info("--range implies --level bin; ignoring --level %s.", level)
        level = "bin"
    elif sel.kind == "contigs" and level == "genome":
        logger.info(
            "%s has no meaning at --level genome (a genome is one row/column, "
            "and part of it cannot be dropped); showing --level contig instead.",
            "--contigs" if contigs else "A contigs.* --filter",
        )
        level = "contig"

    if out is not None:
        check_output_path(out, force, inputs=[uri])
        matplotlib.use("Agg")

    panel = (
        _bin_panel(mc, sel, range1, range2)
        if level == "bin"
        else _aggregated_panel(mc, level, sel)
    )

    mat = _transform_matrix(panel.mat, transform)
    if vmax is None:
        nonzero = mat[mat > 0]
        vmax_val = float(np.percentile(nonzero, 99)) if nonzero.size > 0 else 1.0
    else:
        vmax_val = float(vmax)

    fig, ax = plt.subplots(figsize=(8, 8), dpi=dpi, layout="constrained")
    im = ax.imshow(
        mat,
        cmap=cmap,
        aspect="equal",
        interpolation="none",
        vmin=0,
        vmax=vmax_val,
    )
    ax.set_title(panel.title, fontsize=10)
    _apply_ticks(ax, panel.col, "x")
    _apply_ticks(ax, panel.row, "y")
    if separators:
        for pos in panel.row.seps:
            ax.axhline(pos, color=_SEP_COLOR, linewidth=_SEP_WIDTH)
        for pos in panel.col.seps:
            ax.axvline(pos, color=_SEP_COLOR, linewidth=_SEP_WIDTH)
        for pos in panel.row.group_seps:
            ax.axhline(pos, color=_GROUP_SEP_COLOR, linewidth=_GROUP_SEP_WIDTH)
        for pos in panel.col.group_seps:
            ax.axvline(pos, color=_GROUP_SEP_COLOR, linewidth=_GROUP_SEP_WIDTH)
    fig.colorbar(im, ax=ax, fraction=0.046, pad=0.04)

    if out:
        plt.savefig(out, dpi=dpi)
    else:
        plt.show()
    plt.close(fig)

Range resolution

Range resolution for metacooler region selectors.

Provides :func:parse_metacooler_range, which maps a range string to a half-open (bin_i0, bin_i1) interval. The range string may refer to:

  • a genome name — expands to all bins across every contig in that genome;
  • a contig name — expands to all bins in that contig;
  • a contig range (contig:start-end) — the bins that overlap the given base-pair interval (delegated to cooler.Cooler.extent).

parse_metacooler_range

parse_metacooler_range(mc: MetaCooler, range_str: str) -> tuple[int, int]

Resolve a range string to a (bin_i0, bin_i1) half-open interval.

Resolution order: 1. If the name (part before :) is a genome name, return 🇵🇾meth:MetaCooler.genome_extent. Any :start-end suffix is ignored — genome ranges are always whole-genome. 2. Otherwise treat the string as a contig (optionally with contig:start-end coordinates) and delegate to mc._clr.extent(), which reuses cooler's parse_region logic.

Parameters:

Name Type Description Default
mc MetaCooler

An open :class:~metacooler.api.MetaCooler instance.

required
range_str str

Range specifier, e.g. "MAG_1", "contig_A", or "contig_A:100-500".

required

Returns:

Type Description
tuple[int, int]

(bin_i0, bin_i1) half-open bin index interval.

Raises:

Type Description
ValueError

If the label (part before :) is neither a known genome nor a known contig.

Source code in src/metacooler/ops/range.py
def parse_metacooler_range(mc: MetaCooler, range_str: str) -> tuple[int, int]:
    """Resolve a range string to a ``(bin_i0, bin_i1)`` half-open interval.

    Resolution order:
    1. If the name (part before ``:``) is a **genome name**, return
       :py:meth:`MetaCooler.genome_extent`.  Any ``:start-end`` suffix is
       ignored — genome ranges are always whole-genome.
    2. Otherwise treat the string as a **contig** (optionally with
       ``contig:start-end`` coordinates) and delegate to
       ``mc._clr.extent()``, which reuses cooler's ``parse_region`` logic.

    Args:
        mc: An open :class:`~metacooler.api.MetaCooler` instance.
        range_str: Range specifier, e.g. ``"MAG_1"``, ``"contig_A"``, or
            ``"contig_A:100-500"``.

    Returns:
        ``(bin_i0, bin_i1)`` half-open bin index interval.

    Raises:
        ValueError: If the label (part before ``:``) is neither a known
            genome nor a known contig.
    """
    label = range_str.split(":")[0]

    # Membership through the name -> id maps the open file already holds: the
    # contig names are only listed in the error message, never scanned.
    is_genome = label in mc._genome_ids
    cid = mc._find_contig(label)

    # A coordinate suffix only makes sense on a contig, so when the label is
    # both (``binnify --level genome`` names each ligated contig after its
    # genome) the suffix decides: "G_a:1-6000" is a contig range, which used to
    # be refused because the genome branch was tried first.
    if ":" in range_str and cid is not None:
        return mc.extent(range_str)

    if is_genome:
        if ":" in range_str:
            raise ValueError(
                f"Range {range_str!r}: {label!r} is a genome name — coordinate "
                f"suffixes are not allowed for genome ranges. Use just {label!r}."
            )
        return mc.genome_extent(label)

    if cid is not None:
        # Delegate to cooler -- handles both "contig" and "contig:start-end"
        return mc.extent(range_str)

    def _truncate(names: list, limit: int = 20) -> str:
        if len(names) <= limit:
            return str(names)
        return str(names[:limit]) + f" ... ({len(names) - limit} more)"

    raise ValueError(
        f"Range {range_str!r}: {label!r} is not a known genome or contig.\n"
        f"  Genomes: {_truncate(mc.genomes['name'].tolist())}\n"
        f"  Contigs: {_truncate(mc.chromnames)}"
    )

Contact QC

Contact-quality statistics for a metacool file that already exists.

The classification itself lives in :mod:metacooler.qc; this module is the file-facing half — it opens a map, walks its pixel table in chunks, and optionally writes the result back.

What it measures is necessarily the binned map, so an intra-contig distance here is the gap between two bin midpoints. create pairs computes the same block from raw read positions while it is already reading the pairs file, and records source="pairs"; prefer that one when both exist.

QCResult

Bases: NamedTuple

What :func:qc computed.

Attributes:

Name Type Description
summary dict

The file-level block, as stored under metadata["qc"].

per_genome DataFrame

One row per genome, with the qc_* columns.

qc

qc(
    uri: str | Path,
    *,
    distance_threshold: int = DEFAULT_DISTANCE_THRESHOLD,
    chunksize: int = DEFAULT_CHUNKSIZE,
    store: bool = False,
) -> QCResult

Compute contact-quality statistics from a metacool file's pixel table.

Parameters:

Name Type Description Default
uri str | Path

file.metacool path or file.mmetacool::entries/name URI.

required
distance_threshold int

Intra-contig short/long split, in bp.

DEFAULT_DISTANCE_THRESHOLD
chunksize int

Pixels read per iteration.

DEFAULT_CHUNKSIZE
store bool

If True, write the result back into the file — metadata["qc"] plus the per-genome qc_* columns of /genomes and the per-contig ones of /contigs.

False

Returns:

Name Type Description
A QCResult

class:QCResult.

Raises:

Type Description
ValueError

If distance_threshold is negative.

OSError

If store is set and the file cannot be opened for writing.

Source code in src/metacooler/ops/qc.py
def qc(
    uri: str | Path,
    *,
    distance_threshold: int = DEFAULT_DISTANCE_THRESHOLD,
    chunksize: int = DEFAULT_CHUNKSIZE,
    store: bool = False,
) -> QCResult:
    """Compute contact-quality statistics from a metacool file's pixel table.

    Args:
        uri: ``file.metacool`` path or ``file.mmetacool::entries/name`` URI.
        distance_threshold: Intra-contig short/long split, in bp.
        chunksize: Pixels read per iteration.
        store: If ``True``, write the result back into the file —
            ``metadata["qc"]`` plus the per-genome ``qc_*`` columns of
            ``/genomes`` and the per-contig ones of ``/contigs``.

    Returns:
        A :class:`QCResult`.

    Raises:
        ValueError: If *distance_threshold* is negative.
        OSError: If *store* is set and the file cannot be opened for writing.
    """
    mc = MetaCooler(uri)
    genomes = mc.genomes
    contigs = mc.contigs
    tally = ContactQC(
        n_genomes=len(genomes),
        distance_threshold=distance_threshold,
        source="pixels",
        unbinned_genome=unbinned_genome_id(genomes["name"]),
        n_contigs=len(contigs) if store else None,
    )

    # cooler hands `binsize` back as whatever the attribute holds — a NumPy
    # integer normally, but a string on a file another tool wrote — and this is
    # both compared with an int and JSON-serialised below.
    binsize = mc.binsize
    binsize = None if binsize is None else int(binsize)
    if binsize is not None and binsize >= tally.distance_threshold:
        logger.warning(
            "Bin size (%d bp) is at least the short/long distance threshold "
            "(%d bp), so every intra-contig contact except the diagonal is "
            "reported as long-range. Re-run 'create pairs' (which measures "
            "distances between read positions) or lower --threshold to split "
            "the intra-contig signal meaningfully.",
            binsize,
            tally.distance_threshold,
        )

    n_pixels = tally_map(mc, tally, chunksize=chunksize)

    summary = tally.summary(binsize=binsize)
    per_genome = tally.genome_table(genomes["name"].to_numpy())
    logger.info(
        "QC over %d pixel(s): %s contacts, trans-contig ratio %s",
        n_pixels,
        f"{summary['n_contacts']:,}",
        summary["trans_contig_ratio"],
    )

    if store:
        from metacooler.io._utils import store_qc

        existing = mc.metadata.get(QC_METADATA_KEY)
        if isinstance(existing, dict) and existing.get("source") == "pairs":
            logger.warning(
                "Replacing a block measured on read positions with one measured "
                "between bin midpoints: the intra-contig short/long split will "
                "be coarser than the one 'create pairs' recorded.",
            )
        store_qc(
            mc.store,
            summary,
            per_genome,
            tally.contig_table(contigs["name"].to_numpy()),
            group_path=mc._group_path,
        )
        logger.info(
            "Stored QC block and per-genome and per-contig columns in %s", mc.uri
        )
    return QCResult(summary, per_genome)

qc is re-exported at the top level as metacooler.contact_qc — metacooler.qc is the tally module the writers share, not this function.

Contact probability P(s)

P(s) for a metacool file that already exists.

The grid, the accumulator, the denominators and the output table live in :mod:metacooler.ps; this module is the file-facing half — it opens a map, walks its pixel table (or re-reads a pairs file), and writes the result.

Two sources, one table:

  • pixels (default): what the map itself holds. Intra-contig distances are gaps between bin midpoints, so nothing below the bin size is resolvable.
  • pairs (--pairs): the original contacts, at base-pair resolution. The map is still needed — it supplies the contig→genome assignment, the contig lengths, and any --genomes/--contigs/--filter selection — but the curve is built from read positions, so it runs from 1 bp up.

contact_probability

contact_probability(
    uri: str | Path,
    *,
    pairs: str | Path | None = None,
    by: Literal["all", "genome"] = "all",
    genomes: Sequence[str] | None = None,
    contigs: Sequence[str] | None = None,
    filters: Sequence[str] | None = None,
    bins_per_decade: int = DEFAULT_BINS_PER_DECADE,
    min_distance: int | None = None,
    max_distance: int | None = None,
    chunksize: int = DEFAULT_CHUNKSIZE,
    pairs_kwargs: dict | None = None,
) -> pd.DataFrame

Compute P(s) from the intra-contig contacts of a metacool file.

Parameters:

Name Type Description Default
uri str | Path

file.metacool path or file.mmetacool::entries/name URI.

required
pairs str | Path | None

Optional pairs file to measure from instead of the pixel table (plain text, .gz, .bgz) — read through the very same streamer create pairs uses, so compression and column handling are identical. Gives base-pair distance resolution instead of bin resolution.

None
by Literal['all', 'genome']

"all" pools every selected contig into one curve; "genome" emits one curve per genome (MAG).

'all'
genomes Sequence[str] | None

Restrict to these genomes' contigs.

None
contigs Sequence[str] | None

Restrict to these contigs.

None
filters Sequence[str] | None

--filter expressions narrowing the selection further (see :mod:metacooler.filters).

None
bins_per_decade int

Log-grid resolution.

DEFAULT_BINS_PER_DECADE
min_distance int | None

Upper edge of the leading [0, min) bin, in bp. Defaults to 1 bp with pairs, and to the file's bin size (or the median bin width on a variable-width file) without, since nothing finer is resolvable there.

None
max_distance int | None

Largest separation to report, in bp. Defaults to the longest separation the selected contigs can offer.

None
chunksize int

Pixels (or pairs) read per iteration.

DEFAULT_CHUNKSIZE
pairs_kwargs dict | None

Extra keyword arguments for the pairs reader (column indices), as accepted by create pairs.

None

Returns:

Type Description
DataFrame

A long-format DataFrame with the :data:PS_COLUMNS columns, one row

DataFrame

per (genome, distance bin), sorted by genome then distance.

Raises:

Type Description
ValueError

If by is not a known grouping, or the selection is empty.

Source code in src/metacooler/ops/ps.py
def contact_probability(
    uri: str | Path,
    *,
    pairs: str | Path | None = None,
    by: Literal["all", "genome"] = "all",
    genomes: Sequence[str] | None = None,
    contigs: Sequence[str] | None = None,
    filters: Sequence[str] | None = None,
    bins_per_decade: int = DEFAULT_BINS_PER_DECADE,
    min_distance: int | None = None,
    max_distance: int | None = None,
    chunksize: int = DEFAULT_CHUNKSIZE,
    pairs_kwargs: dict | None = None,
) -> pd.DataFrame:
    """Compute P(s) from the intra-contig contacts of a metacool file.

    Args:
        uri: ``file.metacool`` path or ``file.mmetacool::entries/name`` URI.
        pairs: Optional pairs file to measure from instead of the pixel table
            (plain text, ``.gz``, ``.bgz``) — read through the very same
            streamer ``create pairs`` uses, so compression and column handling
            are identical.  Gives base-pair distance resolution instead of bin
            resolution.
        by: ``"all"`` pools every selected contig into one curve;
            ``"genome"`` emits one curve per genome (MAG).
        genomes: Restrict to these genomes' contigs.
        contigs: Restrict to these contigs.
        filters: ``--filter`` expressions narrowing the selection further
            (see :mod:`metacooler.filters`).
        bins_per_decade: Log-grid resolution.
        min_distance: Upper edge of the leading ``[0, min)`` bin, in bp.
            Defaults to 1 bp with *pairs*, and to the file's bin size (or the
            median bin width on a variable-width file) without, since nothing
            finer is resolvable there.
        max_distance: Largest separation to report, in bp.  Defaults to the
            longest separation the selected contigs can offer.
        chunksize: Pixels (or pairs) read per iteration.
        pairs_kwargs: Extra keyword arguments for the pairs reader (column
            indices), as accepted by ``create pairs``.

    Returns:
        A long-format DataFrame with the :data:`PS_COLUMNS` columns, one row
        per (genome, distance bin), sorted by genome then distance.

    Raises:
        ValueError: If *by* is not a known grouping, or the selection is empty.
    """
    mc = MetaCooler(uri)
    selection = _Selection(mc, by, genomes, contigs, filters)
    if pairs is not None:
        return _from_pairs_file(
            selection,
            Path(pairs),
            bins_per_decade=bins_per_decade,
            min_distance=min_distance,
            max_distance=max_distance,
            chunksize=chunksize,
            pairs_kwargs=pairs_kwargs or {},
        )
    return _from_pixels(
        selection,
        bins_per_decade=bins_per_decade,
        min_distance=min_distance,
        max_distance=max_distance,
        chunksize=chunksize,
    )

plot_ps

plot_ps(
    table: DataFrame,
    out: str | Path,
    *,
    value: str = "prob",
    title: str | None = None,
    dpi: int = 300,
    force: bool = False,
) -> None

Render a P(s) table as a log-log curve, one line per genome.

Parameters:

Name Type Description Default
table DataFrame

Output of :func:contact_probability.

required
out str | Path

Image path; the extension picks the format (.png, .pdf, .svg).

required
value str

Column to plot on the y axis — "prob" (unit-area normalised) or "avg_contacts" (raw rate per opportunity).

'prob'
title str | None

Figure title.

None
dpi int

Raster resolution.

300
force bool

Overwrite an existing file.

False

Raises:

Type Description
FileExistsError

If out exists and force is False.

ValueError

If value is not a column of table.

Source code in src/metacooler/ops/ps.py
def plot_ps(
    table: pd.DataFrame,
    out: str | Path,
    *,
    value: str = "prob",
    title: str | None = None,
    dpi: int = 300,
    force: bool = False,
) -> None:
    """Render a P(s) table as a log-log curve, one line per genome.

    Args:
        table: Output of :func:`contact_probability`.
        out: Image path; the extension picks the format (``.png``, ``.pdf``,
            ``.svg``).
        value: Column to plot on the y axis — ``"prob"`` (unit-area normalised)
            or ``"avg_contacts"`` (raw rate per opportunity).
        title: Figure title.
        dpi: Raster resolution.
        force: Overwrite an existing file.

    Raises:
        FileExistsError: If *out* exists and *force* is False.
        ValueError: If *value* is not a column of *table*.
    """
    import matplotlib

    matplotlib.use("Agg")
    import matplotlib.pyplot as plt

    if value not in table.columns:
        raise ValueError(f"{value!r} is not a column of the P(s) table.")
    check_output_path(out, force)

    groups = list(dict.fromkeys(table["genome"]))
    fig, ax = plt.subplots(figsize=(6, 4.5))
    handles: list = []
    labels: list[str] = []
    for name in groups:
        curve = table[table["genome"] == name]
        # A log axis cannot show a zero, and an empty distance bin is a gap in
        # the curve rather than a probability of zero.
        drawable = curve[(curve[value] > 0) & (curve["dist"] > 0)]
        if drawable.empty:
            continue
        (line,) = ax.plot(
            drawable["dist"], drawable[value], label=str(name), linewidth=1.2
        )
        handles.append(line)
        labels.append(str(name))

    ax.set_xscale("log")
    ax.set_yscale("log")
    ax.set_xlabel("Genomic distance (bp)")
    ax.set_ylabel("P(s)" if value == "prob" else "Mean contacts per opportunity")
    ax.set_title(title or "Contact probability vs genomic distance")
    if 1 < len(handles) <= _MAX_LEGEND_ENTRIES:
        # Handles are passed explicitly: matplotlib hides any label starting
        # with an underscore from an automatic legend, and ``__unbinned__`` —
        # the genome every unassigned contig lands in — is exactly that.
        ax.legend(handles, labels, fontsize="small", frameon=False)
    elif len(handles) > _MAX_LEGEND_ENTRIES:
        logger.info(
            "%d curves drawn without a legend (more than %d).",
            len(handles),
            _MAX_LEGEND_ENTRIES,
        )
    fig.tight_layout()
    fig.savefig(out, dpi=dpi)
    plt.close(fig)
    logger.info("Wrote P(s) plot to %s", out)