molscope 0.6.2__tar.gz → 0.8.0__tar.gz

{molscope-0.6.2 → molscope-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: molscope
-Version: 0.6.2
+Version: 0.8.0
 Summary: Lightweight molecular structure analysis, visualisation, graph export, and coarse-graining in Python.
 Author-email: Roshan Shrestha <roshanpra@gmail.com>
 License-Expression: MIT
@@ -23,6 +23,21 @@ Provides-Extra: viz
 Requires-Dist: py3Dmol>=2.0; extra == "viz"
 Provides-Extra: graph
 Requires-Dist: networkx>=2.6; extra == "graph"
+Provides-Extra: chem
+Requires-Dist: rdkit>=2023.9; extra == "chem"
+Provides-Extra: cif
+Requires-Dist: gemmi>=0.7; extra == "cif"
+Provides-Extra: pyg
+Requires-Dist: torch>=2.0; extra == "pyg"
+Requires-Dist: torch-geometric>=2.3; extra == "pyg"
+Provides-Extra: dgl
+Requires-Dist: torch>=2.0; extra == "dgl"
+Requires-Dist: dgl>=1.1; extra == "dgl"
+Provides-Extra: gnn
+Requires-Dist: networkx>=2.6; extra == "gnn"
+Requires-Dist: torch>=2.0; extra == "gnn"
+Requires-Dist: torch-geometric>=2.3; extra == "gnn"
+Requires-Dist: dgl>=1.1; extra == "gnn"
 Dynamic: license-file
 
 # MolScope
@@ -35,29 +50,65 @@ Dynamic: license-file
 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 is a basic mmCIF parser for standard `_atom_site`
-coordinate loops, not a full mmCIF syntax implementation.
+3D. The `.cif` reader handles standard `_atom_site` coordinate loops, including
+quoted values; optional Gemmi-backed validation is available through
+`pip install "molscope[cif]"`.
 
-| 3D structure rendering | 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) | ![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) |
+| 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) |
 
 ## What it does
 
-- **Read and write** XYZ, PDB, mmCIF and SDF (gzip-aware), fetch structures by
-  id from RCSB, and load multi-model NMR ensembles.
+- **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, inferred bonds
-  and contacts.
+- **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.
 
+## 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.
+
+| Tool | Main focus | How MolScope differs |
+| --- | --- | --- |
+| RDKit | Cheminformatics | MolScope leans toward structure visualisation, protein/PDB-style metadata, and CG prototyping |
+| MDAnalysis | MD trajectories | MolScope is lighter and easier for static structures and teaching |
+| MDTraj | Trajectory analysis | MolScope is simpler and graph/CG oriented |
+| Biopython | Structure parsing / bioinformatics | MolScope adds 3D analysis, ML-graph export, and coarse-graining |
+| PyMOL / VMD | Interactive visualisation | MolScope is Python-first, scriptable, and ML-export friendly |
+| 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.
+
 ## Install
 
 With [uv](https://docs.astral.sh/uv/) (recommended):
@@ -144,6 +195,7 @@ mol.radius_of_gyration              # compactness (angstrom)
 mol.dimensions, mol.formula         # bounding box, Hill-order formula
 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
 
 mol.distance(i, j)                  # bond length
 mol.angle(i, j, k)                  # bond angle (degrees)
@@ -156,12 +208,14 @@ a.alpha_carbons().rmsd(b.alpha_carbons(), align=True)   # CA-RMSD after Kabsch f
 
 ```python
 features = mol.descriptors()                 # flat dict of scalar/vector descriptors
+features = mol.descriptors(preset="native-3d")
 features["radius_of_gyration"]
 features["principal_moments"]                # 3 values
 features["distance_histogram"]               # fixed-size histogram
 
 X, names = ms.featurize_many(
     ["a.pdb", "b.pdb", "c.xyz"],
+    preset="native-basic",
     return_names=True,
 )                                            # numeric matrix + column names
 ```
@@ -170,7 +224,17 @@ Descriptors include atom/residue counts, element counts, molecular mass,
 centres, radius of gyration, bounding-box dimensions, inertia tensor, principal
 moments/axes, shape anisotropy, compactness, distance histograms, bond-length
 summary statistics, and atom/residue contact summaries. Full contact maps remain
-available through `mol.contact_map(...)`.
+available through `mol.contact_map(...)`. With `pip install "molscope[chem]"`,
+you can also request RDKit descriptors directly:
+
+```python
+mol.rdkit_descriptors(names=["MolWt", "TPSA"])
+mol.descriptors(include_rdkit=True, rdkit_descriptor_names=["MolWt", "TPSA"])
+```
+
+For reproducible ML columns, use descriptor presets: `native-basic`,
+`native-3d`, or `rdkit-basic`. Inspect the flattened column order with
+`ms.descriptor_feature_names(...)`.
 
 ### Contact maps
 
@@ -184,6 +248,29 @@ mol.contact_map(level="residue", method="min")        # closest inter-residue at
 mol.contact_map(level="residue", method="com")        # residue centre of mass
 ```
 
+### Secondary structure (DSSP)
+
+Assign protein secondary structure from backbone hydrogen-bond patterns with a
+self-contained, pure-NumPy DSSP (no external `mkdssp` binary needed):
+
+```python
+mol = ms.read("1fqy.pdb")
+ss = mol.secondary_structure()      # SecondaryStructure, one code per residue
+
+ss.string                           # e.g. '--HHHHHHHH--SS--EEEE--'
+ss.codes                            # per-residue array
+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: it reproduces the
+main classes from the Kabsch-Sander hydrogen-bond model but is not bit-identical
+to the reference `mkdssp` on every edge case. 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.
+
 ### NMR ensembles
 
 ```python
@@ -232,9 +319,9 @@ spin_gif(mol, "spin.gif")                    # rotating animation
 
 ### Molecular graphs (for machine learning)
 
-Turn 3D coordinates plus inferred bonds into a graph, then export to the common
-ML frameworks. The base `to_graph()` needs no extra dependencies; each exporter
-imports its backend lazily.
+Turn 3D coordinates plus explicit or inferred bonds into a graph, then export
+to the common ML frameworks. The base `to_graph()` needs no extra dependencies;
+each exporter imports its backend lazily.
 
 ```python
 mol = ms.read("1fqy.pdb")
@@ -243,18 +330,28 @@ g = mol.to_graph()                  # MolecularGraph: nodes + edges, no deps
 g.n_atoms, g.n_bonds                # counts
 g.atomic_numbers, g.masses          # per-node arrays
 g.node_features()                   # (N, 2) default features [atomic_number, mass]
+g.node_features("ml")               # stable ML node preset
+g.edge_features("ml")               # stable ML edge preset
 
 G = mol.to_networkx()               # networkx.Graph with node/edge attributes
 data = mol.to_pyg_data()            # torch_geometric.data.Data (x, pos, edge_index, edge_attr, z)
 dglg = mol.to_dgl_graph()           # dgl.DGLGraph with ndata/edata tensors
 ```
 
-Nodes carry element, atomic number, mass, coordinates and (from PDB/mmCIF) atom
-name, residue and chain. Edges carry the bonded pair, interatomic distance, and
-bond order (`1.0` for geometrically inferred bonds). Install backends as needed:
-`pip install "molscope[graph]"` installs only NetworkX. PyTorch Geometric and
-DGL are optional manual installs: `pip install torch torch_geometric` or
-`pip install dgl` after choosing the right PyTorch build for your platform.
+Nodes carry element, atomic number, mass, coordinates, formal charge, and (from
+PDB/mmCIF) atom name, residue and chain. Edges carry the bonded pair,
+interatomic distance, and bond order from SDF where available (`1.0` for
+PDB/CONECT or geometrically inferred bonds). Install backends as needed:
+`pip install "molscope[graph]"` for NetworkX, `"molscope[pyg]"` for PyTorch
+Geometric, `"molscope[dgl]"` for DGL, or `"molscope[gnn]"` for all graph
+backends. For custom CUDA, ROCm, Apple Silicon, or cluster builds, install the
+matching PyTorch stack first.
+
+Graph feature presets are also available through
+`mol.to_pyg_data(node_preset="ml", edge_preset="ml")` and
+`mol.to_dgl_graph(node_preset="ml", edge_preset="ml")`. Use
+`mol.to_graph(include_chemical_features=True)` to attach optional RDKit-backed
+aromatic atom and bond flags.
 
 ### Coarse-graining
 
@@ -314,12 +411,20 @@ python -m molscope 1fqy.pdb          # equivalent if not pip-installed
 - PDB files are parsed by **fixed columns**, not whitespace splitting, so atoms
   with touching coordinate fields (large or negative values) read correctly.
 - Alternate conformations (altLoc) other than the primary one are skipped.
+  Use `read_pdb(..., altloc="first"|"highest_occupancy"|"all")` to select a
+  different policy.
 - `read_pdb` returns a single model (`model=1` by default); use `read_pdb_models`
   for the whole ensemble.
+- SDF/MOL V2000 bond blocks, formal charges, and PDB `CONECT` records are
+  preserved. PDB output writes explicit bonds back as `CONECT` records.
 - Bond inference uses a `scipy.spatial.cKDTree` when available; without scipy it
   falls back to a dense `O(n^2)` search that is refused above ~8000 atoms.
-- Optional extras: `pip install "molscope[fast]"` (scipy, faster bonds/contacts)
-  and `"molscope[viz]"` (py3Dmol, for `Molecule.view`).
+- 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[pyg]"`, `"molscope[dgl]"`, or `"molscope[gnn]"`. For custom CUDA,
+  ROCm, Apple Silicon, or cluster builds, install the matching PyTorch stack
+  first.
 
 ## Tests and linting
 

{molscope-0.6.2 → molscope-0.8.0}/README.md

@@ -8,29 +8,65 @@
 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 is a basic mmCIF parser for standard `_atom_site`
-coordinate loops, not a full mmCIF syntax implementation.
+3D. The `.cif` reader handles standard `_atom_site` coordinate loops, including
+quoted values; optional Gemmi-backed validation is available through
+`pip install "molscope[cif]"`.
 
-| 3D structure rendering | 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) | ![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) |
+| 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) |
 
 ## What it does
 
-- **Read and write** XYZ, PDB, mmCIF and SDF (gzip-aware), fetch structures by
-  id from RCSB, and load multi-model NMR ensembles.
+- **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, inferred bonds
-  and contacts.
+- **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.
 
+## 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.
+
+| Tool | Main focus | How MolScope differs |
+| --- | --- | --- |
+| RDKit | Cheminformatics | MolScope leans toward structure visualisation, protein/PDB-style metadata, and CG prototyping |
+| MDAnalysis | MD trajectories | MolScope is lighter and easier for static structures and teaching |
+| MDTraj | Trajectory analysis | MolScope is simpler and graph/CG oriented |
+| Biopython | Structure parsing / bioinformatics | MolScope adds 3D analysis, ML-graph export, and coarse-graining |
+| PyMOL / VMD | Interactive visualisation | MolScope is Python-first, scriptable, and ML-export friendly |
+| 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.
+
 ## Install
 
 With [uv](https://docs.astral.sh/uv/) (recommended):
@@ -117,6 +153,7 @@ mol.radius_of_gyration              # compactness (angstrom)
 mol.dimensions, mol.formula         # bounding box, Hill-order formula
 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
 
 mol.distance(i, j)                  # bond length
 mol.angle(i, j, k)                  # bond angle (degrees)
@@ -129,12 +166,14 @@ a.alpha_carbons().rmsd(b.alpha_carbons(), align=True)   # CA-RMSD after Kabsch f
 
 ```python
 features = mol.descriptors()                 # flat dict of scalar/vector descriptors
+features = mol.descriptors(preset="native-3d")
 features["radius_of_gyration"]
 features["principal_moments"]                # 3 values
 features["distance_histogram"]               # fixed-size histogram
 
 X, names = ms.featurize_many(
     ["a.pdb", "b.pdb", "c.xyz"],
+    preset="native-basic",
     return_names=True,
 )                                            # numeric matrix + column names
 ```
@@ -143,7 +182,17 @@ Descriptors include atom/residue counts, element counts, molecular mass,
 centres, radius of gyration, bounding-box dimensions, inertia tensor, principal
 moments/axes, shape anisotropy, compactness, distance histograms, bond-length
 summary statistics, and atom/residue contact summaries. Full contact maps remain
-available through `mol.contact_map(...)`.
+available through `mol.contact_map(...)`. With `pip install "molscope[chem]"`,
+you can also request RDKit descriptors directly:
+
+```python
+mol.rdkit_descriptors(names=["MolWt", "TPSA"])
+mol.descriptors(include_rdkit=True, rdkit_descriptor_names=["MolWt", "TPSA"])
+```
+
+For reproducible ML columns, use descriptor presets: `native-basic`,
+`native-3d`, or `rdkit-basic`. Inspect the flattened column order with
+`ms.descriptor_feature_names(...)`.
 
 ### Contact maps
 
@@ -157,6 +206,29 @@ mol.contact_map(level="residue", method="min")        # closest inter-residue at
 mol.contact_map(level="residue", method="com")        # residue centre of mass
 ```
 
+### Secondary structure (DSSP)
+
+Assign protein secondary structure from backbone hydrogen-bond patterns with a
+self-contained, pure-NumPy DSSP (no external `mkdssp` binary needed):
+
+```python
+mol = ms.read("1fqy.pdb")
+ss = mol.secondary_structure()      # SecondaryStructure, one code per residue
+
+ss.string                           # e.g. '--HHHHHHHH--SS--EEEE--'
+ss.codes                            # per-residue array
+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: it reproduces the
+main classes from the Kabsch-Sander hydrogen-bond model but is not bit-identical
+to the reference `mkdssp` on every edge case. 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.
+
 ### NMR ensembles
 
 ```python
@@ -205,9 +277,9 @@ spin_gif(mol, "spin.gif")                    # rotating animation
 
 ### Molecular graphs (for machine learning)
 
-Turn 3D coordinates plus inferred bonds into a graph, then export to the common
-ML frameworks. The base `to_graph()` needs no extra dependencies; each exporter
-imports its backend lazily.
+Turn 3D coordinates plus explicit or inferred bonds into a graph, then export
+to the common ML frameworks. The base `to_graph()` needs no extra dependencies;
+each exporter imports its backend lazily.
 
 ```python
 mol = ms.read("1fqy.pdb")
@@ -216,18 +288,28 @@ g = mol.to_graph()                  # MolecularGraph: nodes + edges, no deps
 g.n_atoms, g.n_bonds                # counts
 g.atomic_numbers, g.masses          # per-node arrays
 g.node_features()                   # (N, 2) default features [atomic_number, mass]
+g.node_features("ml")               # stable ML node preset
+g.edge_features("ml")               # stable ML edge preset
 
 G = mol.to_networkx()               # networkx.Graph with node/edge attributes
 data = mol.to_pyg_data()            # torch_geometric.data.Data (x, pos, edge_index, edge_attr, z)
 dglg = mol.to_dgl_graph()           # dgl.DGLGraph with ndata/edata tensors
 ```
 
-Nodes carry element, atomic number, mass, coordinates and (from PDB/mmCIF) atom
-name, residue and chain. Edges carry the bonded pair, interatomic distance, and
-bond order (`1.0` for geometrically inferred bonds). Install backends as needed:
-`pip install "molscope[graph]"` installs only NetworkX. PyTorch Geometric and
-DGL are optional manual installs: `pip install torch torch_geometric` or
-`pip install dgl` after choosing the right PyTorch build for your platform.
+Nodes carry element, atomic number, mass, coordinates, formal charge, and (from
+PDB/mmCIF) atom name, residue and chain. Edges carry the bonded pair,
+interatomic distance, and bond order from SDF where available (`1.0` for
+PDB/CONECT or geometrically inferred bonds). Install backends as needed:
+`pip install "molscope[graph]"` for NetworkX, `"molscope[pyg]"` for PyTorch
+Geometric, `"molscope[dgl]"` for DGL, or `"molscope[gnn]"` for all graph
+backends. For custom CUDA, ROCm, Apple Silicon, or cluster builds, install the
+matching PyTorch stack first.
+
+Graph feature presets are also available through
+`mol.to_pyg_data(node_preset="ml", edge_preset="ml")` and
+`mol.to_dgl_graph(node_preset="ml", edge_preset="ml")`. Use
+`mol.to_graph(include_chemical_features=True)` to attach optional RDKit-backed
+aromatic atom and bond flags.
 
 ### Coarse-graining
 
@@ -287,12 +369,20 @@ python -m molscope 1fqy.pdb          # equivalent if not pip-installed
 - PDB files are parsed by **fixed columns**, not whitespace splitting, so atoms
   with touching coordinate fields (large or negative values) read correctly.
 - Alternate conformations (altLoc) other than the primary one are skipped.
+  Use `read_pdb(..., altloc="first"|"highest_occupancy"|"all")` to select a
+  different policy.
 - `read_pdb` returns a single model (`model=1` by default); use `read_pdb_models`
   for the whole ensemble.
+- SDF/MOL V2000 bond blocks, formal charges, and PDB `CONECT` records are
+  preserved. PDB output writes explicit bonds back as `CONECT` records.
 - Bond inference uses a `scipy.spatial.cKDTree` when available; without scipy it
   falls back to a dense `O(n^2)` search that is refused above ~8000 atoms.
-- Optional extras: `pip install "molscope[fast]"` (scipy, faster bonds/contacts)
-  and `"molscope[viz]"` (py3Dmol, for `Molecule.view`).
+- 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[pyg]"`, `"molscope[dgl]"`, or `"molscope[gnn]"`. For custom CUDA,
+  ROCm, Apple Silicon, or cluster builds, install the matching PyTorch stack
+  first.
 
 ## Tests and linting
 

{molscope-0.6.2 → molscope-0.8.0}/molscope/__init__.py

@@ -7,8 +7,10 @@ beads, and visualise everything in 3D.
 
 What it does
 ------------
-- **Read and write** XYZ, PDB, mmCIF and SDF; fetch by id from RCSB; load
-  multi-model NMR ensembles (:func:`read`, :func:`fetch`, :func:`read_pdb_models`).
+- **Read and write** XYZ, PDB, mmCIF and SDF; preserve SDF/PDB explicit bonds
+  and SDF formal charges; fetch by id from RCSB; load multi-model NMR ensembles;
+  validate CIF/mmCIF with optional Gemmi support
+  (:func:`read`, :func:`fetch`, :func:`read_pdb_models`, :func:`validate_cif`).
 - **Select and measure** by chain, element or residue; distances, angles,
   dihedrals and Kabsch-aligned RMSD (:class:`Molecule`).
 - **Analyse** centroids, radius of gyration, inertia tensor, bonds and contacts.
@@ -17,6 +19,8 @@ What it does
   (:mod:`molscope.ensemble`, :func:`cluster`, :func:`rmsd_matrix`).
 - **Export for ML**: structural descriptors and molecular graphs for NetworkX,
   PyTorch Geometric and DGL (:func:`descriptors`, :class:`MolecularGraph`).
+- **Chemical perception**: optional RDKit-backed valence, aromaticity, charge
+  features and descriptors (:func:`chemical_features`, :func:`rdkit_descriptors`).
 - **Coarse-grain** onto residue, Martini-style or custom bead mappings
   (:mod:`molscope.coarsegrain`).
 - **Visualise** with 3D matplotlib plots, an interactive py3Dmol viewer, and
@@ -37,13 +41,16 @@ Examples
 See https://github.com/roshan2004/molscope for the full documentation.
 """
 
-from . import coarsegrain, ensemble
+from . import coarsegrain, dssp, ensemble
+from .chem import ChemicalFeatures, chemical_features, rdkit_descriptors, to_rdkit
+from .cif import CifValidationReport, validate_cif
 from .coarsegrain import BeadMapping, BondMapping, CoarseGrainReport, DroppedAtom
 from .contactmap import ContactMap
-from .descriptors import descriptors, featurize_many
+from .descriptors import descriptor_feature_names, descriptors, featurize_many
+from .dssp import SecondaryStructure
 from .ensemble import Clustering, cluster, rmsd_matrix
 from .ensemble import contact_frequency as ensemble_contact_frequency
-from .graph import MolecularGraph
+from .graph import MolecularGraph, edge_feature_names, node_feature_names
 from .io import (
     fetch,
     read,
@@ -61,6 +68,8 @@ from .plotting import plot_rmsd_heatmap
 
 __all__ = [
     "Clustering",
+    "ChemicalFeatures",
+    "CifValidationReport",
     "BeadMapping",
     "BondMapping",
     "CoarseGrainReport",
@@ -68,11 +77,16 @@ __all__ = [
     "DroppedAtom",
     "Molecule",
     "MolecularGraph",
+    "SecondaryStructure",
     "cluster",
+    "chemical_features",
     "coarsegrain",
+    "descriptor_feature_names",
     "descriptors",
+    "dssp",
     "ensemble",
     "ensemble_contact_frequency",
+    "edge_feature_names",
     "featurize_many",
     "fetch",
     "plot_rmsd_heatmap",
@@ -83,8 +97,12 @@ __all__ = [
     "read_sdf",
     "read_xyz",
     "read_xyz_frames",
+    "rdkit_descriptors",
     "rmsd_matrix",
+    "node_feature_names",
+    "to_rdkit",
+    "validate_cif",
     "write_pdb",
     "write_xyz",
 ]
-__version__ = "0.6.2"
+__version__ = "0.8.0"