metacooler 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- metacooler-0.2.0/.gitignore +89 -0
- metacooler-0.2.0/LICENSE +21 -0
- metacooler-0.2.0/PKG-INFO +296 -0
- metacooler-0.2.0/README.md +257 -0
- metacooler-0.2.0/README.qmd +178 -0
- metacooler-0.2.0/benchmarks/.gitignore +9 -0
- metacooler-0.2.0/benchmarks/README.md +84 -0
- metacooler-0.2.0/benchmarks/bench.sh +180 -0
- metacooler-0.2.0/benchmarks/benchmarks.qmd +1285 -0
- metacooler-0.2.0/benchmarks/simulate.py +457 -0
- metacooler-0.2.0/benchmarks/targets.py +61 -0
- metacooler-0.2.0/docs/api/io.md +79 -0
- metacooler-0.2.0/docs/api/metacooler.md +38 -0
- metacooler-0.2.0/docs/api/ops.md +41 -0
- metacooler-0.2.0/docs/assets/metacooler-mark.svg +1 -0
- metacooler-0.2.0/docs/changelog.md +649 -0
- metacooler-0.2.0/docs/cli.md +1631 -0
- metacooler-0.2.0/docs/concepts.md +153 -0
- metacooler-0.2.0/docs/format.md +311 -0
- metacooler-0.2.0/docs/guides/collect.md +148 -0
- metacooler-0.2.0/docs/guides/export.md +250 -0
- metacooler-0.2.0/docs/guides/from-cool.md +84 -0
- metacooler-0.2.0/docs/guides/from-pairs.md +344 -0
- metacooler-0.2.0/docs/guides/multireso.md +203 -0
- metacooler-0.2.0/docs/index.md +58 -0
- metacooler-0.2.0/docs/installation.md +52 -0
- metacooler-0.2.0/docs/javascripts/metacooler.js +32 -0
- metacooler-0.2.0/docs/quickstart.md +187 -0
- metacooler-0.2.0/docs/stylesheets/metacooler.css +1617 -0
- metacooler-0.2.0/docs/why.md +85 -0
- metacooler-0.2.0/overrides/main.html +12 -0
- metacooler-0.2.0/overrides/partials/header.html +60 -0
- metacooler-0.2.0/overrides/partials/mc-page-footer.html +43 -0
- metacooler-0.2.0/overrides/partials/search.html +8 -0
- metacooler-0.2.0/pyproject.toml +148 -0
- metacooler-0.2.0/src/metacooler/__init__.py +204 -0
- metacooler-0.2.0/src/metacooler/_version.py +5 -0
- metacooler-0.2.0/src/metacooler/api.py +923 -0
- metacooler-0.2.0/src/metacooler/cli/__init__.py +1 -0
- metacooler-0.2.0/src/metacooler/cli/_options.py +333 -0
- metacooler-0.2.0/src/metacooler/cli/_provenance.py +187 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_aggregate.py +90 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_annotate.py +187 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_attrs.py +148 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_binnify.py +92 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_check.py +50 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_collect.py +228 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_cp.py +127 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_create.py +102 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_create_cool.py +144 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_create_pairs.py +216 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_dump.py +210 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_extract.py +112 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_flatten.py +51 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_info.py +128 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_ls.py +92 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_merge.py +80 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_metadata.py +168 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_mv.py +72 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_network.py +91 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_ps.py +210 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_qc.py +150 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_reassign.py +198 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_rm.py +55 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_show.py +170 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_stack.py +140 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_tree.py +70 -0
- metacooler-0.2.0/src/metacooler/cli/cmd_zoomify.py +99 -0
- metacooler-0.2.0/src/metacooler/cli/logging_utils.py +67 -0
- metacooler-0.2.0/src/metacooler/cli/main.py +275 -0
- metacooler-0.2.0/src/metacooler/filters.py +487 -0
- metacooler-0.2.0/src/metacooler/io/__init__.py +1 -0
- metacooler-0.2.0/src/metacooler/io/_utils.py +1372 -0
- metacooler-0.2.0/src/metacooler/io/annotate.py +817 -0
- metacooler-0.2.0/src/metacooler/io/collect.py +1287 -0
- metacooler-0.2.0/src/metacooler/io/colspec.py +317 -0
- metacooler-0.2.0/src/metacooler/io/contigs.py +137 -0
- metacooler-0.2.0/src/metacooler/io/create.py +3257 -0
- metacooler-0.2.0/src/metacooler/io/dump.py +364 -0
- metacooler-0.2.0/src/metacooler/io/extract.py +210 -0
- metacooler-0.2.0/src/metacooler/io/flatten.py +87 -0
- metacooler-0.2.0/src/metacooler/io/genomes.py +71 -0
- metacooler-0.2.0/src/metacooler/io/merge.py +356 -0
- metacooler-0.2.0/src/metacooler/io/mmetacool.py +383 -0
- metacooler-0.2.0/src/metacooler/io/network.py +188 -0
- metacooler-0.2.0/src/metacooler/io/reassign.py +1011 -0
- metacooler-0.2.0/src/metacooler/ops/__init__.py +1 -0
- metacooler-0.2.0/src/metacooler/ops/aggregate.py +245 -0
- metacooler-0.2.0/src/metacooler/ops/binnify.py +795 -0
- metacooler-0.2.0/src/metacooler/ops/ps.py +468 -0
- metacooler-0.2.0/src/metacooler/ops/qc.py +129 -0
- metacooler-0.2.0/src/metacooler/ops/range.py +75 -0
- metacooler-0.2.0/src/metacooler/ops/show.py +862 -0
- metacooler-0.2.0/src/metacooler/ops/zoomify.py +457 -0
- metacooler-0.2.0/src/metacooler/ps.py +466 -0
- metacooler-0.2.0/src/metacooler/qc.py +497 -0
- metacooler-0.2.0/src/metacooler/schema.py +1369 -0
- metacooler-0.2.0/src/metacooler/uri.py +45 -0
- metacooler-0.2.0/tests/_cli_output.py +48 -0
- metacooler-0.2.0/tests/_cools.py +72 -0
- metacooler-0.2.0/tests/conftest.py +369 -0
- metacooler-0.2.0/tests/data/assembly_1.chrom.sizes +44 -0
- metacooler-0.2.0/tests/data/assembly_1.fa +8317 -0
- metacooler-0.2.0/tests/data/assembly_1.fa.fai +44 -0
- metacooler-0.2.0/tests/data/assembly_1_1kb.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_1kb.mmetacool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_DpnII-digested.bed +2658 -0
- metacooler-0.2.0/tests/data/assembly_1_rep1_1kb.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep1_1kb.mcool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep1_1kb.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep1_DpnII.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep1_DpnII.mcool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep1_DpnII.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep2_1kb.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep2_1kb.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep2_DpnII.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_1_rep2_DpnII.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_2.chrom.sizes +30 -0
- metacooler-0.2.0/tests/data/assembly_2.fa +8375 -0
- metacooler-0.2.0/tests/data/assembly_2.fa.fai +30 -0
- metacooler-0.2.0/tests/data/assembly_2_DpnII-digested.bed +2582 -0
- metacooler-0.2.0/tests/data/assembly_2_rep1_1kb.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep1_1kb.mcool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep1_1kb.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep1_DpnII.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep1_DpnII.mcool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep1_DpnII.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep2_1kb.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep2_1kb.metacool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep2_DpnII.cool +0 -0
- metacooler-0.2.0/tests/data/assembly_2_rep2_DpnII.metacool +0 -0
- metacooler-0.2.0/tests/data/cli_tests.sh +666 -0
- metacooler-0.2.0/tests/data/contigs_table_1.tsv +45 -0
- metacooler-0.2.0/tests/data/contigs_table_2.tsv +31 -0
- metacooler-0.2.0/tests/data/generate-raw-files.py +291 -0
- metacooler-0.2.0/tests/data/mag_table_1.tsv +11 -0
- metacooler-0.2.0/tests/data/mag_table_2.tsv +9 -0
- metacooler-0.2.0/tests/data/metadata.yaml +20 -0
- metacooler-0.2.0/tests/data/raw-to-cool.sh +44 -0
- metacooler-0.2.0/tests/test_aggregate.py +34 -0
- metacooler-0.2.0/tests/test_annotate.py +666 -0
- metacooler-0.2.0/tests/test_api.py +441 -0
- metacooler-0.2.0/tests/test_audit_regressions.py +511 -0
- metacooler-0.2.0/tests/test_binnify.py +207 -0
- metacooler-0.2.0/tests/test_binnify_streaming.py +168 -0
- metacooler-0.2.0/tests/test_check.py +180 -0
- metacooler-0.2.0/tests/test_cli.py +235 -0
- metacooler-0.2.0/tests/test_cli_collect.py +245 -0
- metacooler-0.2.0/tests/test_cli_comprehensive.py +2050 -0
- metacooler-0.2.0/tests/test_cli_create.py +1208 -0
- metacooler-0.2.0/tests/test_cli_edge_cases.py +1942 -0
- metacooler-0.2.0/tests/test_cli_mmetacool.py +152 -0
- metacooler-0.2.0/tests/test_cli_network.py +382 -0
- metacooler-0.2.0/tests/test_cli_stack.py +233 -0
- metacooler-0.2.0/tests/test_collect.py +918 -0
- metacooler-0.2.0/tests/test_colspec.py +278 -0
- metacooler-0.2.0/tests/test_contigs.py +216 -0
- metacooler-0.2.0/tests/test_cooler_compat.py +1014 -0
- metacooler-0.2.0/tests/test_create_contig_table.py +336 -0
- metacooler-0.2.0/tests/test_create_correctness.py +816 -0
- metacooler-0.2.0/tests/test_create_edge_cases.py +994 -0
- metacooler-0.2.0/tests/test_create_multiple_pairs.py +479 -0
- metacooler-0.2.0/tests/test_dump.py +303 -0
- metacooler-0.2.0/tests/test_extract.py +161 -0
- metacooler-0.2.0/tests/test_filters.py +506 -0
- metacooler-0.2.0/tests/test_flatten.py +60 -0
- metacooler-0.2.0/tests/test_import_cool.py +632 -0
- metacooler-0.2.0/tests/test_index_retrieval.py +402 -0
- metacooler-0.2.0/tests/test_info_mmetacool.py +66 -0
- metacooler-0.2.0/tests/test_init.py +192 -0
- metacooler-0.2.0/tests/test_merge.py +150 -0
- metacooler-0.2.0/tests/test_metadata_reserved.py +72 -0
- metacooler-0.2.0/tests/test_mmetacool_io.py +252 -0
- metacooler-0.2.0/tests/test_network.py +158 -0
- metacooler-0.2.0/tests/test_nproc.py +221 -0
- metacooler-0.2.0/tests/test_pixel_aggregation.py +239 -0
- metacooler-0.2.0/tests/test_ps.py +579 -0
- metacooler-0.2.0/tests/test_qc.py +604 -0
- metacooler-0.2.0/tests/test_range.py +52 -0
- metacooler-0.2.0/tests/test_reassign.py +1075 -0
- metacooler-0.2.0/tests/test_regressions.py +1380 -0
- metacooler-0.2.0/tests/test_release_audit.py +1003 -0
- metacooler-0.2.0/tests/test_schema.py +106 -0
- metacooler-0.2.0/tests/test_schema_mmetacool.py +120 -0
- metacooler-0.2.0/tests/test_schema_validation.py +275 -0
- metacooler-0.2.0/tests/test_show.py +534 -0
- metacooler-0.2.0/tests/test_storage_filters.py +193 -0
- metacooler-0.2.0/tests/test_table_formats.py +521 -0
- metacooler-0.2.0/tests/test_uri.py +56 -0
- metacooler-0.2.0/tests/test_zoomify.py +100 -0
- metacooler-0.2.0/zensical.toml +102 -0
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
*.egg-info/
|
|
24
|
+
.installed.cfg
|
|
25
|
+
*.egg
|
|
26
|
+
|
|
27
|
+
# PyInstaller
|
|
28
|
+
*.manifest
|
|
29
|
+
*.spec
|
|
30
|
+
|
|
31
|
+
# Installer logs
|
|
32
|
+
pip-log.txt
|
|
33
|
+
pip-delete-this-directory.txt
|
|
34
|
+
|
|
35
|
+
# Unit test / coverage reports
|
|
36
|
+
htmlcov/
|
|
37
|
+
.tox/
|
|
38
|
+
.nox/
|
|
39
|
+
.coverage
|
|
40
|
+
.coverage.*
|
|
41
|
+
.cache
|
|
42
|
+
nosetests.xml
|
|
43
|
+
coverage.xml
|
|
44
|
+
*.cover
|
|
45
|
+
.hypothesis/
|
|
46
|
+
.pytest_cache/
|
|
47
|
+
|
|
48
|
+
# Jupyter Notebook
|
|
49
|
+
.ipynb_checkpoints
|
|
50
|
+
|
|
51
|
+
# Environments
|
|
52
|
+
.env
|
|
53
|
+
.venv
|
|
54
|
+
env/
|
|
55
|
+
venv/
|
|
56
|
+
ENV/
|
|
57
|
+
env.bak/
|
|
58
|
+
venv.bak/
|
|
59
|
+
|
|
60
|
+
# IDEs
|
|
61
|
+
.vscode/
|
|
62
|
+
.idea/
|
|
63
|
+
*.swp
|
|
64
|
+
*.swo
|
|
65
|
+
*~
|
|
66
|
+
|
|
67
|
+
# Hatch / build
|
|
68
|
+
.hatch/
|
|
69
|
+
|
|
70
|
+
# macOS
|
|
71
|
+
.DS_Store
|
|
72
|
+
|
|
73
|
+
###############################################################
|
|
74
|
+
|
|
75
|
+
REVIEW.md
|
|
76
|
+
NOTES.md
|
|
77
|
+
TESTS.md
|
|
78
|
+
TODO.md
|
|
79
|
+
*.metacool
|
|
80
|
+
*.mmetacool
|
|
81
|
+
*.cool
|
|
82
|
+
*.mcool
|
|
83
|
+
!tests/data/*cool
|
|
84
|
+
*.pairs.gz
|
|
85
|
+
outs/
|
|
86
|
+
reviewed/
|
|
87
|
+
site/
|
|
88
|
+
real-data/
|
|
89
|
+
*.png
|
metacooler-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jacques Serizay
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: metacooler
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: metacooler: Hi-C contact maps for metagenomes — an extension of the cooler format.
|
|
5
|
+
Project-URL: Homepage, https://github.com/js2264/metacooler
|
|
6
|
+
Project-URL: Repository, https://github.com/js2264/metacooler
|
|
7
|
+
Project-URL: Documentation, https://js2264.github.io/metacooler
|
|
8
|
+
Project-URL: Changelog, https://js2264.github.io/metacooler/changelog/
|
|
9
|
+
Author: Jacques Serizay
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: contact-maps,cooler,hdf5,hi-c,metagenomics
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: click>=8.1
|
|
24
|
+
Requires-Dist: cooler>=0.10
|
|
25
|
+
Requires-Dist: h5py>=3.8
|
|
26
|
+
Requires-Dist: matplotlib>=3.7
|
|
27
|
+
Requires-Dist: numpy>=1.24
|
|
28
|
+
Requires-Dist: pandas>=2.0
|
|
29
|
+
Requires-Dist: pyarrow>=13
|
|
30
|
+
Requires-Dist: pyfaidx>=0.7.2.2
|
|
31
|
+
Requires-Dist: pyyaml>=6.0
|
|
32
|
+
Requires-Dist: rich-click>=1.9
|
|
33
|
+
Requires-Dist: rich>=13
|
|
34
|
+
Requires-Dist: scipy>=1.10
|
|
35
|
+
Provides-Extra: docs
|
|
36
|
+
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
|
|
37
|
+
Requires-Dist: zensical>=0.0.43; extra == 'docs'
|
|
38
|
+
Description-Content-Type: text/markdown
|
|
39
|
+
|
|
40
|
+
# metacooler: Hi-C contact maps for metagenomes
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
[](https://www.python.org/downloads/) [](https://pypi.org/project/metacooler/) [](https://opensource.org/licenses/MIT) [](https://github.com/astral-sh/ruff) [](https://codecov.io/gh/js2264/metacooler)
|
|
44
|
+
|
|
45
|
+
An extension of the [cooler](https://github.com/open2c/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.
|
|
46
|
+
|
|
47
|
+
`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.
|
|
48
|
+
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
``` console
|
|
52
|
+
pip install metacooler
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
For development, clone the repository and run `uv sync`, which installs the runtime dependencies plus the `dev` dependency group (pytest, ruff, ty, pre-commit).
|
|
56
|
+
|
|
57
|
+
## Quick start
|
|
58
|
+
|
|
59
|
+
``` console
|
|
60
|
+
metacooler create pairs --help
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
``` console
|
|
64
|
+
metacooler create pairs \
|
|
65
|
+
--bins fragments.bed \
|
|
66
|
+
--contigs contigs2mag.tsv \
|
|
67
|
+
--pairs contacts.pairs \
|
|
68
|
+
--output output.metacool \
|
|
69
|
+
--genomes mag_table.tsv ## <-- Optional
|
|
70
|
+
|
|
71
|
+
metacooler info output.metacool
|
|
72
|
+
metacooler dump -t genomes output.metacool
|
|
73
|
+
metacooler aggregate --level genome output.metacool -o genome.cool
|
|
74
|
+
metacooler show output.metacool --level genome -o heatmap.png
|
|
75
|
+
metacooler qc output.metacool --table
|
|
76
|
+
metacooler ps output.metacool --pairs contacts.pairs --by genome --plot ps.png
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
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`.
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
Usage: metacooler create pairs [OPTIONS]
|
|
83
|
+
|
|
84
|
+
Create a metacool file from pairs and contig assignments.
|
|
85
|
+
|
|
86
|
+
╭─ Options ────────────────────────────────────────────────────────────────────╮
|
|
87
|
+
│ * --pairs Pairs file (plain text or gzipped). [required] │
|
|
88
|
+
│ * --bins BED file of bins (without column names), or an │
|
|
89
|
+
│ integer bin size in bp (e.g. 1000). If an │
|
|
90
|
+
│ integer, contig lengths must be available from │
|
|
91
|
+
│ the pairs header or a --fasta should be │
|
|
92
|
+
│ provided. [required] │
|
|
93
|
+
│ * --output -o Output .metacool file path. [required] │
|
|
94
|
+
│ * --contigs Contig-to-genome assignment table. The expected │
|
|
95
|
+
│ layout depends on --contigs-format. [required] │
|
|
96
|
+
│ --contigs-format Format of the contig assignment table. Four │
|
|
97
|
+
│ formats are supported: [default: contigs] │
|
|
98
|
+
│ - contigs: TSV with a header row. Column 1 must │
|
|
99
|
+
│ be named `contig_name` and column 2 │
|
|
100
|
+
│ `genome_name`. Additional columns are stored │
|
|
101
|
+
│ verbatim. │
|
|
102
|
+
│ - contig_genome: Two-column TSV │
|
|
103
|
+
│ (`contig<TAB>genome`) with no header. First │
|
|
104
|
+
│ value is contig name, second is genome │
|
|
105
|
+
│ assignment. │
|
|
106
|
+
│ - metator: MetaTOR output table (ie │
|
|
107
|
+
│ `contig_data_final.txt`). Expects a header with │
|
|
108
|
+
│ columns `Name` (contig) and `Final_bin` │
|
|
109
|
+
│ (genome). Other columns ignored. │
|
|
110
|
+
│ - I,J(,noheader): Column-index spec (1-based). │
|
|
111
|
+
│ Use column `I` for contigs and `J` for genomes. │
|
|
112
|
+
│ Header expected by default. Append `,noheader` │
|
|
113
|
+
│ (e.g., `1,5,noheader`) to treat the first row │
|
|
114
|
+
│ as data. │
|
|
115
|
+
│ --genomes Optional genomes metadata table with header. │
|
|
116
|
+
│ First column must be 'genome_name'; any further │
|
|
117
|
+
│ columns are stored in the /genomes table. │
|
|
118
|
+
│ --filter Keep only rows matching <table>.<column> <op> │
|
|
119
|
+
│ <value>, where <table> is genomes or contigs — │
|
|
120
|
+
│ e.g. --filter 'genomes.length > 1Mb'. │
|
|
121
|
+
│ Operators: > >= < <= == != =~ !~ (=~ is a regex │
|
|
122
|
+
│ match). Numbers accept bp/kb/Mb/Gb suffixes. │
|
|
123
|
+
│ Repeat the option to require several conditions │
|
|
124
|
+
│ at once. │
|
|
125
|
+
│ --metadata Path to a JSON or YAML file containing metadata │
|
|
126
|
+
│ to ingest into the file. │
|
|
127
|
+
│ --qc/--no-qc Tally contact-quality statistics during │
|
|
128
|
+
│ creation and store them in metadata.qc and the │
|
|
129
|
+
│ /genomes qc_* columns. Read them back with │
|
|
130
|
+
│ metacooler qc. [default: qc] │
|
|
131
|
+
│ --qc-threshold Distance splitting short- from long-range │
|
|
132
|
+
│ intra-contig signal. Accepts bp/kb/Mb/Gb │
|
|
133
|
+
│ suffixes. [default: 10000] │
|
|
134
|
+
│ --force -f Overwrite output file if it already exists. │
|
|
135
|
+
│ --verbose -v Increase verbosity (debug logging). │
|
|
136
|
+
│ --quiet -q Suppress informational logging (warnings and │
|
|
137
|
+
│ errors still shown). │
|
|
138
|
+
│ --contig-order Strategy for ordering contigs in the output │
|
|
139
|
+
│ metacool file. │
|
|
140
|
+
│ - genome-then-length: group by genome, │
|
|
141
|
+
│ longest-first within each genome. │
|
|
142
|
+
│ - genome-then-alpha: group by genome, │
|
|
143
|
+
│ alphabetical within each genome. │
|
|
144
|
+
│ - fasta: preserve order from the input FASTA │
|
|
145
|
+
│ (or pairs header). │
|
|
146
|
+
│ - alpha: sort all contigs alphabetically. │
|
|
147
|
+
│ [default: genome-then-length] │
|
|
148
|
+
│ --fasta Assembly FASTA. Used to extract contig lengths │
|
|
149
|
+
│ when --bins is an integer and contig sizes are │
|
|
150
|
+
│ absent from the pairs header. │
|
|
151
|
+
│ --assembly-name Name for this assembly / metagenome. │
|
|
152
|
+
│ --drop-unassigned Drop contigs not assigned to any genome. │
|
|
153
|
+
│ --chunksize Number of pairs to process per chunk. This is │
|
|
154
|
+
│ chunk granularity, not read memory (the pyarrow │
|
|
155
|
+
│ read block is capped separately). Under │
|
|
156
|
+
│ 'external' sorting each chunk is written as a │
|
|
157
|
+
│ temporary cooler at a fixed per-call cost that │
|
|
158
|
+
│ scales with contig count, so smaller chunks │
|
|
159
|
+
│ cost disproportionately more. [default: │
|
|
160
|
+
│ 50000000] │
|
|
161
|
+
│ --ps/--no-ps Accumulate a per-MAG P(s) curve from the same │
|
|
162
|
+
│ pass over the pairs and write it beside the │
|
|
163
|
+
│ output as <output>.ps.tsv. Measured on read │
|
|
164
|
+
│ positions, so it resolves distances the binned │
|
|
165
|
+
│ map cannot. No plot is drawn — pass the table │
|
|
166
|
+
│ to metacooler ps or your own plotting. │
|
|
167
|
+
│ [default: ps] │
|
|
168
|
+
│ --ps-bins-per-decade Number of log-spaced distance bins per decade │
|
|
169
|
+
│ in the P(s) table. [default: 10] │
|
|
170
|
+
│ --sort-strategy Pixel sorting strategy. 'auto': use 'memory' │
|
|
171
|
+
│ unless the binned pixels exceed 100 M rows. │
|
|
172
|
+
│ 'memory': collect all pixels in RAM and sort │
|
|
173
|
+
│ before writing (fast for small files). │
|
|
174
|
+
│ 'external': stream unsorted pixels to cooler's │
|
|
175
|
+
│ external sort (scalable for large files). │
|
|
176
|
+
│ [default: auto] │
|
|
177
|
+
│ --help -h Show this message and exit. │
|
|
178
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
179
|
+
|
|
180
|
+
## Input files
|
|
181
|
+
|
|
182
|
+
**Bins file**: BED-like file with `chrom`, `start`, `end` columns defining the genomic bins.
|
|
183
|
+
|
|
184
|
+
- Can be generated from a FASTA assembly with `cooler makebins` to get fixed-size bins
|
|
185
|
+
- Can be generated from a FASTA assembly with `cooler digest` to get restriction fragments.
|
|
186
|
+
- Otherwise an arbitrary resolution can be used by specifying `--bins 1000` for 1kb bins, etc.
|
|
187
|
+
|
|
188
|
+
``` txt
|
|
189
|
+
contig_1_000 0 721
|
|
190
|
+
contig_1_000 721 747
|
|
191
|
+
contig_1_000 747 767
|
|
192
|
+
contig_1_000 767 1013
|
|
193
|
+
contig_1_000 1013 1099
|
|
194
|
+
...
|
|
195
|
+
contig_1_043 8869 8959
|
|
196
|
+
contig_1_043 8959 9000
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
**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:
|
|
200
|
+
|
|
201
|
+
- A two-column file with NO HEADER: first column is treated as contig name, second column as genome/MAG name.
|
|
202
|
+
- A TSV file with header, whose first column is `contig_name` and second column `genome_name`. Additional metadata columns will be stored in the `contigs/` table.
|
|
203
|
+
|
|
204
|
+
``` txt
|
|
205
|
+
contig_name genome_name gc_content coverage
|
|
206
|
+
contig_1_000 MAG_04 0.51 99.40
|
|
207
|
+
contig_1_001 MAG_02 0.59 75.43
|
|
208
|
+
contig_1_002 MAG_04 0.45 8.81
|
|
209
|
+
contig_1_003 __unbinned__ 0.52 8.28
|
|
210
|
+
...
|
|
211
|
+
contig_1_042 MAG_05 0.52 18.45
|
|
212
|
+
contig_1_043 MAG_05 0.42 97.78
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
**Pairs file**: [4DN-compliant](https://github.com/4dn-dcic/pairix/blob/master/pairs_format_specification.md) 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`](https://github.com/koszullab/metator).
|
|
216
|
+
|
|
217
|
+
``` txt
|
|
218
|
+
#pairs format v1.0
|
|
219
|
+
#sorted: chr1-chr2-pos1-pos2
|
|
220
|
+
#shape: upper triangle
|
|
221
|
+
#genome_assembly: synthetic_assembly_1
|
|
222
|
+
#chromsize: contig_1_000 18000
|
|
223
|
+
#chromsize: contig_1_001 12000
|
|
224
|
+
#chromsize: contig_1_002 3000
|
|
225
|
+
#chromsize: contig_1_003 6000
|
|
226
|
+
...
|
|
227
|
+
#columns: readID chrom1 pos1 chrom2 pos2 strand1 strand2
|
|
228
|
+
read_0 contig_1_007 41718 contig_1_006 6634 + +
|
|
229
|
+
read_1 contig_1_037 2208 contig_1_000 12785 + +
|
|
230
|
+
read_2 contig_1_003 5884 contig_1_028 2231 + +
|
|
231
|
+
read_3 contig_1_014 3164 contig_1_021 47093 + +
|
|
232
|
+
read_4 contig_1_008 138 contig_1_038 6042 + +
|
|
233
|
+
...
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
*\[Optional\]* **Genomes table**: TSV file with at least a column named `genome_name`, and optional metadata columns describing the genomes/MAGs.
|
|
237
|
+
|
|
238
|
+
``` txt
|
|
239
|
+
genome_name phylum completeness contamination quality
|
|
240
|
+
MAG_02 Firmicutes 0.92 0.14 low
|
|
241
|
+
MAG_03 Proteobacteria 0.73 0.03 low
|
|
242
|
+
MAG_01 Bacteroidetes 0.63 0.10 high
|
|
243
|
+
MAG_04 Firmicutes 0.99 0.24 medium
|
|
244
|
+
...
|
|
245
|
+
MAG_09 Proteobacteria 0.95 0.04 low
|
|
246
|
+
MAG_05 Proteobacteria 0.89 0.27 high
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
*\[Optional\]* **Metadata file**: a YAML/JSON file with additional metadata.
|
|
250
|
+
|
|
251
|
+
``` yaml
|
|
252
|
+
sample:
|
|
253
|
+
name: gut_microbiome_T0
|
|
254
|
+
description: This is a gut microbiome sample at time point 0
|
|
255
|
+
organism: human gut metagenome
|
|
256
|
+
enzyme: HpaII
|
|
257
|
+
enzyme_site: "C^CGG"
|
|
258
|
+
sequencing:
|
|
259
|
+
platform: Illumina NovaSeq 6000
|
|
260
|
+
read_length: 150
|
|
261
|
+
n_read_pairs: 245000000
|
|
262
|
+
n_valid_pairs: 180000000
|
|
263
|
+
assembly:
|
|
264
|
+
name: gut_microbiome_T0_assembly.fa
|
|
265
|
+
description: metagenome assembly for the gut microbiome sample at time point 0
|
|
266
|
+
assembler: MEGAHIT v1.2.9
|
|
267
|
+
assembly_date: 2024-06-01
|
|
268
|
+
assembly_stats:
|
|
269
|
+
total_length: 3500000
|
|
270
|
+
n_contigs: 120
|
|
271
|
+
n50: 50000
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
## Design
|
|
275
|
+
|
|
276
|
+
- **Metacool identity**: `metacooler-format="HDF5::MetaCooler"` attribute + `genomes/` group
|
|
277
|
+
- **Implement genomes table**: `name`, `length`, `n_contigs`, `n_bins`, plus optional metadata columns
|
|
278
|
+
- **Support multi-contigs and multi-genomes visualization**: `show` command at `--level bin/contig/genome`
|
|
279
|
+
- **Report contact quality**: the 3D ratio and its intra-contig / intra-MAG / inter-MAG breakdown, tallied at creation time into `metadata.qc` and per-MAG `/genomes` columns, recomputable with `qc`
|
|
280
|
+
- **Export P(s)**: contact probability vs genomic distance, pooled or per MAG, as a table and a log-log plot (`ps`). `create pairs` writes the per-MAG curve at base-pair resolution beside the output as `<output>.ps.tsv`
|
|
281
|
+
- **Cooler compatibility**: soft link `chroms → contigs`, `format="HDF5::Cooler"`, standard `indexes/chrom_offset`
|
|
282
|
+
- **Canonical contig ordering**: configurable (`genome-then-length`, `genome-then-alpha`, `fasta`, `alpha`; `cool` for `create cool`)
|
|
283
|
+
- **Unassigned contigs**: default to `__unbinned__` genome
|
|
284
|
+
- **Re-attributable bins**: `reassign` swaps in a new contig-to-genome table on an existing file — the `/genomes` table and the contig layout are rebuilt, the contacts are not recomputed
|
|
285
|
+
- **Multi-resolution**: `binnify` (exact multiples of the source bin size only) and `zoomify` → a `.mmetacool` collection
|
|
286
|
+
|
|
287
|
+
## Releasing
|
|
288
|
+
|
|
289
|
+
Changelog entries for in-progress work go under `## Unreleased` in `docs/changelog.md` as they land on `devel`. To cut a release:
|
|
290
|
+
|
|
291
|
+
``` console
|
|
292
|
+
uv run bump-my-version bump minor # or patch / major
|
|
293
|
+
git push --follow-tags
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
[`bump-my-version`](https://github.com/callowayproject/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`](.github/workflows/release.yml): it builds the sdist/wheel, fails if the tag doesn’t match `__version__`, publishes to PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/) (no stored token), and opens a GitHub release with that version’s changelog section and the built artifacts attached. [`docs.yml`](.github/workflows/docs.yml) redeploys the documentation site on the same tag.
|
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# metacooler: Hi-C contact maps for metagenomes
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
[](https://www.python.org/downloads/) [](https://pypi.org/project/metacooler/) [](https://opensource.org/licenses/MIT) [](https://github.com/astral-sh/ruff) [](https://codecov.io/gh/js2264/metacooler)
|
|
5
|
+
|
|
6
|
+
An extension of the [cooler](https://github.com/open2c/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.
|
|
7
|
+
|
|
8
|
+
`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.
|
|
9
|
+
|
|
10
|
+
## Installation
|
|
11
|
+
|
|
12
|
+
``` console
|
|
13
|
+
pip install metacooler
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
For development, clone the repository and run `uv sync`, which installs the runtime dependencies plus the `dev` dependency group (pytest, ruff, ty, pre-commit).
|
|
17
|
+
|
|
18
|
+
## Quick start
|
|
19
|
+
|
|
20
|
+
``` console
|
|
21
|
+
metacooler create pairs --help
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
``` console
|
|
25
|
+
metacooler create pairs \
|
|
26
|
+
--bins fragments.bed \
|
|
27
|
+
--contigs contigs2mag.tsv \
|
|
28
|
+
--pairs contacts.pairs \
|
|
29
|
+
--output output.metacool \
|
|
30
|
+
--genomes mag_table.tsv ## <-- Optional
|
|
31
|
+
|
|
32
|
+
metacooler info output.metacool
|
|
33
|
+
metacooler dump -t genomes output.metacool
|
|
34
|
+
metacooler aggregate --level genome output.metacool -o genome.cool
|
|
35
|
+
metacooler show output.metacool --level genome -o heatmap.png
|
|
36
|
+
metacooler qc output.metacool --table
|
|
37
|
+
metacooler ps output.metacool --pairs contacts.pairs --by genome --plot ps.png
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
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`.
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
Usage: metacooler create pairs [OPTIONS]
|
|
44
|
+
|
|
45
|
+
Create a metacool file from pairs and contig assignments.
|
|
46
|
+
|
|
47
|
+
╭─ Options ────────────────────────────────────────────────────────────────────╮
|
|
48
|
+
│ * --pairs Pairs file (plain text or gzipped). [required] │
|
|
49
|
+
│ * --bins BED file of bins (without column names), or an │
|
|
50
|
+
│ integer bin size in bp (e.g. 1000). If an │
|
|
51
|
+
│ integer, contig lengths must be available from │
|
|
52
|
+
│ the pairs header or a --fasta should be │
|
|
53
|
+
│ provided. [required] │
|
|
54
|
+
│ * --output -o Output .metacool file path. [required] │
|
|
55
|
+
│ * --contigs Contig-to-genome assignment table. The expected │
|
|
56
|
+
│ layout depends on --contigs-format. [required] │
|
|
57
|
+
│ --contigs-format Format of the contig assignment table. Four │
|
|
58
|
+
│ formats are supported: [default: contigs] │
|
|
59
|
+
│ - contigs: TSV with a header row. Column 1 must │
|
|
60
|
+
│ be named `contig_name` and column 2 │
|
|
61
|
+
│ `genome_name`. Additional columns are stored │
|
|
62
|
+
│ verbatim. │
|
|
63
|
+
│ - contig_genome: Two-column TSV │
|
|
64
|
+
│ (`contig<TAB>genome`) with no header. First │
|
|
65
|
+
│ value is contig name, second is genome │
|
|
66
|
+
│ assignment. │
|
|
67
|
+
│ - metator: MetaTOR output table (ie │
|
|
68
|
+
│ `contig_data_final.txt`). Expects a header with │
|
|
69
|
+
│ columns `Name` (contig) and `Final_bin` │
|
|
70
|
+
│ (genome). Other columns ignored. │
|
|
71
|
+
│ - I,J(,noheader): Column-index spec (1-based). │
|
|
72
|
+
│ Use column `I` for contigs and `J` for genomes. │
|
|
73
|
+
│ Header expected by default. Append `,noheader` │
|
|
74
|
+
│ (e.g., `1,5,noheader`) to treat the first row │
|
|
75
|
+
│ as data. │
|
|
76
|
+
│ --genomes Optional genomes metadata table with header. │
|
|
77
|
+
│ First column must be 'genome_name'; any further │
|
|
78
|
+
│ columns are stored in the /genomes table. │
|
|
79
|
+
│ --filter Keep only rows matching <table>.<column> <op> │
|
|
80
|
+
│ <value>, where <table> is genomes or contigs — │
|
|
81
|
+
│ e.g. --filter 'genomes.length > 1Mb'. │
|
|
82
|
+
│ Operators: > >= < <= == != =~ !~ (=~ is a regex │
|
|
83
|
+
│ match). Numbers accept bp/kb/Mb/Gb suffixes. │
|
|
84
|
+
│ Repeat the option to require several conditions │
|
|
85
|
+
│ at once. │
|
|
86
|
+
│ --metadata Path to a JSON or YAML file containing metadata │
|
|
87
|
+
│ to ingest into the file. │
|
|
88
|
+
│ --qc/--no-qc Tally contact-quality statistics during │
|
|
89
|
+
│ creation and store them in metadata.qc and the │
|
|
90
|
+
│ /genomes qc_* columns. Read them back with │
|
|
91
|
+
│ metacooler qc. [default: qc] │
|
|
92
|
+
│ --qc-threshold Distance splitting short- from long-range │
|
|
93
|
+
│ intra-contig signal. Accepts bp/kb/Mb/Gb │
|
|
94
|
+
│ suffixes. [default: 10000] │
|
|
95
|
+
│ --force -f Overwrite output file if it already exists. │
|
|
96
|
+
│ --verbose -v Increase verbosity (debug logging). │
|
|
97
|
+
│ --quiet -q Suppress informational logging (warnings and │
|
|
98
|
+
│ errors still shown). │
|
|
99
|
+
│ --contig-order Strategy for ordering contigs in the output │
|
|
100
|
+
│ metacool file. │
|
|
101
|
+
│ - genome-then-length: group by genome, │
|
|
102
|
+
│ longest-first within each genome. │
|
|
103
|
+
│ - genome-then-alpha: group by genome, │
|
|
104
|
+
│ alphabetical within each genome. │
|
|
105
|
+
│ - fasta: preserve order from the input FASTA │
|
|
106
|
+
│ (or pairs header). │
|
|
107
|
+
│ - alpha: sort all contigs alphabetically. │
|
|
108
|
+
│ [default: genome-then-length] │
|
|
109
|
+
│ --fasta Assembly FASTA. Used to extract contig lengths │
|
|
110
|
+
│ when --bins is an integer and contig sizes are │
|
|
111
|
+
│ absent from the pairs header. │
|
|
112
|
+
│ --assembly-name Name for this assembly / metagenome. │
|
|
113
|
+
│ --drop-unassigned Drop contigs not assigned to any genome. │
|
|
114
|
+
│ --chunksize Number of pairs to process per chunk. This is │
|
|
115
|
+
│ chunk granularity, not read memory (the pyarrow │
|
|
116
|
+
│ read block is capped separately). Under │
|
|
117
|
+
│ 'external' sorting each chunk is written as a │
|
|
118
|
+
│ temporary cooler at a fixed per-call cost that │
|
|
119
|
+
│ scales with contig count, so smaller chunks │
|
|
120
|
+
│ cost disproportionately more. [default: │
|
|
121
|
+
│ 50000000] │
|
|
122
|
+
│ --ps/--no-ps Accumulate a per-MAG P(s) curve from the same │
|
|
123
|
+
│ pass over the pairs and write it beside the │
|
|
124
|
+
│ output as <output>.ps.tsv. Measured on read │
|
|
125
|
+
│ positions, so it resolves distances the binned │
|
|
126
|
+
│ map cannot. No plot is drawn — pass the table │
|
|
127
|
+
│ to metacooler ps or your own plotting. │
|
|
128
|
+
│ [default: ps] │
|
|
129
|
+
│ --ps-bins-per-decade Number of log-spaced distance bins per decade │
|
|
130
|
+
│ in the P(s) table. [default: 10] │
|
|
131
|
+
│ --sort-strategy Pixel sorting strategy. 'auto': use 'memory' │
|
|
132
|
+
│ unless the binned pixels exceed 100 M rows. │
|
|
133
|
+
│ 'memory': collect all pixels in RAM and sort │
|
|
134
|
+
│ before writing (fast for small files). │
|
|
135
|
+
│ 'external': stream unsorted pixels to cooler's │
|
|
136
|
+
│ external sort (scalable for large files). │
|
|
137
|
+
│ [default: auto] │
|
|
138
|
+
│ --help -h Show this message and exit. │
|
|
139
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
140
|
+
|
|
141
|
+
## Input files
|
|
142
|
+
|
|
143
|
+
**Bins file**: BED-like file with `chrom`, `start`, `end` columns defining the genomic bins.
|
|
144
|
+
|
|
145
|
+
- Can be generated from a FASTA assembly with `cooler makebins` to get fixed-size bins
|
|
146
|
+
- Can be generated from a FASTA assembly with `cooler digest` to get restriction fragments.
|
|
147
|
+
- Otherwise an arbitrary resolution can be used by specifying `--bins 1000` for 1kb bins, etc.
|
|
148
|
+
|
|
149
|
+
``` txt
|
|
150
|
+
contig_1_000 0 721
|
|
151
|
+
contig_1_000 721 747
|
|
152
|
+
contig_1_000 747 767
|
|
153
|
+
contig_1_000 767 1013
|
|
154
|
+
contig_1_000 1013 1099
|
|
155
|
+
...
|
|
156
|
+
contig_1_043 8869 8959
|
|
157
|
+
contig_1_043 8959 9000
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
**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:
|
|
161
|
+
|
|
162
|
+
- A two-column file with NO HEADER: first column is treated as contig name, second column as genome/MAG name.
|
|
163
|
+
- A TSV file with header, whose first column is `contig_name` and second column `genome_name`. Additional metadata columns will be stored in the `contigs/` table.
|
|
164
|
+
|
|
165
|
+
``` txt
|
|
166
|
+
contig_name genome_name gc_content coverage
|
|
167
|
+
contig_1_000 MAG_04 0.51 99.40
|
|
168
|
+
contig_1_001 MAG_02 0.59 75.43
|
|
169
|
+
contig_1_002 MAG_04 0.45 8.81
|
|
170
|
+
contig_1_003 __unbinned__ 0.52 8.28
|
|
171
|
+
...
|
|
172
|
+
contig_1_042 MAG_05 0.52 18.45
|
|
173
|
+
contig_1_043 MAG_05 0.42 97.78
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**Pairs file**: [4DN-compliant](https://github.com/4dn-dcic/pairix/blob/master/pairs_format_specification.md) 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`](https://github.com/koszullab/metator).
|
|
177
|
+
|
|
178
|
+
``` txt
|
|
179
|
+
#pairs format v1.0
|
|
180
|
+
#sorted: chr1-chr2-pos1-pos2
|
|
181
|
+
#shape: upper triangle
|
|
182
|
+
#genome_assembly: synthetic_assembly_1
|
|
183
|
+
#chromsize: contig_1_000 18000
|
|
184
|
+
#chromsize: contig_1_001 12000
|
|
185
|
+
#chromsize: contig_1_002 3000
|
|
186
|
+
#chromsize: contig_1_003 6000
|
|
187
|
+
...
|
|
188
|
+
#columns: readID chrom1 pos1 chrom2 pos2 strand1 strand2
|
|
189
|
+
read_0 contig_1_007 41718 contig_1_006 6634 + +
|
|
190
|
+
read_1 contig_1_037 2208 contig_1_000 12785 + +
|
|
191
|
+
read_2 contig_1_003 5884 contig_1_028 2231 + +
|
|
192
|
+
read_3 contig_1_014 3164 contig_1_021 47093 + +
|
|
193
|
+
read_4 contig_1_008 138 contig_1_038 6042 + +
|
|
194
|
+
...
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
*\[Optional\]* **Genomes table**: TSV file with at least a column named `genome_name`, and optional metadata columns describing the genomes/MAGs.
|
|
198
|
+
|
|
199
|
+
``` txt
|
|
200
|
+
genome_name phylum completeness contamination quality
|
|
201
|
+
MAG_02 Firmicutes 0.92 0.14 low
|
|
202
|
+
MAG_03 Proteobacteria 0.73 0.03 low
|
|
203
|
+
MAG_01 Bacteroidetes 0.63 0.10 high
|
|
204
|
+
MAG_04 Firmicutes 0.99 0.24 medium
|
|
205
|
+
...
|
|
206
|
+
MAG_09 Proteobacteria 0.95 0.04 low
|
|
207
|
+
MAG_05 Proteobacteria 0.89 0.27 high
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
*\[Optional\]* **Metadata file**: a YAML/JSON file with additional metadata.
|
|
211
|
+
|
|
212
|
+
``` yaml
|
|
213
|
+
sample:
|
|
214
|
+
name: gut_microbiome_T0
|
|
215
|
+
description: This is a gut microbiome sample at time point 0
|
|
216
|
+
organism: human gut metagenome
|
|
217
|
+
enzyme: HpaII
|
|
218
|
+
enzyme_site: "C^CGG"
|
|
219
|
+
sequencing:
|
|
220
|
+
platform: Illumina NovaSeq 6000
|
|
221
|
+
read_length: 150
|
|
222
|
+
n_read_pairs: 245000000
|
|
223
|
+
n_valid_pairs: 180000000
|
|
224
|
+
assembly:
|
|
225
|
+
name: gut_microbiome_T0_assembly.fa
|
|
226
|
+
description: metagenome assembly for the gut microbiome sample at time point 0
|
|
227
|
+
assembler: MEGAHIT v1.2.9
|
|
228
|
+
assembly_date: 2024-06-01
|
|
229
|
+
assembly_stats:
|
|
230
|
+
total_length: 3500000
|
|
231
|
+
n_contigs: 120
|
|
232
|
+
n50: 50000
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
## Design
|
|
236
|
+
|
|
237
|
+
- **Metacool identity**: `metacooler-format="HDF5::MetaCooler"` attribute + `genomes/` group
|
|
238
|
+
- **Implement genomes table**: `name`, `length`, `n_contigs`, `n_bins`, plus optional metadata columns
|
|
239
|
+
- **Support multi-contigs and multi-genomes visualization**: `show` command at `--level bin/contig/genome`
|
|
240
|
+
- **Report contact quality**: the 3D ratio and its intra-contig / intra-MAG / inter-MAG breakdown, tallied at creation time into `metadata.qc` and per-MAG `/genomes` columns, recomputable with `qc`
|
|
241
|
+
- **Export P(s)**: contact probability vs genomic distance, pooled or per MAG, as a table and a log-log plot (`ps`). `create pairs` writes the per-MAG curve at base-pair resolution beside the output as `<output>.ps.tsv`
|
|
242
|
+
- **Cooler compatibility**: soft link `chroms → contigs`, `format="HDF5::Cooler"`, standard `indexes/chrom_offset`
|
|
243
|
+
- **Canonical contig ordering**: configurable (`genome-then-length`, `genome-then-alpha`, `fasta`, `alpha`; `cool` for `create cool`)
|
|
244
|
+
- **Unassigned contigs**: default to `__unbinned__` genome
|
|
245
|
+
- **Re-attributable bins**: `reassign` swaps in a new contig-to-genome table on an existing file — the `/genomes` table and the contig layout are rebuilt, the contacts are not recomputed
|
|
246
|
+
- **Multi-resolution**: `binnify` (exact multiples of the source bin size only) and `zoomify` → a `.mmetacool` collection
|
|
247
|
+
|
|
248
|
+
## Releasing
|
|
249
|
+
|
|
250
|
+
Changelog entries for in-progress work go under `## Unreleased` in `docs/changelog.md` as they land on `devel`. To cut a release:
|
|
251
|
+
|
|
252
|
+
``` console
|
|
253
|
+
uv run bump-my-version bump minor # or patch / major
|
|
254
|
+
git push --follow-tags
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
[`bump-my-version`](https://github.com/callowayproject/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`](.github/workflows/release.yml): it builds the sdist/wheel, fails if the tag doesn’t match `__version__`, publishes to PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/) (no stored token), and opens a GitHub release with that version’s changelog section and the built artifacts attached. [`docs.yml`](.github/workflows/docs.yml) redeploys the documentation site on the same tag.
|