molscope 0.8.2__tar.gz → 0.9.0__tar.gz

molscope-0.9.0/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+All notable changes to MolScope are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+While the package is pre-1.0, minor versions may include backwards-incompatible
+API changes; these are called out under **Changed** where they occur.
+
+## [Unreleased]
+
+## [0.9.0] - 2026-05-29
+
+### Added
+
+- Molecule-table workflow: `molscope select` and the `molscope.library` module
+  read a CSV/XLSX of molecules and pick a diverse subset by MaxMin
+  (farthest-first) selection over descriptors. Select on existing numeric columns
+  (e.g. `MW`, `ALogP`) or compute RDKit descriptors from a SMILES column with
+  `--compute-descriptors --smiles-col`. Adds an `xlsx` extra (`openpyxl`) for
+  spreadsheet I/O; CSV input and selection need no optional backend.
+- Optional MCP (Model Context Protocol) server, `molscope.mcp_server`, exposing
+  MolScope's analyses as tools for AI assistants such as Claude Code and Claude
+  Desktop. Adds a `molscope-mcp` console script, an `mcp` extra
+  (`pip install "molscope[mcp]"`, Python >= 3.10), and nine read-only tools that
+  wrap the existing API: summarise, descriptors, secondary structure, contact
+  map, binding site, molecular graph, coarse-grain, and two PNG render tools.
+- Broadened the DSSP reference cross-check to three fold classes instead of one:
+  helix-dominated Aquaporin-1 (`1fqy`), mixed alpha/beta ubiquitin (`1ubq`), and
+  the all-beta SH3 domain (`1shg`). The test is parametrised and prints
+  per-fold 3-state agreement so results read as a range. Measured against
+  `mkdssp` 4.5.8: 99.1% (`1fqy`), 100% (`1ubq`), 98.2% (`1shg`).
+- Bundled `1ubq.pdb` and `1shg.pdb` in `examples/data` as the new validation
+  structures.
+
+### Changed
+
+- Documentation and the JOSS paper now report DSSP agreement as a measured
+  range across fold classes rather than a single helical figure, and no longer
+  imply that strand-rich folds agree markedly less well.
+
+## [0.8.3] - 2026-05-28
+
+### Added
+
+- JOSS paper draft under `paper/` and Zenodo deposition metadata
+  (`.zenodo.json`) for an archival DOI.
+
+### Changed
+
+- Bumped GitHub Actions to Node 24-ready versions.
+
+## [0.8.2] - 2026-05-28
+
+### Added
+
+- Read the Docs hosting for the documentation site.
+- Coverage reporting via `pytest-cov` and Codecov, measured with the optional
+  backends installed so the RDKit, gemmi, NetworkX, SciPy and Torch paths are
+  exercised rather than skipped.
+- Coarse-grained virtual-site support, preserved as derived coordinate metadata.
+- PDB workflow tutorials and a protein-analysis-from-scratch walkthrough.
+- CLI batch analysis and graph-export subcommands, with improved selection
+  handling.
+- `O(n)` cell-list neighbour search and opt-in periodic-boundary support for the
+  distance and contact methods.
+- Residue contact graphs for ML and an educational coarse-graining workflow.
+- Scientific validation tables, references, and a reproducible benchmarks page.
+
+### Changed
+
+- Reorganised the limitations page by workflow and added a Graph ML section.
+- Refocused the documentation around the three core workflows.
+- Completed the geometry API and added a visual geometry guide validated against
+  MDAnalysis.
+- Polished the coarse-graining workflow, contact maps, and dense distance
+  backends; improved coordinate-format parser errors and added edge-case
+  fixtures.
+- Stopped tracking generated graph exports and added `graphs/` to `.gitignore`.
+
+### Fixed
+
+- Batch CLI crash with `--jobs > 1` on spawn-based platforms.
+- gemmi-backed mmCIF unit-cell read.
+- Lint errors, and made periodic boundaries opt-in for distance and contact
+  methods.
+
+## [0.8.1] - 2026-05-26
+
+### Added
+
+- Tier-2 validation suite cross-checking against reference scientific tools,
+  covering DSSP (`mkdssp`), geometry and RMSD (MDAnalysis), bond perception and
+  chemical features (RDKit), and contact maps.
+- PyTorch Geometric ML tutorial and `CITATION.cff` citation metadata.
+
+### Changed
+
+- DSSP validation now invokes `mkdssp` directly instead of going through
+  Biopython, and the 3-state agreement floor was tightened to 0.95 after
+  observing 99.1% on CI.
+- CI runs the validation job with the required extras and fails loudly if the
+  reference tools cannot be imported.
+- Polished repository layout and documentation.
+
+### Fixed
+
+- README Mermaid diagram syntax.
+
+## [0.8.0] - 2026-05-26
+
+### Added
+
+- Expanded molecular parsing and machine-learning feature support.
+
+## [0.7.0] - 2026-05-25
+
+### Added
+
+- Simplified, dependency-free DSSP-style secondary-structure assignment based on
+  the Kabsch-Sander hydrogen-bond model.
+
+### Changed
+
+- README: added a "Why MolScope" section, a tool comparison, and a CLI output
+  example; the secondary-structure render replaced the earlier hero animation.
+
+## [0.6.2] - 2026-05-25
+
+### Fixed
+
+- README images now render on PyPI, and the publish workflow was hardened.
+
+## [0.6.1] - 2026-05-25
+
+### Added
+
+- PyPI trusted-publishing workflow.
+
+### Changed
+
+- Expanded the package docstring to cover the full feature scope.
+
+## [0.6.0] - 2026-05-25
+
+Initial public release under the **MolScope** name, renamed from the earlier
+`molecule3d` prototype. This release consolidated the core toolkit:
+
+### Added
+
+- `Molecule` object on a NumPy core, with fixed-column PDB parsing and readers
+  and writers for XYZ, PDB, mmCIF and SDF.
+- Per-atom metadata, metadata-based selections, geometry measurements, and RMSD.
+- Molecular graph construction with NetworkX, PyTorch Geometric and DGL
+  exporters.
+- Coarse-graining tools: residue and custom mappings, explicit-bond support,
+  index-based mappings, and a dropped-atom warning.
+- Contact maps and ensemble contact-frequency analysis, plus ensemble RMSD
+  clustering and an RMSD heatmap.
+- Native structural descriptors and a MkDocs documentation site, including a
+  user-guide PDF builder.
+- `uv` support (lockfile, dev dependency group, `.python-version`), continuous
+  integration, and README visual examples.
+
+[Unreleased]: https://github.com/roshan2004/molscope/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/roshan2004/molscope/compare/v0.8.3...v0.9.0
+[0.8.3]: https://github.com/roshan2004/molscope/compare/v0.8.2...v0.8.3
+[0.8.2]: https://github.com/roshan2004/molscope/compare/v0.8.1...v0.8.2
+[0.8.1]: https://github.com/roshan2004/molscope/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/roshan2004/molscope/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/roshan2004/molscope/compare/v0.6.2...v0.7.0
+[0.6.2]: https://github.com/roshan2004/molscope/compare/v0.6.1...v0.6.2
+[0.6.1]: https://github.com/roshan2004/molscope/compare/v0.6.0...v0.6.1
+[0.6.0]: https://github.com/roshan2004/molscope/releases/tag/v0.6.0

{molscope-0.8.2 → molscope-0.9.0}/CITATION.cff

@@ -5,9 +5,19 @@ title: "MolScope: lightweight molecular structure analysis, visualisation, graph
 authors:
   - family-names: Shrestha
     given-names: Roshan
-version: 0.8.2
-date-released: "2026-05-28"
+    orcid: "https://orcid.org/0000-0002-9356-5136"
+    affiliation: "Independent Researcher"
+version: 0.9.0
+date-released: "2026-05-29"
 license: MIT
+doi: 10.5281/zenodo.20433850
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.20433850
+    description: Concept DOI (always resolves to the latest archived version)
+  - type: doi
+    value: 10.5281/zenodo.20433851
+    description: DOI for v0.8.3
 repository-code: "https://github.com/roshan2004/molscope"
 url: "https://github.com/roshan2004/molscope"
 abstract: >

{molscope-0.8.2 → molscope-0.9.0}/MANIFEST.in

@@ -1,4 +1,5 @@
 include CITATION.cff
+include CHANGELOG.md
 include LICENSE
 include README.md
 include mkdocs.yml

{molscope-0.8.2/molscope.egg-info → molscope-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: molscope
-Version: 0.8.2
+Version: 0.9.0
 Summary: Lightweight molecular coordinate workflows for descriptors, graph ML, and coarse-grained beads.
 Author-email: Roshan Shrestha <roshanpra@gmail.com>
 License-Expression: MIT
@@ -30,8 +30,12 @@ Provides-Extra: chem
 Requires-Dist: rdkit>=2023.9; extra == "chem"
 Provides-Extra: cif
 Requires-Dist: gemmi>=0.7; extra == "cif"
+Provides-Extra: xlsx
+Requires-Dist: openpyxl>=3.1; extra == "xlsx"
 Provides-Extra: gpu
 Requires-Dist: torch>=2.0; extra == "gpu"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; python_version >= "3.10" and extra == "mcp"
 Provides-Extra: validation
 Requires-Dist: mdanalysis>=2.7; extra == "validation"
 Requires-Dist: rdkit>=2023.9; extra == "validation"
@@ -57,6 +61,7 @@ Dynamic: license-file
 [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.11%20%7C%203.13-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20433850.svg)](https://doi.org/10.5281/zenodo.20433850)
 
 Lightweight molecular structure analysis, graph export, and coarse-graining in
 Python. MolScope is built around three polished workflows: turn coordinate
@@ -264,11 +269,17 @@ mol.select(chain="A")               # one chain
 mol.select(element="C")             # all carbons
 mol.select(resname="HOH")           # waters
 mol.select(resid=(10, 20))          # an inclusive residue range
+mol.select(resid=100, icode="A")    # PDB/mmCIF insertion code
+mol.residue_ids                     # full ResidueId(chain, resid, icode, resname)
 mol.alpha_carbons()                 # CA atoms (the usual basis for protein RMSD)
 mol.backbone()                      # N, CA, C, O
 mol[mask_or_indices]                # subset by numpy mask / index array
 ```
 
+Residue grouping, contact maps, binding sites and residue graphs use full
+residue identity internally, so residues like `100A` and `100B` stay separate
+while integer `resids` remain available for older code.
+
 ### Analysis and measurements
 
 ```python
@@ -353,10 +364,11 @@ Codes follow DSSP notation: `H`/`G`/`I` helices, `E`/`B` strands, `T` turn, `S`
 bend, `-` coil. This is a simplified **educational** implementation of the
 Kabsch-Sander hydrogen-bond model: not bit-identical to the reference `mkdssp`
 on every edge case, but validated against it. A CI cross-check
-(`tests/validation`) puts it at **~99% per-residue 3-state agreement**
-(helix/strand/coil) with `mkdssp` 4.2.2 on the bundled aquaporin (`1fqy`);
-strand-rich folds, where reference DSSP is hardest to match, will agree less
-closely. It needs backbone N/CA/C/O atoms, so use PDB/mmCIF input (not a bare
+(`tests/validation`) spans three fold classes and reports **~98 to 99%
+per-residue 3-state agreement** (helix/strand/coil) with `mkdssp`: 99.1% on the
+helical aquaporin (`1fqy`), 100% on mixed alpha/beta ubiquitin (`1ubq`), and
+98.2% on the all-beta SH3 domain (`1shg`). It needs backbone N/CA/C/O atoms, so
+use PDB/mmCIF input (not a bare
 `.xyz`). The secondary-structure render in the showcase above (helices red,
 turns cyan, coil grey) is produced this way.
 
@@ -513,7 +525,8 @@ inspection and reuse, not a validated simulation topology.
 
 ## Command-line interface
 
-MolScope provides a powerful CLI for visualization, batch analysis, and ML graph export.
+MolScope provides a CLI for visualization, binding-site tables, batch analysis,
+and ML graph export.
 
 ### View (default)
 Visualize a structure, apply transformations, and save images or animations.
@@ -529,6 +542,14 @@ Batch compute molecular descriptors for many files and save to a CSV table.
 molscope analyze examples/data/*.pdb --out results.csv --preset native-3d --jobs 4
 ```
 
+### Binding sites
+Write protein-ligand binding-site residue contacts and optional pocket
+descriptors to CSV.
+```bash
+molscope binding-site examples/data/3ptb.pdb --out site.csv --cutoff 4.5
+molscope binding-site examples/data/3ptb.pdb --out site.csv --descriptors-out pocket.csv
+```
+
 ### Export
 Batch export molecular graphs to PyTorch Geometric, DGL, or NetworkX formats.
 ```bash
@@ -536,6 +557,53 @@ molscope export "data/*.cif" --to pyg --out-dir pyg_graphs/ --pe laplacian --job
 ```
 Supports advanced features like `--self-loops`, `--global-node`, and `--pe` (positional encodings).
 
+### Select
+Pick a diverse subset from a molecule table (`.csv` or `.xlsx`) by MaxMin
+selection over descriptors. Select on existing numeric columns, or compute
+descriptors from a SMILES column with RDKit.
+```bash
+# diverse pick on existing property columns (no extras needed for CSV)
+molscope select molecules.csv --descriptor-cols MW ALogP -n 100 --out picked.csv
+
+# or compute RDKit descriptors from SMILES first (needs the chem extra;
+# .xlsx input needs the xlsx extra)
+molscope select molecules.xlsx --smiles-col SMILES --compute-descriptors -n 100 --out picked.csv
+```
+`MolLogP` (RDKit's Crippen logP) is the ALogP equivalent. Rows with missing
+descriptors are skipped; selection is deterministic.
+
+## Use from an AI assistant (MCP)
+
+MolScope ships an optional [Model Context Protocol](https://modelcontextprotocol.io)
+server, so an AI assistant such as Claude Code or Claude Desktop can drive its
+analyses in natural language. The server exposes MolScope's existing features as
+MCP tools; it adds no new science, just an adapter layer over the public API.
+
+```bash
+pip install "molscope[mcp]"             # needs Python >= 3.10
+claude mcp add molscope -- molscope-mcp  # register with Claude Code
+```
+
+The server runs over stdio (`molscope-mcp`, or `python -m molscope.mcp_server`)
+and provides these tools:
+
+| Tool | What it does |
+| --- | --- |
+| `summarize_structure` | Load a file or PDB id and report atoms, formula, chains, size. |
+| `compute_descriptors` | Descriptor table across one or more structures (the batch tool). |
+| `secondary_structure` | Per-residue DSSP codes and helix/strand/coil composition. |
+| `contact_map` | Contact count, contact order, and labelled contacting pairs. |
+| `binding_site` | Protein residues around a ligand, closest first. |
+| `molecular_graph` | Node/edge counts and feature names for the ML graph. |
+| `coarse_grain` | Bead assignment statistics for a coarse-grained mapping. |
+| `render_structure`, `render_contact_map` | Return PNG figures. |
+
+Each tool takes a `source` that is either a local coordinate-file path or a
+4-character PDB id (fetched from RCSB). For example, you can ask the assistant to
+*"fetch trypsin (3ptb), find the benzamidine binding-site residues, and render a
+contact map"*, and it will call `binding_site` then `render_contact_map`. See
+[`docs/user-guide/mcp-server.md`](docs/user-guide/mcp-server.md) for the full
+guide.
 
 ## Sample structures
 
@@ -544,6 +612,7 @@ Supports advanced features like `--self-loops`, `--global-node`, and `--pe` (pos
 | `examples/data/helix_201.xyz` | a helix (bare coordinates) |
 | `examples/data/1fqy.pdb` | Aquaporin-1, single model (1661 atoms) |
 | `examples/data/1aml.pdb` | Alzheimer amyloid A4 peptide, 20-model NMR ensemble |
+| `examples/data/3ptb.pdb` | Trypsin-benzamidine complex, ligand-binding-site example |
 
 ## Notes
 
@@ -582,6 +651,20 @@ that run everywhere, plus cross-checks against reference scientific tools (the
 simplified DSSP vs `mkdssp`) that turn "the tests pass" into a measured
 agreement number.
 
+## Changelog
+
+Notable changes for each release are recorded in [`CHANGELOG.md`](CHANGELOG.md),
+following the [Keep a Changelog](https://keepachangelog.com/) format.
+
+## How to cite
+
+Each release of MolScope is archived on Zenodo with a citable DOI. The concept
+DOI [10.5281/zenodo.20433850](https://doi.org/10.5281/zenodo.20433850) always
+resolves to the latest version; each release also has its own version DOI.
+Machine-readable citation metadata lives in [`CITATION.cff`](CITATION.cff), so
+GitHub's "Cite this repository" button on the sidebar produces BibTeX and APA
+entries automatically.
+
 ## License
 
 [MIT](LICENSE)

{molscope-0.8.2 → molscope-0.9.0}/README.md

@@ -7,6 +7,7 @@
 [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.11%20%7C%203.13-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20433850.svg)](https://doi.org/10.5281/zenodo.20433850)
 
 Lightweight molecular structure analysis, graph export, and coarse-graining in
 Python. MolScope is built around three polished workflows: turn coordinate
@@ -214,11 +215,17 @@ mol.select(chain="A")               # one chain
 mol.select(element="C")             # all carbons
 mol.select(resname="HOH")           # waters
 mol.select(resid=(10, 20))          # an inclusive residue range
+mol.select(resid=100, icode="A")    # PDB/mmCIF insertion code
+mol.residue_ids                     # full ResidueId(chain, resid, icode, resname)
 mol.alpha_carbons()                 # CA atoms (the usual basis for protein RMSD)
 mol.backbone()                      # N, CA, C, O
 mol[mask_or_indices]                # subset by numpy mask / index array
 ```
 
+Residue grouping, contact maps, binding sites and residue graphs use full
+residue identity internally, so residues like `100A` and `100B` stay separate
+while integer `resids` remain available for older code.
+
 ### Analysis and measurements
 
 ```python
@@ -303,10 +310,11 @@ Codes follow DSSP notation: `H`/`G`/`I` helices, `E`/`B` strands, `T` turn, `S`
 bend, `-` coil. This is a simplified **educational** implementation of the
 Kabsch-Sander hydrogen-bond model: not bit-identical to the reference `mkdssp`
 on every edge case, but validated against it. A CI cross-check
-(`tests/validation`) puts it at **~99% per-residue 3-state agreement**
-(helix/strand/coil) with `mkdssp` 4.2.2 on the bundled aquaporin (`1fqy`);
-strand-rich folds, where reference DSSP is hardest to match, will agree less
-closely. It needs backbone N/CA/C/O atoms, so use PDB/mmCIF input (not a bare
+(`tests/validation`) spans three fold classes and reports **~98 to 99%
+per-residue 3-state agreement** (helix/strand/coil) with `mkdssp`: 99.1% on the
+helical aquaporin (`1fqy`), 100% on mixed alpha/beta ubiquitin (`1ubq`), and
+98.2% on the all-beta SH3 domain (`1shg`). It needs backbone N/CA/C/O atoms, so
+use PDB/mmCIF input (not a bare
 `.xyz`). The secondary-structure render in the showcase above (helices red,
 turns cyan, coil grey) is produced this way.
 
@@ -463,7 +471,8 @@ inspection and reuse, not a validated simulation topology.
 
 ## Command-line interface
 
-MolScope provides a powerful CLI for visualization, batch analysis, and ML graph export.
+MolScope provides a CLI for visualization, binding-site tables, batch analysis,
+and ML graph export.
 
 ### View (default)
 Visualize a structure, apply transformations, and save images or animations.
@@ -479,6 +488,14 @@ Batch compute molecular descriptors for many files and save to a CSV table.
 molscope analyze examples/data/*.pdb --out results.csv --preset native-3d --jobs 4
 ```
 
+### Binding sites
+Write protein-ligand binding-site residue contacts and optional pocket
+descriptors to CSV.
+```bash
+molscope binding-site examples/data/3ptb.pdb --out site.csv --cutoff 4.5
+molscope binding-site examples/data/3ptb.pdb --out site.csv --descriptors-out pocket.csv
+```
+
 ### Export
 Batch export molecular graphs to PyTorch Geometric, DGL, or NetworkX formats.
 ```bash
@@ -486,6 +503,53 @@ molscope export "data/*.cif" --to pyg --out-dir pyg_graphs/ --pe laplacian --job
 ```
 Supports advanced features like `--self-loops`, `--global-node`, and `--pe` (positional encodings).
 
+### Select
+Pick a diverse subset from a molecule table (`.csv` or `.xlsx`) by MaxMin
+selection over descriptors. Select on existing numeric columns, or compute
+descriptors from a SMILES column with RDKit.
+```bash
+# diverse pick on existing property columns (no extras needed for CSV)
+molscope select molecules.csv --descriptor-cols MW ALogP -n 100 --out picked.csv
+
+# or compute RDKit descriptors from SMILES first (needs the chem extra;
+# .xlsx input needs the xlsx extra)
+molscope select molecules.xlsx --smiles-col SMILES --compute-descriptors -n 100 --out picked.csv
+```
+`MolLogP` (RDKit's Crippen logP) is the ALogP equivalent. Rows with missing
+descriptors are skipped; selection is deterministic.
+
+## Use from an AI assistant (MCP)
+
+MolScope ships an optional [Model Context Protocol](https://modelcontextprotocol.io)
+server, so an AI assistant such as Claude Code or Claude Desktop can drive its
+analyses in natural language. The server exposes MolScope's existing features as
+MCP tools; it adds no new science, just an adapter layer over the public API.
+
+```bash
+pip install "molscope[mcp]"             # needs Python >= 3.10
+claude mcp add molscope -- molscope-mcp  # register with Claude Code
+```
+
+The server runs over stdio (`molscope-mcp`, or `python -m molscope.mcp_server`)
+and provides these tools:
+
+| Tool | What it does |
+| --- | --- |
+| `summarize_structure` | Load a file or PDB id and report atoms, formula, chains, size. |
+| `compute_descriptors` | Descriptor table across one or more structures (the batch tool). |
+| `secondary_structure` | Per-residue DSSP codes and helix/strand/coil composition. |
+| `contact_map` | Contact count, contact order, and labelled contacting pairs. |
+| `binding_site` | Protein residues around a ligand, closest first. |
+| `molecular_graph` | Node/edge counts and feature names for the ML graph. |
+| `coarse_grain` | Bead assignment statistics for a coarse-grained mapping. |
+| `render_structure`, `render_contact_map` | Return PNG figures. |
+
+Each tool takes a `source` that is either a local coordinate-file path or a
+4-character PDB id (fetched from RCSB). For example, you can ask the assistant to
+*"fetch trypsin (3ptb), find the benzamidine binding-site residues, and render a
+contact map"*, and it will call `binding_site` then `render_contact_map`. See
+[`docs/user-guide/mcp-server.md`](docs/user-guide/mcp-server.md) for the full
+guide.
 
 ## Sample structures
 
@@ -494,6 +558,7 @@ Supports advanced features like `--self-loops`, `--global-node`, and `--pe` (pos
 | `examples/data/helix_201.xyz` | a helix (bare coordinates) |
 | `examples/data/1fqy.pdb` | Aquaporin-1, single model (1661 atoms) |
 | `examples/data/1aml.pdb` | Alzheimer amyloid A4 peptide, 20-model NMR ensemble |
+| `examples/data/3ptb.pdb` | Trypsin-benzamidine complex, ligand-binding-site example |
 
 ## Notes
 
@@ -532,6 +597,20 @@ that run everywhere, plus cross-checks against reference scientific tools (the
 simplified DSSP vs `mkdssp`) that turn "the tests pass" into a measured
 agreement number.
 
+## Changelog
+
+Notable changes for each release are recorded in [`CHANGELOG.md`](CHANGELOG.md),
+following the [Keep a Changelog](https://keepachangelog.com/) format.
+
+## How to cite
+
+Each release of MolScope is archived on Zenodo with a citable DOI. The concept
+DOI [10.5281/zenodo.20433850](https://doi.org/10.5281/zenodo.20433850) always
+resolves to the latest version; each release also has its own version DOI.
+Machine-readable citation metadata lives in [`CITATION.cff`](CITATION.cff), so
+GitHub's "Cite this repository" button on the sidebar produces BibTeX and APA
+entries automatically.
+
 ## License
 
 [MIT](LICENSE)

{molscope-0.8.2 → molscope-0.9.0}/docs/api-reference.md

@@ -9,12 +9,22 @@
 - `molscope.write_pdb(molecule, path)`, `write_xyz(molecule, path)`.
 - `molscope.featurize_many(paths, return_names=False)`: build an ML feature matrix.
 - `molscope.descriptor_feature_names(preset)`: stable flattened descriptor columns.
+- `molscope.pocket_descriptor_feature_names("pocket-basic")`: stable binding-pocket descriptor columns.
 - `molscope.node_feature_names(preset)`, `edge_feature_names(preset)`: atom/bond graph preset columns.
 - `molscope.residue_node_feature_names(preset)`, `residue_edge_feature_names(preset)`: residue contact graph preset columns.
 - `molscope.interface_residues(mol, chain_a, chain_b, cutoff=5.0)`, `chain_contact_matrix(mol, cutoff=5.0)`: chain interfaces.
 - `molscope.ligands(mol, ...)`, `binding_site(mol, ligand=None, cutoff=4.5)`: ligand detection and binding-site residues.
 - `molscope.backbone_torsions(mol)`: per-residue phi/psi/omega.
 
+Residue identity helpers:
+
+- `molscope.ResidueId(chain, resid, insertion_code="", resname="")`: full residue identity used by PDB/mmCIF-aware APIs.
+- `molscope.ResidueGroup`: yielded by `Molecule.residue_groups()`; has `.residue_id` and still unpacks as `(atom_indices, resname, resid, chain)`.
+
+`BindingSite` results expose `to_records()`, `to_molecule(mol)`,
+`descriptors(mol, preset="pocket-basic")`, and `plot(mol)` for residue tables,
+pocket descriptor extraction, and quick figures.
+
 ## Molecule
 
 Construction:

{molscope-0.8.2 → molscope-0.9.0}/docs/examples/binding-site.md

@@ -12,7 +12,7 @@ mol = ms.read("examples/data/3ptb.pdb")
 print(mol.ligands())                 # [LigandResidue(A:BEN1, 9 atoms)]
 
 site = mol.binding_site(cutoff=4.5)  # single ligand auto-detected
-print(site)                          # BindingSite(BEN1: 13 residues < 4.5 A)
+print(site)                          # BindingSite(A:BEN1: 13 residues < 4.5 A)
 
 for res, dist in zip(site.residues, site.min_distances):
     print(f"{res!s:<10} {dist:.2f} A")
@@ -23,13 +23,39 @@ for res, dist in zip(site.residues, site.min_distances):
 # A:SER195   3.65   <- catalytic serine
 ```
 
+For quick figures or reports, convert the site to table-friendly residue
+records and extract descriptors for only the site residues:
+
+```python
+site.to_records()[0]
+# {'residue_id': 'A:GLY219', 'chain': 'A', 'resid': 219,
+#  'insertion_code': '', 'resname': 'GLY',
+#  'min_distance': 2.815..., 'n_atom_contacts': 5}
+
+site.descriptors(mol, preset="pocket-basic")
+site.plot(mol, show=False)          # pocket residues plus ligand
+```
+
+The same residue table is available from the command line:
+
+```bash
+molscope binding-site examples/data/3ptb.pdb --out site.csv --cutoff 4.5
+```
+
+Add `--descriptors-out pocket.csv` to also write the one-row
+`pocket-basic` descriptor table.
+
 When a structure has several ligands, select one by residue name or location:
 
 ```python
 mol.binding_site(ligand="BEN")
 mol.binding_site(ligand=("A", 1))
+mol.binding_site(ligand=("A", 100, "A"))  # with insertion code
 ```
 
+The CLI accepts the same choices as `--ligand BEN`, `--ligand A:1`, or
+`--ligand A:100:A`.
+
 A runnable version lives in
 [`examples/binding_site.py`](https://github.com/roshan2004/molscope/blob/main/examples/binding_site.py).
 See the full guide:

{molscope-0.8.2 → molscope-0.9.0}/docs/limitations.md

@@ -122,17 +122,21 @@ style assignment based on backbone hydrogen-bond patterns.
 What is validated:
 
 - The validation suite compares MolScope's simplified DSSP against `mkdssp`
-  where the reference binary is available.
-- On the bundled Aquaporin-1 structure (`1fqy`), CI records about 99%
-  agreement after reducing DSSP states to helix/strand/coil.
+  across three fold classes where the reference binary is available:
+  Aquaporin-1 (`1fqy`, helix-dominated), ubiquitin (`1ubq`, mixed alpha/beta),
+  and the SH3 domain (`1shg`, all-beta).
+- After reducing DSSP states to helix/strand/coil, agreement is high across
+  all three folds: about 99% on the helical and mixed structures and about
+  98% on the all-beta one.
 
 Limits:
 
 - Not bit-identical to reference `mkdssp`. Treat output as the
   educational/prototyping equivalent of DSSP, not as a substitute for it in
   production pipelines.
-- Strand-rich and edge-case folds can disagree more strongly than helical
-  test structures.
+- Disagreements concentrate at the boundary residues of helices and strands,
+  and on irregular or low-quality structures, rather than on any one fold
+  class.
 - Needs backbone N/CA/C/O atoms, so bare XYZ input is insufficient.
 - Only the standard collapsed states (H/E/C) are validated against the
   reference; finer DSSP categories are not.

{molscope-0.8.2 → molscope-0.9.0}/docs/user-guide/descriptors.md

@@ -57,6 +57,20 @@ Preset options:
 - `native-3d`: `native-basic` plus centres, inertia, principal axes/moments, and distance histograms.
 - `rdkit-basic`: `native-basic` plus a stable subset of RDKit scalar descriptors.
 
+Ligand binding sites have their own fixed-size preset because they need a
+ligand context:
+
+```python
+mol = ms.read("examples/data/3ptb.pdb")
+site = mol.binding_site(cutoff=4.5)
+pocket = site.descriptors(mol, preset="pocket-basic")
+names = ms.pocket_descriptor_feature_names("pocket-basic")
+```
+
+`pocket-basic` includes pocket atom and residue counts, amino-acid composition,
+protein-ligand contact counts, radius of gyration, bounding-box dimensions, and
+ligand-distance summaries.
+
 ## RDKit descriptors
 
 Install the optional chemical backend to access RDKit's scalar descriptor set: