Multi-resolution files¶
metacooler supports two related operations for working at multiple resolutions:
binnify— re-bin a single.metacoolfile to a coarser resolution, producing a new.metacoolfile.zoomify— generate a pyramid of resolutions from a base-resolution.metacool, storing all levels in a single.mmetacoolcollection file.
Re-binning a single file (binnify)¶
# 1 kb source → 5 kb output (5000 = 5 × 1000 ✓)
metacooler binnify sample.metacool \
--binsize 5000 \
--output sample_5kb.metacool
Contacts are reassigned to new bins using midpoint assignment.
The target bin size is not arbitrary
For a fixed-bin source, --binsize must be a strict, exact multiple
of the current bin size. From a 1 kb file, the valid targets are 2000, 3000,
4000, 5000, … — --binsize 3500 is now rejected:
$ metacooler binnify sample_1kb.metacool --binsize 3500 -o out.metacool
Error: New binsize (3500) must be an exact multiple of the source binsize
(1000) — 3500 % 1000 = 500. […] Nearest valid multiples: 3000 and 4000.
Older versions accepted this. The midpoint rule then packed an oscillating number of source bins into each output bin (1 kb → 3.5 kb alternates 3 and 4 source bins, a built-in ±14 % checkerboard) while the file advertised a uniform 3500 bp bin size. If you produced such a file, re-bin from the base resolution to a valid multiple.
For a variable-bin source (restriction fragments, contig-level files)
there is no exact multiple to check, so the median source bin width is the
effective resolution: --binsize must be strictly larger than it. A target
between the median and the widest source bin is accepted with a warning —
those widest bins each collapse into one output bin, so the effective
resolution is uneven across the file. Re-binning such a file to a finer
size is refused outright (it used to be accepted and left almost every
output bin empty).
# Also works at genome level (contigs ligated within each genome, longest first)
metacooler binnify sample.metacool --binsize 10000 --level genome -o sample_10kb_genome.metacool
# --chunksize bounds the peak memory of the pixel remapping pass
metacooler binnify sample.metacool --binsize 5000 --chunksize 200000 -o sample_5kb.metacool
Creating a multi-resolution collection (zoomify)¶
zoomify takes a base-resolution .metacool and creates a .mmetacool file
with multiple resolution levels, each doubling the bin size:
This produces:
sample_multireso.mmetacool
└── /entries
├── 1000 ← base resolution (copied from sample.metacool)
├── 2000
├── 4000
├── 8000
└── 16000
Generation stops early: a level that would leave fewer than 2 bins, or that would duplicate an already-written level (once the bin size exceeds the longest contig, every contig collapses to a single bin), is skipped and reported in the log rather than computed and thrown away.
Choosing resolutions explicitly¶
-r/--resolutions uses cooler's own ladder-token grammar — deliberately
not the plain comma list taken by --genomes/--contigs elsewhere in the
CLI, so that metacooler zoomify and cooler zoomify stay interchangeable:
| Form | Meaning |
|---|---|
1000,2000,5000 |
An explicit list. |
1000N |
"Nice" 1-2-5 progression from 1000. |
1000B |
Binary ×2 progression from 1000. |
N / B |
The same, starting from the base bin size. |
4DN |
The 4DN standard ladder (1000,2000,5000N). |
Every level must nest in the base bin size
A requested resolution that is not an exact multiple of the base is
rejected — the pyramid is built by re-binning the base, so a level that does
not nest in it would not be self-consistent. With a 1 kb base,
--resolutions 1500,3000 fails; the message names the nearest valid
resolution. Be careful with N-style tokens against a non-1 kb base: with a
4 kb base, 1000N expands to 5000/10000/20000/50000 — not one of which is a
multiple of 4000.
Controlling temporary disk¶
Each level is written to a temporary directory, appended to the output, and
deleted immediately, so peak scratch use is one level rather than a second copy
of the whole pyramid. Point --temp-dir at fast local scratch on a cluster:
metacooler zoomify sample.metacool --levels 5 \
--temp-dir /scratch/$USER \
-o sample_multireso.mmetacool
Working with collection files¶
# List all resolution levels
metacooler ls sample_multireso.mmetacool
# sample_multireso.mmetacool::entries/1000
# sample_multireso.mmetacool::entries/2000
# ...
# Inspect a specific resolution
metacooler info sample_multireso.mmetacool::entries/4000
Open a specific resolution in Python:
Managing collection entries¶
# Add an existing metacool file as a new entry
metacooler stack sample_5kb.metacool sample_10kb.metacool \
--names "5kb,10kb" \
-o multi.mmetacool
# Copy an entry
metacooler cp multi.mmetacool::entries/5kb multi.mmetacool::entries/5kb_backup
# Rename an entry
metacooler mv multi.mmetacool::entries/5kb_backup multi.mmetacool::entries/5kb_v2
# Remove an entry
metacooler rm multi.mmetacool::entries/5kb_v2
# Cross-file copy
metacooler cp source.mmetacool::entries/rep1 target.mmetacool::entries/rep1
Python API¶
binnify and zoomify are exported from the package root:
import metacooler
# Re-bin (binsize must be an exact multiple of the source bin size)
metacooler.binnify(
"sample.metacool", output="sample_5kb.metacool", binsize=5000, chunksize=1_000_000
)
# Zoomify
metacooler.zoomify(
"sample.metacool",
output="sample_multireso.mmetacool",
levels=5,
temp_dir="/scratch/tmp",
)
# Inspect collection
entries = metacooler.list_entries("sample_multireso.mmetacool")
print(entries) # ['1000', '2000', '4000', ...]
Viewing in HiGlass¶
HiGlass reads multi-resolution coolers laid out as /resolutions/<binsize>
(.mcool). The .mmetacool that metacooler zoomify writes stores its levels
under /entries/<binsize> instead, so HiGlass cannot ingest it directly. Since
every .metacool is also a valid cooler, cooler's own zoomify produces an
.mcool from it:
The result is a plain .mcool: contigs are its chromosomes, and the genome
layer is not carried over.