kawow 0.1.1__tar.gz

kawow-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luc Miaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kawow-0.1.1/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: kawow
+Version: 0.1.1
+Summary: Models for partitioning coefficients (logKow, logKoa and logKaw) from molecular structure, including model based on [Naef & Acree 2024](https://doi.org/10.3390/liquids4010011)
+Author: Luc T. Miaz
+License: MIT
+Project-URL: Repository, https://github.com/LucMiaz/kawow
+Keywords: cheminformatics,logKow,logKoa,logKaw,partition coefficient,QSPR
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: rdkit>=2022.9
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: pylint>=3.0; extra == "lint"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == "docs"
+Requires-Dist: numpydoc>=1.6; extra == "docs"
+Dynamic: license-file
+
+# Kawow (under development)
+
+[![CI](https://github.com/LucMiaz/kawow/actions/workflows/ci.yml/badge.svg)](https://github.com/LucMiaz/kawow/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+![Kawow!](logo/kawow.svg)
+
+Group-additivity prediction of **log*K*ow**, **log*K*oa**, and **log*K*aw** from molecular structure.
+
+*Kawow* implements some models to predict partitioning coefficients (`logKoa`, `logKow` and `logKaw`), in particular the Naef & Acree (2024) group-additivity scheme using RDKit SMARTS pattern matching. Two model families are available depending on how much transparency or accuracy is required.
+
+### Flagging criteria used in outputs
+
+`run_models(...)` returns B/vB and M/vM flags derived from predicted partition values:
+
+- `B`: `logKoa >= 6` and `logKow >= 2`
+- `vB`: `logKoa >= 6` and `logKow >= 5`
+
+based on `doi:10.1126/science.1138275`.
+
+Mobility is computed via an estimated sorption relation:
+
+- `logKoc_est = logKow - 0.4`
+- `M`: `logKoc_est <= 4.5`
+- `vM`: `logKoc_est <= 3.5`
+
+following UBA drinking-water source protection guidance:
+
+- https://www.umweltbundesamt.de/en/publikationen/protecting-the-sources-of-our-drinking-water-the
+
+---
+
+## Installation
+
+```bash
+pip install kawow
+```
+
+Or from source (requires RDKit ≥ 2022.9):
+
+```bash
+git clone https://github.com/LucMiaz/kawow.git
+cd kawow
+pip install -e ".[dev]"
+```
+
+---
+
+## Models at a glance
+
+| Model key | Class | Approach | log*K*ow R² | log*K*oa R² |
+|-----------|-------|----------|-------------|-------------|
+| `kawow` | `PartitionCalculator` | Ridge regression on Crippen + Naef special-group features | 0.922 (cv) | 0.946 (cv) |
+| `smarts` | `NaefAcreePartitionCalculator` | Pure Naef & Acree 2024 group-additivity (no refitting) | 0.857 (S01) | 0.785 (S02) |
+| `smarts_mixed` | `NaefAcreeCrippenMixedPartitionCalculator` | Naef & Acree additivity + Crippen Ridge hybrid | 0.962 (cv) | 0.968 (cv) |
+| `mqg` | `MQGPartitionCalculator` | Random forest on Molecular Quantum Graph fingerprints | 0.881 (cv) | 0.945 (cv) |
+
+Use `run_models()` to run several models at once and get per-molecule B/vB and M/vM flags:
+
+```python
+import kawow
+
+results = kawow.run_models(
+    ["CCCCO", "c1ccccc1", "OC(=O)c1ccccc1"],
+    models=["kawow", "smarts_mixed"],
+)
+for row in results:
+    print(row["smiles"], row["models"]["kawow"]["logKow"],
+          row["models"]["kawow"]["b_class"])
+```
+
+Each element of the returned list is a `dict` with:
+
+| Key | Description |
+|-----|-------------|
+| `smiles` | canonical SMILES |
+| `name` | molecule name from input |
+| `models` | `dict` keyed by model name; each value contains `logKow`, `logKoa`, `logKaw`, `b_class`, `m_class`, `ok` |
+| `ok` | `True` if at least one model succeeded |
+
+---
+
+## 1 — `PartitionCalculator` (recommended for most uses)
+
+Ridge regression fitted on the same S01/S02 datasets. Coefficients are stored in `kawow/data/*.json` so no re-fitting is needed at import time.
+
+```python
+from kawow import PartitionCalculator
+
+calc = PartitionCalculator()           # Ridge (default)
+
+# Single molecule from SMILES
+result = calc.predict("CCCCO")        # 1-butanol
+print(result)
+# {'logKow': 0.88, 'logKoa': 4.12, 'logKaw': -3.24, 'status': 'ok'}
+
+# Batch prediction
+smiles = ["c1ccccc1", "CCCCCCCCCC", "OC(=O)c1ccccc1"]
+for r in calc.predict_batch(smiles):
+    print(r["smiles"], r["logKow"], r["logKoa"], r["logKaw"])
+```
+
+**Predict from an InChI string or SDF file:**
+
+```python
+r = calc.predict("InChI=1S/C4H10O/c1-2-3-4-5/h5H,2-4H2,1H3")
+results = calc.predict("compounds.sdf")   # returns list[dict]
+```
+
+**Inspect model metadata:**
+
+```python
+info = calc.model_info
+print(info["logKow"])
+# {'target': 'logKow', 'n_train': 3234, 'alpha': 51.8,
+#  'r2_cv': 0.9221, 'rmse_cv': 0.5775, ...}
+```
+
+**Re-fit on your own training data:**
+
+```python
+import kawow
+kawow.fit(
+    sdf_logkow="my_logkow.sdf",
+    sdf_logkoa="my_logkoa.sdf",
+    logkow_prop="logP",
+    logkoa_prop="logKoa",
+)
+calc = kawow.PartitionCalculator()   # reload after fitting
+```
+
+### Performance (5-fold cross-validation on Naef & Acree training sets)
+
+| Model | Property | n | R² (cv) | RMSE (cv) |
+|-------|----------|---|---------|----------|
+| `kawow` (Ridge) | log*K*ow | 3 234 | **0.922** | 0.578 |
+| `kawow` (Ridge) | log*K*oa | 1 886 | **0.946** | 0.660 |
+| `smarts_mixed` (hybrid) | log*K*ow | 3 234 | **0.962** | 0.403 |
+| `smarts_mixed` (hybrid) | log*K*oa | 1 886 | **0.968** | 0.532 |
+
+---
+
+## 2 — `NaefAcreePartitionCalculator` (SMARTS additivity, full transparency)
+
+Implements the Naef & Acree 2024 method exactly: each SMARTS pattern from the paper's supplementary tables is matched against the molecule and its tabulated contribution added. No matrix regression — every contribution is directly interpretable.
+
+```python
+from kawow.smarts_model import NaefAcreePartitionCalculator
+
+calc = NaefAcreePartitionCalculator(smiles="c1ccccc1")
+result = calc.predict("c1ccccc1")
+# {'logKow': 2.13, 'logKoa': 2.80, 'logKaw': -0.67, 'in_coverage': True}
+
+# Or pass a pre-built RDKit mol:
+from rdkit import Chem
+mol = Chem.MolFromSmiles("CCCCCCCCCC")
+result = calc.predict(mol)
+
+# Batch via constructor:
+calc_batch = NaefAcreePartitionCalculator(
+    smiles=["c1ccccc1", "CCCCCCCCCC", "OC(=O)c1ccccc1"]
+)
+for mol, coeffs in calc_batch.results.items():
+    print(coeffs)
+```
+
+### Performance on the Naef & Acree training sets
+
+| Dataset | Property | n | R² | RMSE | MAE |
+|---------|----------|---|-----|------|-----|
+| S01 (Naef 2024) | log*K*ow | 3 344 | **0.857** | 0.786 | 0.543 |
+| S02 (Naef 2024) | log*K*oa | 1 983 | **0.785** | 1.387 | 0.784 |
+| Arp & Hale 2023 (SI) | log*K*ow | 687 | **0.644** | 1.138 | 0.686 |
+
+The remaining error is concentrated in specific chemotypes (notably highly heteroatom-rich agrochemical scaffolds), while the broad SMARTS generalization and pi-environment fixes substantially improved overall log*K*oa performance on S02.
+
+### Correlation plots
+
+| log*K*ow vs Naef S01 | log*K*oa vs Naef S02 | log*K*ow vs Arp & Hale |
+|:--------------------:|:--------------------:|:----------------------:|
+| ![logKow vs S01](docs/imgs/corr_smarts_kow_vs_s01.png) | ![logKoa vs S02](docs/imgs/corr_smarts_koa_vs_s02.png) | ![logKow vs Excel](docs/imgs/corr_smarts_kow_vs_excel.png) |
+
+---
+
+## Feature engineering
+
+Each molecule is represented by counts of SMARTS atom-type groups from the Naef & Acree parameter tables, plus five special-group descriptors:
+
+- **pi-neighbour moieties** — the number of conjugated systems adjacent to a centre atom (controls which entry in a pi-stratified table applies; computed by `count_conjugated_neighbor_moieties`)
+- **H-acceptor binary presence** — 1 if any intramolecular H-bond donor/acceptor pair is within 5 bonds
+- **Alkane flag** — 1 if the molecule is a pure saturated hydrocarbon
+- **Unsaturated HC flag** — 1 if the molecule is a pure unsaturated hydrocarbon
+- **Extra −COOH count** — number of carboxylic acid groups beyond the first
+- **Endocyclic C−C single bond count**
+
+The `PartitionCalculator` additionally uses 72 Crippen atom-type features (from RDKit's `Crippen.txt`) on top of the 5 Naef special groups.
+
+---
+
+## Reference
+
+Naef, Rudolf, and William E. Acree, Jr. 2024. "Calculation of the Three Partition Coefficients logPow, logKoa and logKaw of Organic Molecules at Standard Conditions at Once by Means of a Generally Applicable Group-Additivity Method." *Liquids* 4, no. 1: 231–260. [10.3390/liquids4010011](https://doi.org/10.3390/liquids4010011)
+
+Arp, H.P.H. and Hale, S.E. 2023. "From Measured Partition Coefficients to the Prediction of Environmental Fate." Supplementary data: `vg2c00024_si_001` (ACS).
+
+## License
+
+MIT

kawow-0.1.1/README.md

@@ -0,0 +1,209 @@
+# Kawow (under development)
+
+[![CI](https://github.com/LucMiaz/kawow/actions/workflows/ci.yml/badge.svg)](https://github.com/LucMiaz/kawow/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+![Kawow!](logo/kawow.svg)
+
+Group-additivity prediction of **log*K*ow**, **log*K*oa**, and **log*K*aw** from molecular structure.
+
+*Kawow* implements some models to predict partitioning coefficients (`logKoa`, `logKow` and `logKaw`), in particular the Naef & Acree (2024) group-additivity scheme using RDKit SMARTS pattern matching. Two model families are available depending on how much transparency or accuracy is required.
+
+### Flagging criteria used in outputs
+
+`run_models(...)` returns B/vB and M/vM flags derived from predicted partition values:
+
+- `B`: `logKoa >= 6` and `logKow >= 2`
+- `vB`: `logKoa >= 6` and `logKow >= 5`
+
+based on `doi:10.1126/science.1138275`.
+
+Mobility is computed via an estimated sorption relation:
+
+- `logKoc_est = logKow - 0.4`
+- `M`: `logKoc_est <= 4.5`
+- `vM`: `logKoc_est <= 3.5`
+
+following UBA drinking-water source protection guidance:
+
+- https://www.umweltbundesamt.de/en/publikationen/protecting-the-sources-of-our-drinking-water-the
+
+---
+
+## Installation
+
+```bash
+pip install kawow
+```
+
+Or from source (requires RDKit ≥ 2022.9):
+
+```bash
+git clone https://github.com/LucMiaz/kawow.git
+cd kawow
+pip install -e ".[dev]"
+```
+
+---
+
+## Models at a glance
+
+| Model key | Class | Approach | log*K*ow R² | log*K*oa R² |
+|-----------|-------|----------|-------------|-------------|
+| `kawow` | `PartitionCalculator` | Ridge regression on Crippen + Naef special-group features | 0.922 (cv) | 0.946 (cv) |
+| `smarts` | `NaefAcreePartitionCalculator` | Pure Naef & Acree 2024 group-additivity (no refitting) | 0.857 (S01) | 0.785 (S02) |
+| `smarts_mixed` | `NaefAcreeCrippenMixedPartitionCalculator` | Naef & Acree additivity + Crippen Ridge hybrid | 0.962 (cv) | 0.968 (cv) |
+| `mqg` | `MQGPartitionCalculator` | Random forest on Molecular Quantum Graph fingerprints | 0.881 (cv) | 0.945 (cv) |
+
+Use `run_models()` to run several models at once and get per-molecule B/vB and M/vM flags:
+
+```python
+import kawow
+
+results = kawow.run_models(
+    ["CCCCO", "c1ccccc1", "OC(=O)c1ccccc1"],
+    models=["kawow", "smarts_mixed"],
+)
+for row in results:
+    print(row["smiles"], row["models"]["kawow"]["logKow"],
+          row["models"]["kawow"]["b_class"])
+```
+
+Each element of the returned list is a `dict` with:
+
+| Key | Description |
+|-----|-------------|
+| `smiles` | canonical SMILES |
+| `name` | molecule name from input |
+| `models` | `dict` keyed by model name; each value contains `logKow`, `logKoa`, `logKaw`, `b_class`, `m_class`, `ok` |
+| `ok` | `True` if at least one model succeeded |
+
+---
+
+## 1 — `PartitionCalculator` (recommended for most uses)
+
+Ridge regression fitted on the same S01/S02 datasets. Coefficients are stored in `kawow/data/*.json` so no re-fitting is needed at import time.
+
+```python
+from kawow import PartitionCalculator
+
+calc = PartitionCalculator()           # Ridge (default)
+
+# Single molecule from SMILES
+result = calc.predict("CCCCO")        # 1-butanol
+print(result)
+# {'logKow': 0.88, 'logKoa': 4.12, 'logKaw': -3.24, 'status': 'ok'}
+
+# Batch prediction
+smiles = ["c1ccccc1", "CCCCCCCCCC", "OC(=O)c1ccccc1"]
+for r in calc.predict_batch(smiles):
+    print(r["smiles"], r["logKow"], r["logKoa"], r["logKaw"])
+```
+
+**Predict from an InChI string or SDF file:**
+
+```python
+r = calc.predict("InChI=1S/C4H10O/c1-2-3-4-5/h5H,2-4H2,1H3")
+results = calc.predict("compounds.sdf")   # returns list[dict]
+```
+
+**Inspect model metadata:**
+
+```python
+info = calc.model_info
+print(info["logKow"])
+# {'target': 'logKow', 'n_train': 3234, 'alpha': 51.8,
+#  'r2_cv': 0.9221, 'rmse_cv': 0.5775, ...}
+```
+
+**Re-fit on your own training data:**
+
+```python
+import kawow
+kawow.fit(
+    sdf_logkow="my_logkow.sdf",
+    sdf_logkoa="my_logkoa.sdf",
+    logkow_prop="logP",
+    logkoa_prop="logKoa",
+)
+calc = kawow.PartitionCalculator()   # reload after fitting
+```
+
+### Performance (5-fold cross-validation on Naef & Acree training sets)
+
+| Model | Property | n | R² (cv) | RMSE (cv) |
+|-------|----------|---|---------|----------|
+| `kawow` (Ridge) | log*K*ow | 3 234 | **0.922** | 0.578 |
+| `kawow` (Ridge) | log*K*oa | 1 886 | **0.946** | 0.660 |
+| `smarts_mixed` (hybrid) | log*K*ow | 3 234 | **0.962** | 0.403 |
+| `smarts_mixed` (hybrid) | log*K*oa | 1 886 | **0.968** | 0.532 |
+
+---
+
+## 2 — `NaefAcreePartitionCalculator` (SMARTS additivity, full transparency)
+
+Implements the Naef & Acree 2024 method exactly: each SMARTS pattern from the paper's supplementary tables is matched against the molecule and its tabulated contribution added. No matrix regression — every contribution is directly interpretable.
+
+```python
+from kawow.smarts_model import NaefAcreePartitionCalculator
+
+calc = NaefAcreePartitionCalculator(smiles="c1ccccc1")
+result = calc.predict("c1ccccc1")
+# {'logKow': 2.13, 'logKoa': 2.80, 'logKaw': -0.67, 'in_coverage': True}
+
+# Or pass a pre-built RDKit mol:
+from rdkit import Chem
+mol = Chem.MolFromSmiles("CCCCCCCCCC")
+result = calc.predict(mol)
+
+# Batch via constructor:
+calc_batch = NaefAcreePartitionCalculator(
+    smiles=["c1ccccc1", "CCCCCCCCCC", "OC(=O)c1ccccc1"]
+)
+for mol, coeffs in calc_batch.results.items():
+    print(coeffs)
+```
+
+### Performance on the Naef & Acree training sets
+
+| Dataset | Property | n | R² | RMSE | MAE |
+|---------|----------|---|-----|------|-----|
+| S01 (Naef 2024) | log*K*ow | 3 344 | **0.857** | 0.786 | 0.543 |
+| S02 (Naef 2024) | log*K*oa | 1 983 | **0.785** | 1.387 | 0.784 |
+| Arp & Hale 2023 (SI) | log*K*ow | 687 | **0.644** | 1.138 | 0.686 |
+
+The remaining error is concentrated in specific chemotypes (notably highly heteroatom-rich agrochemical scaffolds), while the broad SMARTS generalization and pi-environment fixes substantially improved overall log*K*oa performance on S02.
+
+### Correlation plots
+
+| log*K*ow vs Naef S01 | log*K*oa vs Naef S02 | log*K*ow vs Arp & Hale |
+|:--------------------:|:--------------------:|:----------------------:|
+| ![logKow vs S01](docs/imgs/corr_smarts_kow_vs_s01.png) | ![logKoa vs S02](docs/imgs/corr_smarts_koa_vs_s02.png) | ![logKow vs Excel](docs/imgs/corr_smarts_kow_vs_excel.png) |
+
+---
+
+## Feature engineering
+
+Each molecule is represented by counts of SMARTS atom-type groups from the Naef & Acree parameter tables, plus five special-group descriptors:
+
+- **pi-neighbour moieties** — the number of conjugated systems adjacent to a centre atom (controls which entry in a pi-stratified table applies; computed by `count_conjugated_neighbor_moieties`)
+- **H-acceptor binary presence** — 1 if any intramolecular H-bond donor/acceptor pair is within 5 bonds
+- **Alkane flag** — 1 if the molecule is a pure saturated hydrocarbon
+- **Unsaturated HC flag** — 1 if the molecule is a pure unsaturated hydrocarbon
+- **Extra −COOH count** — number of carboxylic acid groups beyond the first
+- **Endocyclic C−C single bond count**
+
+The `PartitionCalculator` additionally uses 72 Crippen atom-type features (from RDKit's `Crippen.txt`) on top of the 5 Naef special groups.
+
+---
+
+## Reference
+
+Naef, Rudolf, and William E. Acree, Jr. 2024. "Calculation of the Three Partition Coefficients logPow, logKoa and logKaw of Organic Molecules at Standard Conditions at Once by Means of a Generally Applicable Group-Additivity Method." *Liquids* 4, no. 1: 231–260. [10.3390/liquids4010011](https://doi.org/10.3390/liquids4010011)
+
+Arp, H.P.H. and Hale, S.E. 2023. "From Measured Partition Coefficients to the Prediction of Environmental Fate." Supplementary data: `vg2c00024_si_001` (ACS).
+
+## License
+
+MIT

kawow-0.1.1/kawow/__init__.py

@@ -0,0 +1,43 @@
+"""
+kawow
+=========
+Group-additivity prediction of logKow, logKoa and logKaw.
+
+Quick start
+-----------
+>>> import kawow
+>>> calc = kawow.PartitionCalculator()        # loads pre-fitted JSON
+>>> calc.predict("CCCCO")
+{'logKow': 0.88, 'logKoa': 4.12, 'logKaw': -3.24, 'status': 'ok'}
+
+Re-fitting (needs SDF training files)
+--------------------------------------
+>>> kawow.fit(sdf_logkow="S01.sdf", sdf_logkoa="S02.sdf")
+>>> calc = kawow.PartitionCalculator()        # reload after fitting
+
+Reference
+---------
+R. Naef, W.E. Acree Jr., Liquids 4(1):231-260, 2024.
+DOI: 10.3390/liquids4010011
+"""
+
+from .model import PartitionCalculator, MQGPartitionCalculator, fit, fit_mqg, run_models
+from .smarts_model import NaefAcreePartitionCalculator, NaefAcreeCrippenMixedPartitionCalculator
+from .io import parse_input
+from .features import compute_features
+from .atom_types import FEATURE_LABELS, N_FEATURES
+
+__version__ = "0.1.1"
+__all__ = [
+    "PartitionCalculator",
+    "MQGPartitionCalculator",
+    "NaefAcreePartitionCalculator",
+    "NaefAcreeCrippenMixedPartitionCalculator",
+    "fit",
+    "fit_mqg",
+    "run_models",
+    "parse_input",
+    "compute_features",
+    "FEATURE_LABELS",
+    "N_FEATURES",
+]

kawow-0.1.1/kawow/atom_types.py

@@ -0,0 +1,95 @@
+"""
+atom_types.py
+=============
+Atom type definitions for the Naef group-additivity method.
+
+We use RDKit's Crippen atom-type SMARTS as a proxy for Naef's atom types.
+Both methods define atom types via atom-centred SMARTS that encode element,
+local hybridization, and neighbour types — the same mathematical structure.
+The Crippen *contributions* (logP values) are NOT used; only the SMARTS are
+used to count atom occurrences. New ridge-regression coefficients are fitted
+on the S01/S02 SDF training data (Naef & Acree, Liquids 2024).
+
+Naef special groups (beyond atom counts):
+  SG_HB_INTRAMOL  — number of intramolecular H-bond donor/acceptor pairs
+                     within 5 bonds (penalises self-sequestered polarity)
+  SG_ALKANE       — 1 if pure saturated hydrocarbon (C/H only, no rings)
+  SG_UNSAT_HC     — 1 if pure unsaturated hydrocarbon (C/H only, π bonds)
+  SG_EXTRA_COOH   — number of -COOH groups beyond the first
+  SG_ENDOCYCLIC_CC — number of endocyclic C-C single bonds
+
+Atom types are parsed from the Crippen.txt data file shipped with RDKit.
+Each unique ID (e.g. "C1", "N3") represents one atom type. Multiple SMARTS
+rows with the same ID are all used during assignment, with earlier rows having
+priority (matching RDKit's _pyGetAtomContribs logic).
+"""
+
+import os
+from rdkit import Chem, RDConfig
+
+# ── Parse Crippen.txt ─────────────────────────────────────────────────────────
+# Try installed RDDataDir first, fall back to rdkit-src in workspace
+_CRIPPEN_TXT_CANDIDATES = [
+    os.path.join(RDConfig.RDDataDir, "Crippen.txt"),
+    os.path.join(os.path.dirname(os.path.abspath(__file__)), "data", "Crippen.txt"),
+]
+
+def _parse_crippen_txt() -> tuple[list[str], dict[str, list]]:
+    """
+    Parse Crippen.txt into:
+      - order : list of unique atom-type IDs in priority order
+      - patts : dict {id -> [(smarts_str, compiled_mol), ...]}
+    """
+    txt_path = None
+    for candidate in _CRIPPEN_TXT_CANDIDATES:
+        if os.path.exists(candidate):
+            txt_path = candidate
+            break
+    if txt_path is None:
+        raise FileNotFoundError(
+            "Cannot find Crippen.txt. Tried:\n" +
+            "\n".join(f"  {c}" for c in _CRIPPEN_TXT_CANDIDATES)
+        )
+
+    order: list[str] = []
+    patts: dict[str, list] = {}
+    with open(txt_path, "r", encoding="utf-8") as f:
+        for line in f:
+            if line.startswith("#"):
+                continue
+            cols = line.split("\t")
+            if len(cols) < 4 or not cols[0].strip():
+                continue
+            type_id = cols[0].strip()
+            smarts  = cols[1].strip().replace('"', '')
+            if smarts in ("", "SMARTS"):
+                continue
+            mol = Chem.MolFromSmarts(smarts)
+            if mol is None:
+                continue
+            if type_id not in order:
+                order.append(type_id)
+            patts.setdefault(type_id, []).append((smarts, mol))
+    return order, patts
+
+
+# Parsed at module import time (fast: just reads a ~4 KB text file once)
+CRIPPEN_ORDER, CRIPPEN_PATTS = _parse_crippen_txt()
+
+# ── Public constants ──────────────────────────────────────────────────────────
+CRIPPEN_LABELS: list[str] = CRIPPEN_ORDER   # e.g. ["C1", "C2", ..., "Me2"]
+N_ATOM_TYPES: int = len(CRIPPEN_LABELS)
+
+# Special group names (appended after atom-type counts in feature vector)
+SPECIAL_GROUP_LABELS: list[str] = [
+    "SG_HB_INTRAMOL",
+    "SG_ALKANE",
+    "SG_UNSAT_HC",
+    "SG_EXTRA_COOH",
+    "SG_EXTRA_OH",
+    "SG_ENDOCYCLIC_CC",
+]
+
+N_SPECIAL_GROUPS: int = len(SPECIAL_GROUP_LABELS)
+FEATURE_LABELS: list[str] = CRIPPEN_LABELS + SPECIAL_GROUP_LABELS
+N_FEATURES: int = N_ATOM_TYPES + N_SPECIAL_GROUPS