pyCSRML 0.1.0__tar.gz

pycsrml-0.1.0/.gitignore

@@ -0,0 +1,181 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor  
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore

pycsrml-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.1.0] — 2026-03-20
+
+Initial public release.
+
+### Added
+- Parse CSRML XML (ToxPrint v2 and TxP_PFAS v1) to SMARTS
+- Bundled fingerprint definitions: ToxPrint v2.0 (729 bits), TxP_PFAS v1.0.4 (129 bits)
+- `PFASFingerprinter` and `ToxPrintFingerprinter` classes using RDKit
+- `Embedding` and `EmbeddingSet` containers for multi-compound analysis
+- Full support for all key CSRML atom features (pseudo-elements G/Z/Q/X, negated atomList,
+  H-count ranges, combineAtomFeatures OR-of-AND trees, matchingQueryAtom folding,
+  atomHeteroAttachedCount via recursive SMARTS)
+- JSON and YAML input support in `Fingerprinter` (in addition to XML)
+- 99.4 % concordance with ChemoTyper reference (Richard *et al.*, 2023); all 129 bits now ≥ 90 % accuracy

pycsrml-0.1.0/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.

pycsrml-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: pyCSRML
+Version: 0.1.0
+Summary: Python implementation of CSRML chemotype fingerprints (ToxPrint v2 and TxP_PFAS v1)
+Project-URL: Homepage, https://github.com/luc-miaz/pyCSRML
+Project-URL: Documentation, https://pycsrml.readthedocs.io
+Project-URL: Repository, https://github.com/luc-miaz/pyCSRML
+Project-URL: Bug Tracker, https://github.com/luc-miaz/pyCSRML/issues
+Project-URL: Changelog, https://github.com/luc-miaz/pyCSRML/blob/main/CHANGELOG.md
+Author: Luc Miaz
+License: 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.
+License-File: LICENSE
+Keywords: CSRML,PFAS,RDKit,SMARTS,ToxPrint,cheminformatics,chemotype,fingerprint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: rdkit>=2022.3
+Provides-Extra: analysis
+Requires-Dist: matplotlib>=3.6; extra == 'analysis'
+Requires-Dist: pandas>=1.5; extra == 'analysis'
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.6; extra == 'dev'
+Requires-Dist: myst-parser; extra == 'dev'
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pylint>=3; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'dev'
+Requires-Dist: sphinx-rtd-theme>=2; extra == 'dev'
+Requires-Dist: sphinx>=7; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: matplotlib>=3.6; extra == 'full'
+Requires-Dist: pandas>=1.5; extra == 'full'
+Requires-Dist: pyyaml>=6; extra == 'full'
+Requires-Dist: umap-learn>=0.5; extra == 'full'
+Provides-Extra: umap
+Requires-Dist: umap-learn>=0.5; extra == 'umap'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# pyCSRML
+
+[![CI](https://github.com/luc-miaz/pyCSRML/actions/workflows/ci.yml/badge.svg)](https://github.com/luc-miaz/pyCSRML/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyCSRML)](https://pypi.org/project/pyCSRML/)
+[![Python](https://img.shields.io/pypi/pyversions/pyCSRML)](https://pypi.org/project/pyCSRML/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://readthedocs.org/projects/pycsrml/badge/?version=latest)](https://pycsrml.readthedocs.io)
+
+**pyCSRML** is a pure-Python re-implementation of the
+[Chemical Subgraph Representation Markup Language (CSRML)](https://www.molecular-networks.com/products/chemotyper).
+It parses CSRML XML files, converts the subgraph patterns to SMARTS, and computes
+binary chemotype fingerprints for molecules using [RDKit](https://www.rdkit.org/).
+
+The module is not an exact replicate of the original CSRML (see [performance section](#performance)). the original software should be preferred.
+
+The module was implemented from two fingerprints descriptions:
+
+| Fingerprint | Bits | Description | Sourcde |
+|---|---|---|----|
+| **ToxPrint v2.0** | 729 | General toxicologically relevant substructures | Yang *et al.* 2015  |
+| **TxP_PFAS v1.0** | 129 | Per- and polyfluoroalkyl substance (PFAS) chemotypes | Richard *et al.* 2023
+
+
+
+## Performance
+
+Accuracy is measured by comparing pyCSRML bit vectors against the reference
+[ChemoTyper](https://www.molecular-networks.com/products/chemotyper) tool output.  
+Run `pytest tests/test_chemotyper_concordance.py -v -s` to reproduce; the full
+per-bit breakdown is written to `tests/concordance_report.md`.
+
+| Dataset | Compounds | Fingerprint | Overall accuracy | Bits ≥ 90 % acc |
+|---|---|---|---|---|
+| Richard *et al.* 2023 (PFAS set) | 14 710 | TxP_PFAS v1 | **99.4 %** | — |
+| ToxCast (full) | 9 014 | ToxPrint v2 | **98.17 %** | 711 / 729 |
+| ToxCast (CF-containing subset) | 808 | TxP_PFAS v1 | **99.98 %** | 129 / 129 |
+
+> **Reading the table:** "CF-containing subset" means only the 808 ToxCast compounds
+> for which ChemoTyper sets at least one TxP_PFAS bit — the meaningful subset for
+> PFAS accuracy benchmarking. Full-dataset TxP_PFAS accuracy appears inflated (100 %)
+> because the vast majority of compounds are all-zero for every PFAS bit.
+
+### Known discrepancies
+
+The 18 bits below 90 % accuracy in ToxPrint v2 are all in the metal / inorganic
+chemotype groups; TxP_PFAS v1 has 4 bits below 100 % (all above 98.9 %).  
+Root causes (see `tests/_check_tsv_alignment.py` and `tests/concordance_report.md`):
+
+| Bit / category | Fingerprint | Accuracy | Direction | Root cause |
+|---|---|---|---|---|
+| `atom:element_noble_gas` | ToxPrint | 0.0 % | False positives | Noble-gas SMARTS approximated as `[*]` — matches every atom |
+| `atom:element_metal_group_III`, `atom:element_metal_poor_metal`, etc. | ToxPrint | 0.1 – 5 % | False positives | Metal / metalloid element-group patterns use G/Q pseudo-elements that are approximated as `[*]`, causing widespread false positives |
+| `ring:hetero_[6]_N_tetrazine_generic`, `ring:hetero_[6]_N_triazine_generic` | ToxPrint | 30 – 32 % | False positives | Nitrogen-count constraints in 6-membered heteroaromatic rings use atom-count SMARTS that over-match similar rings |
+| `pfas_chain:alkeneLinear_mono-ene_ethylene_generic_F` | TxP_PFAS | 98.9 % | False negatives (recall 40 %) | RDKit perceives the C=C of tautomeric fluoropyrimidines (5-fluorouracil) as aromatic; the SMARTS `[#9]-[#6;A]=[#6;A]` requires aliphatic atoms and misses them |
+| `pfas_bond:C=N_imine_FCN` | TxP_PFAS | 99.5 % | False negatives (recall 33 %) | Same aromaticity issue: the C=N bond in fluorinated heterocycles is perceived as aromatic by RDKit, so the aliphatic imine SMARTS does not match |
+| `pfas_bond:aromatic_FCc1c` | TxP_PFAS | 99.5 % | Slight false positives (precision 97.2 %) | Aromatic F-C pattern slightly over-matches due to SMARTS approximation of the exception clause |
+
+---
+
+## Installation
+
+The module needs RDKit installed. If necessary, start by installing a environment manager first (e.g. Conda/Mamba, like [Miniforge3](https://github.com/conda-forge/miniforge)) and creating an environment, e.g.:
+
+```bash
+mamba create -n rdkit pytho
+mamba activate rdkit
+mamba install -y -c rdkit rdkit
+```
+
+Then install pyCSRML via PyPI:
+
+```bash
+pip install pyCSRML
+```
+
+
+---
+
+## Quick start
+
+### Single molecule
+
+```python
+from pyCSRML import PFASFingerprinter
+from rdkit import Chem
+
+fp = PFASFingerprinter()
+
+mol = Chem.MolFromSmiles("FC(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(=O)O")  # PFOA
+arr, names = fp.fingerprint(mol)
+
+print(f"Bits set: {arr.sum()} / {fp.n_bits}")
+on_bits = [names[i] for i in range(len(arr)) if arr[i]]
+print(on_bits[:5])
+```
+
+### Multiple molecules with analysis
+
+```python
+from pyCSRML import PFASFingerprinter, from_fingerprinter
+
+fp = PFASFingerprinter()
+
+smiles = [
+    "FC(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(=O)O",   # PFOA
+    "FC(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)S(=O)(=O)O",  # PFOS
+    "FCCCF",    # simple difluoro
+    "CCO",      # negative control
+]
+
+eset = from_fingerprinter(fp, smiles_list=smiles, names=["PFOA", "PFOS", "4F-propane", "EtOH"])
+eset.plot(kind="heatmap")
+```
+
+### ToxPrint fingerprints (729 bits)
+
+```python
+from pyCSRML import ToxPrintFingerprinter
+from rdkit import Chem
+
+fp = ToxPrintFingerprinter()
+mol = Chem.MolFromSmiles("c1ccccc1")
+arr, names = fp.fingerprint(mol)
+print(f"Benzene: {arr.sum()} bits set")
+```
+
+### Low-level CSRML parsing
+
+```python
+from pyCSRML._csrml import parse_csrml_xml, ordered_bit_list
+
+data = parse_csrml_xml("path/to/my_fingerprints.xml")
+bits = ordered_bit_list(data)
+for bit in bits[:3]:
+    print(bit["id"], bit["smarts"])
+```
+
+---
+
+## API overview
+
+| Class / function | Module | Description |
+|---|---|---|
+| `PFASFingerprinter` | `pyCSRML` | 129-bit TxP_PFAS fingerprinter |
+| `ToxPrintFingerprinter` | `pyCSRML` | 729-bit ToxPrint v2 fingerprinter |
+| `Fingerprinter` | `pyCSRML` | Base class; load any CSRML XML or JSON |
+| `Embedding` | `pyCSRML` | Single-compound fingerprint container with metadata |
+| `EmbeddingSet` | `pyCSRML` | Multi-compound container with heatmap / UMAP / clustering |
+| `from_fingerprinter` | `pyCSRML` | Convenience factory: list of SMILES → `EmbeddingSet` |
+| `parse_csrml_xml` | `pyCSRML._csrml` | Parse raw CSRML XML → Python dict |
+| `ordered_bit_list` | `pyCSRML._csrml` | Return all bits in order from a parsed dict |
+
+Full API reference: **[pycsrml.readthedocs.io](https://pycsrml.readthedocs.io)**
+
+---
+
+## CSRML features supported
+
+| Feature | Status |
+|---|---|
+| `substructureMatch` → SMARTS | ✅ Full |
+| `substructureException` (global) | ✅ Full |
+| `matchingQueryAtom` → `[!$(...)]` folding | ✅ Full |
+| `combineAtomFeatures` (OR-of-AND trees) | ✅ Full |
+| `atomList` with `negate="true"` | ✅ Full |
+| `attachedHydrogenCount` ranges | ✅ Full |
+| `ringCountAtom` / `ringAtom` / `chainAtom` | ✅ Full |
+| Pseudo-elements G, Z, Q, X | ✅ Full |
+| `mustMatch` / `mustNotMatch` (test cases) | parsed, not used for matching |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/luc-miaz/pyCSRML
+cd pyCSRML
+pip install -e ".[dev]"
+
+# Run tests (fast)
+pytest -m "not slow"
+
+# Run concordance test (~45 s)
+pytest tests/test_chemotyper_concordance.py -v -s
+
+# Pylint
+pylint pyCSRML/
+```
+
+---
+
+## Citation
+
+If you use pyCSRML in academic work, please cite the original ToxPrint / ChemoTyper paper and the TxP_PFAS reference:
+
+- Yang, C., *et al.* (2015). New publicly available chemical query language, CSRML, to support chemotype representations for application to data mining and modelling. *J. Chem. Inf. Model.* **55**, 510–528.
+- Richard, A.M., *et al.* (2023). ToxPrint chemotypes and ChemoTyper portal. *Chem. Res. Toxicol.* **36**, 488–510.
+
+---
+
+## License
+
+MIT © 2026 Luc Miaz
+

pycsrml-0.1.0/README.md

@@ -0,0 +1,204 @@
+# pyCSRML
+
+[![CI](https://github.com/luc-miaz/pyCSRML/actions/workflows/ci.yml/badge.svg)](https://github.com/luc-miaz/pyCSRML/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyCSRML)](https://pypi.org/project/pyCSRML/)
+[![Python](https://img.shields.io/pypi/pyversions/pyCSRML)](https://pypi.org/project/pyCSRML/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Docs](https://readthedocs.org/projects/pycsrml/badge/?version=latest)](https://pycsrml.readthedocs.io)
+
+**pyCSRML** is a pure-Python re-implementation of the
+[Chemical Subgraph Representation Markup Language (CSRML)](https://www.molecular-networks.com/products/chemotyper).
+It parses CSRML XML files, converts the subgraph patterns to SMARTS, and computes
+binary chemotype fingerprints for molecules using [RDKit](https://www.rdkit.org/).
+
+The module is not an exact replicate of the original CSRML (see [performance section](#performance)). the original software should be preferred.
+
+The module was implemented from two fingerprints descriptions:
+
+| Fingerprint | Bits | Description | Sourcde |
+|---|---|---|----|
+| **ToxPrint v2.0** | 729 | General toxicologically relevant substructures | Yang *et al.* 2015  |
+| **TxP_PFAS v1.0** | 129 | Per- and polyfluoroalkyl substance (PFAS) chemotypes | Richard *et al.* 2023
+
+
+
+## Performance
+
+Accuracy is measured by comparing pyCSRML bit vectors against the reference
+[ChemoTyper](https://www.molecular-networks.com/products/chemotyper) tool output.  
+Run `pytest tests/test_chemotyper_concordance.py -v -s` to reproduce; the full
+per-bit breakdown is written to `tests/concordance_report.md`.
+
+| Dataset | Compounds | Fingerprint | Overall accuracy | Bits ≥ 90 % acc |
+|---|---|---|---|---|
+| Richard *et al.* 2023 (PFAS set) | 14 710 | TxP_PFAS v1 | **99.4 %** | — |
+| ToxCast (full) | 9 014 | ToxPrint v2 | **98.17 %** | 711 / 729 |
+| ToxCast (CF-containing subset) | 808 | TxP_PFAS v1 | **99.98 %** | 129 / 129 |
+
+> **Reading the table:** "CF-containing subset" means only the 808 ToxCast compounds
+> for which ChemoTyper sets at least one TxP_PFAS bit — the meaningful subset for
+> PFAS accuracy benchmarking. Full-dataset TxP_PFAS accuracy appears inflated (100 %)
+> because the vast majority of compounds are all-zero for every PFAS bit.
+
+### Known discrepancies
+
+The 18 bits below 90 % accuracy in ToxPrint v2 are all in the metal / inorganic
+chemotype groups; TxP_PFAS v1 has 4 bits below 100 % (all above 98.9 %).  
+Root causes (see `tests/_check_tsv_alignment.py` and `tests/concordance_report.md`):
+
+| Bit / category | Fingerprint | Accuracy | Direction | Root cause |
+|---|---|---|---|---|
+| `atom:element_noble_gas` | ToxPrint | 0.0 % | False positives | Noble-gas SMARTS approximated as `[*]` — matches every atom |
+| `atom:element_metal_group_III`, `atom:element_metal_poor_metal`, etc. | ToxPrint | 0.1 – 5 % | False positives | Metal / metalloid element-group patterns use G/Q pseudo-elements that are approximated as `[*]`, causing widespread false positives |
+| `ring:hetero_[6]_N_tetrazine_generic`, `ring:hetero_[6]_N_triazine_generic` | ToxPrint | 30 – 32 % | False positives | Nitrogen-count constraints in 6-membered heteroaromatic rings use atom-count SMARTS that over-match similar rings |
+| `pfas_chain:alkeneLinear_mono-ene_ethylene_generic_F` | TxP_PFAS | 98.9 % | False negatives (recall 40 %) | RDKit perceives the C=C of tautomeric fluoropyrimidines (5-fluorouracil) as aromatic; the SMARTS `[#9]-[#6;A]=[#6;A]` requires aliphatic atoms and misses them |
+| `pfas_bond:C=N_imine_FCN` | TxP_PFAS | 99.5 % | False negatives (recall 33 %) | Same aromaticity issue: the C=N bond in fluorinated heterocycles is perceived as aromatic by RDKit, so the aliphatic imine SMARTS does not match |
+| `pfas_bond:aromatic_FCc1c` | TxP_PFAS | 99.5 % | Slight false positives (precision 97.2 %) | Aromatic F-C pattern slightly over-matches due to SMARTS approximation of the exception clause |
+
+---
+
+## Installation
+
+The module needs RDKit installed. If necessary, start by installing a environment manager first (e.g. Conda/Mamba, like [Miniforge3](https://github.com/conda-forge/miniforge)) and creating an environment, e.g.:
+
+```bash
+mamba create -n rdkit pytho
+mamba activate rdkit
+mamba install -y -c rdkit rdkit
+```
+
+Then install pyCSRML via PyPI:
+
+```bash
+pip install pyCSRML
+```
+
+
+---
+
+## Quick start
+
+### Single molecule
+
+```python
+from pyCSRML import PFASFingerprinter
+from rdkit import Chem
+
+fp = PFASFingerprinter()
+
+mol = Chem.MolFromSmiles("FC(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(=O)O")  # PFOA
+arr, names = fp.fingerprint(mol)
+
+print(f"Bits set: {arr.sum()} / {fp.n_bits}")
+on_bits = [names[i] for i in range(len(arr)) if arr[i]]
+print(on_bits[:5])
+```
+
+### Multiple molecules with analysis
+
+```python
+from pyCSRML import PFASFingerprinter, from_fingerprinter
+
+fp = PFASFingerprinter()
+
+smiles = [
+    "FC(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(=O)O",   # PFOA
+    "FC(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)C(F)(F)S(=O)(=O)O",  # PFOS
+    "FCCCF",    # simple difluoro
+    "CCO",      # negative control
+]
+
+eset = from_fingerprinter(fp, smiles_list=smiles, names=["PFOA", "PFOS", "4F-propane", "EtOH"])
+eset.plot(kind="heatmap")
+```
+
+### ToxPrint fingerprints (729 bits)
+
+```python
+from pyCSRML import ToxPrintFingerprinter
+from rdkit import Chem
+
+fp = ToxPrintFingerprinter()
+mol = Chem.MolFromSmiles("c1ccccc1")
+arr, names = fp.fingerprint(mol)
+print(f"Benzene: {arr.sum()} bits set")
+```
+
+### Low-level CSRML parsing
+
+```python
+from pyCSRML._csrml import parse_csrml_xml, ordered_bit_list
+
+data = parse_csrml_xml("path/to/my_fingerprints.xml")
+bits = ordered_bit_list(data)
+for bit in bits[:3]:
+    print(bit["id"], bit["smarts"])
+```
+
+---
+
+## API overview
+
+| Class / function | Module | Description |
+|---|---|---|
+| `PFASFingerprinter` | `pyCSRML` | 129-bit TxP_PFAS fingerprinter |
+| `ToxPrintFingerprinter` | `pyCSRML` | 729-bit ToxPrint v2 fingerprinter |
+| `Fingerprinter` | `pyCSRML` | Base class; load any CSRML XML or JSON |
+| `Embedding` | `pyCSRML` | Single-compound fingerprint container with metadata |
+| `EmbeddingSet` | `pyCSRML` | Multi-compound container with heatmap / UMAP / clustering |
+| `from_fingerprinter` | `pyCSRML` | Convenience factory: list of SMILES → `EmbeddingSet` |
+| `parse_csrml_xml` | `pyCSRML._csrml` | Parse raw CSRML XML → Python dict |
+| `ordered_bit_list` | `pyCSRML._csrml` | Return all bits in order from a parsed dict |
+
+Full API reference: **[pycsrml.readthedocs.io](https://pycsrml.readthedocs.io)**
+
+---
+
+## CSRML features supported
+
+| Feature | Status |
+|---|---|
+| `substructureMatch` → SMARTS | ✅ Full |
+| `substructureException` (global) | ✅ Full |
+| `matchingQueryAtom` → `[!$(...)]` folding | ✅ Full |
+| `combineAtomFeatures` (OR-of-AND trees) | ✅ Full |
+| `atomList` with `negate="true"` | ✅ Full |
+| `attachedHydrogenCount` ranges | ✅ Full |
+| `ringCountAtom` / `ringAtom` / `chainAtom` | ✅ Full |
+| Pseudo-elements G, Z, Q, X | ✅ Full |
+| `mustMatch` / `mustNotMatch` (test cases) | parsed, not used for matching |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/luc-miaz/pyCSRML
+cd pyCSRML
+pip install -e ".[dev]"
+
+# Run tests (fast)
+pytest -m "not slow"
+
+# Run concordance test (~45 s)
+pytest tests/test_chemotyper_concordance.py -v -s
+
+# Pylint
+pylint pyCSRML/
+```
+
+---
+
+## Citation
+
+If you use pyCSRML in academic work, please cite the original ToxPrint / ChemoTyper paper and the TxP_PFAS reference:
+
+- Yang, C., *et al.* (2015). New publicly available chemical query language, CSRML, to support chemotype representations for application to data mining and modelling. *J. Chem. Inf. Model.* **55**, 510–528.
+- Richard, A.M., *et al.* (2023). ToxPrint chemotypes and ChemoTyper portal. *Chem. Res. Toxicol.* **36**, 488–510.
+
+---
+
+## License
+
+MIT © 2026 Luc Miaz
+