Collecting single-genome cool files¶
If you already have one .cool file per genome — isolates of a mock community,
reference strains, maps downloaded one species at a time — metacooler collect
zips them into a single .metacool file, one genome per input. There is no
contig-to-genome table to write: the file a contig comes from is its genome.
Basic usage¶
$ metacooler dump -t genomes -H species.metacool | cut -f1-4
name length n_contigs n_bins
B_subtilis 4215000 1 4215
E_coli 4705000 2 4705
S_aureus 2849000 2 2849
Genome rows are always alphabetical: that order defines the genome_id integers
of the format, whatever order the inputs were given in.
Naming¶
Each genome is named after its input's file stem (E_coli.cool → E_coli).
Give explicit names with --names, one per input and in the same order:
metacooler collect run1/sample.cool run2/sample.cool \
--names Escherichia_coli,Bacillus_subtilis \
-o species.metacool
Every contig is then renamed <genome>__<contig>. Assemblies routinely reuse
the same contig names — chromosome, plasmid1, contig_1, 1 — but a
metacool file needs them unique, so the prefix is applied to every contig of
every input, whether or not it clashes. That keeps each genome's names the same
whichever other genomes it is collected with:
$ metacooler dump -t contigs -H species.metacool | cut -f1-3
name length genome
B_subtilis__chromosome 4215000 B_subtilis
E_coli__chromosome 4640000 E_coli
E_coli__plasmid1 65000 E_coli
S_aureus__chromosome 2821000 S_aureus
S_aureus__plasmid1 28000 S_aureus
The new names are what every other command expects: --contigs
E_coli__plasmid1, -r E_coli__chromosome:1000000-2000000, --filter
"contigs.name =~ plasmid".
Resolution¶
A metacool file has a single bin table, so every input must share one bin size — or all have variable, restriction-fragment bins. Inputs binned differently are refused with the resolution of each. From multi-resolution files, pick the same resolution from each with cooler's URI syntax:
metacooler collect \
E_coli.mcool::resolutions/5000 B_subtilis.mcool::resolutions/5000 \
-o species_5kb.metacool
Adding metadata¶
Three optional inputs decorate the collection:
--genomes: one row per genome, first columngenome_name, matched against the genome names; every other column (taxonomy, completeness, growth condition…) lands in/genomes.--contigs: one row per contig, first columncontig_name; every other column lands in/contigs. A contig may be named as in its input cool (chromosome) or as collected (E_coli__chromosome), and agenome_namecolumn says which genome a shared name belongs to. See The contigs table.--metadata: a JSON or YAML file of free-form metadata.
metacooler collect *.cool \
--genomes species.tsv \
--contigs contig_coverage.tsv \
--metadata study.yaml \
-o species.metacool
--filter works as in create, before anything is written, and can use any
column those tables add — and, unlike in create, genomes.n_bins:
metacooler collect *.cool --genomes species.tsv \
--filter "genomes.completeness > 90" --filter "contigs.length >= 5kb" \
-o species.metacool
What the collected map is — and is not¶
Every input was binned on its own, usually from its own library, so no contact between two inputs was ever observed. The collected map has empty inter-genome blocks: it is a block-diagonal stack of the inputs, not the map you would get by aligning one metagenomic library to the combined assembly (for that, see Creating from pairs). Each genome also keeps its own sequencing depth, so compare genomes with that in mind.
Within those limits, nothing is lost. Under the default --contig-order cool,
contigs keep each input's own order and extracting a genome gives back its
input, bin for bin and pixel for pixel — only the contig names carry the
prefix:
That layout is also what makes collect fast: each input is one contiguous
block of bins, its pixels only move within that block, and under cool the
whole collection is streamed into place without sorting anything.
--contig-order genome-then-length (longest contig first, as create does by
default) and genome-then-alpha re-sort only the inputs whose contigs they
actually move, one at a time.
Python API¶
import metacooler
metacooler.collect(
["E_coli.cool", "B_subtilis.mcool::resolutions/5000"],
"species.metacool",
names=["E_coli", "B_subtilis"], # optional; defaults to file stems
genomes_table="species.tsv", # optional
contigs_table="contig_coverage.tsv", # optional
contig_ordering="cool", # or "genome-then-length", ...
)
Compared with the other creation paths¶
| Aspect | create pairs |
create cool |
collect |
|---|---|---|---|
| Input | one .pairs file |
one .cool file |
one .cool per genome |
| Genome assignment | contig table | contig table | the input file |
| Contig names | unchanged | unchanged | <genome>__<contig> |
| Inter-genome contacts | as observed | as observed | none |
| Default contig order | genome-then-length |
genome-then-length |
cool (each input's own) |