Quickstart¶
This guide takes you from raw MetaTOR output to a genome-level contact heatmap in five commands.
Input files¶
You need three files (a fourth is optional):
| File | Description |
|---|---|
contacts.pairs.gz |
4DN-compliant pairs file — contacts between contig positions |
fragments.bed |
BED file of bins (restriction fragments or fixed-size windows) |
contig_data_final.txt |
MetaTOR contig-to-MAG assignment table |
mag_table.tsv |
(optional) MAG metadata (completeness, taxonomy…) |
Generating input files
Pairs files can be produced from raw FASTQ reads with
metator pipeline or
pairtools.
Bin BED files can be generated with cooler makebins (fixed-size) or
cooler digest (restriction fragments).
Step 1 — Create a metacool file¶
metacooler create pairs \
--pairs contacts.pairs.gz \
--bins fragments.bed \
--contigs contig_data_final.txt --contigs-format metator \
--genomes mag_table.tsv \
--output gut_T0.metacool
This streams the pairs file in chunks, bins contacts, and writes an HDF5 file
with the full metacooler schema. The --contigs-format metator flag tells
metacooler to look for Name and Final_bin columns in the contig table.
No MetaTOR?
If your contig table is a simple two-column TSV with no header
(contig_name<TAB>genome_name), use --contigs-format contig_genome instead.
See the Creating from pairs guide for all supported formats.
Step 2 — Inspect the file¶
{
"bin-size": 2000,
"bin-type": "fixed",
"creation-date": "2026-05-12T09:41:00+00:00",
"format": "HDF5::MetaCooler",
"format-url": "https://github.com/js2264/metacooler",
"format-version": 1,
"generated-by": "metacooler-0.1.0",
"assembly": "unknown",
"nbins": 48291,
"ncontigs": 1203,
"ngenomes": 47,
"nnz": 2847193,
"sum": 18043712,
"storage-mode": "symmetric-upper",
"ordering": "genome-then-length"
}
The assembly field is the standard cooler genome-assembly attribute; it
reads "unknown" unless you passed --assembly-name at creation time.
# Rich table format
metacooler info gut_T0.metacool --table
# Inspect the HDF5 hierarchy
metacooler tree gut_T0.metacool
Two more commands judge the library itself: qc reports where its contacts
land, and ps plots contact probability against genomic distance. (create
pairs already recorded both at read resolution while it binned the pairs: the
QC block in the file's metadata, the P(s) table beside it as gut_T0.ps.tsv.)
# 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
See qc for what each contact category means, and
ps for the curve options.
Step 3 — Browse tables¶
# List all genomes / MAGs
metacooler dump gut_T0.metacool -t genomes -H
# List contigs belonging to a specific MAG
metacooler dump gut_T0.metacool -t contigs --genomes MAG_01 -H
Step 4 — Visualise the contact map¶
# Genome-level heatmap (default level). The input path is positional, like
# every other command; -o is the output image.
metacooler show gut_T0.metacool --level genome -o genome_heatmap.png
# Intra-genome heatmap at bin resolution
metacooler show gut_T0.metacool --level bin --genomes MAG_01 -o MAG_01_heatmap.png
# Several genomes: every name goes on both axes, so you get all the intra- and
# inter-genome blocks between them
metacooler show gut_T0.metacool --level contig --genomes MAG_01,MAG_02 -o pair.png
# A specific genomic range (implies --level bin)
metacooler show gut_T0.metacool -r contig_0_0:0-50000 -o range.png
# Re-render over an existing image: -f is --force (it used to mean --file)
metacooler show gut_T0.metacool --level genome -f -o genome_heatmap.png
Step 5 — Export for downstream tools¶
# Aggregate to genome level → standard .cool (works with cooltools, HiGlass)
metacooler aggregate gut_T0.metacool --level genome -o genome_level.cool
# Extract one MAG as a standalone cool file
metacooler extract gut_T0.metacool --genomes MAG_01 -o MAG_01.cool
# Export the genome-level network edge list
metacooler network gut_T0.metacool --level genome -o genome_network.tsv
Python API equivalent¶
The same workflow from Python:
import metacooler
# Create
metacooler.from_pairs(
uri="gut_T0.metacool",
pairs="contacts.pairs.gz",
bins="fragments.bed",
contig_genome_map="contig_data_final.txt",
contig_table_format="metator",
genomes_table="mag_table.tsv",
)
# Open and explore
mc = metacooler.MetaCooler("gut_T0.metacool")
print(mc.info)
print(mc.genomes)
print(mc.contigs.head())
# Genome-level contact map: write a standard cooler, then read it back
mc.to_cooler("genome_level.cool", level="genome")
# Bins for a specific MAG
bins = mc.bins_for_genome("MAG_01")
# Every operation is also a top-level function
metacooler.extract("gut_T0.metacool", output="MAG_01.cool", genomes=["MAG_01"])
metacooler.network("gut_T0.metacool", out="genome_network.tsv", level="genome")
What an open checks
MetaCooler() checks the file's structure on every construction (format
attributes, groups, columns, offset index lengths and endpoints), which
costs milliseconds at any size. The full O(n_bins) check is
metacooler check / metacooler.schema.validate(), which every
metacooler writer also runs on its output. validate=False skips even the
structural checks — use it only on a file you know to be well-formed: