qsarkit-learn 0.5.0__tar.gz

qsarkit_learn-0.5.0/CONTRIBUTING_STYLE.md

@@ -0,0 +1,182 @@
+# qsarkit contribution style guide
+
+This document defines the conventions every module in this package follows.
+Read it before adding a new module.
+
+## 1. Molecule I/O contract
+
+Every public class/function that consumes molecules accepts
+`Iterable[rdkit.Chem.Mol]` (never SMILES strings directly as the primary
+input — SMILES parsing belongs in `qsarkit.chemistry` / `qsarkit.utils`
+helpers, or in explicit `from_smiles` convenience constructors).
+
+Use `qsarkit.base.ensure_mol_list` to validate/materialize input inside
+`transform`.
+
+## 2. Class shape
+
+- Mol -> Mol curation/standardization steps subclass
+  `qsarkit.base.MoleculeToMoleculeTransformer`.
+- Mol -> features/vectors steps (fingerprints, descriptors, embeddings)
+  subclass `qsarkit.base.MoleculeTransformer` or
+  `qsarkit.base.FittableMoleculeTransformer` if they must learn parameters
+  (e.g. Mol2Vec, a fitted scaler).
+- All such classes implement `fit(mols, y=None)` and `_transform(mols)`
+  (the public `transform` is provided by the base class and does
+  validation). They are scikit-learn compatible (`BaseEstimator`,
+  `TransformerMixin`), so `get_params`/`set_params`/`fit_transform` work
+  out of the box — do not override `__init__` in a way that stores
+  anything other than the constructor arguments verbatim (sklearn
+  convention).
+- Data records (e.g. `ActivityRecord`, `Relation`) are `@dataclass`.
+- API clients (`qsarkit.databases.*`) are plain classes (not transformers)
+  with explicit methods per the spec (e.g. `get_by_cid`), using `requests`
+  with a `timeout`, raising `qsarkit.base.DatabaseClientError` on failure.
+- Heavy optional dependencies (torch, transformers, gensim, shap, skopt,
+  bs4/pdfminer/lxml, matplotlib, jinja2) are imported lazily via
+  `qsarkit.base.require("torch")` inside `__init__`/`fit`/the method that
+  needs them — never at module top level. This keeps `import qsarkit`
+  cheap and lets users install only the extras they need
+  (`pip install qsarkit-learn[nlp]`, see `pyproject.toml`).
+
+## 3. Mandatory documentation
+
+Every algorithm, model, metric, database interface, chemical
+transformation and NLP method **must** have a docstring with a
+`References` section citing the original publication (with DOI when
+available) and, where relevant, the official implementation/API docs it
+wraps (RDKit, scikit-learn, PubChem PUG REST, ChEMBL API, etc.). Follow
+the NumPy docstring style used in `qsarkit/base/transformer.py`. A class
+with a non-trivial algorithm and no `References` section is considered
+incomplete.
+
+Example:
+
+```python
+class FooTransformer(MoleculeTransformer):
+    """One-line summary.
+
+    Longer description of what it does and why.
+
+    Parameters
+    ----------
+    radius : int
+        ...
+
+    References
+    ----------
+    - Author et al. (Year). "Title." Journal, vol(issue), pages.
+      https://doi.org/xxxx
+    - RDKit documentation: https://www.rdkit.org/docs/...
+    """
+```
+
+## 4. Error handling
+
+Only catch/validate at real boundaries (parsing untrusted text, network
+calls, user-supplied SMILES). Do not wrap internal RDKit calls in
+defensive `try/except` "just in case" — trust that a `Chem.Mol` produced
+by an earlier validated step is a valid `Mol`. Raise the specific
+exception from `qsarkit.base.exceptions` that matches the failure, not a
+bare `Exception`.
+
+## 5. No premature abstraction
+
+Implement exactly the classes/methods named in `PROMPT.md` for your
+module. Do not invent extra plugin systems, registries or config
+frameworks. Where an algorithm genuinely requires a heavy pretrained
+model (ChemBERTa, MPNN, generative models) that cannot be trained/loaded
+in this environment, still implement the full class with a real
+`__init__`/`fit`/`transform`/`forward` contract and real tensor
+plumbing — using `require()` for the heavy dependency — rather than a
+placeholder that just raises `NotImplementedError`. It is fine for such a
+class to *download or expect* a pretrained checkpoint (document the
+expected source in `References`); it must not silently return fake data.
+
+## 6. Package layout
+
+Each leaf subpackage (e.g. `qsarkit/chemistry/glycans/`) has:
+- one module file per major class (or a couple of closely related classes),
+  e.g. `_detector.py`, `_remover.py`, `_descriptors.py`
+- an `__init__.py` that re-exports the public classes
+
+Look at `qsarkit/chemistry/standardization/` for a worked example of this
+pattern before writing a new module.
+
+## 7. Static typing (mypy / mypyc)
+
+The package is checked with `mypy --strict` (see `[tool.mypy]` in
+`pyproject.toml`) and must stay mypyc-compilable. That means:
+
+- **Every** function, method and `__init__` has full parameter and return
+  annotations. No bare `def f(x):`.
+- `from __future__ import annotations` at the top of every module.
+- Annotate RDKit molecules as `Mol` via a `TYPE_CHECKING` import:
+  ```python
+  from typing import TYPE_CHECKING
+  if TYPE_CHECKING:
+      from rdkit.Chem import Mol
+  ```
+  and use `"Mol"` / `Iterable["Mol"]` in signatures. Do not annotate them
+  as `Any` — RDKit has no stubs, but our own signatures must still be
+  precise for readers.
+- Use `npt.NDArray[np.float64]` (`import numpy.typing as npt`) for array
+  returns, `list[...]`/`dict[...]` builtins (safe under
+  `from __future__ import annotations` on 3.9), `Optional[X]` not `X | None`
+  in runtime-evaluated positions, and `Sequence`/`Iterable` for inputs.
+- Prefer `@dataclass` with annotated fields, `Protocol` for duck-typed
+  interfaces, and `Literal[...]` for string-enum parameters
+  (e.g. `mode: Literal["binary", "count"]`).
+- mypyc-friendliness: avoid monkey-patching instance methods, avoid
+  reassigning a name to a different type, and keep class attributes
+  declared at class level with annotations.
+
+Run `python -m mypy qsarkit/<your_module>` and fix every error in your
+own code before finishing.
+
+## 8. Plotting
+
+**All plotting uses Plotly, not matplotlib.** `plotly` is a core
+dependency. Plotting functions return a `plotly.graph_objects.Figure`
+(never call `.show()` internally, never write a file unless explicitly
+asked). Import it normally at the top of plotting modules:
+
+```python
+import plotly.graph_objects as go
+```
+
+Static image export (`fig.write_image`) needs `kaleido`, which is in the
+`reporting` extra — guard that path with `qsarkit.base.require("kaleido")`.
+
+## 9. Testing
+
+Target **100% statement and branch coverage** of your module
+(`pytest --cov=qsarkit.<module> --cov-branch`). Every public class,
+method, branch and raised exception needs a test. Where a line is only
+reachable with an optional dependency installed, cover it behind
+`pytest.importorskip` rather than excluding it.
+
+
+
+Add lightweight `pytest` unit tests under `tests/<module_path>/` mirroring
+the package path, using small hardcoded molecules (aspirin, benzene,
+ethanol, a flavonoid glycoside, etc.) — not network calls. Tests for
+network-dependent clients (`qsarkit.databases.*`, live entity linking)
+should mock `requests` rather than hitting real APIs.
+
+## Documentation examples must be executable
+
+Every example in a docstring or a documentation page is run by the test
+suite (`pytest tests/docs`). Write them as `>>>` doctests, not as
+`.. code-block:: python`, so that an example which stops being true fails
+CI like any other regression.
+
+A `code-block` is acceptable only where the snippet genuinely cannot run in
+CI — it needs an optional dependency, a file that does not exist, or a
+third-party package. `tests/docs/test_documentation_examples.py` still
+checks that every `qsarkit` name such a block references actually exists.
+
+Numbers in an example must be **measured, not plausible**. Run the code and
+paste what it prints, including when the result is unflattering: a guide
+that quotes an invented R² teaches the reader to expect something the
+package does not deliver.

qsarkit_learn-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frederico Schmitt Kremer
+
+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.

qsarkit_learn-0.5.0/MANIFEST.in

@@ -0,0 +1,26 @@
+# Files to ship in the source distribution beyond what setuptools infers.
+#
+# The test suite is included deliberately: a downstream packager (conda-forge,
+# a Linux distribution) builds from the sdist and needs to be able to run the
+# tests to verify the build. `package.md` and the notebooks are the
+# documentation someone would want alongside the code.
+
+include LICENSE
+include README.md
+include package.md
+include CONTRIBUTING_STYLE.md
+include pyproject.toml
+
+recursive-include tests *.py
+recursive-include notebooks *.ipynb *.md
+recursive-include typings *.pyi
+
+# The RDKit stub shadow is required for `mypy qsarkit` to run at all; see
+# the note in the README.
+include qsarkit/py.typed
+
+# Never ship build artefacts or caches.
+global-exclude *.py[cod]
+global-exclude __pycache__
+prune docs
+prune docs-sphinx/build

qsarkit_learn-0.5.0/PKG-INFO

@@ -0,0 +1,408 @@
+Metadata-Version: 2.4
+Name: qsarkit-learn
+Version: 0.5.0
+Summary: A focused Python library for QSAR modeling: structure curation, molecular representation, model building and selection, OECD-aligned validation, applicability domain, uncertainty and SAR interpretation.
+Author: Frederico Schmitt Kremer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/omixlab/qsarkit-learn
+Project-URL: Documentation, https://omixlab.github.io/qsarkit-learn/
+Project-URL: Repository, https://github.com/omixlab/qsarkit-learn
+Project-URL: Issues, https://github.com/omixlab/qsarkit-learn/issues
+Project-URL: Changelog, https://omixlab.github.io/qsarkit-learn/changelog.html
+Keywords: qsar,cheminformatics,rdkit,molecular-descriptors,machine-learning,drug-discovery,applicability-domain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.9
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: rdkit>=2022.9.1
+Requires-Dist: networkx>=3.0
+Requires-Dist: plotly>=5.15
+Provides-Extra: embeddings
+Requires-Dist: gensim>=4.3; extra == "embeddings"
+Provides-Extra: nlp
+Requires-Dist: transformers>=4.30; extra == "nlp"
+Requires-Dist: torch>=2.0; extra == "nlp"
+Provides-Extra: explainability
+Requires-Dist: shap>=0.42; extra == "explainability"
+Requires-Dist: lime>=0.2; extra == "explainability"
+Provides-Extra: boosting
+Requires-Dist: xgboost>=1.7; extra == "boosting"
+Requires-Dist: lightgbm>=3.3; extra == "boosting"
+Provides-Extra: reporting
+Requires-Dist: kaleido>=0.2.1; extra == "reporting"
+Requires-Dist: reportlab>=4.0; extra == "reporting"
+Provides-Extra: persistence
+Requires-Dist: skops>=0.9; extra == "persistence"
+Provides-Extra: balancing
+Requires-Dist: imbalanced-learn>=0.11; extra == "balancing"
+Provides-Extra: embedding-viz
+Requires-Dist: umap-learn>=0.5; extra == "embedding-viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.3; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: nbformat>=5.9; extra == "dev"
+Requires-Dist: nbclient>=0.8; extra == "dev"
+Requires-Dist: ipykernel>=6.25; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: furo>=2023.9.10; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.24; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: sphinx-design>=0.5; extra == "docs"
+Provides-Extra: all
+Requires-Dist: gensim>=4.3; extra == "all"
+Requires-Dist: transformers>=4.30; extra == "all"
+Requires-Dist: torch>=2.0; extra == "all"
+Requires-Dist: shap>=0.42; extra == "all"
+Requires-Dist: lime>=0.2; extra == "all"
+Requires-Dist: xgboost>=1.7; extra == "all"
+Requires-Dist: lightgbm>=3.3; extra == "all"
+Requires-Dist: kaleido>=0.2.1; extra == "all"
+Requires-Dist: reportlab>=4.0; extra == "all"
+Requires-Dist: umap-learn>=0.5; extra == "all"
+Requires-Dist: skops>=0.9; extra == "all"
+Requires-Dist: imbalanced-learn>=0.11; extra == "all"
+Dynamic: license-file
+
+# qsarkit-learn
+
+A focused, open-source Python library for QSAR (Quantitative Structure-Activity Relationship) modeling.
+
+**[Documentation](https://omixlab.github.io/qsarkit-learn/)** | **[Package reference](package.md)** | **[Notebooks](notebooks/)** | **[Source Code](https://github.com/omixlab/qsarkit-learn)**
+
+`qsarkit-learn` covers the QSAR workflow proper — curating structures, turning them into features, fitting and validating a model, defining where it applies, and interpreting what it learned. It deliberately stops there: it is not a literature-mining, database-retrieval, docking or de-novo design toolkit, and does not pretend to be.
+
+## The Workflow
+
+The package is organized around the core stages of a QSAR project:
+
+1. **Curation** (`qsarkit.chemistry`, `qsarkit.data_quality`): Curate structures and resolve activity data conflicts.
+2. **Representation** (`qsarkit.representation`): Convert molecules into machine-learning ready features (descriptors, fingerprints, learned embeddings).
+3. **Modeling** (`qsarkit.models`, `qsarkit.model_selection`, `qsarkit.feature_selection`): Select features and fit models.
+4. **Validation** (`qsarkit.validation`, `qsarkit.metrics`): Evaluate models aligned with OECD principles.
+5. **Applicability Domain** (`qsarkit.applicability`): Define the chemical space where your model's predictions are trustworthy.
+6. **Uncertainty** (`qsarkit.uncertainty`): Estimate prediction confidence intervals and error bars.
+7. **Interpretation** (`qsarkit.sar`, `qsarkit.explainability`): Explain model decisions and identify activity cliffs.
+8. **Reporting** (`qsarkit.reporting`, `qsarkit.persistence`): Generate model reports and save models reproducibly.
+
+## Design Principles
+
+- **Everything is a scikit-learn estimator**: Transformers accept `Iterable[rdkit.Chem.Mol]` and implement `fit` / `transform`. Models implement `fit` / `predict`. Everything composes seamlessly in `sklearn.pipeline.Pipeline`, works with `GridSearchCV`, and supports `clone()`.
+- **Every algorithm cites its source**: Each class documents its original scientific publication with a DOI.
+- **Typed and checked**: The codebase is strictly typed (`mypy --strict`) and ships with a `py.typed` marker.
+- **Every example is executed**: Docstrings, guide pages, API reference and notebooks all run in the test suite, so none of them can go stale silently.
+- **Narrow on purpose**: Everything here earns its place in the core QSAR workflow. Data acquisition and generative modeling are deliberately kept out of scope to maintain a highly trustworthy, specialized tool.
+
+## Installation
+
+Install from PyPI with pip. Python 3.9+ is required.
+
+```bash
+pip install qsarkit-learn
+```
+
+> The distribution is **`qsarkit-learn`**; the package you import is **`qsarkit`** — the same split as `scikit-learn` and `sklearn`. The bare name `qsarkit` on PyPI belongs to an unrelated project.
+
+The package uses optional dependencies to avoid bloating your environment. You can install specific extras depending on your use case:
+
+```bash
+# For embeddings and NLP-based representations
+pip install qsarkit-learn[embeddings,nlp]
+
+# For tree-based models and explainability tools
+pip install qsarkit-learn[boosting,explainability]
+
+# For pickle-free model saving and PDF reports
+pip install qsarkit-learn[persistence,reporting]
+
+# To install everything
+pip install qsarkit-learn[all]
+```
+
+A missing optional dependency raises an error naming the extra that provides it, rather than an `ImportError` you have to interpret.
+
+| Extra | Enables |
+|---|---|
+| `embeddings` | Mol2Vec embeddings (`gensim`) |
+| `nlp` | ChemBERTa embeddings, MC-dropout (`transformers`, `torch`) |
+| `explainability` | SHAP and LIME attribution |
+| `boosting` | XGBoost and LightGBM estimators |
+| `embedding_viz` | UMAP chemical-space projections (`umap-learn`) |
+| `reporting` | PDF and static image export (`reportlab`, `kaleido`) |
+| `persistence` | Pickle-free model saving (`skops`) |
+| `balancing` | imbalanced-learn samplers |
+
+## A First Example
+
+Here is a simple example showing how to curate a molecule and analyze the Structure-Activity Relationship (SAR) of a dataset:
+
+```python
+from rdkit import Chem
+from qsarkit.chemistry import MolecularStandardizer
+from qsarkit.sar import activity_cliff_report
+
+# Curate: strip the salt, neutralize the charge
+standardizer = MolecularStandardizer()
+mol = Chem.MolFromSmiles("CC(=O)Oc1ccccc1C(=O)[O-].[Na+]")
+curated_mols = standardizer.transform([mol])
+print(Chem.MolToSmiles(curated_mols[0]))
+# Output: 'CC(=O)Oc1ccccc1C(=O)O'
+
+# Diagnose a dataset before modeling it to find activity cliffs
+# (Assuming `mols` is a list of RDKit molecules and `pIC50_values` is an array of activities)
+report = activity_cliff_report(mols, pIC50_values)
+print(report["cliff_ratio"])           # Proportion of the SAR that is discontinuous
+print(report["top_transformations"])   # R-group swaps that cause the cliffs
+```
+
+## The Functional Pipe API
+
+A second way to write the same workflow, reading in the order the work happens — in the spirit of R's `%>%`. It is not a separate implementation: `featurize` takes any transformer and `fit` any estimator, so the pipe reaches the whole package.
+
+`molecules()` accepts RDKit molecules, SMILES and InChI in any mixture, and every step keeps `y` index-aligned with the molecules — dropping a molecule drops its label with it.
+
+```python
+from qsarkit.functional import *
+
+train, test = (
+    molecules(smiles_or_inchi, activities)
+    >> standardize() >> drop_invalid()       # MoleculeSet
+    >> remove_duplicates(agg="mean")
+    >> fingerprint("morgan", n_bits=2048)    # -> FeatureSet
+    >> split("scaffold", test_size=0.2)
+)
+model = train >> select_features(k=200) >> fit("rf")
+```
+
+Steps compose, so a curation protocol can be defined once and applied to train and test alike:
+
+```python
+curate = standardize() >> drop_invalid() >> remove_duplicates(max_spread=1.0)
+train = molecules(train_smiles, train_y) >> curate
+test  = molecules(test_smiles,  test_y)  >> curate
+```
+
+> **Use `>>`, not `>`.** Python parses `a > b > c` as the chained comparison `(a > b) and (b > c)`, so a `>`-based pipe silently discards everything but the last two stages. Piping with `>` raises a `TypeError` explaining why.
+
+A pipeline is a graph, and drawing it is the quickest way to confirm the stages are in the order you meant:
+
+```python
+pipe = standardize() >> drop_invalid() >> fingerprint() >> scale() >> fit("rf")
+
+pipe.plot()                    # a Plotly figure, no extra dependency
+pipe.render("workflow.pdf")    # PNG / PDF / SVG
+print(pipe.to_dot())           # Graphviz DOT source
+```
+
+## Any Estimator You Like
+
+`QSARRegressor` and `QSARClassifier` dispatch on a name (`"rf"`, `"svm"`, `"gbm"`, `"xgboost"`, `"lightgbm"`, `"knn"`, `"pls"`, `"gp"`, …), but they also accept anything following the scikit-learn `fit`/`predict` protocol — XGBoost, LightGBM, CatBoost, or your own wrapper — as a class or an instance:
+
+```python
+from catboost import CatBoostRegressor
+
+model = QSARRegressor(CatBoostRegressor,
+                      model_params={"depth": 6},
+                      fit_params={"verbose": False}).fit(X, y)
+```
+
+`model_args` / `model_params` go to the constructor; `fit_params`, `predict_params` and `predict_proba_params` reach arguments that belong to the call rather than the constructor. An instance you pass is cloned, never mutated, and the facade remains a real scikit-learn estimator.
+
+## Honest Validation
+
+The split is the experiment. A random split of a QSAR dataset measures *interpolation*, because public sets are dense with near-duplicate analogues. On the demo dataset that difference is Q²F1 = 0.82 random against −1.0 by scaffold — same data, same model.
+
+OECD principle 4 asks for three separate things, and a single R² addresses only the first:
+
+```python
+from qsarkit.validation import BootstrapValidator, CrossValidator, YScrambling
+
+CrossValidator(n_splits=5).evaluate(model, X_train, y_train)              # predictivity
+YScrambling(n_iterations=100).run(model, X_train, y_train)["p_value"]     # robustness
+BootstrapValidator(n_iterations=100).run(model, X_train, y_train)         # precision
+```
+
+y-randomization is the check that catches the classic QSAR failure — a few dozen compounds described by thousands of descriptors, where something will always correlate. It is cheap, so there is no excuse for omitting it.
+
+For classification, three traps worth knowing about:
+
+```python
+from qsarkit.metrics import calibration_report, optimal_threshold, threshold_report
+
+# `predict()` cuts at 0.5, which is almost never right on an imbalanced set.
+optimal_threshold(y_val, scores, criterion="mcc")
+optimal_threshold(y_val, scores, criterion="cost", cost_fn=5.0, cost_fp=1.0)
+threshold_report(y_val, scores)          # every criterion, against the 0.5 default
+
+# ROC-AUC depends only on the *ranking* of scores, so a model can have
+# excellent AUC and useless probabilities. Check before you threshold them.
+calibration_report(y_val, scores)["brier_skill_score"]
+```
+
+And for regression, every metric here assumes roughly normal, homoscedastic errors — when that fails, the numbers still compute and quietly mean something else:
+
+```python
+from qsarkit.metrics import qq_data, residual_normality
+
+residual_normality(y_test, y_pred)       # skew, kurtosis, heteroscedasticity
+qq_data(y_test - y_pred)                 # the data behind a normal Q-Q plot
+```
+
+## Applicability Domain
+
+A prediction outside the domain is not *wrong* — it is unsupported by the training data, which is a different claim and the one regulators ask about.
+
+```python
+from qsarkit.applicability import ADAnalyzer, TanimotoSimilarityAD
+
+domain = TanimotoSimilarityAD(threshold=0.35).fit(X_train)
+report = ADAnalyzer(domain).fit(X_train).report(X_test, y_test, y_pred)
+report["rmse_ratio"]     # > 1 means the domain is doing its job
+```
+
+A domain with 100% coverage has told you nothing — and usually indicates a random split rather than a good model.
+
+## Explaining a Model on the Molecule
+
+SHAP and LIME attribute a prediction to *features*. For a fingerprint model those are hash buckets, and "bit 1743 contributed +0.21" is not an explanation a chemist can act on. `AttributionAtomMapper` projects it back onto atoms through the fingerprint's bit-provenance map, and RDKit draws the result:
+
+```python
+from qsarkit.explainability import AttributionAtomMapper, draw_atom_weights
+
+mapper = AttributionAtomMapper(fingerprint)
+weights = mapper.from_shap(mol, explainer, X, index=0)
+
+mapper.collision_rate(mol)               # how much to trust the picture
+svg = draw_atom_weights(mol, weights)    # RDKit similarity map
+```
+
+## Saving a Model That Still Works Next Year
+
+**Not pickle.** A pickled model embeds the exact class layout of every object, so a file written under one scikit-learn release can fail to load — or load into a subtly different object — under the next; and loading one executes arbitrary code.
+
+`qsarkit.persistence` writes a directory bundle instead: plain JSON metadata beside a [skops](https://skops.readthedocs.io) representation of the estimator, which stores parameters as data and refuses to reconstruct untrusted types.
+
+```python
+from qsarkit.persistence import ModelMetadata, inspect_bundle, load_model, save_model
+
+path = save_model(
+    model,
+    "egfr_pIC50",
+    pipeline=fingerprint,                # so the bundle can take molecules
+    metadata=ModelMetadata(name="EGFR", endpoint="pIC50 (-log10 M)"),
+)
+
+inspect_bundle(path)["untrusted"]        # safe to run on a stranger's bundle
+bundle = load_model(path)
+bundle.predict_mols(new_mols)            # straight from structures
+```
+
+A feature-width mismatch is refused rather than producing confident nonsense, and a model loaded under different package versions says so.
+
+## Reports
+
+`QSARReport` renders to plain text, Markdown, HTML, JSON and PDF, with tables and plots carried into each. `OECDReportBuilder` structures the same material around the five validation principles and tracks which are **unaddressed** — a submission fails review over a principle nobody noticed was missing.
+
+```python
+from qsarkit.reporting import OECDReportBuilder, QSARReport
+
+builder = OECDReportBuilder(title="QMRF for EGFR model", endpoint="pIC50")
+builder.add_evidence(1, True, {"endpoint": "pIC50, CHEMBL203"})
+builder.unaddressed                      # [2, 3, 4, 5] — explicit gaps
+
+builder.build().to_pdf("qmrf.pdf")
+```
+
+All plotting returns `plotly.graph_objects.Figure` objects. Functions never call `.show()` and never write files, so the same figure composes into a notebook, a dashboard and a report.
+
+## Learning the Package
+
+- **[`package.md`](package.md)** — the whole package organization in one file: every subpackage, its main classes and functions, and the literature behind them.
+- **[Notebooks](notebooks/)** — five worked walkthroughs covering every public subpackage, committed with their output:
+  1. [Curation and the functional API](notebooks/01_curation_and_the_functional_api.ipynb)
+  2. [Representation and chemical space](notebooks/02_representation_and_chemical_space.ipynb)
+  3. [Modelling, validation and applicability](notebooks/03_modeling_validation_and_applicability.ipynb)
+  4. [SAR, explainability and reporting](notebooks/04_sar_explainability_and_reporting.ipynb)
+  5. [Classification, calibration and deployment](notebooks/05_classification_calibration_and_deployment.ipynb)
+- **[Documentation](https://omixlab.github.io/qsarkit-learn/)** — the API reference, with a worked example and scientific references for every class.
+
+The notebooks use a deliberately *hard* 24-compound dataset: one planted activity-cliff outlier, distinct scaffold families, non-normal residuals. Several of them show models scoring badly on it. That is the point — a worked example where everything succeeds teaches nothing about the failure modes these tools exist to detect.
+
+## Development
+
+```bash
+git clone https://github.com/omixlab/qsarkit-learn
+cd qsarkit-learn
+pip install -e ".[dev]"
+
+pytest                              # the suite
+pytest -m slow                      # plus executing the notebooks
+pytest --cov=qsarkit --cov-branch   # with coverage
+mypy qsarkit                        # strict type check
+ruff check qsarkit                  # lint
+```
+
+Building the documentation. `docs-sphinx/` is the source; `docs/` is the
+built site served by GitHub Pages, and it is committed, so rebuilding it is
+part of preparing a commit that touches the docs:
+
+```bash
+pip install -e ".[docs]"
+
+make docs        # rebuild and copy the site into docs/ — the one to run
+make preview     # build into docs-sphinx/build/html, leaving docs/ alone
+make doctest     # execute every example in the documentation
+make linkcheck   # verify external links resolve
+```
+
+`make docs` builds from scratch with warnings treated as errors, so a broken
+cross-reference or a page deleted from the source cannot reach the published
+site. The same targets exist inside `docs-sphinx/` if you prefer to work
+there (`make publish` is the one that writes to `../docs`).
+
+> `typings/` holds a local stub shadow for RDKit. The `rdkit-stubs` bundled with the RDKit wheel contain an auto-generation bug — a C++ enum member named `None`, which is an illegal annotation target — that otherwise aborts every mypy run and silently hides all real type errors. Don't delete it.
+
+## OECD Compliance
+
+The package is organized around the five OECD validation principles:
+
+| # | Principle | Where it lives |
+|---|---|---|
+| 1 | A defined endpoint | `ModelMetadata`, `QSARReport` |
+| 2 | An unambiguous algorithm | Documented hyperparameters; `MoleculeSet.history`; `persistence` provenance |
+| 3 | A defined applicability domain | `qsarkit.applicability` |
+| 4 | Goodness-of-fit, robustness, predictivity | `qsarkit.metrics`, `qsarkit.validation` |
+| 5 | A mechanistic interpretation, if possible | `qsarkit.sar`, `qsarkit.explainability` |
+
+> OECD (2007). *Guidance Document on the Validation of (Quantitative) Structure-Activity Relationship [(Q)SAR] Models.* OECD Series on Testing and Assessment No. 69, ENV/JM/MONO(2007)2. [doi:10.1787/9789264085442-en](https://doi.org/10.1787/9789264085442-en)
+
+## Contributing
+
+We welcome contributions! Please see the [`CONTRIBUTING_STYLE.md`](CONTRIBUTING_STYLE.md) guide for our conventions on class structures, documentation, error handling, static typing (`mypy`), and unit testing.
+
+## Citing
+
+If `qsarkit-learn` contributes to work you publish, please cite the package along with the primary reference for whichever algorithm you used — each class docstring names it.
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).