mutadock 2.1.0__tar.gz → 2.2.2__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.
- {mutadock-2.1.0 → mutadock-2.2.2}/.gitignore +12 -4
- {mutadock-2.1.0 → mutadock-2.2.2}/CHANGELOG.md +30 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/PKG-INFO +52 -19
- {mutadock-2.1.0 → mutadock-2.2.2}/README.md +49 -18
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/conf.py +2 -2
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/index.rst +88 -35
- {mutadock-2.1.0 → mutadock-2.2.2}/environment.yml +3 -2
- {mutadock-2.1.0 → mutadock-2.2.2}/install.sh +3 -1
- {mutadock-2.1.0 → mutadock-2.2.2}/pyproject.toml +11 -9
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/__init__.py +1 -1
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/np_docking.py +608 -537
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/vina_dock.py +28 -1
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/vina_helper.py +198 -38
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/csv_generator.py +2 -2
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/helpers.py +93 -9
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/quick.py +522 -496
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/test_np_docking.py +474 -471
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/test_vina_dock.py +30 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/test_vina_helper.py +1174 -939
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_helpers.py +52 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/win_install.bat +3 -1
- {mutadock-2.1.0 → mutadock-2.2.2}/.dockerignore +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/.pre-commit-config.yaml +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/.readthedocs.yaml +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/Dockerfile +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/LICENSE +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/data/4QJR.cif +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/data/BLOSUM62 +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/data/Ligand.sdf +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/data/PAM250 +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/Makefile +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/index.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.exceptions.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.np_docking.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.vina_dock.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.vina_helper.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.Amino.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.csv_generator.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.csv_sort.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.ddg_calc.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.ddg_calc_double.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.ddg_calc_triple.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.exceptions.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.generate_mutant_pdb.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.generate_mutants.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.helpers.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.np_mutation.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.predict_ddG.rst +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/docs/make.bat +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/pyrightconfig.json +0 -0
- {mutadock-2.1.0/src → mutadock-2.2.2/src/mutadock}/data/BLOSUM62 +0 -0
- {mutadock-2.1.0/src → mutadock-2.2.2/src/mutadock}/data/PAM250 +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/exceptions.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/Amino.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/csv_sort.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/ddg_calc.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/ddg_calc_double.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/ddg_calc_triple.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/exceptions.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/generate_mutant_pdb.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/generate_mutants.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/np_mutation.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/predict_ddG.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/assets/ngl.min.js +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/data.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/figures.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/html_report.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/ppt_report.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/report.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/structure.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/templates/report.html.j2 +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/conftest.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/conftest.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_csv_generator.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_csv_sort.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_ddg_calc.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_ddg_protocol.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_ddg_resume.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_generate_mutants.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_np_mutation.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_quick.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/__init__.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/conftest.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_data.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_figures.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_html.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_ppt.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_report.py +0 -0
- {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_structure.py +0 -0
|
@@ -87,14 +87,14 @@ demo/
|
|
|
87
87
|
# AutoDock result files
|
|
88
88
|
*.dlg
|
|
89
89
|
|
|
90
|
-
#
|
|
91
|
-
*_out.
|
|
90
|
+
# Raw multi-pose Vina output (also covered by *.pdbqt above)
|
|
91
|
+
*_out.pdbqt
|
|
92
92
|
|
|
93
93
|
# Per-run log files
|
|
94
94
|
*_log.txt
|
|
95
95
|
|
|
96
|
-
#
|
|
97
|
-
*
|
|
96
|
+
# Extracted best-pose SDF output
|
|
97
|
+
*_out.sdf
|
|
98
98
|
|
|
99
99
|
# Docking results aggregate
|
|
100
100
|
docking_results.csv
|
|
@@ -130,3 +130,11 @@ mutation_*/
|
|
|
130
130
|
|
|
131
131
|
# Timestamped backups created by backup()
|
|
132
132
|
backups/
|
|
133
|
+
|
|
134
|
+
# =============================================================================
|
|
135
|
+
# Project-specific: benchmark cross-validation reference dirs
|
|
136
|
+
# (already covered by the wholesale benchmark/ ignore above; listed explicitly
|
|
137
|
+
# so they stay ignored even if benchmark/ scripts are ever un-ignored)
|
|
138
|
+
# =============================================================================
|
|
139
|
+
benchmark/foldx_ref/
|
|
140
|
+
benchmark/mcsm_lig_ref/
|
|
@@ -7,12 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.2.2] - 2026-09-19
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- Local SDF and MOL2 ligand inputs are now validated for a parseable molecule and usable 3-D coordinates before Meeko preparation.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
- RDKit is now an explicit Python dependency rather than an implicit requirement of ligand preparation.
|
|
17
|
+
- Installation, AutoSite, matrix-loading, and generated-output guidance is consistent across the README, Sphinx documentation, environment file, installer scripts, and ignore rules.
|
|
18
|
+
|
|
19
|
+
## [2.2.1] - 2026-09-18
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
- Updated the PyPI and GitHub README for the 2.2 release series, including current docking outputs, reproducibility controls, resume behavior, input warnings, matrix caching, and subprocess timeout settings.
|
|
23
|
+
- Removed the stale fixed-score example and hard-coded coverage badge from the README.
|
|
24
|
+
|
|
25
|
+
## [2.2.0] - 2026-09-18
|
|
26
|
+
|
|
10
27
|
### Added
|
|
11
28
|
- **Per-item checkpoint/resume for ΔΔG.** `calc_ddg` / `calc_double_ddg` / `calc_triple_ddg` (and `md_ddg_single` / `md_ddg_double` / `md_ddg_triple` via a new `--resume` flag) can now continue an interrupted run: the output CSV is its own checkpoint, so an interruption partway through keeps the rows already computed and only the missing mutations/combinations are recomputed — instead of discarding everything and starting over. Each completed row is flushed immediately, a torn trailing line from a mid-write kill is dropped and recomputed cleanly, and resume refuses to mix rows written under a different `ddG_protocol` or `n_replicates` (it starts fresh in that case). `md_mutate` uses this automatically (driven by the existing append default), upgrading its previous coarse "skip only if the whole file is complete" check to true per-item resume — the same granularity the docking side already had via `*_completed.txt`.
|
|
12
29
|
- **Subprocess timeouts for external tools.** `mk_prepare_receptor`, AutoSite, and Vina are now each run with a wall-clock timeout so a single hung job can no longer stall an entire batch — a timeout raises the tool's domain error and the batch loop skips that receptor-ligand combination. Defaults are 15 min (receptor prep), 30 min (AutoSite), and 60 min (Vina), each overridable via `MUTADOCK_RECEPTOR_PREP_TIMEOUT` / `MUTADOCK_AUTOSITE_TIMEOUT` / `MUTADOCK_VINA_TIMEOUT` (seconds; set to `0` to disable that timeout).
|
|
13
30
|
- `read_partial_ddg()` helper in `mutation/helpers.py` — reads the complete rows of a partial ΔΔG CSV for resume, dropping any torn trailing line and enforcing a settings match.
|
|
14
31
|
- Regression tests: ΔΔG resume identity for single/double/triple (resumed run reproduces the exact row set, `sr` numbering, and `combination` names of a from-scratch run), `read_partial_ddg` guards, and TimeoutExpired→domain-error routing for all three subprocesses (including a real sleeping-subprocess timeout).
|
|
15
32
|
|
|
33
|
+
### Changed
|
|
34
|
+
- Docking result rows now record the Vina seed, box centre, box size, and exhaustiveness so every reported affinity retains its run provenance.
|
|
35
|
+
- Vina seed handling is explicit across the CLI and batch workflow; a command-line seed takes precedence over configuration only with a visible warning.
|
|
36
|
+
- Ambiguous simultaneous AutoSite and explicit-config requests are rejected instead of silently selecting one search box.
|
|
37
|
+
- Structure checks now warn about duplicated or highly similar chains that can unintentionally multiply mutation enumeration and docking work.
|
|
38
|
+
|
|
39
|
+
### Fixed
|
|
40
|
+
- Ligand preparation now adds hydrogens with 3-D coordinates before Meeko conversion, preventing polar hydrogens from being written at the origin and preserving hydrogen-bond donor typing.
|
|
41
|
+
- Per-receptor AutoSite boxes are carried through to the corresponding result row instead of being reported as if one global box had been used.
|
|
42
|
+
- Docking CSV append logic remains compatible with older result files while avoiding ragged rows when new provenance columns are present.
|
|
43
|
+
- AutoSite and Vina subprocess failures now preserve clearer context, and configuration/seed validation rejects invalid or contradictory inputs earlier.
|
|
44
|
+
- Substitution matrices now ship inside the installed package, and additional NCBI matrices are cached in a user-writable directory (`~/.cache/mutadock/matrices`, overridable with `MUTADOCK_DATA_DIR`) instead of attempting to write into `site-packages`.
|
|
45
|
+
|
|
16
46
|
## [2.1.0] - 2026-07-03
|
|
17
47
|
|
|
18
48
|
### Added
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mutadock
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.2.2
|
|
4
4
|
Summary: MUTADOCK is a comprehensive library designed for mutation studies and multiple receptor-ligand docking. Refer to README for more information.
|
|
5
5
|
Project-URL: Repository, https://github.com/naisarg14/mutadock
|
|
6
6
|
Project-URL: Issues, https://github.com/naisarg14/mutadock/issues
|
|
@@ -15,6 +15,7 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
|
|
|
15
15
|
Classifier: Programming Language :: Python :: 3.11
|
|
16
16
|
Classifier: Programming Language :: Python :: 3.12
|
|
17
17
|
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
|
|
18
|
+
Requires-Python: >=3.11
|
|
18
19
|
Requires-Dist: biopython
|
|
19
20
|
Requires-Dist: jinja2
|
|
20
21
|
Requires-Dist: matplotlib
|
|
@@ -26,6 +27,7 @@ Requires-Dist: pdbfixer
|
|
|
26
27
|
Requires-Dist: pyarrow
|
|
27
28
|
Requires-Dist: pyrosetta-installer
|
|
28
29
|
Requires-Dist: python-pptx
|
|
30
|
+
Requires-Dist: rdkit
|
|
29
31
|
Requires-Dist: tqdm
|
|
30
32
|
Provides-Extra: dev
|
|
31
33
|
Requires-Dist: black>=24.0; extra == 'dev'
|
|
@@ -48,7 +50,6 @@ Description-Content-Type: text/markdown
|
|
|
48
50
|
[](https://pypi.org/project/mutadock/)
|
|
49
51
|
[](https://pypi.org/project/mutadock/)
|
|
50
52
|
[](https://mutadock.readthedocs.io/en/latest/)
|
|
51
|
-
[]()
|
|
52
53
|
|
|
53
54
|
## Introduction
|
|
54
55
|
|
|
@@ -71,6 +72,13 @@ MUTADOCK is a comprehensive library for protein mutation studies and multi-recep
|
|
|
71
72
|
- Simple CLI for each workflow step
|
|
72
73
|
- Python API for scripting and integration into existing pipelines
|
|
73
74
|
|
|
75
|
+
### What's new in the 2.2 series
|
|
76
|
+
|
|
77
|
+
- Reproducible docking with a configurable random seed (default `19`) and complete run provenance in `docking_results.csv`
|
|
78
|
+
- Safer input validation, including ligand 3D/hydrogen checks and warnings for multi-model, multi-chain, similar-chain, altloc, and insertion-code structures
|
|
79
|
+
- Resumable mutation and docking workflows plus configurable subprocess timeouts
|
|
80
|
+
- PAM250 and BLOSUM62 bundled in the installed package; additional matrices are cached outside the installation directory
|
|
81
|
+
|
|
74
82
|
|
|
75
83
|
## System Requirements
|
|
76
84
|
|
|
@@ -147,15 +155,12 @@ One command takes a **PDB ID**, a **mutation**, and a **ligand code**, and gives
|
|
|
147
155
|
md_quick --pdb-id 4QJR --mutation A:386:ASN:HIS --ligand-code imatinib
|
|
148
156
|
```
|
|
149
157
|
|
|
150
|
-
```
|
|
151
|
-
Mutation : ASN-A386-HIS
|
|
152
|
-
ΔΔG : -27.30 REU (negative = stabilizing)
|
|
153
|
-
Affinity : -5.66 kcal/mol
|
|
154
|
-
Report : mdquick_4QJR/reports/report.html
|
|
155
|
-
```
|
|
156
|
-
|
|
157
158
|
It fetches + cleans the structure, computes the ΔΔG for that single mutation, builds the mutant, fetches the ligand, finds the pocket with AutoSite (or pass `-c config.txt`), docks, and writes the standard `reports/` bundle. Use `-i protein.pdb` for a local structure, `--ligand-file lig.sdf` for a local ligand, or `--ligand-code 2244` / `cid:5291` / `name:aspirin` for PubChem. Requires the `autosite` binary (ADFRsuite) on PATH when no config is given.
|
|
158
159
|
|
|
160
|
+
Scores depend on the input structure and protocol, so treat the values printed by
|
|
161
|
+
the demo as results rather than fixed expected output. Pass `--seed` to reproduce
|
|
162
|
+
a docking run exactly.
|
|
163
|
+
|
|
159
164
|
The staged tools below give you full control over each step.
|
|
160
165
|
|
|
161
166
|
### 1. Generate mutation candidates
|
|
@@ -214,14 +219,21 @@ md_mutate -h # all options
|
|
|
214
219
|
|
|
215
220
|
Provide exactly one of `-i/--input` (a local `.pdb`/`.cif` file) or `--pdb-id` (a
|
|
216
221
|
4-character RCSB accession, downloaded automatically). `md_mutate` also warns when
|
|
217
|
-
the input contains multiple models,
|
|
218
|
-
insertion codes, since these
|
|
222
|
+
the input contains multiple models or chains, similar chain sequences, alternate
|
|
223
|
+
conformations (altlocs), or insertion codes, since these can make chain selection
|
|
224
|
+
and residue numbering ambiguous. Inspect these warnings and isolate the intended
|
|
225
|
+
chain(s) before interpreting results.
|
|
219
226
|
|
|
220
227
|
By default every output file is written next to the input structure. Pass
|
|
221
228
|
`-o/--output-dir DIR` to collect them in `DIR` instead (created if absent); the
|
|
222
229
|
paths recorded in `*_mutants.txt` point into `DIR`, so they remain valid input
|
|
223
230
|
for `md_dock`.
|
|
224
231
|
|
|
232
|
+
`md_mutate` appends to its checkpoint CSVs by default and skips completed items,
|
|
233
|
+
so rerunning an interrupted job resumes it. The direct `md_ddg_single`,
|
|
234
|
+
`md_ddg_double`, and `md_ddg_triple` commands also support `--resume`. Use
|
|
235
|
+
`--no-append` when you intentionally want a fresh run.
|
|
236
|
+
|
|
225
237
|
#### Mutation Output
|
|
226
238
|
|
|
227
239
|
| # | File | Description |
|
|
@@ -241,7 +253,7 @@ for `md_dock`.
|
|
|
241
253
|
ΔΔG is computed as `score(mutant) − score(wild-type self-mutation reference)`, where **both** sides run the identical repack(+minimization) protocol — so a null WT→WT mutation scores ≈ 0 and the values are not biased toward "stabilizing."
|
|
242
254
|
|
|
243
255
|
- **Units:** `ddG_value` is in **Rosetta Energy Units (REU), not kcal/mol.** A `ddG_kcal` column is also written, and reports show both. REU ≈ but ≠ kcal/mol.
|
|
244
|
-
- **Scaling factor:** the REU→kcal/mol factor is
|
|
256
|
+
- **Scaling factor:** the default REU→kcal/mol factor is `0.34` (≈ 1/2.94; the ref2015 `cartesian_ddg` convention, Park et al. 2016). Override it per run with `--reu-to-kcal FACTOR`; modifying installed package code is not required.
|
|
245
257
|
- **Protocol (`--protocol`, default `min`):** the recorded protocol is written to a `ddG_protocol` column, and reports flag screening-only runs.
|
|
246
258
|
|
|
247
259
|
```bash
|
|
@@ -303,6 +315,7 @@ Output files are named `{stem}_{WTAA}-{CHAIN}{POS}-{NEWAA}.pdb` (e.g. `protein_A
|
|
|
303
315
|
```bash
|
|
304
316
|
md_dock -r receptors.txt -l ligands.txt -c config.txt
|
|
305
317
|
md_dock -r receptors.txt -l ligands.txt -c config.txt -o results/ # collect outputs in results/
|
|
318
|
+
md_dock -r receptors.txt -l ligands.txt -c config.txt --seed 19 # reproducible run
|
|
306
319
|
md_dock -h # all options
|
|
307
320
|
```
|
|
308
321
|
|
|
@@ -312,17 +325,22 @@ By default docking outputs go to an `out/` folder next to each receptor. Pass
|
|
|
312
325
|
`-o/--output-dir DIR` to collect poses, logs, `docking_results.csv`, and the
|
|
313
326
|
`*_completed.txt` resume file in a single `DIR` instead. Prepared PDBQT files and
|
|
314
327
|
AutoSite caches still live next to their inputs so they can be reused across runs.
|
|
328
|
+
Completed receptor–ligand pairs are skipped automatically; use
|
|
329
|
+
`--ignore-existing` to dock them again. The default seed is `19`. It can also be
|
|
330
|
+
set as `seed = ...` in the configuration file, while an explicit CLI `--seed`
|
|
331
|
+
takes precedence. The CSV records the search box, exhaustiveness, and seed for
|
|
332
|
+
every result.
|
|
315
333
|
|
|
316
334
|
#### Docking Output
|
|
317
335
|
|
|
318
336
|
| # | Output | Description |
|
|
319
337
|
|---|--------|-------------|
|
|
320
338
|
| 1 | PDBQT files | Prepared receptor and ligand files |
|
|
321
|
-
| 2 |
|
|
322
|
-
| 3 |
|
|
323
|
-
| 4 |
|
|
324
|
-
| 5 |
|
|
325
|
-
| 6 |
|
|
339
|
+
| 2 | `*_log.txt` | Vina output with binding scores per combination |
|
|
340
|
+
| 3 | `*_out.pdbqt` | Raw multi-pose Vina output |
|
|
341
|
+
| 4 | `*_out.sdf` | Extracted best pose for visualization |
|
|
342
|
+
| 5 | `docking_results.csv` | Affinities plus search-box, exhaustiveness, and seed provenance |
|
|
343
|
+
| 6 | `*_completed.txt` | Resume checkpoint containing completed receptor–ligand pairs |
|
|
326
344
|
|
|
327
345
|
### Reports
|
|
328
346
|
|
|
@@ -398,10 +416,13 @@ generate_csv("data/4QJR.cif")
|
|
|
398
416
|
# Use BLOSUM62 (downloaded automatically if absent)
|
|
399
417
|
generate_csv("data/4QJR.cif", matrix="BLOSUM62")
|
|
400
418
|
|
|
401
|
-
#
|
|
402
|
-
score_dict =
|
|
419
|
+
# Resolve a bundled or downloadable matrix by name
|
|
420
|
+
score_dict = resolve_matrix("PAM250") # works in source and installed packages
|
|
403
421
|
score_dict = resolve_matrix("PAM30") # downloads PAM30 from NCBI if needed
|
|
404
422
|
|
|
423
|
+
# Or load a custom matrix file directly
|
|
424
|
+
score_dict = load_matrix("/path/to/custom_matrix")
|
|
425
|
+
|
|
405
426
|
# --- Generate mutant PDB ---
|
|
406
427
|
from mutadock.mutation.generate_mutant_pdb import generate_pdb
|
|
407
428
|
|
|
@@ -431,6 +452,7 @@ dock_vina(
|
|
|
431
452
|
log_file="vina.log",
|
|
432
453
|
center=[10.0, 5.0, 20.0],
|
|
433
454
|
box_size=[20.0, 20.0, 20.0],
|
|
455
|
+
seed=19,
|
|
434
456
|
)
|
|
435
457
|
```
|
|
436
458
|
|
|
@@ -466,6 +488,17 @@ If NCBI FTP is unreachable, download the matrix manually and use `--matrix-file`
|
|
|
466
488
|
md_csv_generator -i protein.pdb --matrix-file /path/to/PAM30
|
|
467
489
|
```
|
|
468
490
|
|
|
491
|
+
PAM250 and BLOSUM62 are included with MUTADOCK. Other downloaded matrices are
|
|
492
|
+
cached in `~/.cache/mutadock/matrices`; set `MUTADOCK_DATA_DIR` to use a different
|
|
493
|
+
cache directory.
|
|
494
|
+
|
|
495
|
+
**An external preparation or docking command times out**
|
|
496
|
+
|
|
497
|
+
The default limits are 900 seconds for receptor preparation, 1800 seconds for
|
|
498
|
+
AutoSite, and 3600 seconds for Vina. Override them with
|
|
499
|
+
`MUTADOCK_RECEPTOR_PREP_TIMEOUT`, `MUTADOCK_AUTOSITE_TIMEOUT`, and
|
|
500
|
+
`MUTADOCK_VINA_TIMEOUT`, respectively. Set a value to `0` to disable that timeout.
|
|
501
|
+
|
|
469
502
|
**CIF file not recognized**
|
|
470
503
|
PDBFixer and BioPython both support `.cif` natively. Make sure the file extension is `.cif` or `.pdb` — other extensions are not accepted.
|
|
471
504
|
|
|
@@ -4,7 +4,6 @@
|
|
|
4
4
|
[](https://pypi.org/project/mutadock/)
|
|
5
5
|
[](https://pypi.org/project/mutadock/)
|
|
6
6
|
[](https://mutadock.readthedocs.io/en/latest/)
|
|
7
|
-
[]()
|
|
8
7
|
|
|
9
8
|
## Introduction
|
|
10
9
|
|
|
@@ -27,6 +26,13 @@ MUTADOCK is a comprehensive library for protein mutation studies and multi-recep
|
|
|
27
26
|
- Simple CLI for each workflow step
|
|
28
27
|
- Python API for scripting and integration into existing pipelines
|
|
29
28
|
|
|
29
|
+
### What's new in the 2.2 series
|
|
30
|
+
|
|
31
|
+
- Reproducible docking with a configurable random seed (default `19`) and complete run provenance in `docking_results.csv`
|
|
32
|
+
- Safer input validation, including ligand 3D/hydrogen checks and warnings for multi-model, multi-chain, similar-chain, altloc, and insertion-code structures
|
|
33
|
+
- Resumable mutation and docking workflows plus configurable subprocess timeouts
|
|
34
|
+
- PAM250 and BLOSUM62 bundled in the installed package; additional matrices are cached outside the installation directory
|
|
35
|
+
|
|
30
36
|
|
|
31
37
|
## System Requirements
|
|
32
38
|
|
|
@@ -103,15 +109,12 @@ One command takes a **PDB ID**, a **mutation**, and a **ligand code**, and gives
|
|
|
103
109
|
md_quick --pdb-id 4QJR --mutation A:386:ASN:HIS --ligand-code imatinib
|
|
104
110
|
```
|
|
105
111
|
|
|
106
|
-
```
|
|
107
|
-
Mutation : ASN-A386-HIS
|
|
108
|
-
ΔΔG : -27.30 REU (negative = stabilizing)
|
|
109
|
-
Affinity : -5.66 kcal/mol
|
|
110
|
-
Report : mdquick_4QJR/reports/report.html
|
|
111
|
-
```
|
|
112
|
-
|
|
113
112
|
It fetches + cleans the structure, computes the ΔΔG for that single mutation, builds the mutant, fetches the ligand, finds the pocket with AutoSite (or pass `-c config.txt`), docks, and writes the standard `reports/` bundle. Use `-i protein.pdb` for a local structure, `--ligand-file lig.sdf` for a local ligand, or `--ligand-code 2244` / `cid:5291` / `name:aspirin` for PubChem. Requires the `autosite` binary (ADFRsuite) on PATH when no config is given.
|
|
114
113
|
|
|
114
|
+
Scores depend on the input structure and protocol, so treat the values printed by
|
|
115
|
+
the demo as results rather than fixed expected output. Pass `--seed` to reproduce
|
|
116
|
+
a docking run exactly.
|
|
117
|
+
|
|
115
118
|
The staged tools below give you full control over each step.
|
|
116
119
|
|
|
117
120
|
### 1. Generate mutation candidates
|
|
@@ -170,14 +173,21 @@ md_mutate -h # all options
|
|
|
170
173
|
|
|
171
174
|
Provide exactly one of `-i/--input` (a local `.pdb`/`.cif` file) or `--pdb-id` (a
|
|
172
175
|
4-character RCSB accession, downloaded automatically). `md_mutate` also warns when
|
|
173
|
-
the input contains multiple models,
|
|
174
|
-
insertion codes, since these
|
|
176
|
+
the input contains multiple models or chains, similar chain sequences, alternate
|
|
177
|
+
conformations (altlocs), or insertion codes, since these can make chain selection
|
|
178
|
+
and residue numbering ambiguous. Inspect these warnings and isolate the intended
|
|
179
|
+
chain(s) before interpreting results.
|
|
175
180
|
|
|
176
181
|
By default every output file is written next to the input structure. Pass
|
|
177
182
|
`-o/--output-dir DIR` to collect them in `DIR` instead (created if absent); the
|
|
178
183
|
paths recorded in `*_mutants.txt` point into `DIR`, so they remain valid input
|
|
179
184
|
for `md_dock`.
|
|
180
185
|
|
|
186
|
+
`md_mutate` appends to its checkpoint CSVs by default and skips completed items,
|
|
187
|
+
so rerunning an interrupted job resumes it. The direct `md_ddg_single`,
|
|
188
|
+
`md_ddg_double`, and `md_ddg_triple` commands also support `--resume`. Use
|
|
189
|
+
`--no-append` when you intentionally want a fresh run.
|
|
190
|
+
|
|
181
191
|
#### Mutation Output
|
|
182
192
|
|
|
183
193
|
| # | File | Description |
|
|
@@ -197,7 +207,7 @@ for `md_dock`.
|
|
|
197
207
|
ΔΔG is computed as `score(mutant) − score(wild-type self-mutation reference)`, where **both** sides run the identical repack(+minimization) protocol — so a null WT→WT mutation scores ≈ 0 and the values are not biased toward "stabilizing."
|
|
198
208
|
|
|
199
209
|
- **Units:** `ddG_value` is in **Rosetta Energy Units (REU), not kcal/mol.** A `ddG_kcal` column is also written, and reports show both. REU ≈ but ≠ kcal/mol.
|
|
200
|
-
- **Scaling factor:** the REU→kcal/mol factor is
|
|
210
|
+
- **Scaling factor:** the default REU→kcal/mol factor is `0.34` (≈ 1/2.94; the ref2015 `cartesian_ddg` convention, Park et al. 2016). Override it per run with `--reu-to-kcal FACTOR`; modifying installed package code is not required.
|
|
201
211
|
- **Protocol (`--protocol`, default `min`):** the recorded protocol is written to a `ddG_protocol` column, and reports flag screening-only runs.
|
|
202
212
|
|
|
203
213
|
```bash
|
|
@@ -259,6 +269,7 @@ Output files are named `{stem}_{WTAA}-{CHAIN}{POS}-{NEWAA}.pdb` (e.g. `protein_A
|
|
|
259
269
|
```bash
|
|
260
270
|
md_dock -r receptors.txt -l ligands.txt -c config.txt
|
|
261
271
|
md_dock -r receptors.txt -l ligands.txt -c config.txt -o results/ # collect outputs in results/
|
|
272
|
+
md_dock -r receptors.txt -l ligands.txt -c config.txt --seed 19 # reproducible run
|
|
262
273
|
md_dock -h # all options
|
|
263
274
|
```
|
|
264
275
|
|
|
@@ -268,17 +279,22 @@ By default docking outputs go to an `out/` folder next to each receptor. Pass
|
|
|
268
279
|
`-o/--output-dir DIR` to collect poses, logs, `docking_results.csv`, and the
|
|
269
280
|
`*_completed.txt` resume file in a single `DIR` instead. Prepared PDBQT files and
|
|
270
281
|
AutoSite caches still live next to their inputs so they can be reused across runs.
|
|
282
|
+
Completed receptor–ligand pairs are skipped automatically; use
|
|
283
|
+
`--ignore-existing` to dock them again. The default seed is `19`. It can also be
|
|
284
|
+
set as `seed = ...` in the configuration file, while an explicit CLI `--seed`
|
|
285
|
+
takes precedence. The CSV records the search box, exhaustiveness, and seed for
|
|
286
|
+
every result.
|
|
271
287
|
|
|
272
288
|
#### Docking Output
|
|
273
289
|
|
|
274
290
|
| # | Output | Description |
|
|
275
291
|
|---|--------|-------------|
|
|
276
292
|
| 1 | PDBQT files | Prepared receptor and ligand files |
|
|
277
|
-
| 2 |
|
|
278
|
-
| 3 |
|
|
279
|
-
| 4 |
|
|
280
|
-
| 5 |
|
|
281
|
-
| 6 |
|
|
293
|
+
| 2 | `*_log.txt` | Vina output with binding scores per combination |
|
|
294
|
+
| 3 | `*_out.pdbqt` | Raw multi-pose Vina output |
|
|
295
|
+
| 4 | `*_out.sdf` | Extracted best pose for visualization |
|
|
296
|
+
| 5 | `docking_results.csv` | Affinities plus search-box, exhaustiveness, and seed provenance |
|
|
297
|
+
| 6 | `*_completed.txt` | Resume checkpoint containing completed receptor–ligand pairs |
|
|
282
298
|
|
|
283
299
|
### Reports
|
|
284
300
|
|
|
@@ -354,10 +370,13 @@ generate_csv("data/4QJR.cif")
|
|
|
354
370
|
# Use BLOSUM62 (downloaded automatically if absent)
|
|
355
371
|
generate_csv("data/4QJR.cif", matrix="BLOSUM62")
|
|
356
372
|
|
|
357
|
-
#
|
|
358
|
-
score_dict =
|
|
373
|
+
# Resolve a bundled or downloadable matrix by name
|
|
374
|
+
score_dict = resolve_matrix("PAM250") # works in source and installed packages
|
|
359
375
|
score_dict = resolve_matrix("PAM30") # downloads PAM30 from NCBI if needed
|
|
360
376
|
|
|
377
|
+
# Or load a custom matrix file directly
|
|
378
|
+
score_dict = load_matrix("/path/to/custom_matrix")
|
|
379
|
+
|
|
361
380
|
# --- Generate mutant PDB ---
|
|
362
381
|
from mutadock.mutation.generate_mutant_pdb import generate_pdb
|
|
363
382
|
|
|
@@ -387,6 +406,7 @@ dock_vina(
|
|
|
387
406
|
log_file="vina.log",
|
|
388
407
|
center=[10.0, 5.0, 20.0],
|
|
389
408
|
box_size=[20.0, 20.0, 20.0],
|
|
409
|
+
seed=19,
|
|
390
410
|
)
|
|
391
411
|
```
|
|
392
412
|
|
|
@@ -422,6 +442,17 @@ If NCBI FTP is unreachable, download the matrix manually and use `--matrix-file`
|
|
|
422
442
|
md_csv_generator -i protein.pdb --matrix-file /path/to/PAM30
|
|
423
443
|
```
|
|
424
444
|
|
|
445
|
+
PAM250 and BLOSUM62 are included with MUTADOCK. Other downloaded matrices are
|
|
446
|
+
cached in `~/.cache/mutadock/matrices`; set `MUTADOCK_DATA_DIR` to use a different
|
|
447
|
+
cache directory.
|
|
448
|
+
|
|
449
|
+
**An external preparation or docking command times out**
|
|
450
|
+
|
|
451
|
+
The default limits are 900 seconds for receptor preparation, 1800 seconds for
|
|
452
|
+
AutoSite, and 3600 seconds for Vina. Override them with
|
|
453
|
+
`MUTADOCK_RECEPTOR_PREP_TIMEOUT`, `MUTADOCK_AUTOSITE_TIMEOUT`, and
|
|
454
|
+
`MUTADOCK_VINA_TIMEOUT`, respectively. Set a value to `0` to disable that timeout.
|
|
455
|
+
|
|
425
456
|
**CIF file not recognized**
|
|
426
457
|
PDBFixer and BioPython both support `.cif` natively. Make sure the file extension is `.cif` or `.pdb` — other extensions are not accepted.
|
|
427
458
|
|
|
@@ -14,6 +14,8 @@ sys.path.insert(0, os.path.abspath("../src"))
|
|
|
14
14
|
project = "MutaDock"
|
|
15
15
|
copyright = "2026, Naisarg Patel"
|
|
16
16
|
author = "Naisarg Patel"
|
|
17
|
+
version = "2.2"
|
|
18
|
+
release = "2.2.2"
|
|
17
19
|
|
|
18
20
|
# -- General configuration ---------------------------------------------------
|
|
19
21
|
|
|
@@ -50,8 +52,6 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
|
|
|
50
52
|
# -- Options for HTML output -------------------------------------------------
|
|
51
53
|
|
|
52
54
|
html_theme = "alabaster"
|
|
53
|
-
html_static_path = ["_static"]
|
|
54
|
-
|
|
55
55
|
html_theme_options = {
|
|
56
56
|
"description": "Mutation analysis and multi-receptor docking toolkit",
|
|
57
57
|
"github_user": "naisarg14",
|