mutadock 2.2.0__tar.gz → 2.2.2__tar.gz

{mutadock-2.2.0 → mutadock-2.2.2}/.gitignore

@@ -87,14 +87,14 @@ demo/
 # AutoDock result files
 *.dlg
 
-# Docking output PDB files
-*_out.pdb
+# Raw multi-pose Vina output (also covered by *.pdbqt above)
+*_out.pdbqt
 
 # Per-run log files
 *_log.txt
 
-# Vina split SDF output
-*_ligand_*.sdf
+# Extracted best-pose SDF output
+*_out.sdf
 
 # Docking results aggregate
 docking_results.csv

{mutadock-2.2.0 → mutadock-2.2.2}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.2] - 2026-09-19
+
+### Added
+- Local SDF and MOL2 ligand inputs are now validated for a parseable molecule and usable 3-D coordinates before Meeko preparation.
+
+### Changed
+- RDKit is now an explicit Python dependency rather than an implicit requirement of ligand preparation.
+- Installation, AutoSite, matrix-loading, and generated-output guidance is consistent across the README, Sphinx documentation, environment file, installer scripts, and ignore rules.
+
+## [2.2.1] - 2026-09-18
+
+### Changed
+- 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.
+- Removed the stale fixed-score example and hard-coded coverage badge from the README.
+
 ## [2.2.0] - 2026-09-18
 
 ### Added

{mutadock-2.2.0 → mutadock-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mutadock
-Version: 2.2.0
+Version: 2.2.2
 Summary: MUTADOCK is a comprehensive library designed for mutation studies and multiple receptor-ligand docking. Refer to README for more information.
 Project-URL: Repository, https://github.com/naisarg14/mutadock
 Project-URL: Issues, https://github.com/naisarg14/mutadock/issues
@@ -27,6 +27,7 @@ Requires-Dist: pdbfixer
 Requires-Dist: pyarrow
 Requires-Dist: pyrosetta-installer
 Requires-Dist: python-pptx
+Requires-Dist: rdkit
 Requires-Dist: tqdm
 Provides-Extra: dev
 Requires-Dist: black>=24.0; extra == 'dev'
@@ -49,7 +50,6 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/mutadock.svg)](https://pypi.org/project/mutadock/)
 [![Python](https://img.shields.io/pypi/pyversions/mutadock.svg)](https://pypi.org/project/mutadock/)
 [![Docs](https://readthedocs.org/projects/mutadock/badge/?version=latest)](https://mutadock.readthedocs.io/en/latest/)
-[![Coverage](https://img.shields.io/badge/coverage-45.45%25-yellow.svg)]()
 
 ## Introduction
 
@@ -72,6 +72,13 @@ MUTADOCK is a comprehensive library for protein mutation studies and multi-recep
 - Simple CLI for each workflow step
 - Python API for scripting and integration into existing pipelines
 
+### What's new in the 2.2 series
+
+- Reproducible docking with a configurable random seed (default `19`) and complete run provenance in `docking_results.csv`
+- Safer input validation, including ligand 3D/hydrogen checks and warnings for multi-model, multi-chain, similar-chain, altloc, and insertion-code structures
+- Resumable mutation and docking workflows plus configurable subprocess timeouts
+- PAM250 and BLOSUM62 bundled in the installed package; additional matrices are cached outside the installation directory
+
 
 ## System Requirements
 
@@ -148,15 +155,12 @@ One command takes a **PDB ID**, a **mutation**, and a **ligand code**, and gives
 md_quick --pdb-id 4QJR --mutation A:386:ASN:HIS --ligand-code imatinib
 ```
 
-```
-  Mutation : ASN-A386-HIS
-  ΔΔG      : -27.30 REU (negative = stabilizing)
-  Affinity : -5.66 kcal/mol
-  Report   : mdquick_4QJR/reports/report.html
-```
-
 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.
 
+Scores depend on the input structure and protocol, so treat the values printed by
+the demo as results rather than fixed expected output. Pass `--seed` to reproduce
+a docking run exactly.
+
 The staged tools below give you full control over each step.
 
 ### 1. Generate mutation candidates
@@ -215,14 +219,21 @@ md_mutate -h                         # all options
 
 Provide exactly one of `-i/--input` (a local `.pdb`/`.cif` file) or `--pdb-id` (a
 4-character RCSB accession, downloaded automatically). `md_mutate` also warns when
-the input contains multiple models, alternate conformations (altlocs), or
-insertion codes, since these affect residue numbering.
+the input contains multiple models or chains, similar chain sequences, alternate
+conformations (altlocs), or insertion codes, since these can make chain selection
+and residue numbering ambiguous. Inspect these warnings and isolate the intended
+chain(s) before interpreting results.
 
 By default every output file is written next to the input structure. Pass
 `-o/--output-dir DIR` to collect them in `DIR` instead (created if absent); the
 paths recorded in `*_mutants.txt` point into `DIR`, so they remain valid input
 for `md_dock`.
 
+`md_mutate` appends to its checkpoint CSVs by default and skips completed items,
+so rerunning an interrupted job resumes it. The direct `md_ddg_single`,
+`md_ddg_double`, and `md_ddg_triple` commands also support `--resume`. Use
+`--no-append` when you intentionally want a fresh run.
+
 #### Mutation Output
 
 | # | File | Description |
@@ -242,7 +253,7 @@ for `md_dock`.
 ΔΔ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."
 
 - **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.
-- **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.
+- **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.
 - **Protocol (`--protocol`, default `min`):** the recorded protocol is written to a `ddG_protocol` column, and reports flag screening-only runs.
 
   ```bash
@@ -304,6 +315,7 @@ Output files are named `{stem}_{WTAA}-{CHAIN}{POS}-{NEWAA}.pdb` (e.g. `protein_A
 ```bash
 md_dock -r receptors.txt -l ligands.txt -c config.txt
 md_dock -r receptors.txt -l ligands.txt -c config.txt -o results/  # collect outputs in results/
+md_dock -r receptors.txt -l ligands.txt -c config.txt --seed 19    # reproducible run
 md_dock -h   # all options
 ```
 
@@ -313,17 +325,22 @@ By default docking outputs go to an `out/` folder next to each receptor. Pass
 `-o/--output-dir DIR` to collect poses, logs, `docking_results.csv`, and the
 `*_completed.txt` resume file in a single `DIR` instead. Prepared PDBQT files and
 AutoSite caches still live next to their inputs so they can be reused across runs.
+Completed receptor–ligand pairs are skipped automatically; use
+`--ignore-existing` to dock them again. The default seed is `19`. It can also be
+set as `seed = ...` in the configuration file, while an explicit CLI `--seed`
+takes precedence. The CSV records the search box, exhaustiveness, and seed for
+every result.
 
 #### Docking Output
 
 | # | Output | Description |
 |---|--------|-------------|
 | 1 | PDBQT files | Prepared receptor and ligand files |
-| 2 | Log file | Vina output with binding scores per combination |
-| 3 | Output PDB | Top 5 docking poses per combination |
-| 4 | Output PDBQT | Best pose (Vina split) per combination |
-| 5 | Output SDF | Best pose as SDF for visualization |
-| 6 | `docking_results.csv` | All affinities tabulated for easy analysis |
+| 2 | `*_log.txt` | Vina output with binding scores per combination |
+| 3 | `*_out.pdbqt` | Raw multi-pose Vina output |
+| 4 | `*_out.sdf` | Extracted best pose for visualization |
+| 5 | `docking_results.csv` | Affinities plus search-box, exhaustiveness, and seed provenance |
+| 6 | `*_completed.txt` | Resume checkpoint containing completed receptor–ligand pairs |
 
 ### Reports
 
@@ -399,10 +416,13 @@ generate_csv("data/4QJR.cif")
 # Use BLOSUM62 (downloaded automatically if absent)
 generate_csv("data/4QJR.cif", matrix="BLOSUM62")
 
-# Load a matrix directly
-score_dict = load_matrix("data/PAM250")   # dict[str, dict[str, int]], 3-letter keys
+# Resolve a bundled or downloadable matrix by name
+score_dict = resolve_matrix("PAM250")     # works in source and installed packages
 score_dict = resolve_matrix("PAM30")      # downloads PAM30 from NCBI if needed
 
+# Or load a custom matrix file directly
+score_dict = load_matrix("/path/to/custom_matrix")
+
 # --- Generate mutant PDB ---
 from mutadock.mutation.generate_mutant_pdb import generate_pdb
 
@@ -432,6 +452,7 @@ dock_vina(
     log_file="vina.log",
     center=[10.0, 5.0, 20.0],
     box_size=[20.0, 20.0, 20.0],
+    seed=19,
 )
 ```
 
@@ -467,6 +488,17 @@ If NCBI FTP is unreachable, download the matrix manually and use `--matrix-file`
 md_csv_generator -i protein.pdb --matrix-file /path/to/PAM30
 ```
 
+PAM250 and BLOSUM62 are included with MUTADOCK. Other downloaded matrices are
+cached in `~/.cache/mutadock/matrices`; set `MUTADOCK_DATA_DIR` to use a different
+cache directory.
+
+**An external preparation or docking command times out**
+
+The default limits are 900 seconds for receptor preparation, 1800 seconds for
+AutoSite, and 3600 seconds for Vina. Override them with
+`MUTADOCK_RECEPTOR_PREP_TIMEOUT`, `MUTADOCK_AUTOSITE_TIMEOUT`, and
+`MUTADOCK_VINA_TIMEOUT`, respectively. Set a value to `0` to disable that timeout.
+
 **CIF file not recognized**
 PDBFixer and BioPython both support `.cif` natively. Make sure the file extension is `.cif` or `.pdb` — other extensions are not accepted.
 

{mutadock-2.2.0 → mutadock-2.2.2}/README.md

@@ -4,7 +4,6 @@
 [![PyPI version](https://img.shields.io/pypi/v/mutadock.svg)](https://pypi.org/project/mutadock/)
 [![Python](https://img.shields.io/pypi/pyversions/mutadock.svg)](https://pypi.org/project/mutadock/)
 [![Docs](https://readthedocs.org/projects/mutadock/badge/?version=latest)](https://mutadock.readthedocs.io/en/latest/)
-[![Coverage](https://img.shields.io/badge/coverage-45.45%25-yellow.svg)]()
 
 ## Introduction
 
@@ -27,6 +26,13 @@ MUTADOCK is a comprehensive library for protein mutation studies and multi-recep
 - Simple CLI for each workflow step
 - Python API for scripting and integration into existing pipelines
 
+### What's new in the 2.2 series
+
+- Reproducible docking with a configurable random seed (default `19`) and complete run provenance in `docking_results.csv`
+- Safer input validation, including ligand 3D/hydrogen checks and warnings for multi-model, multi-chain, similar-chain, altloc, and insertion-code structures
+- Resumable mutation and docking workflows plus configurable subprocess timeouts
+- PAM250 and BLOSUM62 bundled in the installed package; additional matrices are cached outside the installation directory
+
 
 ## System Requirements
 
@@ -103,15 +109,12 @@ One command takes a **PDB ID**, a **mutation**, and a **ligand code**, and gives
 md_quick --pdb-id 4QJR --mutation A:386:ASN:HIS --ligand-code imatinib
 ```
 
-```
-  Mutation : ASN-A386-HIS
-  ΔΔG      : -27.30 REU (negative = stabilizing)
-  Affinity : -5.66 kcal/mol
-  Report   : mdquick_4QJR/reports/report.html
-```
-
 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.
 
+Scores depend on the input structure and protocol, so treat the values printed by
+the demo as results rather than fixed expected output. Pass `--seed` to reproduce
+a docking run exactly.
+
 The staged tools below give you full control over each step.
 
 ### 1. Generate mutation candidates
@@ -170,14 +173,21 @@ md_mutate -h                         # all options
 
 Provide exactly one of `-i/--input` (a local `.pdb`/`.cif` file) or `--pdb-id` (a
 4-character RCSB accession, downloaded automatically). `md_mutate` also warns when
-the input contains multiple models, alternate conformations (altlocs), or
-insertion codes, since these affect residue numbering.
+the input contains multiple models or chains, similar chain sequences, alternate
+conformations (altlocs), or insertion codes, since these can make chain selection
+and residue numbering ambiguous. Inspect these warnings and isolate the intended
+chain(s) before interpreting results.
 
 By default every output file is written next to the input structure. Pass
 `-o/--output-dir DIR` to collect them in `DIR` instead (created if absent); the
 paths recorded in `*_mutants.txt` point into `DIR`, so they remain valid input
 for `md_dock`.
 
+`md_mutate` appends to its checkpoint CSVs by default and skips completed items,
+so rerunning an interrupted job resumes it. The direct `md_ddg_single`,
+`md_ddg_double`, and `md_ddg_triple` commands also support `--resume`. Use
+`--no-append` when you intentionally want a fresh run.
+
 #### Mutation Output
 
 | # | File | Description |
@@ -197,7 +207,7 @@ for `md_dock`.
 ΔΔ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."
 
 - **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.
-- **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.
+- **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.
 - **Protocol (`--protocol`, default `min`):** the recorded protocol is written to a `ddG_protocol` column, and reports flag screening-only runs.
 
   ```bash
@@ -259,6 +269,7 @@ Output files are named `{stem}_{WTAA}-{CHAIN}{POS}-{NEWAA}.pdb` (e.g. `protein_A
 ```bash
 md_dock -r receptors.txt -l ligands.txt -c config.txt
 md_dock -r receptors.txt -l ligands.txt -c config.txt -o results/  # collect outputs in results/
+md_dock -r receptors.txt -l ligands.txt -c config.txt --seed 19    # reproducible run
 md_dock -h   # all options
 ```
 
@@ -268,17 +279,22 @@ By default docking outputs go to an `out/` folder next to each receptor. Pass
 `-o/--output-dir DIR` to collect poses, logs, `docking_results.csv`, and the
 `*_completed.txt` resume file in a single `DIR` instead. Prepared PDBQT files and
 AutoSite caches still live next to their inputs so they can be reused across runs.
+Completed receptor–ligand pairs are skipped automatically; use
+`--ignore-existing` to dock them again. The default seed is `19`. It can also be
+set as `seed = ...` in the configuration file, while an explicit CLI `--seed`
+takes precedence. The CSV records the search box, exhaustiveness, and seed for
+every result.
 
 #### Docking Output
 
 | # | Output | Description |
 |---|--------|-------------|
 | 1 | PDBQT files | Prepared receptor and ligand files |
-| 2 | Log file | Vina output with binding scores per combination |
-| 3 | Output PDB | Top 5 docking poses per combination |
-| 4 | Output PDBQT | Best pose (Vina split) per combination |
-| 5 | Output SDF | Best pose as SDF for visualization |
-| 6 | `docking_results.csv` | All affinities tabulated for easy analysis |
+| 2 | `*_log.txt` | Vina output with binding scores per combination |
+| 3 | `*_out.pdbqt` | Raw multi-pose Vina output |
+| 4 | `*_out.sdf` | Extracted best pose for visualization |
+| 5 | `docking_results.csv` | Affinities plus search-box, exhaustiveness, and seed provenance |
+| 6 | `*_completed.txt` | Resume checkpoint containing completed receptor–ligand pairs |
 
 ### Reports
 
@@ -354,10 +370,13 @@ generate_csv("data/4QJR.cif")
 # Use BLOSUM62 (downloaded automatically if absent)
 generate_csv("data/4QJR.cif", matrix="BLOSUM62")
 
-# Load a matrix directly
-score_dict = load_matrix("data/PAM250")   # dict[str, dict[str, int]], 3-letter keys
+# Resolve a bundled or downloadable matrix by name
+score_dict = resolve_matrix("PAM250")     # works in source and installed packages
 score_dict = resolve_matrix("PAM30")      # downloads PAM30 from NCBI if needed
 
+# Or load a custom matrix file directly
+score_dict = load_matrix("/path/to/custom_matrix")
+
 # --- Generate mutant PDB ---
 from mutadock.mutation.generate_mutant_pdb import generate_pdb
 
@@ -387,6 +406,7 @@ dock_vina(
     log_file="vina.log",
     center=[10.0, 5.0, 20.0],
     box_size=[20.0, 20.0, 20.0],
+    seed=19,
 )
 ```
 
@@ -422,6 +442,17 @@ If NCBI FTP is unreachable, download the matrix manually and use `--matrix-file`
 md_csv_generator -i protein.pdb --matrix-file /path/to/PAM30
 ```
 
+PAM250 and BLOSUM62 are included with MUTADOCK. Other downloaded matrices are
+cached in `~/.cache/mutadock/matrices`; set `MUTADOCK_DATA_DIR` to use a different
+cache directory.
+
+**An external preparation or docking command times out**
+
+The default limits are 900 seconds for receptor preparation, 1800 seconds for
+AutoSite, and 3600 seconds for Vina. Override them with
+`MUTADOCK_RECEPTOR_PREP_TIMEOUT`, `MUTADOCK_AUTOSITE_TIMEOUT`, and
+`MUTADOCK_VINA_TIMEOUT`, respectively. Set a value to `0` to disable that timeout.
+
 **CIF file not recognized**
 PDBFixer and BioPython both support `.cif` natively. Make sure the file extension is `.cif` or `.pdb` — other extensions are not accepted.
 

{mutadock-2.2.0 → mutadock-2.2.2}/docs/conf.py

@@ -14,6 +14,8 @@ sys.path.insert(0, os.path.abspath("../src"))
 project = "MutaDock"
 copyright = "2026, Naisarg Patel"
 author = "Naisarg Patel"
+version = "2.2"
+release = "2.2.2"
 
 # -- General configuration ---------------------------------------------------
 
@@ -50,8 +52,6 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 # -- Options for HTML output -------------------------------------------------
 
 html_theme = "alabaster"
-html_static_path = ["_static"]
-
 html_theme_options = {
     "description": "Mutation analysis and multi-receptor docking toolkit",
     "github_user": "naisarg14",

{mutadock-2.2.0 → mutadock-2.2.2}/docs/index.rst

@@ -1,5 +1,14 @@
 MutaDock documentation
 ======================
+
+Release 2.2.2
+-------------
+
+MUTADOCK 2.2 adds reproducible docking seeds and run provenance, resumable
+mutation and docking workflows, safer structure and ligand validation, and
+timeouts for external preparation and docking tools. Version 2.2.2 also aligns
+the installation metadata and examples and validates local ligand coordinates.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
@@ -50,22 +59,21 @@ How To Guide
 Installation
 ^^^^^^^^^^^^
 
-MutaDock has been deployed on PyPi, making installation quick and simple
+MutaDock is published on PyPI, making installation quick and simple:
 
 .. code-block::
 
    pip install mutadock
 
-The Pyrosetta Installer will be automatically installed but Pyrosetta should be installed using
+The PyRosetta installer is included as a dependency, but PyRosetta itself must
+be installed separately:
 
 .. code-block::
 
-   md_install_dependencies
+   python -c "import pyrosetta_installer; pyrosetta_installer.install_pyrosetta()"
 
-this will install all dependencies including Pyrosetta.
-
-
-* Currently there is a problem with the vina on PyPi, so vina needs to be installed separately, the installation guide can be found at https://autodock-vina.readthedocs.io/en/latest/installation.html
+AutoDock Vina must also be installed separately; follow the `official Vina
+installation guide <https://autodock-vina.readthedocs.io/en/latest/installation.html>`_.
 
 Quick demo (md_quick)
 ^^^^^^^^^^^^^^^^^^^^^^
@@ -83,6 +91,9 @@ name; ``--ligand-file`` takes a local file), locates the pocket with AutoSite (o
 pass ``-c config.txt``), docks, and writes the standard ``reports/`` bundle into
 ``mdquick_<id>/`` (or ``-o``). ``-i protein.pdb`` uses a local structure instead
 of ``--pdb-id``. Requires the ``autosite`` binary on PATH when no config is given.
+Docking uses the reproducible default seed ``19``; pass ``--seed`` to select a
+different seed. A value of ``0`` asks Vina to choose a random, non-reproducible
+seed.
 
 Mutation Studies
 ^^^^^^^^^^^^^^^^
@@ -100,6 +111,17 @@ By default all outputs are written next to the input structure. Pass
 
    md_mutate -i protein.pdb -o results/
 
+The pipeline appends to its checkpoint CSVs by default. Rerunning an interrupted
+job skips completed mutations and resumes the missing work. The direct
+``md_ddg_single``, ``md_ddg_double``, and ``md_ddg_triple`` commands expose the
+same behavior through ``--resume``. Use ``md_mutate --no-append`` when you
+intentionally want to regenerate all mutation results.
+
+MUTADOCK warns when an input contains multiple models or chains, duplicated or
+highly similar chain sequences, alternate conformations, or insertion codes.
+Inspect these warnings and isolate the intended chain or model before interpreting
+residue-numbered results.
+
 Other optional arguments can be changed as required, to check the usage run
 
 .. code-block::
@@ -110,8 +132,8 @@ Other optional arguments can be changed as required, to check the usage run
 reference)`` with the identical protocol on both sides (so a null WT→WT mutation
 scores ≈ 0). ``ddG_value`` is in **Rosetta Energy Units (REU), not kcal/mol**; a
 ``ddG_kcal`` column is also written. The REU→kcal/mol factor is
-``REU_TO_KCAL_SCALE`` in ``src/mutadock/mutation/predict_ddG.py`` (default 0.34 ≈
-1/2.94, Park et al. 2016), overridable with ``--reu-to-kcal``. The default
+0.34 by default (≈ 1/2.94, Park et al. 2016) and is overridable per run with
+``--reu-to-kcal``; editing installed package code is not required. The default
 ``--protocol min`` (repack + minimization) is reliable; ``--protocol cartesian``
 is most accurate; ``--protocol fast`` skips minimization and is **screening
 only** (absolute values unreliable — its reports carry a warning banner). Use
@@ -186,8 +208,10 @@ it to the ΔΔG stages:
 **Available matrices.** ``PAM250`` (default) and ``BLOSUM62`` ship with MUTADOCK.
 Any other matrix name from the `NCBI BLAST FTP
 <https://ftp.ncbi.nih.gov/blast/matrices/>`_ (e.g. ``PAM30``, ``PAM70``,
-``BLOSUM45``, ``BLOSUM80``) is downloaded automatically into ``data/`` on first
-use. A fully custom matrix in NCBI format can be supplied with
+``BLOSUM45``, ``BLOSUM80``) is downloaded automatically into the user-writable
+``~/.cache/mutadock/matrices`` directory on first use. Set
+``MUTADOCK_DATA_DIR`` to choose another cache directory. A fully custom matrix
+in NCBI format can be supplied with
 ``--matrix-file /path/to/matrix`` (this overrides ``--matrix``).
 
 **When to use which.** PAM matrices model accepted point mutations over
@@ -215,18 +239,26 @@ Docking Studies
 ^^^^^^^^^^^^^^^
 
 Docking for multiple receptors and ligands is made simple and efficient by mutadock. The text files containing the names of the receptors and ligands need to be given as input, after that everything is automated. (If md_mutate is used, the text file for receptor is generated automatically)
-Every receptor in the receptor file will be docked with every ligand in the ligand file. A standard Vina configuration file or an AutoSIte prediction output is required.
+Every receptor in the receptor file will be docked with every ligand in the ligand file. Supply a standard Vina configuration file or an existing AutoSite prediction, or omit both to run AutoSite automatically for each receptor.
 Example:
 
 .. code-block::
 
    md_dock -r receptors.txt -l ligands.txt -c config.txt
+   md_dock -r receptors.txt -l ligands.txt -c config.txt --seed 19
 
 By default docking outputs go to an ``out/`` folder next to each receptor. Pass
 ``-o/--output-dir DIR`` to collect poses, logs, ``docking_results.csv``, and the
 resume file in a single ``DIR`` instead. Prepared PDBQT files and AutoSite caches
 still live next to their inputs so they can be reused across runs.
 
+Completed receptor-ligand pairs are skipped automatically using the
+``*_completed.txt`` checkpoint. Pass ``--ignore-existing`` to dock them again.
+The default Vina seed is ``19``. It can also be set with ``seed = ...`` in a
+configuration file; an explicit command-line ``--seed`` takes precedence with a
+visible warning. ``docking_results.csv`` records the box center, box size,
+exhaustiveness, and seed for every result so a run can be reproduced.
+
 .. code-block::
 
    md_dock -r receptors.txt -l ligands.txt -c config.txt -o results/
@@ -249,20 +281,20 @@ The output of md_dock with their description is in the table below:
      - PDBQT files
      - The receptors and ligands will be converted to PDBQT files for AutoDock Vina.
    * - 2.
-     - Output Log
+     - ``*_log.txt``
      - The output of AutoDock Vina with the docking scores will be stored in a log file for each combination.
    * - 3.
-     - Output PDB
-     - The output of AutoDock Vina with the 5 best docking poses will be stored in a PDB file for each combination.
+     - ``*_out.pdbqt``
+     - Raw multi-pose output written by AutoDock Vina for each combination.
    * - 4.
-     - Output PDBQT
-     - The output of AutoDock Vina Split with the best pose will be stored in a PDBQT file for each combination.
+     - ``*_out.sdf``
+     - The extracted best pose in SDF format for visualization.
    * - 5.
-     - Output SDF
-     - The best pose after docking will be stored in a SDF file for visualization and better usability.
+     - ``docking_results.csv``
+     - Affinities and the search-box, exhaustiveness, and seed provenance for every successful combination.
    * - 6.
-     - Docking Results CSV
-     - All the docking affinities are tabulated in a CSV to make analysis trivial.
+     - ``*_completed.txt``
+     - Resume checkpoint containing completed receptor-ligand combinations.
 
 
 Choosing the docking box
@@ -277,7 +309,7 @@ how they interact avoids the most common surprises.
   ``center_y``, ``center_z`` (box center), ``size_x``, ``size_y``, ``size_z``
   (box dimensions in Å — these are independent, so the box may be
   **non-cubic**), plus ``exhaustiveness`` (default 32), ``n_poses`` (20),
-  ``n_poses_write`` (5) and ``overwrite``. Lines beginning with ``#`` are
+  ``n_poses_write`` (5), ``overwrite``, and ``seed`` (19). Lines beginning with ``#`` are
   ignored. Use this when you already know the pocket, want a reproducible box, or
   need to tune the search. **Watch out:** any omitted ``center_*`` key silently
   defaults to ``0.0`` — a config without an explicit center places an empty box
@@ -292,6 +324,7 @@ how they interact avoids the most common surprises.
      size_y = 24
      size_z = 24
      exhaustiveness = 32
+     seed = 19
 
 * **``-a autosite.pdb`` — a fixed AutoSite cluster.** Pass a cluster PDB that
   AutoSite already produced. MUTADOCK sets the center to the cluster's geometric
@@ -307,12 +340,23 @@ how they interact avoids the most common surprises.
   error asking for one of the options above. Prefer this when docking mutants
   whose pockets may shift, since each receptor gets its own box.
 
-**How ``-c`` and ``-a`` interact.** If you pass both, AutoSite wins for the
-*geometry* — the cluster's center and cube override whatever ``center_*`` /
-``size_*`` were in the config — but the config's **search parameters**
-(``exhaustiveness``, ``n_poses``, ``n_poses_write``, ``overwrite``) still apply.
-This lets you take the box from AutoSite while keeping a tuned search from your
-config.
+**Do not combine ``-c`` and ``-a``.** They are mutually exclusive sources of
+docking-box geometry, and MUTADOCK rejects a command that supplies both instead
+of silently choosing one.
+
+External-tool timeouts
+^^^^^^^^^^^^^^^^^^^^^^
+
+MUTADOCK prevents a hung external process from blocking an entire batch. The
+default limits are 900 seconds for receptor preparation, 1800 seconds for
+AutoSite, and 3600 seconds for Vina. Override them with
+``MUTADOCK_RECEPTOR_PREP_TIMEOUT``, ``MUTADOCK_AUTOSITE_TIMEOUT``, and
+``MUTADOCK_VINA_TIMEOUT``, respectively. Set a value to ``0`` to disable that
+timeout.
+
+Ligand preparation adds hydrogens with 3-D coordinates before Meeko conversion.
+Inputs without usable 3-D coordinates are rejected with an actionable error
+instead of producing a misleading docking result.
 
 Reports
 ^^^^^^^
@@ -345,29 +389,38 @@ All CLI Scripts
      - **Command**
      - **Description**
    * - 1.
+     - md_quick
+     - Runs mutation, mutant generation, ligand acquisition, docking, and reporting as a one-command workflow
+   * - 2.
      - md_mutate
      - Predicts the best mutation of the given protein
-   * - 2.
+   * - 3.
      - md_dock
      - Docked all combinations from a list of receptors and ligands
-   * - 3.
+   * - 4.
      - md_vina_dock
      - CLI for AutoDock Vina
-   * - 4.
+   * - 5.
      - md_csv_generator
      - Generates all possible mutations for a protein and also the mutations possible according to PAM Matrix
-   * - 5.
+   * - 6.
      - md_csv_sort
      - Can sort any CSV file according to the column name or number chosen
-   * - 6.
+   * - 7.
      - md_ddg_single
      - Calculates single ddG values for a given CSV of mutations
-   * - 7.
+   * - 8.
      - md_ddg_double
      - Calculates double ddG values for all combinations using a given CSV of mutations
-   * - 8.
+   * - 9.
      - md_ddg_triple
      - Calculates triple ddG values for all combinations using a given CSV of mutations
+   * - 10.
+     - md_generate_pdb
+     - Generates independent or compound mutant PDB files without running ΔΔG scoring
+   * - 11.
+     - md_report
+     - Builds HTML and PowerPoint reports from an existing run directory
 
 
 Applications

{mutadock-2.2.0 → mutadock-2.2.2}/environment.yml

@@ -39,5 +39,6 @@ dependencies:
 # AutoSite (ADFRsuite), used by `md_quick` for automatic pocket detection
 # when no config file is given, is not packaged on conda-forge/PyPI. Download
 # it separately from https://ccsb.scripps.edu/adfr/downloads/ and put its
-# `bin/` directory on PATH, or always pass `-c config.txt` / `--ligand-file`
-# with an explicit box to skip it.
+# `bin/` directory on PATH, or pass `-c config.txt` with an explicit box to
+# skip automatic pocket detection. Selecting a ligand with `--ligand-file`
+# does not define the docking box.

{mutadock-2.2.0 → mutadock-2.2.2}/install.sh

@@ -10,7 +10,7 @@ echo "==> Activating virtual environment..."
 # shellcheck disable=SC1091
 source "$VENV_DIR/bin/activate"
 
-echo "==> Installing mutadock and its dependencies..."
+echo "==> Installing MUTADOCK and its declared Python dependencies..."
 python -m pip install --upgrade pip
 python -m pip install .
 
@@ -20,3 +20,5 @@ python -c 'import pyrosetta_installer; pyrosetta_installer.install_pyrosetta()'
 echo ""
 echo "Installation complete."
 echo "Activate the environment with: source $VENV_DIR/bin/activate"
+echo "AutoDock Vina and AutoSite are external tools and are not installed by this script."
+echo "For the complete native stack, prefer the documented conda or Docker installation."

{mutadock-2.2.0 → mutadock-2.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mutadock"
-version = "2.2.0"
+version = "2.2.2"
 authors = [
   {name = "Naisarg Patel", email = "naisarg.patel14@hotmail.com"}
 ]
@@ -18,9 +18,10 @@ dependencies = [
   'meeko',
   'numpy',
   'openmm',
-  'pdbfixer',
-  'pyrosetta-installer',
-  'tqdm',
+  'pdbfixer',
+  'pyrosetta-installer',
+  'rdkit',
+  'tqdm',
   'pyarrow',
   'pandas',
   'matplotlib',

{mutadock-2.2.0 → mutadock-2.2.2}/src/mutadock/__init__.py

@@ -27,4 +27,4 @@ Top-level package exposing two subpackages:
   preparation and batch docking workflows.
 """
 
-__version__ = "2.2.0"
+__version__ = "2.2.2"

{mutadock-2.2.0 → mutadock-2.2.2}/src/mutadock/docking/vina_helper.py

@@ -145,7 +145,7 @@ def read_pdb_file(file_path: str) -> list[dict[str, Any]]:
         List of atom dicts.
 
     Raises:
-        PDBFileError: If the file cannot be read or parsed.
+        mutadock.docking.exceptions.PDBFileError: If the file cannot be read or parsed.
     """
     import re
 
@@ -189,7 +189,7 @@ def calculate_geometric_center(pdb_file: str) -> tuple[float, float, float]:
         A 3-tuple ``(cx, cy, cz)`` of mean coordinates.
 
     Raises:
-        PDBFileError: If the PDB file cannot be parsed.
+        mutadock.docking.exceptions.PDBFileError: If the PDB file cannot be parsed.
     """
     atoms = read_pdb_file(pdb_file)
     num_atoms = len(atoms)
@@ -214,7 +214,7 @@ def calculate_radius(pdb_file: str) -> float:
         Max distance in Ångströms.
 
     Raises:
-        PDBFileError: If the PDB file cannot be parsed.
+        mutadock.docking.exceptions.PDBFileError: If the PDB file cannot be parsed.
     """
     import math
 
@@ -420,6 +420,23 @@ def fetch_ligand(
     return str(dest)
 
 
+def _require_3d_ligand(mol: Any, source: str) -> None:
+    """Validate that an RDKit ligand is non-empty and has a 3-D conformer."""
+    if mol is None or mol.GetNumAtoms() == 0:
+        raise LigandPreparationError(
+            f"Ligand '{source}' does not contain a parseable molecule."
+        )
+    if mol.GetNumConformers() == 0:
+        raise LigandPreparationError(
+            f"Ligand '{source}' has no coordinates; provide a 3-D SDF or MOL2 file."
+        )
+    if not mol.GetConformer().Is3D():
+        raise LigandPreparationError(
+            f"Ligand '{source}' contains only 2-D coordinates; provide a 3-D "
+            "SDF or MOL2 file."
+        )
+
+
 def prepare_ligand(in_file: str, out_file: Optional[str] = None) -> str:
     """Convert an SDF or MOL2 ligand file to PDBQT format using meeko.
 
@@ -434,33 +451,28 @@ def prepare_ligand(in_file: str, out_file: Optional[str] = None) -> str:
     Raises:
         LigandPreparationError: If preparation fails for any reason.
     """
-    try:
-        import sys
+    suffix = Path(in_file).suffix.lower()
+    if suffix not in {".sdf", ".mol2"}:
+        raise LigandPreparationError("Input file is not in SDF or MOL2 format.")
 
+    try:
         from meeko import MoleculePreparation, PDBQTWriterLegacy
         from rdkit import Chem
-    except ModuleNotFoundError:
-        msg = "Error with importing modules for preparing ligand files for Docking.\n"
-        msg += "Easiest way to fix this is to install meeko and rdkit using the following command:\n\n"
-        msg += "python -m pip install meeko rdkit\n"
-        msg += "If you already have meeko and rdkit installed, please check the installation.\n"
-        msg += "If the problem persists, please create a github issue or contact developer at naisarg.patel14@hotmail.com"
-        logger.error(msg)
-        sys.exit(2)
+    except ModuleNotFoundError as e:
+        raise LigandPreparationError(
+            "Ligand preparation requires meeko and RDKit. Install MUTADOCK's "
+            "declared dependencies or run 'python -m pip install meeko rdkit'."
+        ) from e
 
     if out_file is None:
-        if in_file.endswith(".sdf"):
-            out_file = f"{in_file.removesuffix('.sdf')}.pdbqt"
-        elif in_file.endswith(".mol2"):
-            out_file = f"{in_file.removesuffix('.mol2')}.pdbqt"
-        else:
-            raise LigandPreparationError("Input file is not in SDF or MOL2 format.")
+        out_file = str(Path(in_file).with_suffix(".pdbqt"))
 
     try:
-        if in_file.endswith(".sdf"):
+        if suffix == ".sdf":
             mol = Chem.SDMolSupplier(in_file)[0]
-        if in_file.endswith(".mol2"):
+        else:
             mol = Chem.MolFromMol2File(in_file)
+        _require_3d_ligand(mol, in_file)
 
         # addCoords=True is REQUIRED. Without it RDKit adds the hydrogens as
         # topology only, with no 3D coordinates, and meeko then writes every one
@@ -873,7 +885,7 @@ def dock_vina(
 
     Raises:
         ConfigError: If the config file cannot be read.
-        PDBFileError: If the autosite PDB cannot be parsed.
+        mutadock.docking.exceptions.PDBFileError: If the autosite PDB cannot be parsed.
         DockingRunError: If the Vina subprocess exits with a non-zero code.
     """
     if config is not None:

{mutadock-2.2.0 → mutadock-2.2.2}/src/mutadock/mutation/csv_generator.py

@@ -74,7 +74,7 @@ def generate_csv(
         ``(out_op, out_all)`` paths.
 
     Raises:
-        PDBFileError: If the PDB file cannot be read.
+        mutadock.mutation.exceptions.PDBFileError: If the PDB file cannot be read.
         CSVGenerationError: If the PDB file contains no residues.
         MutationError: If the matrix cannot be loaded or downloaded.
     """
@@ -160,7 +160,7 @@ def get_residues(file: str) -> dict[int, tuple[str, int, str]]:
         Mapping of sequential index to ``(chain_id, position, residue_name)``.
 
     Raises:
-        PDBFileError: If the file is not found.
+        mutadock.mutation.exceptions.PDBFileError: If the file is not found.
     """
     residues: dict[int, tuple[str, int, str]] = {}
     count = 1

{mutadock-2.2.0 → mutadock-2.2.2}/tests/test_docking/test_vina_helper.py

@@ -331,9 +331,12 @@ class TestPrepareLigand(unittest.TestCase):
 
         shutil.rmtree(self.tmpdir, ignore_errors=True)
 
-    def _stubs(self, pdbqt_string="PDBQT_DATA"):
-        mock_mol = MagicMock()
-        mock_chem = MagicMock()
+    def _stubs(self, pdbqt_string="PDBQT_DATA"):
+        mock_mol = MagicMock()
+        mock_mol.GetNumAtoms.return_value = 2
+        mock_mol.GetNumConformers.return_value = 1
+        mock_mol.GetConformer.return_value.Is3D.return_value = True
+        mock_chem = MagicMock()
         mock_chem.SDMolSupplier.return_value.__getitem__ = MagicMock(
             return_value=mock_mol
         )
@@ -382,14 +385,43 @@ class TestPrepareLigand(unittest.TestCase):
             vina_helper.prepare_ligand(in_file)
         self.assertTrue(Path(expected_out).is_file())
 
-    def test_exception_raises_ligand_preparation_error(self):
+    def test_exception_raises_ligand_preparation_error(self):
         in_file = str(self.tmpdir / "lig.sdf")
         Path(in_file).write_text("mol")
         meeko_stub, rdkit_stub = self._stubs()
         rdkit_stub.Chem.AddHs.side_effect = RuntimeError("bad mol")
         with patch.dict(sys.modules, self._modules(meeko_stub, rdkit_stub)):
             with self.assertRaises(LigandPreparationError):
-                vina_helper.prepare_ligand(in_file)
+                vina_helper.prepare_ligand(in_file)
+
+    def test_unparseable_local_ligand_is_rejected(self):
+        in_file = str(self.tmpdir / "bad.sdf")
+        Path(in_file).write_text("not an sdf")
+        meeko_stub, rdkit_stub = self._stubs()
+        rdkit_stub.Chem.SDMolSupplier.return_value.__getitem__.return_value = None
+        with patch.dict(sys.modules, self._modules(meeko_stub, rdkit_stub)):
+            with self.assertRaisesRegex(LigandPreparationError, "parseable"):
+                vina_helper.prepare_ligand(in_file)
+
+    def test_local_ligand_without_coordinates_is_rejected(self):
+        in_file = str(self.tmpdir / "flat.sdf")
+        Path(in_file).write_text("mol")
+        meeko_stub, rdkit_stub = self._stubs()
+        mol = rdkit_stub.Chem.SDMolSupplier.return_value.__getitem__.return_value
+        mol.GetNumConformers.return_value = 0
+        with patch.dict(sys.modules, self._modules(meeko_stub, rdkit_stub)):
+            with self.assertRaisesRegex(LigandPreparationError, "no coordinates"):
+                vina_helper.prepare_ligand(in_file)
+
+    def test_local_ligand_with_2d_coordinates_is_rejected(self):
+        in_file = str(self.tmpdir / "flat.sdf")
+        Path(in_file).write_text("mol")
+        meeko_stub, rdkit_stub = self._stubs()
+        mol = rdkit_stub.Chem.SDMolSupplier.return_value.__getitem__.return_value
+        mol.GetConformer.return_value.Is3D.return_value = False
+        with patch.dict(sys.modules, self._modules(meeko_stub, rdkit_stub)):
+            with self.assertRaisesRegex(LigandPreparationError, "2-D coordinates"):
+                vina_helper.prepare_ligand(in_file)
 
     def test_addhs_requests_coordinates(self):
         """AddHs MUST pass addCoords=True.

{mutadock-2.2.0 → mutadock-2.2.2}/win_install.bat

@@ -18,7 +18,7 @@ if errorlevel 1 (
     exit /b 1
 )
 
-echo =^> Installing mutadock and its dependencies...
+echo =^> Installing MUTADOCK and its declared Python dependencies...
 python -m pip install --upgrade pip
 python -m pip install .
 if errorlevel 1 (
@@ -36,4 +36,6 @@ if errorlevel 1 (
 echo.
 echo Installation complete.
 echo Activate the environment with: %VENV_DIR%\Scripts\activate.bat
+echo AutoDock Vina and AutoSite are external tools and are not installed by this script.
+echo For the complete native stack, prefer the documented conda or Docker installation.
 pause