MultiMM 2.0.2__tar.gz → 2.1.0__tar.gz

multimm-2.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: MultiMM
+Version: 2.1.0
+Summary: A tool for chromatin modeling from nucleosomes to chromosomal territories.
+Author-email: Sebastian Korsak <s.korsak@datascience.edu.pl>
+License: GNU General Public License v3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: argparse>=1.4.0
+Requires-Dist: matplotlib>=3.8.2
+Requires-Dist: mdtraj>=1.9.9
+Requires-Dist: seaborn>=0.12.2
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: configparser>=6.0.1
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: pyBigWig>=0.3.22
+Requires-Dist: hilbertcurve>=2.0.5
+Requires-Dist: tqdm>=4.65.2
+Requires-Dist: pyvista[all]
+Requires-Dist: OpenMM>=8.5.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cooler>=0.10.2
+Requires-Dist: scikit-image>=0.21.0
+Provides-Extra: hic
+Requires-Dist: hic-straw>=1.3.1; extra == "hic"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: docformatter; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/multimm_logo.svg" alt="MultiMM" width="100%">
+</p>
+
+**MultiMM** is an [OpenMM](https://openmm.org)-based tool for building 3D models of chromatin, from single genomic regions to the whole human genome. It is *multiscale*: one energy function covers nucleosomes, loops and TADs, A/B compartments, chromosome territories and the nucleus. You give it loop calls, and optionally compartments or a Hi-C map, and it returns a 3D structure that you can open in any molecular viewer. The model is fast because it starts from a compact Hilbert-curve conformation and runs on GPUs through OpenMM.
+
+<p align="center">
+  <img src="docs/assets/workflow.png" alt="MultiMM workflow" width="720">
+</p>
+
+## Scales of modelling
+
+One energy function ties together five scales. Each is a different way of looking at the same chain of beads.
+
+| Scale | What it means | How MultiMM models it |
+|---|---|---|
+| **Nucleosome / fibre** | DNA wrapped around histones, forming a ~10 nm fibre | Beads joined by bonds and angle (stiffness) terms, with excluded volume so beads do not overlap |
+| **Loops** | Pairs of distant sites held together, e.g. by CTCF and cohesin | Harmonic springs between loop anchors, taken from your loop file |
+| **TADs / Hi-C contacts** | Domains that fold together more than with their surroundings | Optional restraints derived from a Hi-C map by Boltzmann inversion |
+| **A/B compartments** | Active (A) and inactive (B) chromatin that cluster by type | Soft attraction between beads of the same compartment type |
+| **Chromosomes and nucleus** | Chromosome territories inside a nucleus, anchored at the lamina | Container wall, lamina and chromosome-block forces |
+
+## Install
+
+From PyPI:
+
+```bash
+pip install MultiMM
+```
+
+With [uv](https://docs.astral.sh/uv/) (fast, isolated):
+
+```bash
+uv pip install MultiMM          # into the current environment
+uv tool install MultiMM         # or as a standalone command-line tool
+```
+
+For `.hic` Hi-C files, also install the optional reader (`pip install "MultiMM[hic]"`); `.cool` and `.mcool` files work out of the box.
+
+Requires Python 3.10 or newer. Linux is the main platform; macOS works without CUDA. The documentation covers installation from source.
+
+## Run
+
+All settings live in one config file:
+
+```bash
+MultiMM -c config.ini
+```
+
+Any setting can also be overridden on the command line, for example `--n_beads 2000`.
+
+## A config file
+
+You only write what you want to change; everything else has a default.
+
+```ini
+[Main]
+CHROM            = chr1
+LOC_START        = 160_000_000
+LOC_END          = 173_000_000
+N_BEADS          = 5000
+
+LOOPS_PATH       = data/loops.bedpe          ; chromatin loops
+COMPARTMENT_PATH = data/compartments.bed     ; optional A/B compartments
+COB_USE_COMPARTMENT_BLOCKS = True
+
+OUT_PATH         = results/chr1_region
+```
+
+## Documentation
+
+The full documentation, with the mathematics of every force and a table of all arguments, is written with [MkDocs](https://www.mkdocs.org) and its source is in [`docs/`](docs). To read it locally:
+
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
+## Development
+
+```bash
+git clone https://github.com/SFGLab/MultiMM.git
+cd MultiMM
+uv sync --extra dev             # or: pip install -e ".[dev]"
+```
+
+Run the tests (all are quick checks, no full simulation, about half a minute):
+
+```bash
+uv run pytest -q                # or: pytest -q
+uv run pytest tests/test_force_signs.py   # a single file
+```
+
+Console output has four levels: no flag shows only the pipeline stages and progress bars; `-v` adds details, `-vv` adds statistics tables, `-vvv` is fully verbose.
+
+## Citation
+
+If you use MultiMM in your research, please cite:
+
+> 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.
+
+## License
+
+MultiMM is free software, distributed under the GNU General Public License v3.0.

multimm-2.1.0/README.md

@@ -0,0 +1,104 @@
+<p align="center">
+  <img src="docs/assets/multimm_logo.svg" alt="MultiMM" width="100%">
+</p>
+
+**MultiMM** is an [OpenMM](https://openmm.org)-based tool for building 3D models of chromatin, from single genomic regions to the whole human genome. It is *multiscale*: one energy function covers nucleosomes, loops and TADs, A/B compartments, chromosome territories and the nucleus. You give it loop calls, and optionally compartments or a Hi-C map, and it returns a 3D structure that you can open in any molecular viewer. The model is fast because it starts from a compact Hilbert-curve conformation and runs on GPUs through OpenMM.
+
+<p align="center">
+  <img src="docs/assets/workflow.png" alt="MultiMM workflow" width="720">
+</p>
+
+## Scales of modelling
+
+One energy function ties together five scales. Each is a different way of looking at the same chain of beads.
+
+| Scale | What it means | How MultiMM models it |
+|---|---|---|
+| **Nucleosome / fibre** | DNA wrapped around histones, forming a ~10 nm fibre | Beads joined by bonds and angle (stiffness) terms, with excluded volume so beads do not overlap |
+| **Loops** | Pairs of distant sites held together, e.g. by CTCF and cohesin | Harmonic springs between loop anchors, taken from your loop file |
+| **TADs / Hi-C contacts** | Domains that fold together more than with their surroundings | Optional restraints derived from a Hi-C map by Boltzmann inversion |
+| **A/B compartments** | Active (A) and inactive (B) chromatin that cluster by type | Soft attraction between beads of the same compartment type |
+| **Chromosomes and nucleus** | Chromosome territories inside a nucleus, anchored at the lamina | Container wall, lamina and chromosome-block forces |
+
+## Install
+
+From PyPI:
+
+```bash
+pip install MultiMM
+```
+
+With [uv](https://docs.astral.sh/uv/) (fast, isolated):
+
+```bash
+uv pip install MultiMM          # into the current environment
+uv tool install MultiMM         # or as a standalone command-line tool
+```
+
+For `.hic` Hi-C files, also install the optional reader (`pip install "MultiMM[hic]"`); `.cool` and `.mcool` files work out of the box.
+
+Requires Python 3.10 or newer. Linux is the main platform; macOS works without CUDA. The documentation covers installation from source.
+
+## Run
+
+All settings live in one config file:
+
+```bash
+MultiMM -c config.ini
+```
+
+Any setting can also be overridden on the command line, for example `--n_beads 2000`.
+
+## A config file
+
+You only write what you want to change; everything else has a default.
+
+```ini
+[Main]
+CHROM            = chr1
+LOC_START        = 160_000_000
+LOC_END          = 173_000_000
+N_BEADS          = 5000
+
+LOOPS_PATH       = data/loops.bedpe          ; chromatin loops
+COMPARTMENT_PATH = data/compartments.bed     ; optional A/B compartments
+COB_USE_COMPARTMENT_BLOCKS = True
+
+OUT_PATH         = results/chr1_region
+```
+
+## Documentation
+
+The full documentation, with the mathematics of every force and a table of all arguments, is written with [MkDocs](https://www.mkdocs.org) and its source is in [`docs/`](docs). To read it locally:
+
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
+## Development
+
+```bash
+git clone https://github.com/SFGLab/MultiMM.git
+cd MultiMM
+uv sync --extra dev             # or: pip install -e ".[dev]"
+```
+
+Run the tests (all are quick checks, no full simulation, about half a minute):
+
+```bash
+uv run pytest -q                # or: pytest -q
+uv run pytest tests/test_force_signs.py   # a single file
+```
+
+Console output has four levels: no flag shows only the pipeline stages and progress bars; `-v` adds details, `-vv` adds statistics tables, `-vvv` is fully verbose.
+
+## Citation
+
+If you use MultiMM in your research, please cite:
+
+> 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.
+
+## License
+
+MultiMM is free software, distributed under the GNU General Public License v3.0.

{multimm-2.0.2 → multimm-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "MultiMM"
-version = "2.0.2"
+version = "2.1.0"
 description = "A tool for chromatin modeling from nucleosomes to chromosomal territories."
 readme = "README.md"
 authors = [
@@ -34,9 +34,13 @@ dependencies = [
     "pyvista[all]",
     "OpenMM>=8.5.1",
     "pydantic>=2.0.0",
+    "cooler>=0.10.2",
+    "scikit-image>=0.21.0",
 ]
 
 [project.optional-dependencies]
+# .hic files need hic-straw, which compiles C++ code and may fail to install; .cool/.mcool do not need it
+hic = ["hic-straw>=1.3.1"]
 dev = [
     "ruff",
     "black",

multimm-2.1.0/src/MultiMM.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: MultiMM
+Version: 2.1.0
+Summary: A tool for chromatin modeling from nucleosomes to chromosomal territories.
+Author-email: Sebastian Korsak <s.korsak@datascience.edu.pl>
+License: GNU General Public License v3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: scipy>=1.11
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: argparse>=1.4.0
+Requires-Dist: matplotlib>=3.8.2
+Requires-Dist: mdtraj>=1.9.9
+Requires-Dist: seaborn>=0.12.2
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: configparser>=6.0.1
+Requires-Dist: typing-extensions>=4.7.1
+Requires-Dist: pyBigWig>=0.3.22
+Requires-Dist: hilbertcurve>=2.0.5
+Requires-Dist: tqdm>=4.65.2
+Requires-Dist: pyvista[all]
+Requires-Dist: OpenMM>=8.5.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: cooler>=0.10.2
+Requires-Dist: scikit-image>=0.21.0
+Provides-Extra: hic
+Requires-Dist: hic-straw>=1.3.1; extra == "hic"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: docformatter; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/multimm_logo.svg" alt="MultiMM" width="100%">
+</p>
+
+**MultiMM** is an [OpenMM](https://openmm.org)-based tool for building 3D models of chromatin, from single genomic regions to the whole human genome. It is *multiscale*: one energy function covers nucleosomes, loops and TADs, A/B compartments, chromosome territories and the nucleus. You give it loop calls, and optionally compartments or a Hi-C map, and it returns a 3D structure that you can open in any molecular viewer. The model is fast because it starts from a compact Hilbert-curve conformation and runs on GPUs through OpenMM.
+
+<p align="center">
+  <img src="docs/assets/workflow.png" alt="MultiMM workflow" width="720">
+</p>
+
+## Scales of modelling
+
+One energy function ties together five scales. Each is a different way of looking at the same chain of beads.
+
+| Scale | What it means | How MultiMM models it |
+|---|---|---|
+| **Nucleosome / fibre** | DNA wrapped around histones, forming a ~10 nm fibre | Beads joined by bonds and angle (stiffness) terms, with excluded volume so beads do not overlap |
+| **Loops** | Pairs of distant sites held together, e.g. by CTCF and cohesin | Harmonic springs between loop anchors, taken from your loop file |
+| **TADs / Hi-C contacts** | Domains that fold together more than with their surroundings | Optional restraints derived from a Hi-C map by Boltzmann inversion |
+| **A/B compartments** | Active (A) and inactive (B) chromatin that cluster by type | Soft attraction between beads of the same compartment type |
+| **Chromosomes and nucleus** | Chromosome territories inside a nucleus, anchored at the lamina | Container wall, lamina and chromosome-block forces |
+
+## Install
+
+From PyPI:
+
+```bash
+pip install MultiMM
+```
+
+With [uv](https://docs.astral.sh/uv/) (fast, isolated):
+
+```bash
+uv pip install MultiMM          # into the current environment
+uv tool install MultiMM         # or as a standalone command-line tool
+```
+
+For `.hic` Hi-C files, also install the optional reader (`pip install "MultiMM[hic]"`); `.cool` and `.mcool` files work out of the box.
+
+Requires Python 3.10 or newer. Linux is the main platform; macOS works without CUDA. The documentation covers installation from source.
+
+## Run
+
+All settings live in one config file:
+
+```bash
+MultiMM -c config.ini
+```
+
+Any setting can also be overridden on the command line, for example `--n_beads 2000`.
+
+## A config file
+
+You only write what you want to change; everything else has a default.
+
+```ini
+[Main]
+CHROM            = chr1
+LOC_START        = 160_000_000
+LOC_END          = 173_000_000
+N_BEADS          = 5000
+
+LOOPS_PATH       = data/loops.bedpe          ; chromatin loops
+COMPARTMENT_PATH = data/compartments.bed     ; optional A/B compartments
+COB_USE_COMPARTMENT_BLOCKS = True
+
+OUT_PATH         = results/chr1_region
+```
+
+## Documentation
+
+The full documentation, with the mathematics of every force and a table of all arguments, is written with [MkDocs](https://www.mkdocs.org) and its source is in [`docs/`](docs). To read it locally:
+
+```bash
+pip install mkdocs-material
+mkdocs serve
+```
+
+## Development
+
+```bash
+git clone https://github.com/SFGLab/MultiMM.git
+cd MultiMM
+uv sync --extra dev             # or: pip install -e ".[dev]"
+```
+
+Run the tests (all are quick checks, no full simulation, about half a minute):
+
+```bash
+uv run pytest -q                # or: pytest -q
+uv run pytest tests/test_force_signs.py   # a single file
+```
+
+Console output has four levels: no flag shows only the pipeline stages and progress bars; `-v` adds details, `-vv` adds statistics tables, `-vvv` is fully verbose.
+
+## Citation
+
+If you use MultiMM in your research, please cite:
+
+> 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.
+
+## License
+
+MultiMM is free software, distributed under the GNU General Public License v3.0.

{multimm-2.0.2 → multimm-2.1.0}/src/MultiMM.egg-info/SOURCES.txt

@@ -12,16 +12,35 @@ src/multimm/args_definition.py
 src/multimm/bridge.py
 src/multimm/config.py
 src/multimm/enums.py
+src/multimm/facts.py
+src/multimm/hic_force.py
 src/multimm/initial_structure_tools.py
 src/multimm/logger.py
 src/multimm/model.py
 src/multimm/nucleosome_interpolation.py
 src/multimm/plots.py
+src/multimm/quality_tests.py
+src/multimm/read_hic.py
 src/multimm/run.py
+src/multimm/structural_analysis.py
 src/multimm/utils.py
 src/multimm/validation.py
 src/multimm/data/hg38_gtf_annotations.tsv
 src/multimm/forcefields/dna_histones_ff.xml
 src/multimm/forcefields/ff.xml
+tests/test_config.py
+tests/test_force_signs.py
+tests/test_genes.py
+tests/test_hic_force.py
+tests/test_known_issues.py
+tests/test_lamina.py
+tests/test_logger.py
+tests/test_loops.py
+tests/test_nucleosomes.py
+tests/test_presets.py
+tests/test_read_hic.py
 tests/test_run_validation.py
-tests/test_simulations.py
+tests/test_simulations.py
+tests/test_structure_tools.py
+tests/test_utils.py
+tests/test_validation_metrics.py

{multimm-2.0.2 → multimm-2.1.0}/src/MultiMM.egg-info/requires.txt

@@ -14,6 +14,8 @@ tqdm>=4.65.2
 pyvista[all]
 OpenMM>=8.5.1
 pydantic>=2.0.0
+cooler>=0.10.2
+scikit-image>=0.21.0
 
 [dev]
 ruff
@@ -21,3 +23,6 @@ black
 isort
 docformatter
 pytest
+
+[hic]
+hic-straw>=1.3.1

multimm-2.1.0/src/multimm/__init__.py

@@ -0,0 +1,11 @@
+from .bridge import SimulationEngine as SimulationEngine
+
+
+def main(*args, **kwargs):
+    """Command-line entry point (imported lazily so `python -m multimm.run` stays warning-free)."""
+    from .run import main as _main
+
+    return _main(*args, **kwargs)
+
+
+__version__ = "2.1.0"

{multimm-2.0.2 → multimm-2.1.0}/src/multimm/bridge.py

@@ -8,7 +8,6 @@ import openmm
 
 from .config import SimulationConfig
 from .model import MultiMM
-from .run import write_config
 
 logger = logging.getLogger(__name__)
 
@@ -91,6 +90,7 @@ class SimulationEngine:
         try:
             base_out_path = config.OUT_PATH
 
+            from .run import write_config  # lazy: keeps `python -m multimm.run` warning-free
             write_config(config)
 
             if config.GENERATE_ENSEMBLE and config.N_ENSEMBLE is not None:
@@ -141,6 +141,7 @@ class SimulationEngine:
         os.makedirs(metadata_dir, exist_ok=True)
         config_path = os.path.join(metadata_dir, "config_auto.ini")
 
+        from .run import write_config
         write_config(config)
 
         cmd = [