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_mappingmaps each bin id to a contig or genome id; - :func:
_write_aggregated_coolstreams 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 |
required |
output
|
str | Path
|
Destination path for the output |
required |
level
|
Literal['contig', 'genome']
|
Aggregation level — |
'contig'
|
count_col
|
str
|
Pixel column to use as contact count (default: |
'count'
|
chunksize
|
int
|
Number of pixels to process per chunk. |
DEFAULT_CHUNKSIZE
|
Source code in src/metacooler/ops/aggregate.py
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 |
required |
output
|
str | Path
|
Destination path for the output |
required |
binsize
|
int
|
New bin size in base pairs. |
required |
level
|
Literal['contig', 'genome']
|
Tiling level. |
'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
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 |
required |
output
|
str | Path
|
Destination path for the output |
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
|
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
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 | |
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 |
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
|
|
None
|
range1
|
str | None
|
Row-dimension range: genome name, contig name, or
|
None
|
range2
|
str | None
|
Column-dimension range (defaults to range1 when omitted).
Implies |
None
|
transform
|
Literal['log1p', 'log10', 'none']
|
Value transform ( |
'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
|
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
746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 | |
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 tocooler.Cooler.extent).
parse_metacooler_range ¶
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: |
required |
range_str
|
str
|
Range specifier, e.g. |
required |
Returns:
| Type | Description |
|---|---|
tuple[int, int]
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If the label (part before |
Source code in src/metacooler/ops/range.py
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 |
per_genome |
DataFrame
|
One row per genome, with the |
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
|
|
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 |
False
|
Returns:
| Name | Type | Description |
|---|---|---|
A |
QCResult
|
class: |
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
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/--filterselection — 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
|
|
required |
pairs
|
str | Path | None
|
Optional pairs file to measure from instead of the pixel table
(plain text, |
None
|
by
|
Literal['all', 'genome']
|
|
'all'
|
genomes
|
Sequence[str] | None
|
Restrict to these genomes' contigs. |
None
|
contigs
|
Sequence[str] | None
|
Restrict to these contigs. |
None
|
filters
|
Sequence[str] | None
|
|
None
|
bins_per_decade
|
int
|
Log-grid resolution. |
DEFAULT_BINS_PER_DECADE
|
min_distance
|
int | None
|
Upper edge of the leading |
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 |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
A long-format DataFrame with the :data: |
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
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: |
required |
out
|
str | Path
|
Image path; the extension picks the format ( |
required |
value
|
str
|
Column to plot on the y axis — |
'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. |