metacooler: Hi-C contact maps for metagenomes
An extension of the cooler format for multi-genome (metagenomic) Hi-C data. metacooler adds a genomes/ hierarchy on top of cooler’s chroms/bins/pixels model, while preserving full backward compatibility: any .metacool file can be opened with cooler.Cooler() out of the box.
metacooler builds on cooler to provide a framework for storing and analysing metagenomic contact maps: every .metacool file is also a valid cooler, so cooler, cooltools and the rest of the ecosystem keep working on it.
Installation
pip install metacooler
For development, clone the repository and run uv sync, which installs the runtime dependencies plus the dev dependency group (pytest, ruff, ty, pre-commit).
Quick start
metacooler create pairs --help
metacooler create pairs \
--bins fragments.bed \
--contigs contigs2mag.tsv \
--pairs contacts.pairs \
--output output.metacool \
--genomes mag_table.tsv ## <-- Optional
metacooler info output.metacool
metacooler dump -t genomes output.metacool
metacooler aggregate --level genome output.metacool -o genome.cool
metacooler show output.metacool --level genome -o heatmap.png
metacooler qc output.metacool --table
metacooler ps output.metacool --pairs contacts.pairs --by genome --plot ps.png
Every command takes its input as a positional path (or an file.mmetacool::entries/<name> URI), and shares -o/--output, -f/--force, -v/--verbose, and -q/--quiet.
Usage: metacooler create pairs [OPTIONS]
Create a metacool file from pairs and contig assignments.
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ * --pairs Pairs file (plain text or gzipped). [required] │
│ * --bins BED file of bins (without column names), or an │
│ integer bin size in bp (e.g. 1000). If an │
│ integer, contig lengths must be available from │
│ the pairs header or a --fasta should be │
│ provided. [required] │
│ * --output -o Output .metacool file path. [required] │
│ * --contigs Contig-to-genome assignment table. The expected │
│ layout depends on --contigs-format. [required] │
│ --contigs-format Format of the contig assignment table. Four │
│ formats are supported: [default: contigs] │
│ - contigs: TSV with a header row. Column 1 must │
│ be named `contig_name` and column 2 │
│ `genome_name`. Additional columns are stored │
│ verbatim. │
│ - contig_genome: Two-column TSV │
│ (`contig<TAB>genome`) with no header. First │
│ value is contig name, second is genome │
│ assignment. │
│ - metator: MetaTOR output table (ie │
│ `contig_data_final.txt`). Expects a header with │
│ columns `Name` (contig) and `Final_bin` │
│ (genome). Other columns ignored. │
│ - I,J(,noheader): Column-index spec (1-based). │
│ Use column `I` for contigs and `J` for genomes. │
│ Header expected by default. Append `,noheader` │
│ (e.g., `1,5,noheader`) to treat the first row │
│ as data. │
│ --genomes Optional genomes metadata table with header. │
│ First column must be 'genome_name'; any further │
│ columns are stored in the /genomes table. │
│ --filter Keep only rows matching <table>.<column> <op> │
│ <value>, where <table> is genomes or contigs — │
│ e.g. --filter 'genomes.length > 1Mb'. │
│ Operators: > >= < <= == != =~ !~ (=~ is a regex │
│ match). Numbers accept bp/kb/Mb/Gb suffixes. │
│ Repeat the option to require several conditions │
│ at once. │
│ --metadata Path to a JSON or YAML file containing metadata │
│ to ingest into the file. │
│ --qc/--no-qc Tally contact-quality statistics during │
│ creation and store them in metadata.qc and the │
│ /genomes qc_* columns. Read them back with │
│ metacooler qc. [default: qc] │
│ --qc-threshold Distance splitting short- from long-range │
│ intra-contig signal. Accepts bp/kb/Mb/Gb │
│ suffixes. [default: 10000] │
│ --force -f Overwrite output file if it already exists. │
│ --verbose -v Increase verbosity (debug logging). │
│ --quiet -q Suppress informational logging (warnings and │
│ errors still shown). │
│ --contig-order Strategy for ordering contigs in the output │
│ metacool file. │
│ - genome-then-length: group by genome, │
│ longest-first within each genome. │
│ - genome-then-alpha: group by genome, │
│ alphabetical within each genome. │
│ - fasta: preserve order from the input FASTA │
│ (or pairs header). │
│ - alpha: sort all contigs alphabetically. │
│ [default: genome-then-length] │
│ --fasta Assembly FASTA. Used to extract contig lengths │
│ when --bins is an integer and contig sizes are │
│ absent from the pairs header. │
│ --assembly-name Name for this assembly / metagenome. │
│ --drop-unassigned Drop contigs not assigned to any genome. │
│ --chunksize Number of pairs to process per chunk. This is │
│ chunk granularity, not read memory (the pyarrow │
│ read block is capped separately). Under │
│ 'external' sorting each chunk is written as a │
│ temporary cooler at a fixed per-call cost that │
│ scales with contig count, so smaller chunks │
│ cost disproportionately more. [default: │
│ 50000000] │
│ --ps/--no-ps Accumulate a per-MAG P(s) curve from the same │
│ pass over the pairs and write it beside the │
│ output as <output>.ps.tsv. Measured on read │
│ positions, so it resolves distances the binned │
│ map cannot. No plot is drawn — pass the table │
│ to metacooler ps or your own plotting. │
│ [default: ps] │
│ --ps-bins-per-decade Number of log-spaced distance bins per decade │
│ in the P(s) table. [default: 10] │
│ --sort-strategy Pixel sorting strategy. 'auto': use 'memory' │
│ unless the binned pixels exceed 100 M rows. │
│ 'memory': collect all pixels in RAM and sort │
│ before writing (fast for small files). │
│ 'external': stream unsorted pixels to cooler's │
│ external sort (scalable for large files). │
│ [default: auto] │
│ --help -h Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
Input files
Bins file: BED-like file with chrom, start, end columns defining the genomic bins.
- Can be generated from a FASTA assembly with
cooler makebinsto get fixed-size bins - Can be generated from a FASTA assembly with
cooler digestto get restriction fragments. - Otherwise an arbitrary resolution can be used by specifying
--bins 1000for 1kb bins, etc.
contig_1_000 0 721
contig_1_000 721 747
contig_1_000 747 767
contig_1_000 767 1013
contig_1_000 1013 1099
...
contig_1_043 8869 8959
contig_1_043 8959 9000
Contig-genome map: TSV file mapping contigs to genomes (MAGs). This is used to populate the contigs table and map contigs to genomes. Must be either:
- A two-column file with NO HEADER: first column is treated as contig name, second column as genome/MAG name.
- A TSV file with header, whose first column is
contig_nameand second columngenome_name. Additional metadata columns will be stored in thecontigs/table.
contig_name genome_name gc_content coverage
contig_1_000 MAG_04 0.51 99.40
contig_1_001 MAG_02 0.59 75.43
contig_1_002 MAG_04 0.45 8.81
contig_1_003 __unbinned__ 0.52 8.28
...
contig_1_042 MAG_05 0.52 18.45
contig_1_043 MAG_05 0.42 97.78
Pairs file: 4DN-compliant tab-delimited file with readID, chrom1, pos1, chrom2, pos2, strand1, strand2 columns defining the Hi-C contacts. Can be generated from raw FASTQ reads with metator pipeline.
#pairs format v1.0
#sorted: chr1-chr2-pos1-pos2
#shape: upper triangle
#genome_assembly: synthetic_assembly_1
#chromsize: contig_1_000 18000
#chromsize: contig_1_001 12000
#chromsize: contig_1_002 3000
#chromsize: contig_1_003 6000
...
#columns: readID chrom1 pos1 chrom2 pos2 strand1 strand2
read_0 contig_1_007 41718 contig_1_006 6634 + +
read_1 contig_1_037 2208 contig_1_000 12785 + +
read_2 contig_1_003 5884 contig_1_028 2231 + +
read_3 contig_1_014 3164 contig_1_021 47093 + +
read_4 contig_1_008 138 contig_1_038 6042 + +
...
[Optional] Genomes table: TSV file with at least a column named genome_name, and optional metadata columns describing the genomes/MAGs.
genome_name phylum completeness contamination quality
MAG_02 Firmicutes 0.92 0.14 low
MAG_03 Proteobacteria 0.73 0.03 low
MAG_01 Bacteroidetes 0.63 0.10 high
MAG_04 Firmicutes 0.99 0.24 medium
...
MAG_09 Proteobacteria 0.95 0.04 low
MAG_05 Proteobacteria 0.89 0.27 high
[Optional] Metadata file: a YAML/JSON file with additional metadata.
sample:
name: gut_microbiome_T0
description: This is a gut microbiome sample at time point 0
organism: human gut metagenome
enzyme: HpaII
enzyme_site: "C^CGG"
sequencing:
platform: Illumina NovaSeq 6000
read_length: 150
n_read_pairs: 245000000
n_valid_pairs: 180000000
assembly:
name: gut_microbiome_T0_assembly.fa
description: metagenome assembly for the gut microbiome sample at time point 0
assembler: MEGAHIT v1.2.9
assembly_date: 2024-06-01
assembly_stats:
total_length: 3500000
n_contigs: 120
n50: 50000
Design
- Metacool identity:
metacooler-format="HDF5::MetaCooler"attribute +genomes/group - Implement genomes table:
name,length,n_contigs,n_bins, plus optional metadata columns - Support multi-contigs and multi-genomes visualization:
showcommand at--level bin/contig/genome - Report contact quality: the 3D ratio and its intra-contig / intra-MAG / inter-MAG breakdown, tallied at creation time into
metadata.qcand per-MAG/genomescolumns, recomputable withqc - Export P(s): contact probability vs genomic distance, pooled or per MAG, as a table and a log-log plot (
ps).create pairswrites the per-MAG curve at base-pair resolution beside the output as<output>.ps.tsv - Cooler compatibility: soft link
chroms → contigs,format="HDF5::Cooler", standardindexes/chrom_offset - Canonical contig ordering: configurable (
genome-then-length,genome-then-alpha,fasta,alpha;coolforcreate cool) - Unassigned contigs: default to
__unbinned__genome - Re-attributable bins:
reassignswaps in a new contig-to-genome table on an existing file — the/genomestable and the contig layout are rebuilt, the contacts are not recomputed - Multi-resolution:
binnify(exact multiples of the source bin size only) andzoomify→ a.mmetacoolcollection
Releasing
Changelog entries for in-progress work go under ## Unreleased in docs/changelog.md as they land on devel. To cut a release:
uv run bump-my-version bump minor # or patch / major
git push --follow-tags
bump-my-version (configured in pyproject.toml) promotes ## Unreleased to a dated ## X.Y.Z - YYYY-MM-DD section, bumps __version__ in src/metacooler/_version.py — the single source of truth for the package version — and commits and tags the result, all in one step. Pushing the tag triggers release.yml: it builds the sdist/wheel, fails if the tag doesn’t match __version__, publishes to PyPI via trusted publishing (no stored token), and opens a GitHub release with that version’s changelog section and the built artifacts attached. docs.yml redeploys the documentation site on the same tag.
Metadata
Release files for metacooler 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| metacooler-0.2.0.tar.gz | 2.3 MB | With provenance | Details for metacooler-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| metacooler-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for metacooler-0.2.0-py3-none-any.whl |
Total release size: 2.6 MB
Release files / metacooler-0.2.0.tar.gz
| Download URL | metacooler-0.2.0.tar.gz |
|---|---|
| Size | 2.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b0b165fe0cd3dd2b204dca17c9489e30c61f4a6069cdbb927190bd011eb736cf
|
|
BLAKE2b-256 checksum How to use checksums |
cc5faf42e1054e020b30f0bbf0123eb3932d6ffda9e694b204b2051f0a7de98d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / metacooler-0.2.0-py3-none-any.whl
| Download URL | metacooler-0.2.0-py3-none-any.whl |
|---|---|
| Size | 275.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9dc1f49e9a4dddd3f43a29859c1f902609aa39b71bfd5bba1c60fa0fa630a75
|
|
BLAKE2b-256 checksum How to use checksums |
2d5819dba990235ad512a5058ba4df00d2d1a41c81a18bfe67e56357f5aca29c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for metacooler 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for metacooler-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.