MultiMM 1.0.16__tar.gz → 1.0.17__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.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.2
1
+ Metadata-Version: 2.4
2
2
  Name: MultiMM
3
- Version: 1.0.16
3
+ Version: 1.0.17
4
4
  Summary: A tool for chromatin modeling from nucleosomes to chromosomal territories.
5
5
  Home-page: https://github.com/SFGLab/MultiMM
6
6
  Author: Sebastian Korsak
@@ -34,6 +34,7 @@ Dynamic: description
34
34
  Dynamic: description-content-type
35
35
  Dynamic: home-page
36
36
  Dynamic: license
37
+ Dynamic: license-file
37
38
  Dynamic: requires-dist
38
39
  Dynamic: requires-python
39
40
  Dynamic: summary
@@ -55,6 +56,7 @@ After running the MultiMM model, users obtain a genome-wide structure. Users can
55
56
  - Efficient simulation of chromatin interactions using 3D conformations.
56
57
  - Can simulate the scales of nucleosomes, TADs, compartments, chromosomal territories and interactions with lamina. Scalable simulations across different force fields and resolution levels.
57
58
  - Compatible with modern GPU-accelerated simulation libraries. CPU acceleration can also be done.
59
+ - Possibility of creation of ensembles of 3D structures of chromatin.
58
60
 
59
61
  ## About Operating Systems
60
62
 
@@ -71,6 +73,7 @@ PyPI software: https://pypi.org/project/MultiMM/.
71
73
 
72
74
  ## Input Data
73
75
 
76
+ ### Loops (bedpe file)
74
77
  MultiMM relies on three types of datasets:
75
78
 
76
79
  - Loop interactions in `bedpe` format (mandatory).
@@ -87,6 +90,7 @@ chr10 101190000 101200000 chr10 101470000 101480000 181
87
90
  chr10 101600000 101605000 chr10 101805000 101810000 152
88
91
  ```
89
92
 
93
+ ### Compartments
90
94
  The file may contain interactions for all chromosomes, which MultiMM can automatically model. For single-cell data, users can provide a file with the second and third columns identical (the same for the fifth and sixth columns) and strength set to 1.
91
95
 
92
96
  For **(sub)compartment interactions**, the file should be in the format produced by the CALDER software: https://github.com/CSOgroup/CALDER2. Users do not need to run CALDER specifically, but the file format must match. The file should contain at least the first four columns with chromosome, regions, and the subcompartment label. Example:
@@ -98,10 +102,46 @@ chr1 1400001 1850000 A.1.1.1.1.2.1.2.2.2.1 1 . 1400001 1850000 #FF0000
98
102
  chr1 1850001 2100000 B.1.1.2.2.1.2.1 0.5 . 1850001 2100000 #DADAFF
99
103
  ```
100
104
 
105
+ Alternatively, the user can provide a file in `.tsv` format with the first eigenvector. MultiMM would discretise it and convert it to compartments.
106
+
107
+ ```txt
108
+ chrom start end E1
109
+ chr1 600000 700000 0.05836110001861745
110
+ chr1 800000 900000 0.8317623736592369
111
+ chr1 900000 1000000 0.9789303554074167
112
+ chr1 1000000 1100000 1.060977133694018
113
+ chr1 1100000 1200000 1.0742104160308021
114
+ chr1 1200000 1300000 0.9966570829436122
115
+ chr1 1300000 1400000 1.032129387572702
116
+ chr1 1400000 1500000 1.145813878361721
117
+ ```
118
+
119
+ ### Nucleosomes
120
+
101
121
  For **ATAC-Seq data**, users should provide a file with p-values in BigWig format. The `pyBigWig` library is required, which does not work on Windows systems.
102
122
 
103
123
  **Note:** At present, MultiMM only works for human genome data. The code may run for other organisms with some debugging and modifications. We hope that it will be generalized in future versions. *MultiMM can run for different types of datasets. It is possible to call loops from any kind of experiment: Hi-C, scHi-C, ChIA-PET, Hi-ChIP. However, we cannot guarantee that the default choice of parameters is the most appropriate one for any dataset. Therefore, the user should test it and check the convergence of the algorithm for their own data. Before making any changes in the parameters, read the method paper carefully and try to understand the function of each force.*
104
124
 
125
+ ### Definition of a region based on a gene (optional)
126
+
127
+ In case that you would like to model a region around a gene, it is enough if you load a `.tsv` file with genes and determine either the gene name or the gene id.
128
+
129
+ The file should look like as the following one,
130
+
131
+ ```text
132
+ gene_id gene_name chromosome start end
133
+ ENSG00000160072 ATAD3B chr1 1471765 1497848
134
+ ENSG00000279928 DDX11L17 chr1 182696 184174
135
+ ENSG00000228037 chr1 2581560 2584533
136
+ ENSG00000142611 PRDM16 chr1 3069168 3438621
137
+ ENSG00000284616 chr1 5301928 5307394
138
+ ENSG00000157911 PEX10 chr1 2403964 2413797
139
+ ENSG00000269896 chr1 2350414 2352820
140
+ ENSG00000228463 chr1 257864 359681
141
+ ENSG00000260972 chr1 5492978 5494674
142
+ ENSG00000224340 chr1 10054445 10054781
143
+ ```
144
+
105
145
  ## Usage
106
146
  All the model's parameters are specified in a `config.ini` file. This file should have the following format:
107
147
 
@@ -175,9 +215,13 @@ We would like once again to thank people who developed `pyvista` library and all
175
215
 
176
216
  MultiMM has numerous configurable parameters. Below is a description of each argument and its default values. The defaults have been tested for genome-wide simulation but can be modified in the configuration file if needed. Units are typically assumed based on OpenMM conventions, though explicit unit specification is not required.
177
217
 
218
+ Here we can see the long table of the simulation arguments. Somtimes MultiMM might not work for some choices of arguments. For example:
219
+
220
+ * If you would like to model lamina interaction having disabled compartment interactions.
221
+ * If you do not provide appropriate data i.e. for compartmentalization but you have enabled (sub)compartent-specific forcefield.
178
222
 
223
+ Therefore, it is advisable to read the paper and understand well the meaning of each force before you start running simulations. MultiMM is a research model, not a market product and thus it requires a level of expertise (despite the easiness of usage) to underatand and run it.
179
224
 
180
- This version should now be more precise and polished. Let me know if you'd like to adjust anything further!
181
225
 
182
226
  | Argument Name | Type | Value | Units | Description |
183
227
  |------------------------------|--------------|-------------|---------------|-------------|
@@ -193,8 +237,13 @@ This version should now be more precise and polished. Let me know if you'd like
193
237
  | N_BEADS | int | 50000 | None | Number of Simulation Beads. |
194
238
  | COMPARTMENT_PATH | str | None | None | It should be a `.bed` file with subcompartments from Calder. |
195
239
  | LOOPS_PATH | str | None | None | A `.bedpe` file path with loops. It is required. |
240
+ | EIGENVECTOR_TSV | str | '' | None | Compartmentalization in the format of the first eigenvector of Hi-C in TSV data. |
196
241
  | ATACSEQ_PATH | str | None | None | A `.bw` or `.BigWig` file path with atacseq data for nucleosome interpolation. It is not required. |
197
242
  | OUT_PATH | str | results | None | Output folder name. |
243
+ | GENE_TSV | str | '' | None | A .tsv with genes and their locations in the genome. |
244
+ | GENE_NAME | str | '' | None | The name of the gene of interest. |
245
+ | GENE_ID | str | '' | None | The id of the gene of interest. |
246
+ | GENE_WINDOW | int | 200000| bp | The window around the area of the gene of interest. |
198
247
  | LOC_START | int | None | None | Starting region coordinate (*in case that you do not want to model the whole genome*). |
199
248
  | LOC_END | int | None | None | Ending region coordinate (*in case that you do not want to model the whole genome*). |
200
249
  | CHROM | str | None | None | Chromosome that corresponds the the modelling region of interest (*in case that you do not want to model the whole genome*). |
@@ -255,8 +304,8 @@ This version should now be more precise and polished. Let me know if you'd like
255
304
 
256
305
  ## Copyrights
257
306
 
258
- The software is freely distributed under the GNU license and everybody can use it how they want, improve it, or apply it to their research interests. In case that the software would be used for research, we would like that you will cite our paper:
307
+ The software is freely distributed under the GNU license and everybody is free to use it for their research interests following the open-source lisence of MultiMM. In case that the software would be used for research or any other activity, the method paper should be cited:
259
308
 
260
309
  - Korsak, Sevastianos, Krzysztof Banecki, and Dariusz Plewczynski. "Multiscale molecular modeling of chromatin with MultiMM: From nucleosomes to the whole genome." Computational and Structural Biotechnology Journal 23 (2024): 3537-3548.
261
310
 
262
- Please, communicate with the authors in case that you would like to contribute in this model, and you would like to improve it.
311
+ Please, communicate with the authors in case that you would like to contribute in this model and you would like to improve it. In case, that you have problems to run it, your feedback is very valuable to us and we are open to help you.
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.2
1
+ Metadata-Version: 2.4
2
2
  Name: MultiMM
3
- Version: 1.0.16
3
+ Version: 1.0.17
4
4
  Summary: A tool for chromatin modeling from nucleosomes to chromosomal territories.
5
5
  Home-page: https://github.com/SFGLab/MultiMM
6
6
  Author: Sebastian Korsak
@@ -34,6 +34,7 @@ Dynamic: description
34
34
  Dynamic: description-content-type
35
35
  Dynamic: home-page
36
36
  Dynamic: license
37
+ Dynamic: license-file
37
38
  Dynamic: requires-dist
38
39
  Dynamic: requires-python
39
40
  Dynamic: summary
@@ -55,6 +56,7 @@ After running the MultiMM model, users obtain a genome-wide structure. Users can
55
56
  - Efficient simulation of chromatin interactions using 3D conformations.
56
57
  - Can simulate the scales of nucleosomes, TADs, compartments, chromosomal territories and interactions with lamina. Scalable simulations across different force fields and resolution levels.
57
58
  - Compatible with modern GPU-accelerated simulation libraries. CPU acceleration can also be done.
59
+ - Possibility of creation of ensembles of 3D structures of chromatin.
58
60
 
59
61
  ## About Operating Systems
60
62
 
@@ -71,6 +73,7 @@ PyPI software: https://pypi.org/project/MultiMM/.
71
73
 
72
74
  ## Input Data
73
75
 
76
+ ### Loops (bedpe file)
74
77
  MultiMM relies on three types of datasets:
75
78
 
76
79
  - Loop interactions in `bedpe` format (mandatory).
@@ -87,6 +90,7 @@ chr10 101190000 101200000 chr10 101470000 101480000 181
87
90
  chr10 101600000 101605000 chr10 101805000 101810000 152
88
91
  ```
89
92
 
93
+ ### Compartments
90
94
  The file may contain interactions for all chromosomes, which MultiMM can automatically model. For single-cell data, users can provide a file with the second and third columns identical (the same for the fifth and sixth columns) and strength set to 1.
91
95
 
92
96
  For **(sub)compartment interactions**, the file should be in the format produced by the CALDER software: https://github.com/CSOgroup/CALDER2. Users do not need to run CALDER specifically, but the file format must match. The file should contain at least the first four columns with chromosome, regions, and the subcompartment label. Example:
@@ -98,10 +102,46 @@ chr1 1400001 1850000 A.1.1.1.1.2.1.2.2.2.1 1 . 1400001 1850000 #FF0000
98
102
  chr1 1850001 2100000 B.1.1.2.2.1.2.1 0.5 . 1850001 2100000 #DADAFF
99
103
  ```
100
104
 
105
+ Alternatively, the user can provide a file in `.tsv` format with the first eigenvector. MultiMM would discretise it and convert it to compartments.
106
+
107
+ ```txt
108
+ chrom start end E1
109
+ chr1 600000 700000 0.05836110001861745
110
+ chr1 800000 900000 0.8317623736592369
111
+ chr1 900000 1000000 0.9789303554074167
112
+ chr1 1000000 1100000 1.060977133694018
113
+ chr1 1100000 1200000 1.0742104160308021
114
+ chr1 1200000 1300000 0.9966570829436122
115
+ chr1 1300000 1400000 1.032129387572702
116
+ chr1 1400000 1500000 1.145813878361721
117
+ ```
118
+
119
+ ### Nucleosomes
120
+
101
121
  For **ATAC-Seq data**, users should provide a file with p-values in BigWig format. The `pyBigWig` library is required, which does not work on Windows systems.
102
122
 
103
123
  **Note:** At present, MultiMM only works for human genome data. The code may run for other organisms with some debugging and modifications. We hope that it will be generalized in future versions. *MultiMM can run for different types of datasets. It is possible to call loops from any kind of experiment: Hi-C, scHi-C, ChIA-PET, Hi-ChIP. However, we cannot guarantee that the default choice of parameters is the most appropriate one for any dataset. Therefore, the user should test it and check the convergence of the algorithm for their own data. Before making any changes in the parameters, read the method paper carefully and try to understand the function of each force.*
104
124
 
125
+ ### Definition of a region based on a gene (optional)
126
+
127
+ In case that you would like to model a region around a gene, it is enough if you load a `.tsv` file with genes and determine either the gene name or the gene id.
128
+
129
+ The file should look like as the following one,
130
+
131
+ ```text
132
+ gene_id gene_name chromosome start end
133
+ ENSG00000160072 ATAD3B chr1 1471765 1497848
134
+ ENSG00000279928 DDX11L17 chr1 182696 184174
135
+ ENSG00000228037 chr1 2581560 2584533
136
+ ENSG00000142611 PRDM16 chr1 3069168 3438621
137
+ ENSG00000284616 chr1 5301928 5307394
138
+ ENSG00000157911 PEX10 chr1 2403964 2413797
139
+ ENSG00000269896 chr1 2350414 2352820
140
+ ENSG00000228463 chr1 257864 359681
141
+ ENSG00000260972 chr1 5492978 5494674
142
+ ENSG00000224340 chr1 10054445 10054781
143
+ ```
144
+
105
145
  ## Usage
106
146
  All the model's parameters are specified in a `config.ini` file. This file should have the following format:
107
147
 
@@ -175,9 +215,13 @@ We would like once again to thank people who developed `pyvista` library and all
175
215
 
176
216
  MultiMM has numerous configurable parameters. Below is a description of each argument and its default values. The defaults have been tested for genome-wide simulation but can be modified in the configuration file if needed. Units are typically assumed based on OpenMM conventions, though explicit unit specification is not required.
177
217
 
218
+ Here we can see the long table of the simulation arguments. Somtimes MultiMM might not work for some choices of arguments. For example:
219
+
220
+ * If you would like to model lamina interaction having disabled compartment interactions.
221
+ * If you do not provide appropriate data i.e. for compartmentalization but you have enabled (sub)compartent-specific forcefield.
178
222
 
223
+ Therefore, it is advisable to read the paper and understand well the meaning of each force before you start running simulations. MultiMM is a research model, not a market product and thus it requires a level of expertise (despite the easiness of usage) to underatand and run it.
179
224
 
180
- This version should now be more precise and polished. Let me know if you'd like to adjust anything further!
181
225
 
182
226
  | Argument Name | Type | Value | Units | Description |
183
227
  |------------------------------|--------------|-------------|---------------|-------------|
@@ -193,8 +237,13 @@ This version should now be more precise and polished. Let me know if you'd like
193
237
  | N_BEADS | int | 50000 | None | Number of Simulation Beads. |
194
238
  | COMPARTMENT_PATH | str | None | None | It should be a `.bed` file with subcompartments from Calder. |
195
239
  | LOOPS_PATH | str | None | None | A `.bedpe` file path with loops. It is required. |
240
+ | EIGENVECTOR_TSV | str | '' | None | Compartmentalization in the format of the first eigenvector of Hi-C in TSV data. |
196
241
  | ATACSEQ_PATH | str | None | None | A `.bw` or `.BigWig` file path with atacseq data for nucleosome interpolation. It is not required. |
197
242
  | OUT_PATH | str | results | None | Output folder name. |
243
+ | GENE_TSV | str | '' | None | A .tsv with genes and their locations in the genome. |
244
+ | GENE_NAME | str | '' | None | The name of the gene of interest. |
245
+ | GENE_ID | str | '' | None | The id of the gene of interest. |
246
+ | GENE_WINDOW | int | 200000| bp | The window around the area of the gene of interest. |
198
247
  | LOC_START | int | None | None | Starting region coordinate (*in case that you do not want to model the whole genome*). |
199
248
  | LOC_END | int | None | None | Ending region coordinate (*in case that you do not want to model the whole genome*). |
200
249
  | CHROM | str | None | None | Chromosome that corresponds the the modelling region of interest (*in case that you do not want to model the whole genome*). |
@@ -255,8 +304,8 @@ This version should now be more precise and polished. Let me know if you'd like
255
304
 
256
305
  ## Copyrights
257
306
 
258
- The software is freely distributed under the GNU license and everybody can use it how they want, improve it, or apply it to their research interests. In case that the software would be used for research, we would like that you will cite our paper:
307
+ The software is freely distributed under the GNU license and everybody is free to use it for their research interests following the open-source lisence of MultiMM. In case that the software would be used for research or any other activity, the method paper should be cited:
259
308
 
260
309
  - Korsak, Sevastianos, Krzysztof Banecki, and Dariusz Plewczynski. "Multiscale molecular modeling of chromatin with MultiMM: From nucleosomes to the whole genome." Computational and Structural Biotechnology Journal 23 (2024): 3537-3548.
261
310
 
262
- Please, communicate with the authors in case that you would like to contribute in this model, and you would like to improve it.
311
+ Please, communicate with the authors in case that you would like to contribute in this model and you would like to improve it. In case, that you have problems to run it, your feedback is very valuable to us and we are open to help you.
@@ -15,6 +15,7 @@ After running the MultiMM model, users obtain a genome-wide structure. Users can
15
15
  - Efficient simulation of chromatin interactions using 3D conformations.
16
16
  - Can simulate the scales of nucleosomes, TADs, compartments, chromosomal territories and interactions with lamina. Scalable simulations across different force fields and resolution levels.
17
17
  - Compatible with modern GPU-accelerated simulation libraries. CPU acceleration can also be done.
18
+ - Possibility of creation of ensembles of 3D structures of chromatin.
18
19
 
19
20
  ## About Operating Systems
20
21
 
@@ -31,6 +32,7 @@ PyPI software: https://pypi.org/project/MultiMM/.
31
32
 
32
33
  ## Input Data
33
34
 
35
+ ### Loops (bedpe file)
34
36
  MultiMM relies on three types of datasets:
35
37
 
36
38
  - Loop interactions in `bedpe` format (mandatory).
@@ -47,6 +49,7 @@ chr10 101190000 101200000 chr10 101470000 101480000 181
47
49
  chr10 101600000 101605000 chr10 101805000 101810000 152
48
50
  ```
49
51
 
52
+ ### Compartments
50
53
  The file may contain interactions for all chromosomes, which MultiMM can automatically model. For single-cell data, users can provide a file with the second and third columns identical (the same for the fifth and sixth columns) and strength set to 1.
51
54
 
52
55
  For **(sub)compartment interactions**, the file should be in the format produced by the CALDER software: https://github.com/CSOgroup/CALDER2. Users do not need to run CALDER specifically, but the file format must match. The file should contain at least the first four columns with chromosome, regions, and the subcompartment label. Example:
@@ -58,10 +61,46 @@ chr1 1400001 1850000 A.1.1.1.1.2.1.2.2.2.1 1 . 1400001 1850000 #FF0000
58
61
  chr1 1850001 2100000 B.1.1.2.2.1.2.1 0.5 . 1850001 2100000 #DADAFF
59
62
  ```
60
63
 
64
+ Alternatively, the user can provide a file in `.tsv` format with the first eigenvector. MultiMM would discretise it and convert it to compartments.
65
+
66
+ ```txt
67
+ chrom start end E1
68
+ chr1 600000 700000 0.05836110001861745
69
+ chr1 800000 900000 0.8317623736592369
70
+ chr1 900000 1000000 0.9789303554074167
71
+ chr1 1000000 1100000 1.060977133694018
72
+ chr1 1100000 1200000 1.0742104160308021
73
+ chr1 1200000 1300000 0.9966570829436122
74
+ chr1 1300000 1400000 1.032129387572702
75
+ chr1 1400000 1500000 1.145813878361721
76
+ ```
77
+
78
+ ### Nucleosomes
79
+
61
80
  For **ATAC-Seq data**, users should provide a file with p-values in BigWig format. The `pyBigWig` library is required, which does not work on Windows systems.
62
81
 
63
82
  **Note:** At present, MultiMM only works for human genome data. The code may run for other organisms with some debugging and modifications. We hope that it will be generalized in future versions. *MultiMM can run for different types of datasets. It is possible to call loops from any kind of experiment: Hi-C, scHi-C, ChIA-PET, Hi-ChIP. However, we cannot guarantee that the default choice of parameters is the most appropriate one for any dataset. Therefore, the user should test it and check the convergence of the algorithm for their own data. Before making any changes in the parameters, read the method paper carefully and try to understand the function of each force.*
64
83
 
84
+ ### Definition of a region based on a gene (optional)
85
+
86
+ In case that you would like to model a region around a gene, it is enough if you load a `.tsv` file with genes and determine either the gene name or the gene id.
87
+
88
+ The file should look like as the following one,
89
+
90
+ ```text
91
+ gene_id gene_name chromosome start end
92
+ ENSG00000160072 ATAD3B chr1 1471765 1497848
93
+ ENSG00000279928 DDX11L17 chr1 182696 184174
94
+ ENSG00000228037 chr1 2581560 2584533
95
+ ENSG00000142611 PRDM16 chr1 3069168 3438621
96
+ ENSG00000284616 chr1 5301928 5307394
97
+ ENSG00000157911 PEX10 chr1 2403964 2413797
98
+ ENSG00000269896 chr1 2350414 2352820
99
+ ENSG00000228463 chr1 257864 359681
100
+ ENSG00000260972 chr1 5492978 5494674
101
+ ENSG00000224340 chr1 10054445 10054781
102
+ ```
103
+
65
104
  ## Usage
66
105
  All the model's parameters are specified in a `config.ini` file. This file should have the following format:
67
106
 
@@ -135,9 +174,13 @@ We would like once again to thank people who developed `pyvista` library and all
135
174
 
136
175
  MultiMM has numerous configurable parameters. Below is a description of each argument and its default values. The defaults have been tested for genome-wide simulation but can be modified in the configuration file if needed. Units are typically assumed based on OpenMM conventions, though explicit unit specification is not required.
137
176
 
177
+ Here we can see the long table of the simulation arguments. Somtimes MultiMM might not work for some choices of arguments. For example:
178
+
179
+ * If you would like to model lamina interaction having disabled compartment interactions.
180
+ * If you do not provide appropriate data i.e. for compartmentalization but you have enabled (sub)compartent-specific forcefield.
138
181
 
182
+ Therefore, it is advisable to read the paper and understand well the meaning of each force before you start running simulations. MultiMM is a research model, not a market product and thus it requires a level of expertise (despite the easiness of usage) to underatand and run it.
139
183
 
140
- This version should now be more precise and polished. Let me know if you'd like to adjust anything further!
141
184
 
142
185
  | Argument Name | Type | Value | Units | Description |
143
186
  |------------------------------|--------------|-------------|---------------|-------------|
@@ -153,8 +196,13 @@ This version should now be more precise and polished. Let me know if you'd like
153
196
  | N_BEADS | int | 50000 | None | Number of Simulation Beads. |
154
197
  | COMPARTMENT_PATH | str | None | None | It should be a `.bed` file with subcompartments from Calder. |
155
198
  | LOOPS_PATH | str | None | None | A `.bedpe` file path with loops. It is required. |
199
+ | EIGENVECTOR_TSV | str | '' | None | Compartmentalization in the format of the first eigenvector of Hi-C in TSV data. |
156
200
  | ATACSEQ_PATH | str | None | None | A `.bw` or `.BigWig` file path with atacseq data for nucleosome interpolation. It is not required. |
157
201
  | OUT_PATH | str | results | None | Output folder name. |
202
+ | GENE_TSV | str | '' | None | A .tsv with genes and their locations in the genome. |
203
+ | GENE_NAME | str | '' | None | The name of the gene of interest. |
204
+ | GENE_ID | str | '' | None | The id of the gene of interest. |
205
+ | GENE_WINDOW | int | 200000| bp | The window around the area of the gene of interest. |
158
206
  | LOC_START | int | None | None | Starting region coordinate (*in case that you do not want to model the whole genome*). |
159
207
  | LOC_END | int | None | None | Ending region coordinate (*in case that you do not want to model the whole genome*). |
160
208
  | CHROM | str | None | None | Chromosome that corresponds the the modelling region of interest (*in case that you do not want to model the whole genome*). |
@@ -215,8 +263,8 @@ This version should now be more precise and polished. Let me know if you'd like
215
263
 
216
264
  ## Copyrights
217
265
 
218
- The software is freely distributed under the GNU license and everybody can use it how they want, improve it, or apply it to their research interests. In case that the software would be used for research, we would like that you will cite our paper:
266
+ The software is freely distributed under the GNU license and everybody is free to use it for their research interests following the open-source lisence of MultiMM. In case that the software would be used for research or any other activity, the method paper should be cited:
219
267
 
220
268
  - Korsak, Sevastianos, Krzysztof Banecki, and Dariusz Plewczynski. "Multiscale molecular modeling of chromatin with MultiMM: From nucleosomes to the whole genome." Computational and Structural Biotechnology Journal 23 (2024): 3537-3548.
221
269
 
222
- Please, communicate with the authors in case that you would like to contribute in this model, and you would like to improve it.
270
+ Please, communicate with the authors in case that you would like to contribute in this model and you would like to improve it. In case, that you have problems to run it, your feedback is very valuable to us and we are open to help you.
@@ -6,7 +6,7 @@ with open('README.md', 'r', encoding='utf-8') as f:
6
6
 
7
7
  setup(
8
8
  name='MultiMM', # Package name
9
- version='1.0.16', # Version of the software
9
+ version='1.0.17', # Version of the software
10
10
  description='A tool for chromatin modeling from nucleosomes to chromosomal territories.',
11
11
  long_description=long_description,
12
12
  long_description_content_type='text/markdown',
@@ -1,4 +1,4 @@
1
1
  # Importing specific functions or classes from submodules
2
2
  from .run import main
3
3
 
4
- __version__ = "1.0.16"
4
+ __version__ = "1.0.17"
@@ -10,10 +10,9 @@ from openmm.unit import Quantity
10
10
 
11
11
  # Dynamically set the default path to the XML file in the package
12
12
  try:
13
- with importlib.resources.path('loopsage.forcefields', 'classic_sm_ff.xml') as default_xml_path:
13
+ with importlib.resources.path('simulation.forcefields', 'ff.xml') as default_xml_path:
14
14
  default_xml_path = str(default_xml_path)
15
15
  except FileNotFoundError:
16
- # If running in a development setup without the resource installed, fallback to a relative path
17
16
  default_xml_path = 'simulation/forcefields/ff.xml'
18
17
 
19
18
  @dataclass
@@ -146,7 +145,12 @@ args = ListOfArgs([
146
145
  Arg('FORCEFIELD_PATH', help="Path to XML file with forcefield.", type=str, default=default_xml_path, val=default_xml_path),
147
146
  Arg('N_BEADS', help="Number of Simulation Beads.", type=int, default='50000', val='50000'),
148
147
  Arg('COMPARTMENT_PATH', help="It should be a .bed file with subcompartments from Calder (or something in the same format).", type=str, default='', val=''),
148
+ Arg('EIGENVECTOR_TSV', help="Compartmentalization in the format of the first eigenvector of Hi-C in tsv data.", type=str, default='', val=''),
149
149
  Arg('LOOPS_PATH', help="A .bedpe file path with loops. It is required.", type=str, default='', val=''),
150
+ Arg('GENE_TSV', help="A .tsv with genes and their locations in the genome.", type=str, default='', val=''),
151
+ Arg('GENE_NAME', help="The name of the gene of interest.", type=str, default='', val=''),
152
+ Arg('GENE_ID', help="The id of the gene of interest.", type=str, default='', val=''),
153
+ Arg('GENE_WINDOW', help="The window around of the area around the gene of interest.", type=int, default='200000', val='200000'),
150
154
  Arg('ATACSEQ_PATH', help="A .bw or .BigWig file path with atacseq data. It is not required.", type=str, default='', val=''),
151
155
  Arg('OUT_PATH', help="Output folder name.", type=str, default='results', val='results'),
152
156
  Arg('LOC_START', help="Starting region coordinate.", type=int, default='', val=''),
@@ -176,7 +180,7 @@ args = ListOfArgs([
176
180
  Arg('EV_USE_EXCLUDED_VOLUME', help="Use excluded volume.", type=bool, default='True', val='True'),
177
181
  Arg('EV_EPSILON', help="Epsilon parameter.", type=float, default='100.0', val='100.0'),
178
182
  Arg('EV_R_SMALL', help="Add something small in denominator to make it not exploding all the time.", type=float, default='0.05', val='0.05'),
179
- Arg('EV_POWER', help="Power in the exponent of EV potential.", type=float, default='3.0', val='3.0'),
183
+ Arg('EV_POWER', help="Power in the exponent of EV potential.", type=float, default='6.0', val='6.0'),
180
184
 
181
185
  # Spherical container
182
186
  Arg('SC_USE_SPHERICAL_CONTAINER', help='Use Spherical container', type=bool, default='False', val='False'),
@@ -30,22 +30,40 @@ class MultiMM:
30
30
  os.makedirs(os.path.join(self.save_path, 'plots'), exist_ok=True)
31
31
 
32
32
  self.args = args
33
+ chrom = args.CHROM
33
34
  coords = [args.LOC_START,args.LOC_END] if args.LOC_START!=None else None
35
+
36
+ if (args.GENE_TSV!=None):
37
+ if args.GENE_ID!=None:
38
+ print('Gene ID:',args.GENE_ID)
39
+ chrom, coords = get_gene_region(gene_tsv=args.GENE_TSV,gene_id=args.GENE_ID,window_size=args.GENE_WINDOW)
40
+ print(f'We model the region {coords[0]}-{coords[1]} of chrom {chrom} of the gene {args.GENE_ID}.\n')
41
+ elif args.GENE_NAME!=None:
42
+ print('Gene name:',args.GENE_NAME)
43
+ chrom, coords = get_gene_region(gene_tsv=args.GENE_TSV,gene_name=args.GENE_NAME,window_size=args.GENE_WINDOW)
44
+ print(f'We model the region {coords[0]}-{coords[1]} of chrom {chrom} of the gene {args.GENE_NAME}.\n')
45
+ else:
46
+ raise InterruptedError('You did not provide gene name or ID.')
34
47
 
35
48
  # Compartments
36
- if args.COMPARTMENT_PATH!=None:
49
+ if args.EIGENVECTOR_TSV!=None:
50
+ if args.EIGENVECTOR_TSV.lower().endswith('.tsv'):
51
+ self.Cs, self.chr_ends = get_eigenvector(args.EIGENVECTOR_TSV, args.N_BEADS, chrom, coords)
52
+ else:
53
+ raise InterruptedError('Eigenvector should be in tsv format.')
54
+ elif args.COMPARTMENT_PATH!=None:
37
55
  if args.COMPARTMENT_PATH.lower().endswith('.bed'):
38
56
  self.Cs, self.chr_ends, self.chrom_idxs = import_bed(bed_file=args.COMPARTMENT_PATH,N_beads=self.args.N_BEADS,\
39
- chrom=self.args.CHROM,coords=coords,\
57
+ chrom=chrom,coords=coords,\
40
58
  save_path=self.save_path,\
41
59
  shuffle=args.SHUFFLE_CHROMS,seed=args.SHUFFLING_SEED)
42
60
  else:
43
61
  raise InterruptedError('Compartments file should be in .bed format.')
44
-
62
+
45
63
  # Loops
46
64
  if args.LOOPS_PATH.lower().endswith('.bedpe'):
47
65
  self.ms, self.ns, self.ds, self.chr_ends, self.chrom_idxs = import_mns_from_bedpe(bedpe_file = args.LOOPS_PATH,N_beads=self.args.N_BEADS,\
48
- coords = coords, chrom=args.CHROM,\
66
+ coords = coords, chrom=chrom,\
49
67
  path=self.save_path,\
50
68
  shuffle=args.SHUFFLE_CHROMS,seed=args.SHUFFLING_SEED,down_prob=args.DOWNSAMPLING_PROB)
51
69
  else:
@@ -9,18 +9,20 @@ from .args_definition import *
9
9
  from .model import *
10
10
 
11
11
  def args_tests(args):
12
- if args.COMPARTMENT_PATH==None and args.COB_USE_COMPARTMENT_BLOCKS:
12
+ if args.LOOPS_PATH==None or args.LOOPS_PATH=='':
13
+ raise InterruptedError('\033[91mMultiMM cannot run without providing interactions in .bedpe format!!!\033[0m')
14
+ elif (args.COMPARTMENT_PATH==None or args.COMPARTMENT_PATH=='') and args.COB_USE_COMPARTMENT_BLOCKS:
13
15
  raise InterruptedError('\033[91mYou cannot model compartments without providing a file in .bed format. Either disable COB_USE_COMPARTMENT_BLOCKS or import data from some compartment caller according to the documentation.\033[0m')
14
16
  elif args.NUC_DO_INTERPOLATION and args.ATACSEQ_PATH==None:
15
17
  raise InterruptedError('\033[91mYou enabled nucleosome simulation without providing nucleosome data. Either import a .bigwig file that shows nucleosome occupancy or disable NUC_DO_INTERPOLATION.\033[0m')
16
- elif args.COMPARTMENT_PATH==None and args.SCB_USE_SUBCOMPARTMENT_BLOCKS:
18
+ elif (args.COMPARTMENT_PATH==None or args.COMPARTMENT_PATH=='') and args.SCB_USE_SUBCOMPARTMENT_BLOCKS:
17
19
  raise InterruptedError('\033[91mYou cannot model subcompartments without providing a file in .bed format. Either disable SCB_USE_SUBCOMPARTMENT_BLOCKS or import data from some compartment caller according to the documentation.\033[0m')
18
20
  elif args.COMPARTMENT_PATH==None and args.IBL_USE_B_LAMINA_INTERACTION:
19
21
  raise InterruptedError('\033[91mLamina interactions are compartment specific, but you did not provide a .bed file for compartments. Maybe you should disable the IBL_USE_B_LAMINA_INTERACTION?\033[0m')
20
22
  elif args.IBL_USE_B_LAMINA_INTERACTION and not (args.SCB_USE_SUBCOMPARTMENT_BLOCKS or COB_USE_COMPARTMENT_BLOCKS):
21
23
  raise InterruptedError('\033[91mYou have enabled lamina interactions which are compartment specific, but you did not enable compartment or subcompartment forces. Please, read the documentation and the paper to understand better the forcefield!\033[0m')
22
24
  elif args.CF_USE_CENTRAL_FORCE and args.CHROM!=None:
23
- raise InterruptedError('\033[91mOoo00ops! You enabled chromosome attraction, but you want to model only one chromosome. Maybe disable CF_USE_CENTRAL_FORCE?')
25
+ raise InterruptedError('\033[91mOoo00ops! You enabled chromosome-specific attraction to the nucleolus, but you want to model only one chromosome. Maybe disable CF_USE_CENTRAL_FORCE?')
24
26
  elif args.CHB_USE_CHROMOSOMAL_BLOCKS and args.CHROM!=None:
25
27
  raise InterruptedError('\033[91mBetter disable CHB_USE_CHROMOSOMAL_BLOCKS when you model only one chromosome.')
26
28
 
@@ -6,6 +6,7 @@ from matplotlib.pyplot import figure
6
6
  from matplotlib.colors import to_hex
7
7
  import matplotlib.pyplot as plt
8
8
  import pandas as pd
9
+ import re
9
10
  import numpy as np
10
11
  from scipy.spatial import distance
11
12
  from tqdm import tqdm
@@ -188,8 +189,8 @@ def import_bed(bed_file,N_beads,coords=None,chrom=None,save_path='',shuffle=Fals
188
189
  val = -2
189
190
  elif comps_df[3][i].startswith('B.1') or comps_df[3][i].startswith('B1') or comps_df[3][i].startswith('B'):
190
191
  val = -1
191
-
192
192
  comps_array[comps_df[1][i]:comps_df[2][i]] = val
193
+
193
194
  np.save(save_path+'compartments.npy',comps_array)
194
195
  np.save(save_path+'chrom_idxs.npy',chrom_idxs)
195
196
  print('Done')
@@ -291,8 +292,8 @@ def import_mns_from_bedpe(bedpe_file, N_beads, coords=None, chrom=None, threshol
291
292
  ms, ns = mns[0,:], mns[1,:]
292
293
  ms[ms>=N_beads],ns[ns>=N_beads]=N_beads-1, N_beads-1
293
294
  ms,ns,cs = ms[ns>ms+min_loop_dist], ns[ns>ms+min_loop_dist], cs[ns>ms+min_loop_dist]
294
- ds = 0.1+0.1*min_max_trans(1/cs**2/3) if not np.all(cs==cs[0]) else np.ones(len(ms))
295
-
295
+ ds = 0.1+0.1*min_max_trans(1/cs**(2/3)) if not np.all(cs==cs[0]) else np.ones(len(ms))
296
+
296
297
  # Perform some data cleaning
297
298
  mask = (ns-ms)!=0
298
299
  ms = ms[mask]
@@ -415,3 +416,93 @@ def import_bw(bw_path,N_beads,coords=None,chrom=None,viz=False,binary=False,path
415
416
  np.save(path+'signal.npy',genomewide_signal)
416
417
 
417
418
  return genomewide_signal
419
+
420
+ def get_gene_region(gene_tsv, gene_id=None, gene_name=None, window_size = 200000):
421
+ '''
422
+ Input a gene tsv and ouputs a region around the gene
423
+ '''
424
+ genes = pd.read_csv(gene_tsv,sep='\t')
425
+ if gene_id!=None:
426
+ print('Region will be define based on gene ID.')
427
+ chrom = genes[genes['gene_id']==gene_id]['chromosome'].values[0]
428
+ start = genes[genes['gene_id']==gene_id]['start'].values[0]
429
+ end = genes[genes['gene_id']==gene_id]['end'].values[0]
430
+ elif gene_name!=None:
431
+ print('Region will be define based on gene name.')
432
+ chrom = genes[genes['gene_name']==gene_name]['chromosome'].values[0]
433
+ start = genes[genes['gene_name']==gene_name]['start'].values[0]
434
+ end = genes[genes['gene_name']==gene_name]['end'].values[0]
435
+
436
+ region = [max(0,int(start-window_size)), int(end+window_size)]
437
+ return chrom, region
438
+
439
+ def discretize_array(arr, thresholds):
440
+ """
441
+ Discretize a NumPy array based on 4 thresholds.
442
+
443
+ Parameters:
444
+ arr (np.ndarray): Input array.
445
+ thresholds (list or np.ndarray): List of 4 increasing threshold values.
446
+
447
+ Returns:
448
+ np.ndarray: Discretized array with integer labels from 0 to 4.
449
+ """
450
+ thresholds = np.sort(thresholds)
451
+ return np.digitize(arr, bins=thresholds, right=False)
452
+
453
+ def chrom_sort_key(chrom):
454
+ match = re.match(r'chr(\d+|X|Y)', chrom)
455
+ val = match.group(1)
456
+ return int(val) if val.isdigit() else {'X': 23, 'Y': 24}[val]
457
+
458
+ def get_eigenvector(eigenvec_tsv, N_beads, chrom=None, region=None, viz=False):
459
+ # Import dataset
460
+ eigenvector = pd.read_csv(eigenvec_tsv,sep='\t')
461
+ chroms = np.unique(eigenvector['chrom'].values)
462
+ chroms = sorted(chroms, key=chrom_sort_key)
463
+ n_chroms = len(np.unique(eigenvector['chrom'].values))
464
+
465
+ # Determine the ends of the chromosomes
466
+ chrom_ends = [0]
467
+ for i in range(n_chroms):
468
+ chr_end = max(eigenvector[eigenvector['chrom'] == chroms[i]]['end'].values)
469
+ chrom_ends.append(chr_end)
470
+ chrom_ends = np.array(chrom_ends)
471
+ eigenvector = eigenvector[eigenvector['chrom']==chrom].reset_index(drop=True)
472
+ eigenvec_array = eigenvector['E1'].values
473
+
474
+ # Determine spins by digitalizing array
475
+ thres = np.linspace(np.min(eigenvec_array), np.max(eigenvec_array), 5)[:4]
476
+ s_array = discretize_array(eigenvec_array, thres)-2
477
+ s_array[s_array<=0] = s_array[s_array<=0]-1
478
+ eigenvector['s'] = s_array
479
+
480
+ # Keep only the region of interest
481
+ if chrom!=None:
482
+ resolution = (region[1]-region[0])//N_beads
483
+ eigenvector = eigenvector[(eigenvector['end']>region[0])&(eigenvector['start']<region[1])].reset_index(drop=True)
484
+ eigenvector['start'] = (eigenvector['start']-region[0])//resolution
485
+ eigenvector['end'] = (eigenvector['end']-region[0])//resolution
486
+ else:
487
+ for i in range(n_chroms):
488
+ eigenvector[eigenvector['chrom']==chroms[i]]['start']=eigenvector[eigenvector['chrom']==chroms[i]]['start']+chrom_ends[i]
489
+ eigenvector[eigenvector['chrom']==chroms[i]]['end']=eigenvector[eigenvector['chrom']==chroms[i]]['end']+chrom_ends[i]
490
+ resolution = np.max(eigenvector['end'].values)//N_beads
491
+ eigenvector['start'] = eigenvector['start']//resolution
492
+ eigenvector['end'] = eigenvector['end']//resolution
493
+ eigenvec_array = eigenvector['E1'].values
494
+ starts, ends = eigenvector['start'].values, eigenvector['end'].values
495
+ starts[0], ends[-1] = 0, N_beads
496
+
497
+ Ss = eigenvector['s'].values
498
+ spins = np.zeros(N_beads)
499
+ for i in range(len(starts)):
500
+ spins[starts[i]:ends[i]] = Ss[i]
501
+
502
+ # In case that you want to see the eigenvector
503
+ if viz:
504
+ plt.plot(eigenvec_array)
505
+ plt.ylabel('Eigenvector')
506
+ plt.xlabel('Genomic Distance')
507
+ plt.show()
508
+ return spins, chrom_ends
File without changes
File without changes
File without changes