molscope 0.8.1__tar.gz → 0.8.2__tar.gz

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

@@ -5,8 +5,8 @@ title: "MolScope: lightweight molecular structure analysis, visualisation, graph
 authors:
   - family-names: Shrestha
     given-names: Roshan
-version: 0.8.1
-date-released: "2026-05-26"
+version: 0.8.2
+date-released: "2026-05-28"
 license: MIT
 repository-code: "https://github.com/roshan2004/molscope"
 url: "https://github.com/roshan2004/molscope"

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

@@ -7,5 +7,7 @@ recursive-include docs *.md *.png
 recursive-include examples *.py
 recursive-include examples/data *.pdb *.xyz
 recursive-include notebooks *.ipynb
+recursive-include scripts *.py
 recursive-include tests *.py
+recursive-include tests/fixtures *.xyz *.pdb *.cif *.sdf
 prune notebooks/.ipynb_checkpoints

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

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: molscope
-Version: 0.8.1
-Summary: Lightweight molecular structure analysis, visualisation, graph export, and coarse-graining in Python.
+Version: 0.8.2
+Summary: Lightweight molecular coordinate workflows for descriptors, graph ML, and coarse-grained beads.
 Author-email: Roshan Shrestha <roshanpra@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/roshan2004/molscope
 Project-URL: Repository, https://github.com/roshan2004/molscope
-Project-URL: Documentation, https://roshan2004.github.io/molscope/
+Project-URL: Documentation, https://molscope.readthedocs.io/
 Project-URL: Issues, https://github.com/roshan2004/molscope/issues
 Keywords: chemistry,molecular-structure,pdb,xyz,mmcif,coarse-graining,molecular-graphs,machine-learning,visualization
 Classifier: Programming Language :: Python :: 3
@@ -19,6 +19,7 @@ Requires-Dist: numpy>=1.21
 Requires-Dist: matplotlib>=3.5
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
 Provides-Extra: fast
 Requires-Dist: scipy>=1.7; extra == "fast"
 Provides-Extra: viz
@@ -29,6 +30,8 @@ Provides-Extra: chem
 Requires-Dist: rdkit>=2023.9; extra == "chem"
 Provides-Extra: cif
 Requires-Dist: gemmi>=0.7; extra == "cif"
+Provides-Extra: gpu
+Requires-Dist: torch>=2.0; extra == "gpu"
 Provides-Extra: validation
 Requires-Dist: mdanalysis>=2.7; extra == "validation"
 Requires-Dist: rdkit>=2023.9; extra == "validation"
@@ -48,27 +51,35 @@ Dynamic: license-file
 # MolScope
 
 [![CI](https://github.com/roshan2004/molscope/actions/workflows/ci.yml/badge.svg)](https://github.com/roshan2004/molscope/actions/workflows/ci.yml)
-[![Docs](https://img.shields.io/badge/docs-MkDocs%20Material-blue)](https://roshan2004.github.io/molscope/)
+[![codecov](https://codecov.io/gh/roshan2004/molscope/branch/main/graph/badge.svg)](https://codecov.io/gh/roshan2004/molscope)
+[![Docs](https://readthedocs.org/projects/molscope/badge/?version=latest)](https://molscope.readthedocs.io/en/latest/)
 [![PyPI](https://img.shields.io/pypi/v/molscope.svg)](https://pypi.org/project/molscope/)
 [![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)
 
-Lightweight molecular structure analysis, visualisation, graph export, and
-coarse-graining in Python. Read `.xyz`, `.pdb`, `.cif` and `.sdf` files
-(optionally gzip-compressed), select and analyse atoms, and visualise them in
-3D. The `.cif` reader handles standard `_atom_site` coordinate loops, including
-quoted values; optional Gemmi-backed validation is available through
-`pip install "molscope[cif]"`.
+Lightweight molecular structure analysis, graph export, and coarse-graining in
+Python. MolScope is built around three polished workflows: turn coordinate
+files into descriptor tables, graph-ML inputs, or coarse-grained bead
+representations without pulling in a full simulation stack.
 
-MolScope is a small scientific Python toolkit for turning molecular coordinate
-files into inspectable structures, descriptors, ML-ready graphs, and
-coarse-grained bead models without pulling in a full simulation stack.
+Read `.xyz`, `.pdb`, `.cif` and `.sdf` files, select and analyse atoms, and
+visualise structures in 3D. Optional extras add Gemmi validation, RDKit chemical
+features, PyTorch Geometric, DGL, and other backend integrations only when a
+workflow needs them.
 
 | 3D structure (element) | Secondary structure (DSSP) | Residue contact map | Coarse-grained beads |
 | --- | --- | --- | --- |
 | ![Aquaporin-1 rendered as a 3D element-coloured molecular structure](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/aquaporin-structure-v2.png) | ![Aquaporin-1 coloured by DSSP secondary structure: helices red, turns cyan, coil grey](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/secondary-structure.png) | ![Residue-level contact map heatmap for Aquaporin-1](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/residue-contact-map.png) | ![Coarse-grained bead model of Aquaporin-1](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/coarse-grained-beads-v2.png) |
 
+## Core workflows
+
+| Workflow | Start here | Output |
+| --- | --- | --- |
+| **PDB to descriptors** | [`docs/tutorials/pdb-to-descriptors.md`](docs/tutorials/pdb-to-descriptors.md) | Fixed-width structural and optional RDKit-backed feature tables for screening, QC, and classical ML. |
+| **PDB to graph/GNN** | [`docs/tutorials/pdb-to-graph-gnn.md`](docs/tutorials/pdb-to-graph-gnn.md) | Atom/bond, residue-contact, and PyTorch Geometric-ready graph data for message-passing experiments. |
+| **PDB to coarse-grained beads** | [`docs/tutorials/pdb-to-coarse-grained-beads.md`](docs/tutorials/pdb-to-coarse-grained-beads.md) | Residue, simplified Martini-style, custom, and virtual-site bead models for inspection and graph prototyping. |
+
 ## Who is this for?
 
 - Students learning molecular-coordinate formats, structure analysis, and basic
@@ -78,29 +89,22 @@ coarse-grained bead models without pulling in a full simulation stack.
 - ML-for-molecules learners who need deterministic descriptors and graph exports
   before moving to larger chemistry or simulation frameworks.
 
-## What it does
-
-- **Read and write** XYZ, PDB, mmCIF and SDF (gzip-aware), preserve SDF/PDB
-  explicit bonds and SDF formal charges where present, fetch structures by id
-  from RCSB, and load multi-model NMR ensembles.
-- **Validate mmCIF** syntax, atom-site coordinate columns, and supplied
-  dictionary files with optional Gemmi support.
-- **Select and measure** by chain, element or residue; compute distances,
-  angles, dihedrals and Kabsch-aligned RMSD.
-- **Analyse** centroids, radius of gyration, the inertia tensor,
-  explicit/inferred bonds, and contacts.
-- **Contact maps** at atom or residue level, with heatmap plots.
-- **Secondary structure** via a self-contained, dependency-free DSSP, with
-  `plot(color_by="ss")`.
-- **Ensembles**: pairwise RMSD, RMSF, averaging, and conformer clustering.
-- **Export for ML**: flat structural descriptors and molecular graphs for
-  NetworkX, PyTorch Geometric and DGL.
-- **Chemical perception and descriptors**: optional RDKit-backed formal charge,
-  valence, aromaticity and scalar descriptor features with
-  `pip install "molscope[chem]"`.
-- **Coarse-grain** onto residue, Martini-style or custom bead mappings.
-- **Visualise** with 3D matplotlib plots, an interactive py3Dmol viewer, spin
-  GIFs, and a command-line interface.
+## Supporting capabilities
+
+MolScope keeps the broad feature surface organized around those workflows:
+
+- **Input layer**: read and write XYZ, PDB, mmCIF and SDF, preserve explicit
+  bonds and charges where present, fetch structures from RCSB, and validate
+  mmCIF files with optional Gemmi support.
+- **Structure analysis**: select atoms by metadata, compute geometry, RMSD,
+  contacts, contact maps, interfaces, binding sites, and ensemble summaries.
+- **Annotations and descriptors**: run dependency-free secondary-structure
+  assignment, native structural descriptors, and optional RDKit-backed
+  chemistry descriptors.
+- **Representation outputs**: export descriptor tables, atom/bond graphs,
+  residue-contact graphs, and coarse-grained bead graphs to common ML backends.
+- **Inspection and automation**: visualize with Matplotlib or py3Dmol and use
+  the CLI for view, analyze, and export workflows.
 
 ## Architecture
 
@@ -116,17 +120,36 @@ graph LR
 
 ## Why MolScope?
 
-MolScope is **not** intended to replace full molecular-simulation or
-cheminformatics frameworks. It is a lightweight **educational and prototyping**
-toolkit for reading common molecular structure files, performing simple
-structural analysis, exporting graph representations for ML workflows, and
-experimenting with coarse-grained mappings. Its core depends only on NumPy and
-Matplotlib, and the API is Python-first and scriptable.
-
-In particular, the coarse-graining tools are for **educational CG mapping and
-bead-graph prototyping**: useful for exploring mappings before moving to a
-production Martini workflow. They are not a validated Martini force-field
-generator.
+MolScope takes you from a structure file to a descriptor table, a
+machine-learning graph, or a coarse-grained model with the smallest install that
+gets the job done. The core depends only on NumPy and Matplotlib, so
+`pip install molscope` stays light. Everything heavier (RDKit, PyTorch, PyTorch
+Geometric, DGL, MDAnalysis, Gemmi) is an opt-in [extra](#install) you add only
+when one of those workflows needs it.
+
+That makes it an on-ramp rather than a framework:
+
+- **Structure to ML graph in a few lines.** `mol.to_graph()` runs with zero extra
+  dependencies; `mol.to_pyg_data()`, `mol.to_networkx()` and `mol.to_dgl_graph()`
+  hand off to the ecosystem when you want it. This is the path MolScope is built
+  to make easy.
+- **Descriptor tables without a framework.** Native structural descriptors and
+  optional RDKit-backed chemistry descriptors share the same `Molecule` and
+  batch-featurization APIs.
+- **CG as a representation tool.** Residue, simplified Martini-style, custom
+  bead, and virtual-site mappings are inspectable molecules and bead graphs,
+  not hidden simulation setup state.
+- **Light enough to teach and prototype with.** A readable, Python-first API over
+  static structures, with no trajectory engine or build step to wrestle.
+- **Honest about its numbers.** Bonds, geometry and DSSP are cross-checked against
+  reference tools (MDAnalysis, `mkdssp`) in CI, so you know where the results come
+  from.
+
+MolScope is **not** a replacement for full molecular-simulation or
+cheminformatics frameworks. In particular, the coarse-graining tools are for
+**educational CG mapping and bead-graph prototyping**: useful for exploring
+mappings before moving to a production Martini workflow, not a validated Martini
+force-field generator.
 
 | Tool | Main focus | How MolScope differs |
 | --- | --- | --- |
@@ -138,8 +161,8 @@ generator.
 | nglview | Notebook structure viewer | MolScope also does analysis, descriptors, graphs and CG, not just viewing |
 
 Reach for those tools when you need their depth and validation. Reach for
-MolScope when you want something small, readable, and quick to teach or
-prototype with.
+MolScope when you want the shortest path from a structure file to analysis, an
+ML graph, or a CG prototype.
 
 ## Install
 
@@ -177,6 +200,11 @@ python scripts/build_user_guide_pdf.py
 Docs source lives in `docs/`; the site configuration is `mkdocs.yml`. The PDF
 builder requires Pandoc and a LaTeX engine such as `xelatex`.
 
+Scientific validation is documented in
+[`docs/validation.md`](docs/validation.md): reference tools, assumptions,
+failure modes, and tolerances for MDAnalysis, RDKit, `mkdssp`, and invariant
+checks.
+
 ## Quickstart
 
 A runnable end-to-end tour over the bundled sample structures lives in
@@ -190,12 +218,24 @@ MPLBACKEND=Agg uv run python examples/tour.py   # headless: saves PNGs instead
 It reads an `.xyz` and a `.pdb`, prints derived properties, compares the NMR
 models of `1aml`, writes a transformed structure back out, and renders a plot.
 
-For a focused workflow, see
-[`docs/examples/pdb-to-graph-cg.md`](docs/examples/pdb-to-graph-cg.md):
-from PDB to molecular graph and coarse-grained beads in about 10 minutes.
-For an ML-oriented walkthrough, see
-[`docs/examples/pdb-to-pyg-ml.md`](docs/examples/pdb-to-pyg-ml.md):
-PDB ensemble to PyTorch Geometric classifier/regressor toy model.
+For polished, focused workflows, start with the tutorials:
+[`PDB to descriptors`](docs/tutorials/pdb-to-descriptors.md),
+[`PDB to graph/GNN`](docs/tutorials/pdb-to-graph-gnn.md), and
+[`PDB to coarse-grained beads`](docs/tutorials/pdb-to-coarse-grained-beads.md).
+For coarse-graining as a runnable visual workflow, run
+[`examples/coarse_graining.py`](examples/coarse_graining.py): residue
+center-of-mass beads, residue centroids, and a simplified backbone/sidechain
+mapping with a visual atomistic-to-CG comparison.
+
+For protein-coordinate analysis from scratch, see
+[`docs/examples/protein-analysis-from-scratch.md`](docs/examples/protein-analysis-from-scratch.md)
+and [`notebooks/protein_analysis_from_scratch.ipynb`](notebooks/protein_analysis_from_scratch.ipynb):
+backbone atoms, residues, chains, alpha carbons, contact maps, NMR ensemble
+contacts, ligands, waters, binding sites, and simplified DSSP.
+
+For a runnable, narrated version of that ML walkthrough, open the notebook
+[`notebooks/pdb_to_gnn.ipynb`](notebooks/pdb_to_gnn.ipynb): structure file to a
+trained GNN, end to end (needs `pip install 'molscope[pyg]'`).
 
 ## Library
 
@@ -235,6 +275,7 @@ mol[mask_or_indices]                # subset by numpy mask / index array
 mol.centroid, mol.center_of_mass    # geometric / mass-weighted centre
 mol.radius_of_gyration              # compactness (angstrom)
 mol.dimensions, mol.formula         # bounding box, Hill-order formula
+mol.distance_matrix()               # dense pairwise matrix (NumPy, Torch, CuPy)
 mol.bonds()                         # inferred bond index pairs (KD-tree if scipy)
 mol.contacts(cutoff=5.0)            # atom pairs within a distance
 mol.contact_count(cutoff=5.0)       # count pairs without returning them
@@ -288,12 +329,14 @@ mol.plot_contact_map(cutoff=8.0)                      # heatmap
 mol.contact_map(level="atom")                         # atom-level map
 mol.contact_map(level="residue", method="min")        # closest inter-residue atom
 mol.contact_map(level="residue", method="com")        # residue centre of mass
+mol.contact_map(level="residue", backend="torch", device="cuda")  # optional GPU
 ```
 
 ### Secondary structure (DSSP)
 
 Assign protein secondary structure from backbone hydrogen-bond patterns with a
-self-contained, pure-NumPy DSSP (no external `mkdssp` binary needed):
+self-contained, pure-NumPy, **simplified DSSP-style** implementation (no
+external `mkdssp` binary needed):
 
 ```python
 mol = ms.read("examples/data/1fqy.pdb")
@@ -306,8 +349,8 @@ ss.summary()                        # helix/strand/coil counts and fractions
 mol.plot(color_by="ss")             # colour the 3D view by secondary structure
 ```
 
-Codes follow DSSP: `H`/`G`/`I` helices, `E`/`B` strands, `T` turn, `S` bend,
-`-` coil. This is a simplified **educational** implementation of the
+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**
@@ -399,6 +442,18 @@ Graph feature presets are also available through
 `mol.to_graph(include_chemical_features=True)` to attach optional RDKit-backed
 aromatic atom and bond flags.
 
+For protein-scale spatial graphs, build a residue contact graph instead:
+
+```python
+rg = mol.to_residue_contact_graph(cutoff=8.0, method="ca", min_seq_sep=4)
+RG = rg.to_networkx()
+residue_data = rg.to_pyg_data(node_preset="ml", edge_preset="ml")
+```
+
+Use atom/bond graphs when covalent chemistry is the signal. Use residue or
+bead contact graphs when 3D neighborhoods, interfaces, folded shape or
+long-range contacts are the signal.
+
 ### Coarse-graining
 
 Map an atomistic structure onto a smaller set of beads. The result is an
@@ -411,6 +466,7 @@ mol = ms.read("examples/data/1fqy.pdb")
 cg = mol.coarse_grain("residue_com")        # one bead per residue (centre of mass)
 cg = mol.coarse_grain("residue_centroid")   # ...or geometric centroid
 cg = mol.coarse_grain("martini")            # simplified backbone + side-chain beads
+cg = mol.coarse_grain("martini", virtual_sites=[{"name": "MID", "parents": [0, 2]}])
 cg.plot(scale=200)                          # beads + backbone topology
 print(cg.mapping_report())                  # explain beads, dropped atoms, and bonds
 
@@ -426,24 +482,61 @@ cg = mol.coarse_grain({"head": [0, 1, 2, 3], "tail": [4, 5, 6, 7]},
 cg.to_graph()                               # CG bead network, ready for ML
 ```
 
+Visualise the mapping, inspect the per-bead assignment, and export it:
+
+```python
+ms.plot_mapping(mol, cg)                    # atoms coloured by bead, beads + bonds overlaid
+
+report = cg.coarse_grain_report             # structured assignment
+print(report.coverage())                    # "426 beads from 1661/1661 atoms"
+print(report.beads[0].atom_indices)          # source atoms folded into bead 0
+
+cg.write_mapping("mapping.json")            # round-trippable JSON record
+record = ms.read_cg_mapping("mapping.json")
+cg2 = ms.apply_cg_mapping(mol, record)      # rebuild on a matching structure
+cg.write_index("mapping.ndx")               # GROMACS-style index, one group per bead
+```
+
 Bead positions are mass-weighted (or centroids). For residue mappings bonds are
 generated automatically (within a residue, plus a backbone chain between
 residues); pass `bonds=` to define them yourself. Name-based bonds are intended
 for unique bead names such as `head`/`tail`; repeated names such as `BB`/`SC`
 are ambiguous, so use bead indices for those. Atoms you leave unassigned are
-dropped with a warning. This is meant
-for teaching and prototyping CG mappings, not as a replacement for production
-Martini parameters.
+dropped with a warning. The `"martini"` mapping teaches the idea of backbone and
+sidechain beads. Virtual sites are represented explicitly as derived coordinate
+sites and graph flags, but MolScope does not assign Martini bead types,
+bonded/nonbonded parameters, charges, exclusions, GROMACS virtual-site topology
+sections, or simulation-engine topology files. This is meant for teaching and
+prototyping CG mappings, not as a replacement for production Martini
+preparation: the JSON and `.ndx` exports describe a bead assignment for
+inspection and reuse, not a validated simulation topology.
+
+## Command-line interface
 
-## Command line
+MolScope provides a powerful CLI for visualization, batch analysis, and ML graph export.
 
+### View (default)
+Visualize a structure, apply transformations, and save images or animations.
 ```bash
-molscope examples/data/helix_201.xyz --translate 1 2 -1
 molscope examples/data/1fqy.pdb --select atom_name=CA --color-by residue --save ca.png
+molscope examples/data/1fqy.pdb --select "chain=A and atom_name=CA" --save chain-a-ca.png
 molscope --fetch 1aml --center --gif amyloid.gif
-python -m molscope examples/data/1fqy.pdb          # equivalent if not pip-installed
 ```
 
+### Analyze
+Batch compute molecular descriptors for many files and save to a CSV table.
+```bash
+molscope analyze examples/data/*.pdb --out results.csv --preset native-3d --jobs 4
+```
+
+### Export
+Batch export molecular graphs to PyTorch Geometric, DGL, or NetworkX formats.
+```bash
+molscope export "data/*.cif" --to pyg --out-dir pyg_graphs/ --pe laplacian --jobs 8
+```
+Supports advanced features like `--self-loops`, `--global-node`, and `--pe` (positional encodings).
+
+
 ## Sample structures
 
 | File | Contents |
@@ -468,6 +561,7 @@ python -m molscope examples/data/1fqy.pdb          # equivalent if not pip-insta
 - Optional extras: `pip install "molscope[fast]"` (scipy, faster bonds/contacts),
   `"molscope[viz]"` (py3Dmol, for `Molecule.view`), `"molscope[graph]"`
   (NetworkX), `"molscope[chem]"` (RDKit), `"molscope[cif]"` (Gemmi),
+  `"molscope[gpu]"` (PyTorch dense distance/contact-map backend),
   `"molscope[pyg]"`, `"molscope[dgl]"`, or `"molscope[gnn]"`. For custom CUDA,
   ROCm, Apple Silicon, or cluster builds, install the matching PyTorch stack
   first.