Why metacooler?¶
Metagenomic Hi-C binning tools such as MetaTOR and bin3C produce per-contig contact maps across dozens or hundreds of MAGs simultaneously. Standard cooler files have no concept of genome identity — contigs from different MAGs appear as independent "chromosomes" with no shared metadata.
What metacooler adds¶
metacooler solves this by:
- Storing a
/genomestable linking contigs to MAGs, with optional quality metadata (completeness, contamination, taxonomy…). - Computing genome-level and contig-level aggregated contact matrices without re-creating the file.
- Recording contact-quality statistics — the 3D ratio, and how much signal is intra-contig, intra-MAG and inter-MAG — at creation time, per file and per MAG, plus P(s) curves for judging the library itself.
- Providing a
/contigstable as the canonical chromosome table, with a soft link at/chromsso cooler compatibility is transparent. - Offering a collection format (
.mmetacool) to group multiple assemblies, samples, or resolutions in a single file.
See Concepts for the full data model.
A quick look¶
# Create from MetaTOR output
metacooler create pairs \
--pairs contacts.pairs.gz \
--bins fragments.bed \
--contigs contig_data_final.txt --contigs-format metator \
--genomes mag_table.tsv \
-o gut_T0.metacool
# Inspect
metacooler info gut_T0.metacool
# Contact quality: the 3D ratio and its breakdown
metacooler qc gut_T0.metacool --table
# P(s), one curve per MAG — create pairs already wrote gut_T0.ps.tsv at
# base-pair resolution; this re-reads it from the binned map, or from the
# original pairs with --pairs
metacooler ps gut_T0.metacool --by genome --plot ps.png
# Genome-level heatmap
metacooler show gut_T0.metacool --level genome -o heatmap.png
# Export one MAG as a standard cool file
metacooler extract gut_T0.metacool --genomes MAG_01 -o MAG_01.cool
The Quickstart walks through the same session step by step.
Compatibility¶
| Tool | Compatibility |
|---|---|
cooler.Cooler() |
✅ Full — reads .metacool as a standard cooler |
| cooltools | ✅ Works on files produced by metacooler extract or aggregate |
| HiGlass | ✅ Via cooler zoomify on a .metacool (or an exported .cool), which writes the multi-resolution .mcool HiGlass ingests — see Multi-resolution files |
| pairtools | ✅ Pairs files are the primary input format |
| MetaTOR | ✅ Native support via --contigs-format metator |
How a single file can be both a cooler and a metacooler is explained in Cooler compatibility.
Where next¶
| If you want to… | Go to |
|---|---|
| Install the package | Installation |
| Follow an end-to-end example | Quickstart |
| Understand the data model | Concepts |
| Build a file from pairs or a cooler | Creating from pairs, from a cooler |
| Combine one cooler per genome into one file | Collecting single-genome cools |
| Get data back out | Exporting data |
| Work at multiple resolutions | Multi-resolution files |
| Look up a command | CLI reference |
| Call metacooler from Python | Python API |
| Read the on-disk format | Format specification |