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.
Files changed (191) hide show
  1. metacooler-0.2.0/.gitignore +89 -0
  2. metacooler-0.2.0/LICENSE +21 -0
  3. metacooler-0.2.0/PKG-INFO +296 -0
  4. metacooler-0.2.0/README.md +257 -0
  5. metacooler-0.2.0/README.qmd +178 -0
  6. metacooler-0.2.0/benchmarks/.gitignore +9 -0
  7. metacooler-0.2.0/benchmarks/README.md +84 -0
  8. metacooler-0.2.0/benchmarks/bench.sh +180 -0
  9. metacooler-0.2.0/benchmarks/benchmarks.qmd +1285 -0
  10. metacooler-0.2.0/benchmarks/simulate.py +457 -0
  11. metacooler-0.2.0/benchmarks/targets.py +61 -0
  12. metacooler-0.2.0/docs/api/io.md +79 -0
  13. metacooler-0.2.0/docs/api/metacooler.md +38 -0
  14. metacooler-0.2.0/docs/api/ops.md +41 -0
  15. metacooler-0.2.0/docs/assets/metacooler-mark.svg +1 -0
  16. metacooler-0.2.0/docs/changelog.md +649 -0
  17. metacooler-0.2.0/docs/cli.md +1631 -0
  18. metacooler-0.2.0/docs/concepts.md +153 -0
  19. metacooler-0.2.0/docs/format.md +311 -0
  20. metacooler-0.2.0/docs/guides/collect.md +148 -0
  21. metacooler-0.2.0/docs/guides/export.md +250 -0
  22. metacooler-0.2.0/docs/guides/from-cool.md +84 -0
  23. metacooler-0.2.0/docs/guides/from-pairs.md +344 -0
  24. metacooler-0.2.0/docs/guides/multireso.md +203 -0
  25. metacooler-0.2.0/docs/index.md +58 -0
  26. metacooler-0.2.0/docs/installation.md +52 -0
  27. metacooler-0.2.0/docs/javascripts/metacooler.js +32 -0
  28. metacooler-0.2.0/docs/quickstart.md +187 -0
  29. metacooler-0.2.0/docs/stylesheets/metacooler.css +1617 -0
  30. metacooler-0.2.0/docs/why.md +85 -0
  31. metacooler-0.2.0/overrides/main.html +12 -0
  32. metacooler-0.2.0/overrides/partials/header.html +60 -0
  33. metacooler-0.2.0/overrides/partials/mc-page-footer.html +43 -0
  34. metacooler-0.2.0/overrides/partials/search.html +8 -0
  35. metacooler-0.2.0/pyproject.toml +148 -0
  36. metacooler-0.2.0/src/metacooler/__init__.py +204 -0
  37. metacooler-0.2.0/src/metacooler/_version.py +5 -0
  38. metacooler-0.2.0/src/metacooler/api.py +923 -0
  39. metacooler-0.2.0/src/metacooler/cli/__init__.py +1 -0
  40. metacooler-0.2.0/src/metacooler/cli/_options.py +333 -0
  41. metacooler-0.2.0/src/metacooler/cli/_provenance.py +187 -0
  42. metacooler-0.2.0/src/metacooler/cli/cmd_aggregate.py +90 -0
  43. metacooler-0.2.0/src/metacooler/cli/cmd_annotate.py +187 -0
  44. metacooler-0.2.0/src/metacooler/cli/cmd_attrs.py +148 -0
  45. metacooler-0.2.0/src/metacooler/cli/cmd_binnify.py +92 -0
  46. metacooler-0.2.0/src/metacooler/cli/cmd_check.py +50 -0
  47. metacooler-0.2.0/src/metacooler/cli/cmd_collect.py +228 -0
  48. metacooler-0.2.0/src/metacooler/cli/cmd_cp.py +127 -0
  49. metacooler-0.2.0/src/metacooler/cli/cmd_create.py +102 -0
  50. metacooler-0.2.0/src/metacooler/cli/cmd_create_cool.py +144 -0
  51. metacooler-0.2.0/src/metacooler/cli/cmd_create_pairs.py +216 -0
  52. metacooler-0.2.0/src/metacooler/cli/cmd_dump.py +210 -0
  53. metacooler-0.2.0/src/metacooler/cli/cmd_extract.py +112 -0
  54. metacooler-0.2.0/src/metacooler/cli/cmd_flatten.py +51 -0
  55. metacooler-0.2.0/src/metacooler/cli/cmd_info.py +128 -0
  56. metacooler-0.2.0/src/metacooler/cli/cmd_ls.py +92 -0
  57. metacooler-0.2.0/src/metacooler/cli/cmd_merge.py +80 -0
  58. metacooler-0.2.0/src/metacooler/cli/cmd_metadata.py +168 -0
  59. metacooler-0.2.0/src/metacooler/cli/cmd_mv.py +72 -0
  60. metacooler-0.2.0/src/metacooler/cli/cmd_network.py +91 -0
  61. metacooler-0.2.0/src/metacooler/cli/cmd_ps.py +210 -0
  62. metacooler-0.2.0/src/metacooler/cli/cmd_qc.py +150 -0
  63. metacooler-0.2.0/src/metacooler/cli/cmd_reassign.py +198 -0
  64. metacooler-0.2.0/src/metacooler/cli/cmd_rm.py +55 -0
  65. metacooler-0.2.0/src/metacooler/cli/cmd_show.py +170 -0
  66. metacooler-0.2.0/src/metacooler/cli/cmd_stack.py +140 -0
  67. metacooler-0.2.0/src/metacooler/cli/cmd_tree.py +70 -0
  68. metacooler-0.2.0/src/metacooler/cli/cmd_zoomify.py +99 -0
  69. metacooler-0.2.0/src/metacooler/cli/logging_utils.py +67 -0
  70. metacooler-0.2.0/src/metacooler/cli/main.py +275 -0
  71. metacooler-0.2.0/src/metacooler/filters.py +487 -0
  72. metacooler-0.2.0/src/metacooler/io/__init__.py +1 -0
  73. metacooler-0.2.0/src/metacooler/io/_utils.py +1372 -0
  74. metacooler-0.2.0/src/metacooler/io/annotate.py +817 -0
  75. metacooler-0.2.0/src/metacooler/io/collect.py +1287 -0
  76. metacooler-0.2.0/src/metacooler/io/colspec.py +317 -0
  77. metacooler-0.2.0/src/metacooler/io/contigs.py +137 -0
  78. metacooler-0.2.0/src/metacooler/io/create.py +3257 -0
  79. metacooler-0.2.0/src/metacooler/io/dump.py +364 -0
  80. metacooler-0.2.0/src/metacooler/io/extract.py +210 -0
  81. metacooler-0.2.0/src/metacooler/io/flatten.py +87 -0
  82. metacooler-0.2.0/src/metacooler/io/genomes.py +71 -0
  83. metacooler-0.2.0/src/metacooler/io/merge.py +356 -0
  84. metacooler-0.2.0/src/metacooler/io/mmetacool.py +383 -0
  85. metacooler-0.2.0/src/metacooler/io/network.py +188 -0
  86. metacooler-0.2.0/src/metacooler/io/reassign.py +1011 -0
  87. metacooler-0.2.0/src/metacooler/ops/__init__.py +1 -0
  88. metacooler-0.2.0/src/metacooler/ops/aggregate.py +245 -0
  89. metacooler-0.2.0/src/metacooler/ops/binnify.py +795 -0
  90. metacooler-0.2.0/src/metacooler/ops/ps.py +468 -0
  91. metacooler-0.2.0/src/metacooler/ops/qc.py +129 -0
  92. metacooler-0.2.0/src/metacooler/ops/range.py +75 -0
  93. metacooler-0.2.0/src/metacooler/ops/show.py +862 -0
  94. metacooler-0.2.0/src/metacooler/ops/zoomify.py +457 -0
  95. metacooler-0.2.0/src/metacooler/ps.py +466 -0
  96. metacooler-0.2.0/src/metacooler/qc.py +497 -0
  97. metacooler-0.2.0/src/metacooler/schema.py +1369 -0
  98. metacooler-0.2.0/src/metacooler/uri.py +45 -0
  99. metacooler-0.2.0/tests/_cli_output.py +48 -0
  100. metacooler-0.2.0/tests/_cools.py +72 -0
  101. metacooler-0.2.0/tests/conftest.py +369 -0
  102. metacooler-0.2.0/tests/data/assembly_1.chrom.sizes +44 -0
  103. metacooler-0.2.0/tests/data/assembly_1.fa +8317 -0
  104. metacooler-0.2.0/tests/data/assembly_1.fa.fai +44 -0
  105. metacooler-0.2.0/tests/data/assembly_1_1kb.metacool +0 -0
  106. metacooler-0.2.0/tests/data/assembly_1_1kb.mmetacool +0 -0
  107. metacooler-0.2.0/tests/data/assembly_1_DpnII-digested.bed +2658 -0
  108. metacooler-0.2.0/tests/data/assembly_1_rep1_1kb.cool +0 -0
  109. metacooler-0.2.0/tests/data/assembly_1_rep1_1kb.mcool +0 -0
  110. metacooler-0.2.0/tests/data/assembly_1_rep1_1kb.metacool +0 -0
  111. metacooler-0.2.0/tests/data/assembly_1_rep1_DpnII.cool +0 -0
  112. metacooler-0.2.0/tests/data/assembly_1_rep1_DpnII.mcool +0 -0
  113. metacooler-0.2.0/tests/data/assembly_1_rep1_DpnII.metacool +0 -0
  114. metacooler-0.2.0/tests/data/assembly_1_rep2_1kb.cool +0 -0
  115. metacooler-0.2.0/tests/data/assembly_1_rep2_1kb.metacool +0 -0
  116. metacooler-0.2.0/tests/data/assembly_1_rep2_DpnII.cool +0 -0
  117. metacooler-0.2.0/tests/data/assembly_1_rep2_DpnII.metacool +0 -0
  118. metacooler-0.2.0/tests/data/assembly_2.chrom.sizes +30 -0
  119. metacooler-0.2.0/tests/data/assembly_2.fa +8375 -0
  120. metacooler-0.2.0/tests/data/assembly_2.fa.fai +30 -0
  121. metacooler-0.2.0/tests/data/assembly_2_DpnII-digested.bed +2582 -0
  122. metacooler-0.2.0/tests/data/assembly_2_rep1_1kb.cool +0 -0
  123. metacooler-0.2.0/tests/data/assembly_2_rep1_1kb.mcool +0 -0
  124. metacooler-0.2.0/tests/data/assembly_2_rep1_1kb.metacool +0 -0
  125. metacooler-0.2.0/tests/data/assembly_2_rep1_DpnII.cool +0 -0
  126. metacooler-0.2.0/tests/data/assembly_2_rep1_DpnII.mcool +0 -0
  127. metacooler-0.2.0/tests/data/assembly_2_rep1_DpnII.metacool +0 -0
  128. metacooler-0.2.0/tests/data/assembly_2_rep2_1kb.cool +0 -0
  129. metacooler-0.2.0/tests/data/assembly_2_rep2_1kb.metacool +0 -0
  130. metacooler-0.2.0/tests/data/assembly_2_rep2_DpnII.cool +0 -0
  131. metacooler-0.2.0/tests/data/assembly_2_rep2_DpnII.metacool +0 -0
  132. metacooler-0.2.0/tests/data/cli_tests.sh +666 -0
  133. metacooler-0.2.0/tests/data/contigs_table_1.tsv +45 -0
  134. metacooler-0.2.0/tests/data/contigs_table_2.tsv +31 -0
  135. metacooler-0.2.0/tests/data/generate-raw-files.py +291 -0
  136. metacooler-0.2.0/tests/data/mag_table_1.tsv +11 -0
  137. metacooler-0.2.0/tests/data/mag_table_2.tsv +9 -0
  138. metacooler-0.2.0/tests/data/metadata.yaml +20 -0
  139. metacooler-0.2.0/tests/data/raw-to-cool.sh +44 -0
  140. metacooler-0.2.0/tests/test_aggregate.py +34 -0
  141. metacooler-0.2.0/tests/test_annotate.py +666 -0
  142. metacooler-0.2.0/tests/test_api.py +441 -0
  143. metacooler-0.2.0/tests/test_audit_regressions.py +511 -0
  144. metacooler-0.2.0/tests/test_binnify.py +207 -0
  145. metacooler-0.2.0/tests/test_binnify_streaming.py +168 -0
  146. metacooler-0.2.0/tests/test_check.py +180 -0
  147. metacooler-0.2.0/tests/test_cli.py +235 -0
  148. metacooler-0.2.0/tests/test_cli_collect.py +245 -0
  149. metacooler-0.2.0/tests/test_cli_comprehensive.py +2050 -0
  150. metacooler-0.2.0/tests/test_cli_create.py +1208 -0
  151. metacooler-0.2.0/tests/test_cli_edge_cases.py +1942 -0
  152. metacooler-0.2.0/tests/test_cli_mmetacool.py +152 -0
  153. metacooler-0.2.0/tests/test_cli_network.py +382 -0
  154. metacooler-0.2.0/tests/test_cli_stack.py +233 -0
  155. metacooler-0.2.0/tests/test_collect.py +918 -0
  156. metacooler-0.2.0/tests/test_colspec.py +278 -0
  157. metacooler-0.2.0/tests/test_contigs.py +216 -0
  158. metacooler-0.2.0/tests/test_cooler_compat.py +1014 -0
  159. metacooler-0.2.0/tests/test_create_contig_table.py +336 -0
  160. metacooler-0.2.0/tests/test_create_correctness.py +816 -0
  161. metacooler-0.2.0/tests/test_create_edge_cases.py +994 -0
  162. metacooler-0.2.0/tests/test_create_multiple_pairs.py +479 -0
  163. metacooler-0.2.0/tests/test_dump.py +303 -0
  164. metacooler-0.2.0/tests/test_extract.py +161 -0
  165. metacooler-0.2.0/tests/test_filters.py +506 -0
  166. metacooler-0.2.0/tests/test_flatten.py +60 -0
  167. metacooler-0.2.0/tests/test_import_cool.py +632 -0
  168. metacooler-0.2.0/tests/test_index_retrieval.py +402 -0
  169. metacooler-0.2.0/tests/test_info_mmetacool.py +66 -0
  170. metacooler-0.2.0/tests/test_init.py +192 -0
  171. metacooler-0.2.0/tests/test_merge.py +150 -0
  172. metacooler-0.2.0/tests/test_metadata_reserved.py +72 -0
  173. metacooler-0.2.0/tests/test_mmetacool_io.py +252 -0
  174. metacooler-0.2.0/tests/test_network.py +158 -0
  175. metacooler-0.2.0/tests/test_nproc.py +221 -0
  176. metacooler-0.2.0/tests/test_pixel_aggregation.py +239 -0
  177. metacooler-0.2.0/tests/test_ps.py +579 -0
  178. metacooler-0.2.0/tests/test_qc.py +604 -0
  179. metacooler-0.2.0/tests/test_range.py +52 -0
  180. metacooler-0.2.0/tests/test_reassign.py +1075 -0
  181. metacooler-0.2.0/tests/test_regressions.py +1380 -0
  182. metacooler-0.2.0/tests/test_release_audit.py +1003 -0
  183. metacooler-0.2.0/tests/test_schema.py +106 -0
  184. metacooler-0.2.0/tests/test_schema_mmetacool.py +120 -0
  185. metacooler-0.2.0/tests/test_schema_validation.py +275 -0
  186. metacooler-0.2.0/tests/test_show.py +534 -0
  187. metacooler-0.2.0/tests/test_storage_filters.py +193 -0
  188. metacooler-0.2.0/tests/test_table_formats.py +521 -0
  189. metacooler-0.2.0/tests/test_uri.py +56 -0
  190. metacooler-0.2.0/tests/test_zoomify.py +100 -0
  191. 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
@@ -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
+ [![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue)](https://www.python.org/downloads/) [![PyPI version](https://img.shields.io/pypi/v/metacooler.svg)](https://pypi.org/project/metacooler/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![codecov](https://codecov.io/gh/js2264/metacooler/branch/devel/graph/badge.svg?token=XMYgQxb7KH)](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
+ [![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue)](https://www.python.org/downloads/) [![PyPI version](https://img.shields.io/pypi/v/metacooler.svg)](https://pypi.org/project/metacooler/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![codecov](https://codecov.io/gh/js2264/metacooler/branch/devel/graph/badge.svg?token=XMYgQxb7KH)](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.