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.
Files changed (95) hide show
  1. {mutadock-2.1.0 → mutadock-2.2.2}/.gitignore +12 -4
  2. {mutadock-2.1.0 → mutadock-2.2.2}/CHANGELOG.md +30 -0
  3. {mutadock-2.1.0 → mutadock-2.2.2}/PKG-INFO +52 -19
  4. {mutadock-2.1.0 → mutadock-2.2.2}/README.md +49 -18
  5. {mutadock-2.1.0 → mutadock-2.2.2}/docs/conf.py +2 -2
  6. {mutadock-2.1.0 → mutadock-2.2.2}/docs/index.rst +88 -35
  7. {mutadock-2.1.0 → mutadock-2.2.2}/environment.yml +3 -2
  8. {mutadock-2.1.0 → mutadock-2.2.2}/install.sh +3 -1
  9. {mutadock-2.1.0 → mutadock-2.2.2}/pyproject.toml +11 -9
  10. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/__init__.py +1 -1
  11. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/np_docking.py +608 -537
  12. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/vina_dock.py +28 -1
  13. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/vina_helper.py +198 -38
  14. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/csv_generator.py +2 -2
  15. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/helpers.py +93 -9
  16. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/quick.py +522 -496
  17. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/test_np_docking.py +474 -471
  18. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/test_vina_dock.py +30 -0
  19. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/test_vina_helper.py +1174 -939
  20. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_helpers.py +52 -0
  21. {mutadock-2.1.0 → mutadock-2.2.2}/win_install.bat +3 -1
  22. {mutadock-2.1.0 → mutadock-2.2.2}/.dockerignore +0 -0
  23. {mutadock-2.1.0 → mutadock-2.2.2}/.pre-commit-config.yaml +0 -0
  24. {mutadock-2.1.0 → mutadock-2.2.2}/.readthedocs.yaml +0 -0
  25. {mutadock-2.1.0 → mutadock-2.2.2}/Dockerfile +0 -0
  26. {mutadock-2.1.0 → mutadock-2.2.2}/LICENSE +0 -0
  27. {mutadock-2.1.0 → mutadock-2.2.2}/data/4QJR.cif +0 -0
  28. {mutadock-2.1.0 → mutadock-2.2.2}/data/BLOSUM62 +0 -0
  29. {mutadock-2.1.0 → mutadock-2.2.2}/data/Ligand.sdf +0 -0
  30. {mutadock-2.1.0 → mutadock-2.2.2}/data/PAM250 +0 -0
  31. {mutadock-2.1.0 → mutadock-2.2.2}/docs/Makefile +0 -0
  32. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/index.rst +0 -0
  33. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.exceptions.rst +0 -0
  34. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.np_docking.rst +0 -0
  35. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.vina_dock.rst +0 -0
  36. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.docking.vina_helper.rst +0 -0
  37. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.Amino.rst +0 -0
  38. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.csv_generator.rst +0 -0
  39. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.csv_sort.rst +0 -0
  40. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.ddg_calc.rst +0 -0
  41. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.ddg_calc_double.rst +0 -0
  42. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.ddg_calc_triple.rst +0 -0
  43. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.exceptions.rst +0 -0
  44. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.generate_mutant_pdb.rst +0 -0
  45. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.generate_mutants.rst +0 -0
  46. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.helpers.rst +0 -0
  47. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.np_mutation.rst +0 -0
  48. {mutadock-2.1.0 → mutadock-2.2.2}/docs/api/mutadock.mutation.predict_ddG.rst +0 -0
  49. {mutadock-2.1.0 → mutadock-2.2.2}/docs/make.bat +0 -0
  50. {mutadock-2.1.0 → mutadock-2.2.2}/pyrightconfig.json +0 -0
  51. {mutadock-2.1.0/src → mutadock-2.2.2/src/mutadock}/data/BLOSUM62 +0 -0
  52. {mutadock-2.1.0/src → mutadock-2.2.2/src/mutadock}/data/PAM250 +0 -0
  53. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/__init__.py +0 -0
  54. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/docking/exceptions.py +0 -0
  55. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/Amino.py +0 -0
  56. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/__init__.py +0 -0
  57. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/csv_sort.py +0 -0
  58. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/ddg_calc.py +0 -0
  59. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/ddg_calc_double.py +0 -0
  60. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/ddg_calc_triple.py +0 -0
  61. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/exceptions.py +0 -0
  62. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/generate_mutant_pdb.py +0 -0
  63. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/generate_mutants.py +0 -0
  64. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/np_mutation.py +0 -0
  65. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/mutation/predict_ddG.py +0 -0
  66. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/__init__.py +0 -0
  67. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/assets/ngl.min.js +0 -0
  68. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/data.py +0 -0
  69. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/figures.py +0 -0
  70. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/html_report.py +0 -0
  71. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/ppt_report.py +0 -0
  72. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/report.py +0 -0
  73. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/structure.py +0 -0
  74. {mutadock-2.1.0 → mutadock-2.2.2}/src/mutadock/report/templates/report.html.j2 +0 -0
  75. {mutadock-2.1.0 → mutadock-2.2.2}/tests/__init__.py +0 -0
  76. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/__init__.py +0 -0
  77. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_docking/conftest.py +0 -0
  78. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/__init__.py +0 -0
  79. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/conftest.py +0 -0
  80. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_csv_generator.py +0 -0
  81. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_csv_sort.py +0 -0
  82. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_ddg_calc.py +0 -0
  83. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_ddg_protocol.py +0 -0
  84. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_ddg_resume.py +0 -0
  85. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_generate_mutants.py +0 -0
  86. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_mutation/test_np_mutation.py +0 -0
  87. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_quick.py +0 -0
  88. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/__init__.py +0 -0
  89. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/conftest.py +0 -0
  90. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_data.py +0 -0
  91. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_figures.py +0 -0
  92. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_html.py +0 -0
  93. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_ppt.py +0 -0
  94. {mutadock-2.1.0 → mutadock-2.2.2}/tests/test_report/test_report.py +0 -0
  95. {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
- # Docking output PDB files
91
- *_out.pdb
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
- # Vina split SDF output
97
- *_ligand_*.sdf
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.1.0
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
  [![PyPI version](https://img.shields.io/pypi/v/mutadock.svg)](https://pypi.org/project/mutadock/)
49
51
  [![Python](https://img.shields.io/pypi/pyversions/mutadock.svg)](https://pypi.org/project/mutadock/)
50
52
  [![Docs](https://readthedocs.org/projects/mutadock/badge/?version=latest)](https://mutadock.readthedocs.io/en/latest/)
51
- [![Coverage](https://img.shields.io/badge/coverage-45.45%25-yellow.svg)]()
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, alternate conformations (altlocs), or
218
- insertion codes, since these affect residue numbering.
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 **`REU_TO_KCAL_SCALE` in `src/mutadock/mutation/predict_ddG.py`** (default `0.34`, ≈ 1/2.94; the ref2015 `cartesian_ddg` convention, Park et al. 2016). **To change it, edit that constant** or pass `--reu-to-kcal FACTOR` per run.
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 | Log file | Vina output with binding scores per combination |
322
- | 3 | Output PDB | Top 5 docking poses per combination |
323
- | 4 | Output PDBQT | Best pose (Vina split) per combination |
324
- | 5 | Output SDF | Best pose as SDF for visualization |
325
- | 6 | `docking_results.csv` | All affinities tabulated for easy analysis |
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
- # Load a matrix directly
402
- score_dict = load_matrix("data/PAM250") # dict[str, dict[str, int]], 3-letter keys
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
  [![PyPI version](https://img.shields.io/pypi/v/mutadock.svg)](https://pypi.org/project/mutadock/)
5
5
  [![Python](https://img.shields.io/pypi/pyversions/mutadock.svg)](https://pypi.org/project/mutadock/)
6
6
  [![Docs](https://readthedocs.org/projects/mutadock/badge/?version=latest)](https://mutadock.readthedocs.io/en/latest/)
7
- [![Coverage](https://img.shields.io/badge/coverage-45.45%25-yellow.svg)]()
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, alternate conformations (altlocs), or
174
- insertion codes, since these affect residue numbering.
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 **`REU_TO_KCAL_SCALE` in `src/mutadock/mutation/predict_ddG.py`** (default `0.34`, ≈ 1/2.94; the ref2015 `cartesian_ddg` convention, Park et al. 2016). **To change it, edit that constant** or pass `--reu-to-kcal FACTOR` per run.
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 | Log file | Vina output with binding scores per combination |
278
- | 3 | Output PDB | Top 5 docking poses per combination |
279
- | 4 | Output PDBQT | Best pose (Vina split) per combination |
280
- | 5 | Output SDF | Best pose as SDF for visualization |
281
- | 6 | `docking_results.csv` | All affinities tabulated for easy analysis |
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
- # Load a matrix directly
358
- score_dict = load_matrix("data/PAM250") # dict[str, dict[str, int]], 3-letter keys
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",