gnome3d 0.1.1__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 (66) hide show
  1. gnome3d-0.1.1/MANIFEST.in +5 -0
  2. gnome3d-0.1.1/PKG-INFO +157 -0
  3. gnome3d-0.1.1/README.md +130 -0
  4. gnome3d-0.1.1/SETTINGS.md +382 -0
  5. gnome3d-0.1.1/gnome3d/__init__.py +0 -0
  6. gnome3d-0.1.1/gnome3d/__main__.py +4 -0
  7. gnome3d-0.1.1/gnome3d/anchor_contacts.py +136 -0
  8. gnome3d-0.1.1/gnome3d/cli.py +198 -0
  9. gnome3d-0.1.1/gnome3d/data.py +529 -0
  10. gnome3d-0.1.1/gnome3d/extract.py +148 -0
  11. gnome3d-0.1.1/gnome3d/geometry.py +32 -0
  12. gnome3d-0.1.1/gnome3d/hierarchy.py +271 -0
  13. gnome3d-0.1.1/gnome3d/io.py +519 -0
  14. gnome3d-0.1.1/gnome3d/log.py +168 -0
  15. gnome3d-0.1.1/gnome3d/mc/__init__.py +33 -0
  16. gnome3d-0.1.1/gnome3d/mc/jax/__init__.py +19 -0
  17. gnome3d-0.1.1/gnome3d/mc/jax/arcs.py +1188 -0
  18. gnome3d-0.1.1/gnome3d/mc/jax/arcs_energy.py +213 -0
  19. gnome3d-0.1.1/gnome3d/mc/jax/memory.py +56 -0
  20. gnome3d-0.1.1/gnome3d/mc/jax/share.py +146 -0
  21. gnome3d-0.1.1/gnome3d/mc/jax/smooth.py +2536 -0
  22. gnome3d-0.1.1/gnome3d/mc/jax/util.py +204 -0
  23. gnome3d-0.1.1/gnome3d/mc/numba/__init__.py +28 -0
  24. gnome3d-0.1.1/gnome3d/mc/numba/arcs.py +158 -0
  25. gnome3d-0.1.1/gnome3d/mc/numba/arcs_solver.py +418 -0
  26. gnome3d-0.1.1/gnome3d/mc/numba/cells.py +70 -0
  27. gnome3d-0.1.1/gnome3d/mc/numba/common.py +370 -0
  28. gnome3d-0.1.1/gnome3d/mc/numba/heatmap.py +584 -0
  29. gnome3d-0.1.1/gnome3d/mc/numba/ib.py +168 -0
  30. gnome3d-0.1.1/gnome3d/mc/numba/smooth.py +521 -0
  31. gnome3d-0.1.1/gnome3d/mc/numba/terms.py +1124 -0
  32. gnome3d-0.1.1/gnome3d/pipeline/__init__.py +54 -0
  33. gnome3d-0.1.1/gnome3d/pipeline/coarse/__init__.py +59 -0
  34. gnome3d-0.1.1/gnome3d/pipeline/coarse/build.py +1224 -0
  35. gnome3d-0.1.1/gnome3d/pipeline/coarse/heatmap.py +148 -0
  36. gnome3d-0.1.1/gnome3d/pipeline/coarse/stages.py +197 -0
  37. gnome3d-0.1.1/gnome3d/pipeline/dag.py +67 -0
  38. gnome3d-0.1.1/gnome3d/pipeline/executor.py +385 -0
  39. gnome3d-0.1.1/gnome3d/pipeline/holes.py +261 -0
  40. gnome3d-0.1.1/gnome3d/pipeline/ib/__init__.py +35 -0
  41. gnome3d-0.1.1/gnome3d/pipeline/ib/arcs.py +332 -0
  42. gnome3d-0.1.1/gnome3d/pipeline/ib/buckets.py +24 -0
  43. gnome3d-0.1.1/gnome3d/pipeline/ib/chain.py +52 -0
  44. gnome3d-0.1.1/gnome3d/pipeline/ib/densify.py +190 -0
  45. gnome3d-0.1.1/gnome3d/pipeline/ib/estimate_dist.py +225 -0
  46. gnome3d-0.1.1/gnome3d/pipeline/ib/maxent.py +470 -0
  47. gnome3d-0.1.1/gnome3d/pipeline/ib/smooth.py +234 -0
  48. gnome3d-0.1.1/gnome3d/pipeline/ib/start.py +186 -0
  49. gnome3d-0.1.1/gnome3d/pipeline/multigpu.py +149 -0
  50. gnome3d-0.1.1/gnome3d/pipeline/registry.py +42 -0
  51. gnome3d-0.1.1/gnome3d/pipeline/relax.py +194 -0
  52. gnome3d-0.1.1/gnome3d/pipeline/stage.py +47 -0
  53. gnome3d-0.1.1/gnome3d/pipeline/state.py +113 -0
  54. gnome3d-0.1.1/gnome3d/pipeline/stitch.py +292 -0
  55. gnome3d-0.1.1/gnome3d/polymer.py +260 -0
  56. gnome3d-0.1.1/gnome3d/production.py +252 -0
  57. gnome3d-0.1.1/gnome3d/reconstruct.py +218 -0
  58. gnome3d-0.1.1/gnome3d/settings.py +1090 -0
  59. gnome3d-0.1.1/gnome3d/simulate.py +143 -0
  60. gnome3d-0.1.1/gnome3d/skeleton.py +328 -0
  61. gnome3d-0.1.1/gnome3d/tracks.py +237 -0
  62. gnome3d-0.1.1/gnome3d/types.py +213 -0
  63. gnome3d-0.1.1/gnome3d/util.py +104 -0
  64. gnome3d-0.1.1/gnome3d.egg-info/SOURCES.txt +63 -0
  65. gnome3d-0.1.1/pyproject.toml +121 -0
  66. gnome3d-0.1.1/setup.cfg +4 -0
@@ -0,0 +1,5 @@
1
+ # setuptools-scm adds every tracked file to the source distribution. The package needs these.
2
+ global-exclude *
3
+ include pyproject.toml README.md SETTINGS.md MANIFEST.in
4
+ graft gnome3d
5
+ global-exclude __pycache__ *.py[cod]
gnome3d-0.1.1/PKG-INFO ADDED
@@ -0,0 +1,157 @@
1
+ Metadata-Version: 2.4
2
+ Name: gnome3d
3
+ Version: 0.1.1
4
+ Summary: 3D chromatin structure modeling from ChIA-PET loops and Hi-C contacts
5
+ Project-URL: Repository, https://github.com/SFGLab/3dgnome-ng
6
+ Project-URL: Issues, https://github.com/SFGLab/3dgnome-ng/issues
7
+ Requires-Python: >=3.11
8
+ Description-Content-Type: text/markdown
9
+ Requires-Dist: numpy>=1.24.0
10
+ Requires-Dist: numba>=0.59.0
11
+ Requires-Dist: scipy>=1.10
12
+ Requires-Dist: threadpoolctl>=3.1
13
+ Provides-Extra: dev
14
+ Requires-Dist: ruff>=0.6; extra == "dev"
15
+ Requires-Dist: pyright>=1.1.380; extra == "dev"
16
+ Requires-Dist: pytest>=8; extra == "dev"
17
+ Provides-Extra: jax
18
+ Requires-Dist: jax>=0.4.30; extra == "jax"
19
+ Provides-Extra: extract
20
+ Requires-Dist: cooler>=0.9; extra == "extract"
21
+ Provides-Extra: validation
22
+ Requires-Dist: scipy>=1.10; extra == "validation"
23
+ Requires-Dist: cooler>=0.9; extra == "validation"
24
+ Requires-Dist: cooltools>=0.7; extra == "validation"
25
+ Requires-Dist: hicrep>=0.2.6; extra == "validation"
26
+ Requires-Dist: pyBigWig>=0.3.18; extra == "validation"
27
+
28
+ # 3D-GNOMEᴺᴳ
29
+
30
+ 3D-GNOMEᴺᴳ predicts the 3D structure of chromosomes from ChIA-PET loops and Hi-C contacts. It returns an ensemble of
31
+ bead chains as mmCIF files, one bead per kilobase in the production configuration. A run covers one region, one
32
+ chromosome or the whole genome.
33
+
34
+ ## Install
35
+
36
+ Python 3.11 or later is required.
37
+
38
+ ```bash
39
+ pip install gnome3d
40
+ ```
41
+
42
+ A checkout installs in place. The version is the latest git tag.
43
+
44
+ ```bash
45
+ python -m venv .venv
46
+ source .venv/bin/activate
47
+ pip install -e .
48
+ ```
49
+
50
+ Three extras add optional parts.
51
+
52
+ | Extra | Content |
53
+ |-------|---------|
54
+ | `jax` | The GPU kernels. This extra installs JAX for the CPU. Add the build for your hardware, as in `pip install -e ".[jax]" "jax[cuda12]"`. |
55
+ | `extract` | cooler, for `gnome3d extract`. |
56
+ | `dev` | ruff, pyright and pytest. |
57
+
58
+ ## Run
59
+
60
+ ```bash
61
+ gnome3d --config slurm/ensemble/gm12878_hic_arcs.ini --region chr1:18288319-20307135 -n 10 --out out/
62
+ ```
63
+
64
+ `--region` takes one region `chr1:18288319-20307135`, one chromosome `chr14`, a list `chr1,chr3,chrX` or a range
65
+ `chr1-chr22,chrX`. Without it the run covers chr1 to chr22 and chrX. `-n` is the number of structures. `--data-dir`
66
+ replaces `data_dir` of the config.
67
+
68
+ The run writes one mmCIF file and one bead table per structure, `chr1_18288319_20307135_s1.cif` and
69
+ `chr1_18288319_20307135_s1.beads.tsv` for the first structure of the command above. ChimeraX opens the CIF as one
70
+ chain. Loop anchors have the residue name ALA and the beads between them GLY.
71
+
72
+ `--members 0-9` selects structures by index in place of `-n`. Several jobs with disjoint sets produce the same ensemble
73
+ as one job. A job that starts again skips the structures that are already written.
74
+
75
+ The same run from Python:
76
+
77
+ ```python
78
+ from gnome3d.io import write_cif
79
+ from gnome3d.simulate import run_region
80
+
81
+ structures = run_region(
82
+ config_path="slurm/ensemble/gm12878_hic_arcs.ini",
83
+ region="chr1:18288319-20307135",
84
+ n_structures=10,
85
+ data_dir="data/GM12878",
86
+ )
87
+ for i, beads in enumerate(structures, start=1):
88
+ write_cif(f"structure_{i}.cif", beads, entry_id=f"structure_{i}")
89
+ ```
90
+
91
+ A bead is a tuple `(start, end, x, y, z, kind)`. `run_genome` takes the same region forms as the command and returns
92
+ one dict of chromosome to bead list per structure.
93
+
94
+ ## Configuration
95
+
96
+ A config is an ini file. [SETTINGS.md](SETTINGS.md) lists every key with its default, its production value and its
97
+ meaning. It also states the distance law. The production values are `CANONICAL` in
98
+ [gnome3d/production.py](gnome3d/production.py). The configs under `slurm/ensemble/` are generated from it by
99
+ `slurm/ensemble/make_configs.py`, one per cell line and input set.
100
+
101
+ ## Input files
102
+
103
+ The `[data]` section of the config points to the input files. The repository does not hold them.
104
+
105
+ | Key | Format | Content |
106
+ |-----|--------|---------|
107
+ | `anchors` | BED, `chr start end orientation` | Loop anchors with the orientation of the CTCF motif. |
108
+ | `clusters` | BEDPE, `chr1 s1 e1 chr2 s2 e2 score` | Loops as PET clusters. Several files give several loop factors, CTCF first. |
109
+ | `singletons` | BEDPE | Contacts for the exponent fit and the coarse heatmaps. ChIA-PET singletons or Hi-C bin pairs. |
110
+ | `segment_split` | BED | Segment breakpoints. |
111
+
112
+ `gnome3d extract` writes the bin pairs of one region of an mcool file in the format of `singletons`.
113
+
114
+ ```bash
115
+ gnome3d extract --mcool sample.mcool --region chr1:11500000-12600000 --out region.bedpe
116
+ ```
117
+
118
+ The optional inputs are a compartment track, an anchor activity track, an anchor contact table and a contact map for
119
+ the stretches without loops. SETTINGS.md describes them.
120
+
121
+ ## Tests
122
+
123
+ ```bash
124
+ .venv/bin/pytest # every test, about two and a half minutes on a laptop
125
+ .venv/bin/pytest -m "not slow" # without the files that take over a minute
126
+ ```
127
+
128
+ `tests/unit/` has one file per feature. `tests/integration/` runs the whole pipeline on synthetic inputs and on one
129
+ GM12878 region when its inputs are under `data/`.
130
+
131
+ ## Acknowledgements
132
+
133
+ 3D-GNOMEᴺᴳ builds on the 3D-GNOME family of tools and on the work of their authors. Please cite these papers when you
134
+ use it in academic work.
135
+
136
+ - Tang Z., Luo O. J., Li X., Zheng M., Zhu J. J., Szalaj P., Trzaskoma P., Magalska A., Wlodarczyk J., Ruszczycki B.,
137
+ Michalski P., Piecuch E., Wang P., Wang D., Tian S. Z., Penrad-Mobayed M., Sachs L. M., Ruan X., Wei C.-L., Liu E. T.,
138
+ Wilczynski G. M., Plewczynski D., Li G., Ruan Y. (2015). **CTCF-Mediated Human 3D Genome Architecture Reveals
139
+ Chromatin Topology for Transcription.** *Cell.*
140
+ [doi:10.1016/j.cell.2015.11.024](https://doi.org/10.1016/j.cell.2015.11.024)
141
+
142
+ - Szałaj P., Tang Z., Michalski P., Pietal M. J., Luo O. J., Sadowski M., Li X., Radew K., Ruan Y., Plewczynski D.
143
+ (2016). **An integrated 3-Dimensional Genome Modeling Engine for data-driven simulation of spatial genome
144
+ organization.** *Genome Research.* [doi:10.1101/gr.205062.116](https://doi.org/10.1101/gr.205062.116)
145
+
146
+ - Wlasnowolski M., Sadowski M., Czarnota T., Jodkowska K., Szalaj P., Tang Z., Ruan Y., Plewczynski D. (2020).
147
+ **3D-GNOME 2.0: a three-dimensional genome modeling engine for predicting structural variation-driven alterations of
148
+ chromatin spatial structure in the human genome.** *Nucleic Acids Research,* 48(W1), W170–W176.
149
+ [doi:10.1093/nar/gkaa388](https://doi.org/10.1093/nar/gkaa388)
150
+
151
+ - Wlasnowolski M., Kadlof M., Sengupta K., Plewczynski D. (2023). **3D-GNOME 3.0: a three-dimensional genome modelling
152
+ engine for analysing changes of promoter-enhancer contacts in the human genome.** *Nucleic Acids Research,* 51(W1),
153
+ W5–W10. [doi:10.1093/nar/gkad354](https://doi.org/10.1093/nar/gkad354)
154
+
155
+ - Wlasnowolski M., Grabowski P., Roszczyk D., Kaczmarski K., Plewczynski D. (2023). **cudaMMC: GPU-enhanced multiscale
156
+ Monte Carlo chromatin 3D modelling.** *Bioinformatics.*
157
+ [doi:10.1093/bioinformatics/btad588](https://doi.org/10.1093/bioinformatics/btad588)
@@ -0,0 +1,130 @@
1
+ # 3D-GNOMEᴺᴳ
2
+
3
+ 3D-GNOMEᴺᴳ predicts the 3D structure of chromosomes from ChIA-PET loops and Hi-C contacts. It returns an ensemble of
4
+ bead chains as mmCIF files, one bead per kilobase in the production configuration. A run covers one region, one
5
+ chromosome or the whole genome.
6
+
7
+ ## Install
8
+
9
+ Python 3.11 or later is required.
10
+
11
+ ```bash
12
+ pip install gnome3d
13
+ ```
14
+
15
+ A checkout installs in place. The version is the latest git tag.
16
+
17
+ ```bash
18
+ python -m venv .venv
19
+ source .venv/bin/activate
20
+ pip install -e .
21
+ ```
22
+
23
+ Three extras add optional parts.
24
+
25
+ | Extra | Content |
26
+ |-------|---------|
27
+ | `jax` | The GPU kernels. This extra installs JAX for the CPU. Add the build for your hardware, as in `pip install -e ".[jax]" "jax[cuda12]"`. |
28
+ | `extract` | cooler, for `gnome3d extract`. |
29
+ | `dev` | ruff, pyright and pytest. |
30
+
31
+ ## Run
32
+
33
+ ```bash
34
+ gnome3d --config slurm/ensemble/gm12878_hic_arcs.ini --region chr1:18288319-20307135 -n 10 --out out/
35
+ ```
36
+
37
+ `--region` takes one region `chr1:18288319-20307135`, one chromosome `chr14`, a list `chr1,chr3,chrX` or a range
38
+ `chr1-chr22,chrX`. Without it the run covers chr1 to chr22 and chrX. `-n` is the number of structures. `--data-dir`
39
+ replaces `data_dir` of the config.
40
+
41
+ The run writes one mmCIF file and one bead table per structure, `chr1_18288319_20307135_s1.cif` and
42
+ `chr1_18288319_20307135_s1.beads.tsv` for the first structure of the command above. ChimeraX opens the CIF as one
43
+ chain. Loop anchors have the residue name ALA and the beads between them GLY.
44
+
45
+ `--members 0-9` selects structures by index in place of `-n`. Several jobs with disjoint sets produce the same ensemble
46
+ as one job. A job that starts again skips the structures that are already written.
47
+
48
+ The same run from Python:
49
+
50
+ ```python
51
+ from gnome3d.io import write_cif
52
+ from gnome3d.simulate import run_region
53
+
54
+ structures = run_region(
55
+ config_path="slurm/ensemble/gm12878_hic_arcs.ini",
56
+ region="chr1:18288319-20307135",
57
+ n_structures=10,
58
+ data_dir="data/GM12878",
59
+ )
60
+ for i, beads in enumerate(structures, start=1):
61
+ write_cif(f"structure_{i}.cif", beads, entry_id=f"structure_{i}")
62
+ ```
63
+
64
+ A bead is a tuple `(start, end, x, y, z, kind)`. `run_genome` takes the same region forms as the command and returns
65
+ one dict of chromosome to bead list per structure.
66
+
67
+ ## Configuration
68
+
69
+ A config is an ini file. [SETTINGS.md](SETTINGS.md) lists every key with its default, its production value and its
70
+ meaning. It also states the distance law. The production values are `CANONICAL` in
71
+ [gnome3d/production.py](gnome3d/production.py). The configs under `slurm/ensemble/` are generated from it by
72
+ `slurm/ensemble/make_configs.py`, one per cell line and input set.
73
+
74
+ ## Input files
75
+
76
+ The `[data]` section of the config points to the input files. The repository does not hold them.
77
+
78
+ | Key | Format | Content |
79
+ |-----|--------|---------|
80
+ | `anchors` | BED, `chr start end orientation` | Loop anchors with the orientation of the CTCF motif. |
81
+ | `clusters` | BEDPE, `chr1 s1 e1 chr2 s2 e2 score` | Loops as PET clusters. Several files give several loop factors, CTCF first. |
82
+ | `singletons` | BEDPE | Contacts for the exponent fit and the coarse heatmaps. ChIA-PET singletons or Hi-C bin pairs. |
83
+ | `segment_split` | BED | Segment breakpoints. |
84
+
85
+ `gnome3d extract` writes the bin pairs of one region of an mcool file in the format of `singletons`.
86
+
87
+ ```bash
88
+ gnome3d extract --mcool sample.mcool --region chr1:11500000-12600000 --out region.bedpe
89
+ ```
90
+
91
+ The optional inputs are a compartment track, an anchor activity track, an anchor contact table and a contact map for
92
+ the stretches without loops. SETTINGS.md describes them.
93
+
94
+ ## Tests
95
+
96
+ ```bash
97
+ .venv/bin/pytest # every test, about two and a half minutes on a laptop
98
+ .venv/bin/pytest -m "not slow" # without the files that take over a minute
99
+ ```
100
+
101
+ `tests/unit/` has one file per feature. `tests/integration/` runs the whole pipeline on synthetic inputs and on one
102
+ GM12878 region when its inputs are under `data/`.
103
+
104
+ ## Acknowledgements
105
+
106
+ 3D-GNOMEᴺᴳ builds on the 3D-GNOME family of tools and on the work of their authors. Please cite these papers when you
107
+ use it in academic work.
108
+
109
+ - Tang Z., Luo O. J., Li X., Zheng M., Zhu J. J., Szalaj P., Trzaskoma P., Magalska A., Wlodarczyk J., Ruszczycki B.,
110
+ Michalski P., Piecuch E., Wang P., Wang D., Tian S. Z., Penrad-Mobayed M., Sachs L. M., Ruan X., Wei C.-L., Liu E. T.,
111
+ Wilczynski G. M., Plewczynski D., Li G., Ruan Y. (2015). **CTCF-Mediated Human 3D Genome Architecture Reveals
112
+ Chromatin Topology for Transcription.** *Cell.*
113
+ [doi:10.1016/j.cell.2015.11.024](https://doi.org/10.1016/j.cell.2015.11.024)
114
+
115
+ - Szałaj P., Tang Z., Michalski P., Pietal M. J., Luo O. J., Sadowski M., Li X., Radew K., Ruan Y., Plewczynski D.
116
+ (2016). **An integrated 3-Dimensional Genome Modeling Engine for data-driven simulation of spatial genome
117
+ organization.** *Genome Research.* [doi:10.1101/gr.205062.116](https://doi.org/10.1101/gr.205062.116)
118
+
119
+ - Wlasnowolski M., Sadowski M., Czarnota T., Jodkowska K., Szalaj P., Tang Z., Ruan Y., Plewczynski D. (2020).
120
+ **3D-GNOME 2.0: a three-dimensional genome modeling engine for predicting structural variation-driven alterations of
121
+ chromatin spatial structure in the human genome.** *Nucleic Acids Research,* 48(W1), W170–W176.
122
+ [doi:10.1093/nar/gkaa388](https://doi.org/10.1093/nar/gkaa388)
123
+
124
+ - Wlasnowolski M., Kadlof M., Sengupta K., Plewczynski D. (2023). **3D-GNOME 3.0: a three-dimensional genome modelling
125
+ engine for analysing changes of promoter-enhancer contacts in the human genome.** *Nucleic Acids Research,* 51(W1),
126
+ W5–W10. [doi:10.1093/nar/gkad354](https://doi.org/10.1093/nar/gkad354)
127
+
128
+ - Wlasnowolski M., Grabowski P., Roszczyk D., Kaczmarski K., Plewczynski D. (2023). **cudaMMC: GPU-enhanced multiscale
129
+ Monte Carlo chromatin 3D modelling.** *Bioinformatics.*
130
+ [doi:10.1093/bioinformatics/btad588](https://doi.org/10.1093/bioinformatics/btad588)