From d8ff4f3cb01748a13eb4fd1d4bdd6355312fd44c Mon Sep 17 00:00:00 2001 From: RaulFD-creator Date: Thu, 20 Aug 2026 12:09:54 +0100 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Update=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architectures.md | 193 ++++++++++++++++++++++++ docs/autopeptideml.md | 298 ++++++++++++++++++++++++------------- docs/cli.md | 178 ++++++++++++++++++++++ docs/metrics.md | 145 ++++++++++++++++++ docs/negative_sampling.md | 140 +++++++++++++++++ docs/pipeline.md | 305 ++++++++++++++++++++++++++++++++++++++ docs/repenginebase.md | 143 +++++++++++------- docs/repenginefp.md | 132 ++++++++++++++++- docs/repenginelm.md | 186 ++++++++++++++++++++++- docs/repengineseqbased.md | 121 ++++++++++++++- mkdocs.yml | 72 ++++----- 11 files changed, 1708 insertions(+), 205 deletions(-) create mode 100644 docs/architectures.md create mode 100644 docs/cli.md create mode 100644 docs/metrics.md create mode 100644 docs/negative_sampling.md create mode 100644 docs/pipeline.md diff --git a/docs/architectures.md b/docs/architectures.md new file mode 100644 index 0000000..fb4783c --- /dev/null +++ b/docs/architectures.md @@ -0,0 +1,193 @@ +# Model Architectures + +**Module:** `autopeptideml.train.architectures` + +## Overview + +This module provides the model ensemble infrastructure used to save, load, and run predictions with trained AutoPeptideML models. The two main classes are: + +- [`VotingEnsemble`](#votingensemble) — the trained ensemble that averages predictions from multiple individual models. +- [`OnnxModel`](#onnxmodel) — a thin wrapper around an ONNX Runtime session for a single saved model. + +Supported model families for training and export: + +| Identifier | Family | Notes | +|---|---|---| +| `'knn'` | K-Nearest Neighbours | scikit-learn | +| `'svm'` | Support Vector Machine | scikit-learn | +| `'rf'` | Random Forest | scikit-learn | +| `'gradboost'` | Gradient Boosting | scikit-learn | +| `'lightgbm'` | LightGBM | requires `pip install lightgbm` | +| `'xgboost'` | XGBoost | requires `pip install xgboost` | + +--- + +## `VotingEnsemble` + +An ensemble that combines predictions from multiple models, each potentially trained on a different feature representation. Predictions are averaged across all models; both mean and standard deviation are returned. + +### Attributes + +| Attribute | Type | Description | +|---|---|---| +| `models` | `List[Callable]` | Individual trained models (scikit-learn API or `OnnxModel`). | +| `reps` | `List[str]` | Representation key for each model (same order as `models`). | +| `dims` | `Dict[str, int]` | Feature dimensions per representation. Populated on first `predict` / `predict_proba` call. Required for `save`. | + +### Constructor + +```python +VotingEnsemble(models: List[Callable], reps: List[str]) +``` + +| Parameter | Type | Description | +|---|---|---| +| `models` | `List[Callable]` | Trained model objects. | +| `reps` | `List[str]` | Representation identifier for each model. | + +--- + +### `predict` + +```python +predict( + x: Union[np.ndarray, Dict[str, np.ndarray]] +) -> Tuple[np.ndarray, np.ndarray] +``` + +Run regression or classification label prediction across the ensemble. + +| Parameter | Type | Description | +|---|---|---| +| `x` | `np.ndarray` or `Dict[str, np.ndarray]` | If a dict, keys must match `self.reps`. | + +**Returns:** `(mean_predictions, std_predictions)` — both of shape `(n_samples,)`. + +--- + +### `predict_proba` + +```python +predict_proba( + x: Dict[str, np.ndarray] +) -> Tuple[np.ndarray, np.ndarray] +``` + +Run probability prediction for binary classification. + +**Returns:** `(mean_probabilities, std_probabilities)` — both of shape `(n_samples,)`. + +--- + +### `save` + +```python +save(path: str) -> None +``` + +Exports each model in the ensemble to an ONNX file inside `path/`. Files are named `{index}_{rep}.onnx`. + +**Requires:** `predict` or `predict_proba` must be called first to populate `self.dims`. + +**Supported export backends:** + +| Model type | ONNX converter | +|---|---| +| scikit-learn (`knn`, `svm`, `rf`, `gradboost`) | `skl2onnx.to_onnx` | +| LightGBM | `onnxmltools.convert_lightgbm` | +| XGBoost | `onnxmltools.convert_xgboost` | +| CatBoost | `onnxmltools.convert_catboost` | + +**Raises:** + +- `RuntimeError` — if `save` is called before `predict`/`predict_proba`. +- `FileExistsError` — if `path` points to an existing file. + +--- + +### `load` *(classmethod)* + +```python +VotingEnsemble.load(path: str) -> VotingEnsemble +``` + +Reconstructs a `VotingEnsemble` from a directory of ONNX files. Each file must be named `{index}_{rep}.onnx` as written by `save`. + +**Raises:** + +- `NotADirectoryError` — if `path` is not a directory. +- `RuntimeError` — if any file in `path` is not an ONNX file. + +--- + +## `OnnxModel` + +A thin wrapper around an `onnxruntime.InferenceSession` for a single ONNX model file. + +### Constructor + +```python +OnnxModel(path: str) +``` + +| Parameter | Type | Description | +|---|---|---| +| `path` | `str` | Path to the `.onnx` model file. | + +Loads the model with `CPUExecutionProvider` and suppresses verbose runtime logging. + +--- + +### `predict` + +```python +predict(x: np.ndarray) -> np.ndarray +``` + +Run inference and return raw predictions (labels or regression values). + +| Parameter | Type | Description | +|---|---|---| +| `x` | `np.ndarray` | Input array of shape `(n_samples, n_features)` as `float32`. | + +--- + +### `predict_proba` + +```python +predict_proba(x: np.ndarray) -> np.ndarray +``` + +Run inference and return class probabilities for the positive class. + +**Returns:** Array of shape `(n_samples,)` with the probability of class `1`. + +--- + +## Example + +```python +from autopeptideml.train.architectures import VotingEnsemble +import numpy as np + +# --- Load a saved ensemble --- +ensemble = VotingEnsemble.load('results/2024-01-01 12:00:00/ensemble') + +# --- Predict on new data --- +x = {'ecfp': np.random.rand(10, 1024).astype(np.float32)} + +# For classification +mean_proba, uncertainty = ensemble.predict_proba(x) +print(mean_proba) # predicted probabilities +print(uncertainty) # std across models (uncertainty) + +# For regression +mean_val, uncertainty = ensemble.predict(x) +``` + +--- + +## Notes + +- The ONNX export converts all models to `float32` input type. Ensure your feature arrays are cast to `float32` before passing to `predict` / `predict_proba` on a loaded ensemble. +- The `VotingEnsemble` expects the `x` dict keys to match the `reps` list exactly. Key order does not matter. diff --git a/docs/autopeptideml.md b/docs/autopeptideml.md index 72a27e5..c459ef9 100644 --- a/docs/autopeptideml.md +++ b/docs/autopeptideml.md @@ -1,164 +1,256 @@ -# Class AutoPeptideML +# `AutoPeptideML` — Main Pipeline Class + +**Module:** `autopeptideml.apml` +**Version:** 2.0.8 ## Overview -`AutoPeptideML` is a configurable machine learning workflow class designed for peptide modeling. It integrates data pipelines, representations, model training (with HPO), evaluation, and export. +`AutoPeptideML` is the top-level class that orchestrates the complete peptide bioactivity ML workflow: +data ingestion, sequence preprocessing, negative sampling, dataset partitioning, feature representation, hyperparameter optimisation (HPO), evaluation, and reporting. --- -## Class: `AutoPeptideML` - -### Constructor +## Constructor ```python -AutoPeptideML(config: dict) +AutoPeptideML( + data: Union[pd.DataFrame, List[str]], + outputdir: str, + sequence_field: str = None, + label_field: str = None, + remove_duplicates: bool = True +) ``` -* Initializes the AutoPeptideML workflow with a provided configuration dictionary. -* Creates output directories and stores pipeline, representation, training, and database settings. - ---- +Creates a timestamped subdirectory under `outputdir` and writes an initial `metadata/metadata.yml` file. -### Public Methods +| Parameter | Type | Default | Description | +|---|---|---|---| +| `data` | `pd.DataFrame` or `List[str]` | — | Input data. Pass a DataFrame with sequence and label columns, or a plain list of sequences (all assumed positive). | +| `outputdir` | `str` | — | Base output directory. A timestamped sub-folder is created automatically. | +| `sequence_field` | `str` | `None` | Column name containing peptide sequences or SMILES strings. Required when `data` is a DataFrame. | +| `label_field` | `str` | `None` | Column name containing binary (`0`/`1`) or continuous labels. Required when `data` is a DataFrame. | +| `remove_duplicates` | `bool` | `True` | Drop rows with duplicate sequences before any processing. | -#### `get_pipeline` +**Output directory layout (created on init):** -```python -get_pipeline(pipe_config: Optional[dict] = None) -> Pipeline ``` - -Load or construct the preprocessing pipeline. - -#### `get_database` - -```python -get_database(db_config: Optional[dict] = None) -> Database +// + metadata/ + metadata.yml # run metadata and status + start-data.tsv # copy of the raw input data ``` -Create or load the peptide database with optional negative data support. - -#### `get_reps` - -```python -get_reps(rep_config: Optional[dict] = None) -> Tuple[Dict[str, RepEngineBase], Dict[str, np.ndarray]] -``` +--- -Load or compute representations for the data. +## Class Attributes -#### `get_test` +| Attribute | Type | Description | +|---|---|---| +| `df` | `pd.DataFrame` | Active working dataset. Extended with `apml-smiles` and `apml-seqs` columns during preprocessing. | +| `metadata` | `dict` | Run metadata written to YAML after every step. | +| `parts` | `dict` | Train / test partition index arrays (keys: `'train'`, `'test'`). Populated by `build_models`. | +| `x` | `dict[str, np.ndarray]` | Representation arrays, keyed by representation name. | +| `ensemble` | `VotingEnsemble` | Best trained ensemble model. Available after `build_models`. | -```python -get_test(test_config: Optional[Dict] = None) -> HestiaGenerator -``` +--- -Partition the dataset into training/validation/test using `HestiaGenerator`. +## Public Methods -#### `get_train` +### `sample_negatives` ```python -get_train(train_config: Optional[Dict] = None) -> BaseTrainer +sample_negatives( + target_db: Union[str, pd.DataFrame], + activities_to_exclude: List[str] = [], + desired_ratio: float = 1.0, + verbose: bool = True, + sample_by: str = 'mw', + n_jobs: int = cpu_count(), + random_state: int = 1 +) ``` -Load and return the trainer based on the configuration (supports Optuna and Grid). +Augments the dataset with negative samples drawn from a peptide database to reach the requested negative/positive ratio. Internally delegates to [`add_negatives_from_db`](negative_sampling.md#add_negatives_from_db). -#### `run_hpo` +| Parameter | Type | Default | Description | +|---|---|---|---| +| `target_db` | `str` or `pd.DataFrame` | — | Built-in database name (`'canonical'`, `'non-canonical'`, `'both'`) or a custom DataFrame. | +| `activities_to_exclude` | `List[str]` | `[]` | Column names flagging known active entries that must not appear as negatives. | +| `desired_ratio` | `float` | `1.0` | Target negatives-to-positives ratio. | +| `verbose` | `bool` | `True` | Print progress information. | +| `sample_by` | `str` | `'mw'` | Matching strategy. `'mw'` bins by molecular weight (requires RDKit); `'length'` bins by sequence length. | +| `n_jobs` | `int` | all CPUs | Number of parallel workers for feature computation. | +| `random_state` | `int` | `1` | Random seed for reproducibility. | -```python -run_hpo() -> Dict -``` - -Perform hyperparameter optimization across dataset partitions. +--- -#### `run_evaluation` +### `build_models` ```python -run_evaluation(models) -> pd.DataFrame +build_models( + task: str = 'class', + ensemble: bool = False, + reps: Union[str, List[str], Dict[str, RepEngineBase]] = ['ecfp-16'], + models: Union[str, List[str]] = ALL_MODELS, + split_strategy: str = 'min', + hestia_generator: HestiaGenerator = None, + model_configs: Dict[str, dict] = {}, + partitions: Dict[str, np.ndarray] = None, + folds: List[Tuple[np.ndarray, np.ndarray]] = None, + n_folds_cv: int = 5, + verbose: bool = True, + n_trials: int = 100, + sim_args: SimArguments = None, + device: str = 'cpu', + random_state: int = 1, + extra_x: np.ndarray = None, + n_jobs: int = cpu_count() +) ``` -Run evaluation on the trained models and return a DataFrame of results. - -#### `save_experiment` +The main training entry-point. Internally calls `_preprocessing_data`, `_partitioning`, `_representing`, `_hpo`, and `_evaluating` in sequence. + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `task` | `str` | `'class'` | Task type. `'class'` for binary classification, `'reg'` for regression. | +| `ensemble` | `bool` | `False` | Build an ensemble over multiple representations. | +| `reps` | `str`, `List[str]`, or `Dict[str, RepEngineBase]` | `['ecfp-16']` | Representation(s) to compute. Shortcuts: `'ecfp'`, `'esm2-8m'`, `'one-hot'`, etc. Pass a dict to provide pre-built engine objects. See [Representations](repenginebase.md) for all options. | +| `models` | `str` or `List[str]` | all models | Model families to include in HPO. Supported: `'knn'`, `'svm'`, `'rf'`, `'gradboost'`, `'lightgbm'`, `'xgboost'`. | +| `split_strategy` | `str` | `'min'` | Data split strategy. `'random'` uses 80/20 random split; `'min'` uses Hestia similarity-based partitioning to minimise leakage. | +| `hestia_generator` | `HestiaGenerator` | `None` | Pre-computed Hestia generator to reuse existing partitions. | +| `model_configs` | `Dict[str, dict]` | `{}` | Custom hyperparameter search space overrides per model. | +| `partitions` | `Dict[str, np.ndarray]` | `None` | Pre-defined index arrays (`{'train': ..., 'test': ...}`). Skips Hestia partitioning. | +| `folds` | `List[Tuple[np.ndarray, np.ndarray]]` | `None` | Custom cross-validation folds as `(train_idx, val_idx)` pairs. | +| `n_folds_cv` | `int` | `5` | Number of cross-validation folds (used when `folds` is None). | +| `verbose` | `bool` | `True` | Print progress at each stage. | +| `n_trials` | `int` | `100` | Number of Optuna HPO trials. | +| `sim_args` | `SimArguments` | `None` | Custom Hestia similarity arguments. | +| `device` | `str` | `'cpu'` | Compute device for language model representations: `'cpu'`, `'cuda'`, or `'mps'`. | +| `random_state` | `int` | `1` | Global random seed. | +| `extra_x` | `np.ndarray` | `None` | Additional feature columns concatenated to every representation array. | +| `n_jobs` | `int` | all CPUs | Parallelism for preprocessing and partitioning. | -```python -save_experiment(model_backend: str = 'onnx', save_reps: bool = False, save_test: bool = True, save_all_models: bool = True) -``` - -Save the full experiment including models, test partitions, and configuration. +--- -#### `save_database` +### `represent` ```python -save_database() +represent( + mols: List[str], + rep: str, + n_jobs: int = cpu_count(), + verbose: bool = True +) -> Dict[str, np.ndarray] ``` -Export the database to CSV. +Compute a single representation for an arbitrary list of sequences or SMILES strings using an already-initialised engine stored in `self.repengines`. Returns a dictionary `{rep: array}`. + +--- -#### `save_models` +### `create_report` ```python -save_models(ensemble_path: str, backend: str = 'onnx', save_all: bool = True) +create_report() ``` -Save models using `onnx` or `joblib` backends. +Renders a Quarto (`.qmd`) HTML report summarising evaluation metrics and results. Requires [Quarto](https://quarto.org) to be installed. -#### `save_reps` +--- + +## Example Usage ```python -save_reps(rep_dir: str) +import pandas as pd +from autopeptideml import AutoPeptideML + +# --- Build a classification model --- +df = pd.read_csv('peptides.csv') + +apml = AutoPeptideML( + data=df, + outputdir='results', + sequence_field='sequence', + label_field='label' +) + +# Optional: add negative samples from the built-in canonical peptide DB +apml.sample_negatives( + target_db='canonical', + activities_to_exclude=['antimicrobial'], + desired_ratio=1.0 +) + +# Train models using ECFP fingerprints and ESM2-8M embeddings +apml.build_models( + task='class', + reps=['ecfp', 'esm2-8m'], + models=['rf', 'lightgbm'], + split_strategy='min', + n_trials=50, + device='cpu' +) + +# Generate a Quarto PDF report +apml.create_report() ``` -Save precomputed representations to disk. +After training, the output directory contains: -#### `predict` - -```python -predict(df: pd.DataFrame, feature_field: str, experiment_dir: str, backend: str = 'onnx') -> np.ndarray ``` - -Load a saved experiment and predict using the trained ensemble on new data. +// + data.tsv # pre-processed dataset with apml-smiles, apml-seqs columns + ensemble/ # ONNX models (one per rep × best-model) + metadata/ + metadata.yml # full run metadata + hpo_history.tsv # per-trial HPO scores + cv-folds.pckl # cross-validation fold indices + reps.pckl # cached representation arrays + parts.pckl # train/test partition indices + preds.npy # test-set predictions +``` --- -### Configuration Keys - -The `config` dictionary passed to the constructor must include the following keys: - -* `outputdir`: str -* `pipeline`: dict or str -* `representation`: dict or str -* `train`: dict or str -* `databases`: dict -* `test`: dict +## Representation Shortcuts + +The `reps` argument of `build_models` accepts the following short identifiers: + +| Shortcut | Engine | Notes | +|---|---|---| +| `'ecfp'` | `RepEngineFP` | Defaults to radius 8, 1024 bits. Format: `ecfp--` | +| `'fcfp'` | `RepEngineFP` | Feature-class Morgan. Format: `fcfp--` | +| `'pepfunn'` | `RepEngineFP` | Requires `pepfunn` package. | +| `'one-hot'` | `RepEngineOnehot` | One-hot encoding of canonical sequences (max length 50). | +| `'esm2-8m'` | `RepEngineLM` | ESM-2 8M parameter model. | +| `'esm2-35m'` | `RepEngineLM` | ESM-2 35M parameter model. | +| `'esm2-150m'` | `RepEngineLM` | ESM-2 150M parameter model. | +| `'esm2-650m'` | `RepEngineLM` | ESM-2 650M parameter model. | +| `'esm2-3b'` | `RepEngineLM` | ESM-2 3B parameter model. | +| `'esm2-15b'` | `RepEngineLM` | ESM-2 15B parameter model. | +| `'prot-t5-xl'` | `RepEngineLM` | ProtT5-XL encoder. | +| `'ankh-base'` | `RepEngineLM` | ANKH base model. | +| `'molformer-xl'` | `RepEngineLM` | IBM MoLFormer-XL (SMILES-based). | +| `'chemberta-2'` | `RepEngineLM` | ChemBERTa 77M (SMILES-based). | +| `'peptideclm'` | `RepEngineLM` | PeptideCLM 23M (SMILES-based). Requires `smilesPE`. | --- -### Dependencies +## Split Strategies -* pandas, numpy -* yaml, json -* hestia -* sklearn -* skl2onnx, onnxmltools, joblib (optional) +| Strategy | Description | +|---|---| +| `'random'` | 80/20 random split (no similarity awareness). | +| `'min'` | Uses [Hestia](https://github.com/IBM/Hestia-OOD) to compute similarity-based partitions and selects the least-leaky split. Recommended for trustworthy evaluation. | --- -## Example Usage - -```python -from autopipeline.autopeptideml import AutoPeptideML - -config = yaml.safe_load(open('config.yml')) -runner = AutoPeptideML(config) -pipeline = runner.get_pipeline() -db = runner.get_database() -reps, x = runner.get_reps() -test = runner.get_test() -trainer = runner.get_train() -models = runner.run_hpo() -evaluation = runner.run_evaluation(models) -runner.save_experiment() -``` - ---- +## Dependencies -For detailed config templates and supported options, see the corresponding YAML schema documentation. +- `pandas`, `numpy` +- `pyyaml`, `tqdm` +- `hestia` (for similarity-based partitioning) +- `rdkit` (for SMILES handling and molecular weight, when using fingerprints or negative sampling) +- `torch`, `transformers` (for language model representations) +- `optuna` (for HPO) +- `onnxmltools`, `onnxruntime`, `skl2onnx` (for model export and inference) diff --git a/docs/cli.md b/docs/cli.md new file mode 100644 index 0000000..db2e9bd --- /dev/null +++ b/docs/cli.md @@ -0,0 +1,178 @@ +# CLI Reference + +**Entry point:** `autopeptideml` + +AutoPeptideML exposes a command-line interface built with [Typer](https://typer.tiangolo.com/). Three commands are available: + +| Command | Description | +|---|---| +| [`build-model`](#build-model) | Interactive model builder (with optional config file). | +| [`prepare-config`](#prepare-config) | Generate a YAML config file without training. | +| [`predict`](#predict) | Run predictions using a previously trained ensemble. | + +--- + +## `build-model` + +```bash +autopeptideml build-model [OPTIONS] +``` + +Builds, trains, and evaluates an AutoPeptideML model. If no `--config-path` is provided, an interactive prompt guides you through dataset and training setup. + +### Options + +| Option | Type | Default | Description | +|---|---|---|---| +| `--outdir` | `str` | `apml-result` | Directory where all output files will be saved. A timestamped subdirectory is created inside. | +| `--config-path` | `str` | `/setup-config.yml` | Path to an existing YAML configuration file. If omitted, the interactive wizard runs and writes the config to `/setup-config.yml`. | + +### Workflow + +1. If `--config-path` is not given, the interactive wizard collects: + - Task type (classification / regression) + - Dataset path and column mapping + - Negative sampling strategy (for classification) + - Model families and representations to try + - Number of HPO trials and compute device + +2. Loads the dataset from the path in `config['datasets']['main']['path']`. + +3. If `config['datasets']['neg-db']` is present, calls `sample_negatives`. + +4. Calls `build_models` with the config parameters. + +5. Calls `create_report` to render the Quarto evaluation report. + +### Config File Keys + +```yaml +datasets: + main: + path: path/to/data.csv # or .tsv / .fasta + feat-fields: sequence # column with sequences/SMILES + label-field: label # column with labels (or 'Assume all entries are positive') + neg-db: # optional + path: canonical # 'canonical', 'non-canonical', 'both', or a custom path + feat-fields: null + activities-to-exclude: [] # list of activity columns to exclude from negatives + +task: class # 'class' or 'reg' +pipeline: to-smiles +reps: [ecfp, esm2-8m] # representation short names +models: [rf, lightgbm, knn] # model families +n-trials: 100 # Optuna HPO trials +device: cpu # 'cpu', 'cuda', or 'mps' +split-strategy: min +metric: mcc # 'mcc' (class) or 'spcc' (reg) +direction: maximize +n-jobs: -1 # -1 = all CPUs +``` + +### Example + +```bash +# Interactive wizard, results saved to 'my-experiment' +autopeptideml build-model --outdir my-experiment + +# Use a pre-existing config +autopeptideml build-model --outdir my-experiment --config-path my-experiment/setup-config.yml +``` + +--- + +## `prepare-config` + +```bash +autopeptideml prepare-config CONFIG_PATH +``` + +Runs the interactive wizard and saves the resulting YAML config to `CONFIG_PATH` **without** training a model. The `.yml` suffix is appended automatically if missing. + +### Arguments + +| Argument | Type | Description | +|---|---|---| +| `CONFIG_PATH` | `str` | Destination path for the YAML config file. | + +### Example + +```bash +autopeptideml prepare-config experiments/antimicrobial-config +# → writes experiments/antimicrobial-config.yml +``` + +--- + +## `predict` + +```bash +autopeptideml predict RESULT_DIR FEATURES_PATH [OPTIONS] +``` + +Loads a trained ensemble from a previous `build-model` run and generates predictions on new data. + +### Arguments + +| Argument | Type | Description | +|---|---|---| +| `RESULT_DIR` | `str` | Path to the experiment output directory (the **timestamped** subdirectory). Must contain `ensemble/` and optionally `metadata/metadata.yml`. | +| `FEATURES_PATH` | `str` | Path to the input file (CSV / TSV) containing the molecules to predict. | + +### Options + +| Option | Type | Default | Description | +|---|---|---|---| +| `--feature-field` | `str` | auto-detected | Column name with sequences or SMILES. Auto-detects `'sequence'`, `'smiles'`, or `'SMILES'` if not provided. | +| `--output-path` | `str` | `predictions.tsv` | Where to write the predictions. Output is tab-separated with added `preds` and `uncertainty` columns. | +| `--n-jobs` | `int` | `-1` (all CPUs) | Parallelism for preprocessing. | +| `--device` | `str` | `'cpu'` | Device for language model inference: `'cpu'`, `'cuda'`, or `'mps'`. | + +### Output Format + +The output file is a tab-separated copy of the input data with two extra columns: + +| Column | Description | +|---|---| +| `preds` | Predicted probability (classification) or continuous value (regression). | +| `uncertainty` | Standard deviation of predictions across ensemble members. Use as a calibrated uncertainty estimate. | + +### Example + +```bash +autopeptideml predict \ + my-experiment/2024-06-01_12:00:00 \ + new_peptides.csv \ + --feature-field sequence \ + --output-path predictions.tsv \ + --device cpu +``` + +### Raises + +- `RuntimeError` — if the `ensemble/` subdirectory does not exist in `RESULT_DIR`. +- `FileNotFoundError` — if `FEATURES_PATH` does not exist. + +--- + +## Python API Equivalent + +All CLI commands map directly to Python calls: + +```python +from autopeptideml import AutoPeptideML +from autopeptideml.train.architectures import VotingEnsemble +from autopeptideml.utils.dataset_parsing import read_data +from autopeptideml.pipeline import get_pipeline + +# build-model equivalent +apml = AutoPeptideML(data=df, outputdir='my-experiment', + sequence_field='sequence', label_field='label') +apml.build_models(task='class', reps=['ecfp'], models=['rf'], n_trials=50) +apml.create_report() + +# predict equivalent +ensemble = VotingEnsemble.load('my-experiment/2024-06-01_12:00:00/ensemble') +``` + +For full API details, see the [AutoPeptideML class reference](autopeptideml.md). diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 0000000..d9b65b8 --- /dev/null +++ b/docs/metrics.md @@ -0,0 +1,145 @@ +# Metrics + +**Module:** `autopeptideml.train.metrics` + +## Overview + +The metrics module provides evaluation functions for both classification and regression tasks. Two entry points are available: + +- [`evaluate`](#evaluate) — single-pass evaluation on a fixed test set. +- [`bootstrap_evaluate`](#bootstrap_evaluate) — bootstrap resampling to compute confidence intervals. + +--- + +## Classification Metrics + +Used when `pred_task='class'`. + +| Key | Metric | Notes | +|---|---|---| +| `mcc` | Matthews Correlation Coefficient | Primary optimisation metric for classification. Balanced measure that accounts for all four confusion-matrix cells. | +| `acc` | Accuracy | Fraction of correct predictions. | +| `f1` | F1 Score | Harmonic mean of precision and recall. | +| `f1_weighted` | Weighted F1 | F1 weighted by support per class. | +| `precision` | Precision | TP / (TP + FP). | +| `recall` | Recall | TP / (TP + FN). Zero-division handled (returns `0`). | +| `auroc` | Area Under ROC Curve | Computed on raw probabilities (not thresholded). | +| `log_loss` | Log Loss | Normalised cross-entropy. Computed on raw probabilities. | +| `tp` | True Positives | Raw count. | +| `tn` | True Negatives | Raw count. | +| `fp` | False Positives | Raw count. | +| `fn` | False Negatives | Raw count. | + +> **Threshold:** All metrics except `auroc` and `log_loss` use a decision threshold of `0.5`. + +--- + +## Regression Metrics + +Used when `pred_task='reg'`. + +| Key | Metric | Notes | +|---|---|---| +| `mse` | Mean Squared Error | | +| `mae` | Mean Absolute Error | | +| `pcc` | Pearson Correlation Coefficient | | +| `spcc` | Spearman Correlation Coefficient | Primary optimisation metric for regression. | +| `r2` | R² Score | Coefficient of determination. | + +--- + +## `evaluate` + +```python +evaluate( + preds: np.ndarray, + truth: np.ndarray, + pred_task: str +) -> Dict[str, float] +``` + +Compute all metrics for the given task in a single pass. + +| Parameter | Type | Description | +|---|---|---| +| `preds` | `np.ndarray` | Model predictions. For classification these should be probabilities in `[0, 1]`. | +| `truth` | `np.ndarray` | Ground truth labels. | +| `pred_task` | `str` | `'class'` for classification, `'reg'` for regression. | + +**Returns:** A dictionary mapping metric names to their float values. Any metric that cannot be computed (e.g. single-class test sets) is set to `0.0`. + +### Example + +```python +import numpy as np +from autopeptideml.train.metrics import evaluate + +preds = np.array([0.9, 0.3, 0.8, 0.1, 0.7]) +truth = np.array([1, 0, 1, 0, 1 ]) + +results = evaluate(preds, truth, pred_task='class') +print(results['mcc']) # Matthews Correlation Coefficient +print(results['auroc']) # AUROC +``` + +--- + +## `bootstrap_evaluate` + +```python +bootstrap_evaluate( + preds: np.ndarray, + truth: np.ndarray, + pred_task: str, + n_bootstrap_samples: int = 1000, + ci: float = 0.95, + all_results: bool = False +) -> Dict[str, Dict[str, float]] +``` + +Estimates confidence intervals for all metrics via bootstrap resampling (sampling with replacement). + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `preds` | `np.ndarray` | — | Model predictions. | +| `truth` | `np.ndarray` | — | Ground truth labels. | +| `pred_task` | `str` | — | `'class'` or `'reg'`. | +| `n_bootstrap_samples` | `int` | `1000` | Number of bootstrap iterations. | +| `ci` | `float` | `0.95` | Confidence level for intervals (e.g. `0.95` → 95% CI). | +| `all_results` | `bool` | `False` | If `True`, return all per-sample scores instead of aggregated statistics. | + +**Returns (default):** A nested dictionary: + +```python +{ + 'mcc': {'mean': 0.82, 'ci_lower': 0.74, 'ci_upper': 0.89}, + 'auroc': {'mean': 0.94, 'ci_lower': 0.89, 'ci_upper': 0.98}, + ... +} +``` + +**Returns (`all_results=True`):** A dictionary mapping each metric name to a list of per-bootstrap scores. + +### Example + +```python +from autopeptideml.train.metrics import bootstrap_evaluate + +results = bootstrap_evaluate( + preds=preds, + truth=truth, + pred_task='class', + n_bootstrap_samples=2000, + ci=0.95 +) + +for metric, stats in results.items(): + print(f"{metric}: {stats['mean']:.3f} [{stats['ci_lower']:.3f}, {stats['ci_upper']:.3f}]") +``` + +--- + +## Notes + +- `NaN` values in metric scores (e.g. from degenerate bootstrap samples) are handled with `np.nanmean` and `np.nanpercentile`. +- For classification, `preds` are thresholded at `0.5` for all discrete metrics before bootstrap sampling. diff --git a/docs/negative_sampling.md b/docs/negative_sampling.md new file mode 100644 index 0000000..7392888 --- /dev/null +++ b/docs/negative_sampling.md @@ -0,0 +1,140 @@ +# Negative Sampling + +**Module:** `autopeptideml.db.negative_sampling` + +## Overview + +The negative sampling module provides utilities for augmenting a positive-only peptide dataset with negative examples drawn from curated peptide databases. It implements a class-balanced sampling strategy based on molecular weight or sequence length to ensure negatives are physically comparable to the positive samples. + +--- + +## `get_neg_db` + +```python +get_neg_db( + target_db: str, + verbose: bool, + return_path: bool = False +) -> Union[pd.DataFrame, Tuple[pd.DataFrame, str]] +``` + +Retrieves a precompiled negative-sample database. If the database is not present locally it is downloaded automatically using [`gdown`](https://pypi.org/project/gdown/). + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `target_db` | `str` | — | Database identifier. Must be one of `'canonical'`, `'non-canonical'`, or `'both'`. | +| `verbose` | `bool` | — | Print download progress. | +| `return_path` | `bool` | `False` | If `True`, also return the local file path alongside the DataFrame. | + +**Returns:** `pd.DataFrame` (or `Tuple[pd.DataFrame, str]` when `return_path=True`). + +**Raises:** `ImportError` if `gdown` is not installed and download is required. + +### Available Databases + +| ID | Contents | +|---|---| +| `'canonical'` | Bioactive peptides composed of the 20 standard amino acids. | +| `'non-canonical'` | Bioactive peptides with non-standard residues or chemical modifications. | +| `'both'` | Merged version of canonical and non-canonical databases. | + +The databases are downloaded on first use from Google Drive and cached locally under `autopeptideml/data/dbs/`. + +--- + +## `add_negatives_from_db` + +```python +add_negatives_from_db( + df: pd.DataFrame, + target_db: Union[str, pd.DataFrame], + sequence_field: str, + activities_to_exclude: List[str] = [], + label_field: str = None, + desired_ratio: float = 1.0, + verbose: bool = True, + sample_by: str = 'mw', + n_jobs: int = cpu_count(), + random_state: int = 1 +) -> pd.DataFrame +``` + +Augments a dataset with negative samples to reach the desired negative/positive ratio. Negatives are drawn from `target_db` using a property-matched sampling strategy so that the resulting negative set has a similar molecular-weight (or length) distribution to the positive set. + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `df` | `pd.DataFrame` | — | Input DataFrame containing the positive samples. | +| `target_db` | `str` or `pd.DataFrame` | — | Source of negatives. Either a built-in database name (`'canonical'`, `'non-canonical'`, `'both'`) or a custom DataFrame with at least a `'smiles'` column. | +| `sequence_field` | `str` | — | Column in `df` containing SMILES strings of the positive samples (automatically set to `'apml-smiles'` when called through `AutoPeptideML`). | +| `activities_to_exclude` | `List[str]` | `[]` | Column names in the database that flag known bioactive entries. Rows where any of these columns equals `1` are excluded from the negative pool. | +| `label_field` | `str` | `None` | Column containing the label. If `None`, defaults to `'label'` and all input rows are assumed positive. | +| `desired_ratio` | `float` | `1.0` | Target `negatives / positives` ratio. | +| `verbose` | `bool` | `True` | Print warnings and progress. | +| `sample_by` | `str` | `'mw'` | Binning strategy. `'mw'` uses molecular weight (requires RDKit); `'length'` uses sequence length. | +| `n_jobs` | `int` | all CPUs | Parallel workers for feature computation. | +| `random_state` | `int` | `1` | Random seed for reproducibility. | + +**Returns:** A new `pd.DataFrame` combining the original positive samples and the newly added negatives, shuffled. + +**Raises:** + +- `ValueError` — if `label_field` is not found in `df`, `sequence_field` is missing, or `target_db` / `sample_by` are invalid. + +### Sampling Strategy + +1. Compute a molecular property (mass or length) for both the positives and the database. +2. Discretise both into bins using `sklearn`'s `KBinsDiscretizer`. +3. For each bin, sample the required number of negatives to approximate `desired_ratio` while staying within the available pool. + +If a bin in the database has fewer molecules than needed, all available molecules in that bin are used (partial fill without replacement). + +--- + +## `setup_databases` + +```python +setup_databases() +``` + +Downloads all three precompiled negative databases (`canonical`, `non-canonical`, `both`) to `autopeptideml/data/dbs/`. Requires `gdown`. + +Useful for pre-downloading databases in offline environments. + +--- + +## Example + +```python +import pandas as pd +from autopeptideml.db.negative_sampling import add_negatives_from_db + +# Positive-only dataset +df = pd.read_csv('positive_peptides.csv') +df['label'] = 1 + +# Augment with canonical negatives at 1:1 ratio +df_augmented = add_negatives_from_db( + df=df, + target_db='canonical', + sequence_field='smiles', + label_field='label', + desired_ratio=1.0, + sample_by='mw', + random_state=42 +) + +print(df_augmented['label'].value_counts()) +``` + +Alternatively, use a custom negative DataFrame: + +```python +neg_db = pd.read_csv('my_negatives.csv') # must contain 'smiles' column +df_augmented = add_negatives_from_db( + df=df, + target_db=neg_db, + sequence_field='smiles', + activities_to_exclude=['antibacterial', 'antifungal'], + desired_ratio=2.0 +) +``` diff --git a/docs/pipeline.md b/docs/pipeline.md new file mode 100644 index 0000000..f243e93 --- /dev/null +++ b/docs/pipeline.md @@ -0,0 +1,305 @@ +# Pipeline — Preprocessing Modules + +**Module:** `autopeptideml.pipeline` + +## Overview + +The pipeline module provides composable preprocessing elements for converting between peptide sequence formats (amino-acid sequences, SMILES, BILN). It is built around two core abstractions: + +- [`BaseElement`](#baseelement) — a single processing step that can be applied to one molecule or parallelised over a list. +- [`Pipeline`](#pipeline) — an ordered sequence of `BaseElement` (or nested `Pipeline`) instances. + +Three ready-to-use pipelines are available via [`get_pipeline`](#get_pipeline). + +--- + +## `BaseElement` + +**Module:** `autopeptideml.pipeline.pipeline` + +Abstract base class for a single molecular processing step. Subclasses implement `_single_call` and are invoked as callables. + +### Attributes + +| Attribute | Type | Default | Description | +|---|---|---|---| +| `name` | `str` | — | Human-readable identifier for this element. | +| `properties` | `dict` | `{}` | Serialisable configuration dictionary. | +| `parallel` | `str` | `'threading'` | Parallelism backend: `'threading'` (default) or `'processing'`. | + +### `__call__` + +```python +element( + mol: Union[str, List[str]], + n_jobs: int = cpu_count(), + verbose: bool = False +) -> Union[str, List[str]] +``` + +Dispatches to `_single_call` for a single string, or `_parallel_call` for a list. + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `mol` | `str` or `List[str]` | — | Molecule(s) to process. | +| `n_jobs` | `int` | all CPUs | Parallel workers. `1` forces sequential execution. | +| `verbose` | `bool` | `False` | Show a `tqdm` progress bar. | + +### Abstract: `_single_call` + +```python +_single_call(mol: str) -> Optional[str] +``` + +Process a single molecule string. Return `None` to discard the molecule (filtered out by `_clean`). + +**Raises:** `NotImplementedError` + +--- + +## `Pipeline` + +**Module:** `autopeptideml.pipeline.pipeline` + +An ordered sequence of processing steps. Each step receives the output of the previous one (or the original input, if `aggregate=True`). + +### Constructor + +```python +Pipeline( + elements: List[Union[BaseElement, Pipeline]], + name: str = 'pipeline', + aggregate: bool = False +) +``` + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `elements` | `List` | — | Ordered list of `BaseElement` or nested `Pipeline` instances. | +| `name` | `str` | `'pipeline'` | Identifier for this pipeline. | +| `aggregate` | `bool` | `False` | If `True`, apply all elements independently on the original input and return their combined outputs. Used for forked processing (e.g. separate streams for SMILES and sequences that are then merged). | + +### `__call__` + +```python +pipeline( + mols: List[str], + n_jobs: int = cpu_count(), + verbose: bool = False +) -> Union[List[str], List[List[str]]] +``` + +### `save` + +```python +save(filename: str) +``` + +Serialises pipeline properties to a YAML file. + +### `load` *(classmethod)* + +```python +Pipeline.load(filename: str, element_registry: dict) -> Pipeline +``` + +Reconstructs a `Pipeline` from a saved YAML file using an element registry mapping names to constructors. + +--- + +## Built-in Processing Elements + +### Sequence Elements + +**Module:** `autopeptideml.pipeline.sequence` + +#### `CanonicalCleaner` + +Replaces non-canonical residues in a sequence with a substitution character. + +```python +CanonicalCleaner(substitution: str = 'X') +``` + +| Parameter | Default | Description | +|---|---|---| +| `substitution` | `'X'` | Character to use for non-canonical residues. | + +**Example:** +```python +from autopeptideml.pipeline.sequence import CanonicalCleaner +cleaner = CanonicalCleaner(substitution='G') +cleaner('ACDB3L') # → 'ACDGGL' (non-canonical '3' → 'G') +``` + +#### `CanonicalFilter` + +Keeps or discards sequences based on whether they consist entirely of the 20 canonical amino acids. + +```python +CanonicalFilter(keep_canonical: bool = True) +``` + +| Parameter | Default | Description | +|---|---|---| +| `keep_canonical` | `True` | `True` → keep canonical sequences; `False` → keep non-canonical. | + +Non-matching sequences are returned as `None` and removed from the output list. + +--- + +### SMILES Elements + +**Module:** `autopeptideml.pipeline.smiles` + +#### `SequenceToSmiles` + +Converts a canonical amino-acid sequence to a SMILES string using the ChEMBL monomer library. + +```python +SequenceToSmiles() +``` + +Uses multiprocessing (`parallel = 'processing'`). Non-canonical residues are omitted; returns `None` for empty results. + +#### `FilterSmiles` + +Passes through only molecules that are (or are not) valid SMILES strings. + +```python +FilterSmiles(keep_smiles: Optional[bool] = True) +``` + +| Parameter | Default | Description | +|---|---|---| +| `keep_smiles` | `True` | `True` → keep valid SMILES; `False` → keep non-SMILES (sequences). | + +#### `CanonicalizeSmiles` + +Converts a SMILES string to RDKit canonical form. Returns `None` for invalid SMILES. + +```python +CanonicalizeSmiles() +``` + +#### `SmilesToSequence` + +Converts a SMILES string back to a canonical amino-acid sequence by decomposing it into monomers and matching them against the ChEMBL library. + +```python +SmilesToSequence(keep_analog: bool = True) +``` + +| Parameter | Default | Description | +|---|---|---| +| `keep_analog` | `True` | If `True`, non-canonical monomers are substituted by their closest canonical analogue; if `False`, they are replaced with `'X'`. | + +#### `SmilesToBiln` + +Converts a SMILES string to BILN (Biopolymer Identifier Language for Non-standard peptides) notation. + +```python +SmilesToBiln(human_readable: bool = False, handle_errors: bool = False) +``` + +| Parameter | Default | Description | +|---|---|---| +| `human_readable` | `False` | If `True`, outputs a more descriptive BILN with full monomer names. | +| `handle_errors` | `False` | If `True`, returns `None` on parse errors rather than raising. | + +#### `BilnToSmiles` + +Converts a BILN string back to SMILES. + +```python +BilnToSmiles() +``` + +--- + +## `get_pipeline` + +**Module:** `autopeptideml.pipeline.default_pipelines` + +```python +get_pipeline(name: str, **kwargs) -> Pipeline +``` + +Retrieve a pre-built pipeline by name. + +| Parameter | Type | Description | +|---|---|---| +| `name` | `str` | Pipeline identifier. | +| `**kwargs` | `Any` | Arguments forwarded to the pipeline constructor. | + +**Raises:** `ValueError` if `name` is not a recognised pipeline. + +--- + +## Built-in Pipelines + +### `'to-smiles'` + +Converts sequences **and** existing SMILES to canonical SMILES. + +**Flow:** + +``` +input + ├── [non-SMILES path] FilterSmiles(keep_smiles=False) → CanonicalCleaner → SequenceToSmiles + └── [SMILES path] FilterSmiles(keep_smiles=True) + └── aggregate both streams → CanonicalizeSmiles +``` + +**Kwargs:** + +| Kwarg | Type | Default | Description | +|---|---|---|---| +| `substitution` | `str` | `'G'` | Substitution for non-canonical residues before SMILES conversion. | + +--- + +### `'to-smiles-fast'` + +Same as `'to-smiles'` but skips the final `CanonicalizeSmiles` step for speed. + +--- + +### `'to-sequences'` + +Converts sequences and SMILES to canonical amino-acid sequences. + +**Flow:** + +``` +input + ├── [non-SMILES path] FilterSmiles(keep_smiles=False) + └── [SMILES path] FilterSmiles(keep_smiles=True) → SmilesToSequence + └── aggregate both streams → CanonicalCleaner(substitution) +``` + +**Kwargs:** + +| Kwarg | Type | Default | Description | +|---|---|---|---| +| `substitution` | `str` | `'X'` | Substitution for residues not in the canonical alphabet. | +| `keep_analog` | `bool` | `True` | Preserve closest analogue for non-canonical monomers during SMILES → sequence. | + +--- + +## Example + +```python +from autopeptideml.pipeline import get_pipeline + +# Convert a mix of sequences and SMILES to canonical SMILES +pipe = get_pipeline('to-smiles') +inputs = ['ACDEFGHIKL', 'CC(=O)NC(CCC(N)=O)C(=O)O'] +smiles = pipe(inputs, n_jobs=4, verbose=True) +print(smiles) + +# Convert to sequences +pipe2 = get_pipeline('to-sequences') +seqs = pipe2(inputs, n_jobs=4) +print(seqs) +``` diff --git a/docs/repenginebase.md b/docs/repenginebase.md index b97c702..328e65d 100644 --- a/docs/repenginebase.md +++ b/docs/repenginebase.md @@ -1,39 +1,39 @@ +# `RepEngineBase` — Abstract Representation Engine +**Module:** `autopeptideml.reps.engine` -# `RepEngineBase` Class Documentation +## Overview -**Module:** `rep_engine_base` +`RepEngineBase` is the abstract base class for all molecular representation engines in AutoPeptideML. It defines the standard interface for batch-level representation computation, serialisation, and property management. All concrete engines — fingerprints, language models, one-hot encoding — inherit from this class. -## Purpose -`RepEngineBase` is an abstract base class for molecular representation engines. It defines a standard interface and utilities for computing molecular representations from a list of molecules (e.g., SMILES strings), particularly in batched processing. This class is intended to be subclassed, with core functionality like preprocessing and representation computation implemented in derived classes. +Subclasses must implement: + +- [`_preprocess_batch`](#_preprocess_batch) +- [`_rep_batch`](#_rep_batch) +- [`dim`](#dim) --- ## Attributes -- **`engine`** (`str`): - Name of the representation engine. Typically defined in a subclass or passed during instantiation. - -- **`rep`** (`str`): - Type of molecular representation (e.g., `'fingerprint'`, `'embedding'`). - -- **`properties`** (`dict`): - A deep copy of the instance's dictionary at initialization. Captures configuration state. +| Attribute | Type | Description | +|---|---|---| +| `engine` | `str` | Class-level identifier for the engine type (e.g. `'fp'`, `'lm'`, `'one-hot'`). | +| `rep` | `str` | Instance-level representation name passed at construction. | +| `properties` | `dict` | Deep copy of all instance attributes captured at `__init__` time. Used for serialisation. | --- ## Constructor ```python -def __init__(self, rep: str, **args) +RepEngineBase(rep: str, **args) ``` -**Parameters:** -- `rep` (`str`): Type of molecular representation. -- `**args` (`dict`): Additional configuration options stored as attributes. - -**Effect:** -Initializes the object, stores `rep`, and adds all additional keyword arguments to the instance. Also creates a deep copy of all these attributes in `self.properties` for serialization. +| Parameter | Type | Description | +|---|---|---| +| `rep` | `str` | Representation identifier (e.g. `'ecfp'`, `'esm2-8m'`). | +| `**args` | `Any` | Additional keyword arguments added as instance attributes and captured in `self.properties`. | --- @@ -42,79 +42,112 @@ Initializes the object, stores `rep`, and adds all additional keyword arguments ### `compute_reps` ```python -def compute_reps(self, mols: List[str], verbose: Optional[bool] = False, batch_size: Optional[int] = 12) -> Union[np.ndarray, List[np.ndarray]] +compute_reps( + mols: List[str], + verbose: Optional[bool] = False, + batch_size: Optional[int] = 12 +) -> Union[np.ndarray, List[np.ndarray]] ``` -**Description:** -Computes molecular representations in batches using `_preprocess_batch` and `_rep_batch`. +Computes representations for a list of molecules by calling `_preprocess_batch` then `_rep_batch` on successive batches. -**Parameters:** -- `mols` (`List[str]`): List of molecular inputs (e.g., SMILES strings). -- `verbose` (`bool`, optional): If `True`, shows a progress bar. -- `batch_size` (`int`, optional): Number of molecules per batch. +| Parameter | Type | Default | Description | +|---|---|---|---| +| `mols` | `List[str]` | — | Input molecules as SMILES strings or amino-acid sequences. | +| `verbose` | `bool` | `False` | Show a `tqdm` progress bar over batches. | +| `batch_size` | `int` | `12` | Number of molecules per batch. | -**Returns:** -- `np.ndarray` if `average_pooling` is `True` or unset. -- `List[np.ndarray]` if `average_pooling` is explicitly set to `False`. +**Returns:** + +- `np.ndarray` — stacked array of shape `(n_mols, dim)` when `average_pooling` is `True` or not set. +- `List[np.ndarray]` — list of per-molecule arrays (variable length) when `average_pooling=False`. --- ### `dim` ```python -def dim(self) -> int +dim() -> int ``` -**Description:** -Abstract method. Must return the dimensionality of the computed representation. +Returns the dimensionality of the computed representation vector. -**Raises:** -- `NotImplementedError` +**Raises:** `NotImplementedError` — must be implemented by subclasses. --- -### `_rep_batch` +### `get_num_params` + +```python +get_num_params() -> int +``` + +Returns the total number of learnable parameters in the engine. The base implementation returns `0`; language model engines override this to return the actual parameter count. + +--- + +### `save` ```python -def _rep_batch(self, batch: List[str]) -> np.ndarray +save(filename: str) ``` -**Description:** -Abstract method. Must compute and return the representation for a batch of molecules. +Serialises `self.properties` to a YAML file at `filename`. This enables reloading the engine configuration later. -**Raises:** -- `NotImplementedError` +| Parameter | Type | Description | +|---|---|---| +| `filename` | `str` | Destination path for the YAML file. | --- -### `_preprocess_batch` +### `__str__` + +```python +__str__() -> str +``` + +Returns a JSON string representation of `self.properties`. + +--- + +## Abstract Methods (must be implemented by subclasses) + +### `_rep_batch` ```python -def _preprocess_batch(self, batch: List[str]) -> List[str] +_rep_batch(batch: List[str]) -> np.ndarray ``` -**Description:** -Abstract method. Must return a preprocessed version of the batch for representation. +Compute and return representations for a single batch. -**Raises:** -- `NotImplementedError` +**Raises:** `NotImplementedError` --- -### `save` +### `_preprocess_batch` ```python -def save(self, filename: str) +_preprocess_batch(batch: List[str]) -> List[str] ``` -**Description:** -Serializes and saves the engine’s properties to a YAML file. +Apply any necessary preprocessing to a batch before representation computation (e.g. tokenisation, canonical conversion). + +**Raises:** `NotImplementedError` + +--- + +## Subclasses -**Parameters:** -- `filename` (`str`): Destination path for the YAML file. +| Class | Module | Description | +|---|---|---| +| [`RepEngineFP`](repenginefp.md) | `autopeptideml.reps.fps` | Molecular fingerprints via RDKit (ECFP, FCFP, PepFuNN). | +| [`RepEngineLM`](repenginelm.md) | `autopeptideml.reps.lms` | Pre-trained language model embeddings (ESM2, ProtT5, MoLFormer, …). | +| [`RepEngineOnehot`](repengineseqbased.md) | `autopeptideml.reps.seq_based` | Fixed-length one-hot encoding for canonical amino acid sequences. | + +--- ## Design Notes -- This class provides **batch processing** support and optional **average pooling** control. -- The use of `batched` from `itertools` supports Python 3.10+ but also includes a fallback implementation for older versions. -- Intended for extension: Subclasses must implement `_rep_batch`, `_preprocess_batch`, and `dim`. +- **Batch processing** is handled centrally by `compute_reps`; subclasses only need to implement single-batch logic in `_rep_batch`. +- **Pooling control:** setting `self.average_pooling = False` before calling `compute_reps` causes it to return raw per-residue tensors rather than pooled vectors. This is useful for sequence-level models. +- **Python compatibility:** `batched` from `itertools` is used (Python ≥ 3.12) with a fallback `islice`-based implementation for earlier versions. diff --git a/docs/repenginefp.md b/docs/repenginefp.md index b5db073..303cdb4 100644 --- a/docs/repenginefp.md +++ b/docs/repenginefp.md @@ -1,4 +1,132 @@ -# RepEngineFP +# `RepEngineFP` — Fingerprint Representation Engine -::: autopeptideml.reps.fps.RepEngineFP +**Module:** `autopeptideml.reps.fps` +**Inherits from:** [`RepEngineBase`](repenginebase.md) +## Overview + +`RepEngineFP` computes fixed-length molecular fingerprint bit vectors using [RDKit](https://www.rdkit.org/). It supports Extended-Connectivity Fingerprints (ECFP / Morgan), Feature-class Fingerprints (FCFP), and peptide-specific fingerprints via [PepFuNN](https://github.com/novonordisk-research/pepfunn). + +**Requires:** `pip install rdkit` +**PepFuNN fingerprints additionally require:** `pip install git+https://github.com/novonordisk-research/pepfunn` + +--- + +## Attributes + +| Attribute | Type | Description | +|---|---|---| +| `engine` | `str` | Fixed to `'fp'`. | +| `nbits` | `int` | Fingerprint bit-vector length. | +| `radius` | `int` | Neighbourhood radius for the Morgan algorithm. | +| `name` | `str` | Auto-generated identifier in the form `fp---`. | +| `generator` | object | RDKit fingerprint generator instance (or `PepFunn_Generator` for PepFuNN). | +| `count` | `bool` | If `True`, uses count-simulation fingerprints instead of binary. | + +--- + +## Constructor + +```python +RepEngineFP(rep: str, nbits: int, radius: int) +``` + +| Parameter | Type | Description | +|---|---|---| +| `rep` | `str` | Fingerprint type. Accepted values: `'ecfp'`, `'ecfp-count'`, `'morgan'`, `'fcfp'`, `'fcfp-count'`, `'pepfunn'`. | +| `nbits` | `int` | Number of bits in the fingerprint vector (e.g. `1024`, `2048`). | +| `radius` | `int` | Morgan radius (e.g. `2` for ECFP4, `4` for ECFP8). | + +--- + +## Methods + +### `compute_reps` *(inherited)* + +```python +compute_reps( + mols: List[str], + verbose: bool = False, + batch_size: int = 12 +) -> np.ndarray +``` + +Compute fingerprints for a list of SMILES strings. Returns an array of shape `(n_mols, nbits)`. + +--- + +### `dim` + +```python +dim() -> int +``` + +Returns `self.nbits`. + +--- + +### `_preprocess_batch` + +```python +_preprocess_batch(batch: List[str]) -> List[str] +``` + +For standard fingerprints, returns the batch unchanged. For PepFuNN fingerprints, converts SMILES to BILN notation using the [`SmilesToBiln`](pipeline.md#smilestobiln) transformer. + +--- + +### `_rep_batch` + +```python +_rep_batch(batch: List[str]) -> List[np.ndarray] +``` + +Converts each SMILES to an RDKit `Mol` object and computes the fingerprint. Invalid molecules (where `MolFromSmiles` returns `None`) produce zero vectors of length `nbits`. + +--- + +### `_load_generator` + +```python +_load_generator(rep: str) -> object +``` + +Instantiates the appropriate RDKit generator based on `rep`: + +| `rep` value | Generator | +|---|---| +| `'ecfp'` / `'morgan'` | `rdFingerprintGenerator.GetMorganGenerator` | +| `'ecfp-count'` | `GetMorganGenerator` with `countSimulation=True` | +| `'fcfp'` | `GetMorganGenerator` with `GetMorganFeatureAtomInvGen()` | +| `'pepfunn'` | `PepFunn_Generator` | + +--- + +## Representation Shortcuts in `build_models` + +When passing `reps` to `AutoPeptideML.build_models`, fingerprints can be specified as: + +| Format | Example | Meaning | +|---|---|---| +| `` | `'ecfp'` | Uses default radius 8, 1024 bits | +| `-` | `'ecfp-4'` | Uses 1024 bits, radius 4 | +| `--` | `'ecfp-4-2048'` | Explicit radius and bit size | + +--- + +## Example + +```python +from autopeptideml.reps.fps import RepEngineFP + +engine = RepEngineFP(rep='ecfp', nbits=1024, radius=4) + +smiles = [ + 'CC(=O)NC(CCC(N)=O)C(=O)NC(CCC(N)=O)C(=O)O', + 'CC(N)C(=O)O', +] + +fps = engine.compute_reps(smiles, verbose=False) +print(fps.shape) # (2, 1024) +print(engine.dim()) # 1024 +``` diff --git a/docs/repenginelm.md b/docs/repenginelm.md index 2cd6371..660a416 100644 --- a/docs/repenginelm.md +++ b/docs/repenginelm.md @@ -1,4 +1,186 @@ -# RepEngineLM +# `RepEngineLM` — Language Model Representation Engine -::: autopeptideml.reps.lms.RepEngineLM +**Module:** `autopeptideml.reps.lms` +**Inherits from:** [`RepEngineBase`](repenginebase.md) +## Overview + +`RepEngineLM` generates dense vector embeddings for peptide sequences or SMILES strings using pre-trained transformer language models loaded from HuggingFace. It supports protein language models (ESM-2, ProtT5, ANKH, …) and small-molecule language models (MoLFormer, ChemBERTa, PeptideCLM). + +**Requires:** `pip install torch transformers` + +--- + +## Attributes + +| Attribute | Type | Description | +|---|---|---| +| `engine` | `str` | Fixed to `'lm'`. | +| `device` | `str` | Compute device: `'cuda'`, `'mps'`, or `'cpu'` (auto-detected). | +| `model` | object | Loaded HuggingFace model. | +| `tokenizer` | object | Associated tokenizer. | +| `model_name` | `str` | Canonical HuggingFace model name. | +| `dimension` | `int` | Embedding dimensionality. | +| `lab` | `str` | HuggingFace organisation name (e.g. `'facebook'`, `'Rostlab'`). | +| `name` | `str` | Engine identifier in the form `lm-`. | +| `average_pooling` | `bool` | If `True` (default), residue embeddings are mean-pooled per sequence. | +| `cls_token` | `bool` | If `True`, use only the `[CLS]` token embedding (takes precedence over pooling). | +| `fp16` | `bool` | If `True`, use bfloat16 precision via `torch.autocast` where supported. | + +--- + +## Constructor + +```python +RepEngineLM( + model: str, + average_pooling: Optional[bool] = True, + cls_token: Optional[bool] = False, + fp16: bool = True +) +``` + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `model` | `str` | — | Model name or short synonym. See [Available Models](#available-models). | +| `average_pooling` | `bool` | `True` | Average all token embeddings to produce a fixed-size sequence vector. | +| `cls_token` | `bool` | `False` | Use only the `[CLS]` token embedding. Overrides `average_pooling`. | +| `fp16` | `bool` | `True` | Enable bfloat16 autocast when the device supports it. | + +--- + +## Public Methods + +### `compute_reps` *(inherited)* + +```python +compute_reps( + mols: List[str], + verbose: bool = False, + batch_size: int = 12 +) -> Union[np.ndarray, List[np.ndarray]] +``` + +Compute embeddings for a list of sequences/SMILES. With `average_pooling=True` returns a `(n_mols, dimension)` array. + +--- + +### `dim` + +```python +dim() -> int +``` + +Returns the embedding dimension of the model. + +--- + +### `max_len` + +```python +max_len() -> int +``` + +Returns the maximum accepted sequence length for the loaded model: + +| Lab | Max length | +|---|---| +| `facebook` (ESM) | 1022 | +| `EvolutionaryScale` / `InstaDeepAI` | 2046 | +| `DeepChem` (ChemBERTa) | 512 | +| All others | 2046 | + +--- + +### `move_to_device` + +```python +move_to_device(device: str) +``` + +Moves the model to the specified device. Useful when the device is not available at construction time. + +| Parameter | Type | Description | +|---|---|---| +| `device` | `str` | Target device: `'cpu'`, `'cuda'`, or `'mps'`. | + +--- + +### `get_num_params` + +```python +get_num_params(human_readable: bool = False) -> Union[int, str] +``` + +Returns the total number of trainable model parameters. + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `human_readable` | `bool` | `False` | If `True`, returns a formatted string like `"650.000M"` instead of an integer. | + +--- + +## Available Models + +The `model` argument accepts either a canonical HuggingFace name or a short synonym. + +| Short Synonym | Canonical Name | Dimension | Type | +|---|---|---|---| +| `esm2-8m` | `esm2_t6_8M_UR50D` | 320 | Protein LM | +| `esm2-35m` | `esm2_t12_35M_UR50D` | 480 | Protein LM | +| `esm2-150m` | `esm2_t30_150M_UR50D` | 640 | Protein LM | +| `esm2-650m` | `esm2_t33_650M_UR50D` | 1280 | Protein LM | +| `esm1b` | `esm1b_t33_650M_UR50S` | 1280 | Protein LM | +| `esm2-3b` | `esm2_t36_3B_UR50D` | 2560 | Protein LM | +| `esm2-15b` | `esm2_t48_15B_UR50D` | 5120 | Protein LM | +| `esmc-300m` | `ESMplusplus_small` | 960 | Protein LM | +| `esmc-600m` | `ESMplusplus_large` | 1152 | Protein LM | +| `prot-t5-xl` | `prot_t5_xl_half_uniref50-enc` | 1024 | Protein LM | +| `prot-t5-xxl` | `prot_t5_xxl_uniref50` | 1024 | Protein LM | +| `protbert` | `prot_bert` | 1024 | Protein LM | +| `prost-t5` | `ProstT5` | 1024 | Protein LM | +| `ankh-base` | `ankh-base` | 768 | Protein LM | +| `ankh-large` | `ankh-large` | 1536 | Protein LM | +| `molformer-xl` | `MoLFormer-XL-both-10pct` | 768 | Small molecule LM | +| `chemberta-2` | `ChemBERTa-77M-MLM` | 384 | Small molecule LM | +| `chemberta-3` | `ChemBERTa-100M-MLM` | 768 | Small molecule LM | +| `peptideclm` | `PeptideCLM-23M-all` | 768 | Peptide SMILES LM | +| `peptidemtr` | `PeptideMTR_lg` | 1024 | Peptide LM | +| `nt2-500m-ms` | `nucleotide-transformer-v2-500m-multi-species` | 1024 | Nucleotide LM | + +!!! note "PeptideCLM" + Using `peptideclm` requires the `smilesPE` package: `pip install smilesPE`. + The tokenizer vocabulary files are downloaded automatically on first use from the PeptideCLM GitHub repository. + +!!! warning "MoLFormer" + MoLFormer does not support `transformers >= 5.0.0`. Pin to `transformers==4.41.2` if you encounter issues. + +--- + +## Example + +```python +from autopeptideml.reps.lms import RepEngineLM + +# Load ESM-2 8M on CPU +engine = RepEngineLM(model='esm2-8m', average_pooling=True) + +sequences = ['ACDEFGHIKLMNPQRSTVWY', 'AACGWYLP'] +embeddings = engine.compute_reps(sequences, verbose=True, batch_size=4) + +print(embeddings.shape) # (2, 320) +print(engine.dim()) # 320 +print(engine.get_num_params(human_readable=True)) # e.g. "8.000M" +``` + +--- + +## Preprocessing per Model Family + +`_preprocess_batch` performs model-specific sequence preparation: + +| Lab / Model | Preprocessing | +|---|---| +| `Rostlab` (ProtT5, ProtBERT) | Space-delimited residues: `"A C D E F …"` | +| `ProstT5` | Prepended with `" "` | +| All others | Sequences truncated to `max_len()` only | diff --git a/docs/repengineseqbased.md b/docs/repengineseqbased.md index 475c7a3..716f893 100644 --- a/docs/repengineseqbased.md +++ b/docs/repengineseqbased.md @@ -1,4 +1,121 @@ -# RepEngineOneHotEncoding +# `RepEngineOnehot` — One-Hot Sequence Encoder -::: autopeptideml.reps.seq_based.RepEngineOnehot +**Module:** `autopeptideml.reps.seq_based` +**Inherits from:** [`RepEngineBase`](repenginebase.md) +## Overview + +`RepEngineOnehot` encodes canonical amino acid sequences as fixed-length binary one-hot vectors. Each position in the sequence maps to a 21-element binary vector (20 standard amino acids + unknown `'X'`). Sequences longer than `max_length` are truncated; shorter ones are zero-padded. + +This encoder is useful as a lightweight baseline representation that requires no third-party dependencies beyond NumPy. + +--- + +## Residue Alphabet + +The encoder uses a fixed alphabet of 21 characters: + +| Index | Residue | Index | Residue | Index | Residue | +|---|---|---|---|---|---| +| 0 | V (Val) | 7 | H (His) | 14 | T (Thr) | +| 1 | I (Ile) | 8 | W (Trp) | 15 | M (Met) | +| 2 | L (Leu) | 9 | F (Phe) | 16 | A (Ala) | +| 3 | E (Glu) | 10 | Y (Tyr) | 17 | G (Gly) | +| 4 | Q (Gln) | 11 | R (Arg) | 18 | P (Pro) | +| 5 | D (Asp) | 12 | K (Lys) | 19 | C (Cys) | +| 6 | N (Asn) | 13 | S (Ser) | 20 | X (unknown) | + +Non-canonical residues are not mapped and should be converted to `'X'` beforehand using [`CanonicalCleaner`](pipeline.md#canonicalcleaner). + +--- + +## Attributes + +| Attribute | Type | Description | +|---|---|---| +| `engine` | `str` | Fixed to `'one-hot'`. | +| `max_length` | `int` | Maximum sequence length. Sequences are truncated to this value. | +| `name` | `str` | Fixed to `'one-hot'`. | + +--- + +## Constructor + +```python +RepEngineOnehot(max_length: int) +``` + +| Parameter | Type | Description | +|---|---|---| +| `max_length` | `int` | Maximum number of residues per sequence. Determines the output vector length as `max_length × 21`. | + +--- + +## Methods + +### `compute_reps` *(inherited)* + +```python +compute_reps( + mols: List[str], + verbose: bool = False, + batch_size: int = 12 +) -> np.ndarray +``` + +Returns an `int8` array of shape `(n_seqs, max_length × 21)`. + +--- + +### `dim` + +```python +dim() -> int +``` + +Returns `max_length × 21`. + +--- + +### `_preprocess_batch` + +```python +_preprocess_batch(batch: List[str]) -> List[str] +``` + +Truncates each sequence to `max_length` characters. + +--- + +### `_rep_batch` + +```python +_rep_batch(batch: List[str]) -> np.ndarray +``` + +Converts each sequence in the batch into a flattened one-hot matrix of shape `(max_length × 21,)`. +Returns a 2D `int8` array of shape `(len(batch), max_length × 21)`. + +--- + +## Example + +```python +from autopeptideml.reps.seq_based import RepEngineOnehot + +engine = RepEngineOnehot(max_length=10) + +sequences = ['ACDEFGHIKL', 'MWGY'] +X = engine.compute_reps(sequences) + +print(X.shape) # (2, 210) — 10 × 21 +print(engine.dim()) # 210 +``` + +--- + +## Notes + +- In `AutoPeptideML.build_models`, pass `reps=['one-hot']` to use this encoder with the default `max_length=50`. +- For variable-length sequences, `max_length` should be set to the maximum expected length in your dataset to avoid truncation of long sequences. +- The encoder operates on canonical sequences. Use the [`to-sequences`](pipeline.md#built-in-pipelines) preprocessing pipeline to convert SMILES or mixed input to canonical sequences before passing to this engine. diff --git a/mkdocs.yml b/mkdocs.yml index a88afb8..fcaceca 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,48 +5,39 @@ watch: [autopeptideml] nav: - Home: - Overview: index.md - - Code reference: autopeptideml/ -- Code reference: - - AutoPeptideML: - - autopeptideml.md - - RepEngineBase: - - repenginebase.md - - RepEngineFP: - - repenginefp.md - - RepEngineLM: - - repenginelm.md - - RepEngineSeqBased: - - repengineseqbased.md +- Code Reference: + - AutoPeptideML: autopeptideml.md + - Representations: + - RepEngineBase: repenginebase.md + - RepEngineFP: repenginefp.md + - RepEngineLM: repenginelm.md + - RepEngineOnehot: repengineseqbased.md + - Pipeline: pipeline.md + - Negative Sampling: negative_sampling.md + - Model Architectures: architectures.md + - Metrics: metrics.md + - CLI Reference: cli.md + markdown_extensions: - attr_list theme: - name: material + name: material + features: + - content.code.annotate + - navigation.tabs + - navigation.top + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: black + accent: purple features: - - content.code.annotate - - navigation.tabs - - navigation.top - palette: - - media: "(prefers-color-scheme: light)" - scheme: default - primary: black - accent: purple - # toggle: - # icon: material/weather-sunny - # name: Switch to light mode - # - media: "(prefers-color-scheme: dark)" - # scheme: slate - # primary: black - # accent: lime - # toggle: - # icon: material/weather-night - # name: Switch to dark mode - features: - - search.suggest - - search.highlight - - content.tabs.link - icon: - repo: fontawesome/brands/github-alt - language: en + - search.suggest + - search.highlight + - content.tabs.link + icon: + repo: fontawesome/brands/github-alt + language: en repo_name: IBM/AutoPeptideML repo_url: https://github.com/IBM/AutoPeptideML edit_uri: '' @@ -58,13 +49,12 @@ plugins: python: load_external_modules: - https://docs.python.org/3/objects.inv - - https://installer.readthedocs.io/en/stable/objects.inv # demonstration purpose in the docs + - https://installer.readthedocs.io/en/stable/objects.inv - https://mkdocstrings.github.io/autorefs/objects.inv options: show_source: false docstring_style: sphinx - docstring_options: - # ignore_init_summary: yes + docstring_options: {} merge_init_into_class: yes show_submodules: yes - markdownextradata: From 2c8256390b90a92a49150d0b1e9c3e67f56903f4 Mon Sep 17 00:00:00 2001 From: RaulFD-creator Date: Thu, 20 Aug 2026 12:11:14 +0100 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=9A=80=20v.2.1.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- autopeptideml/apml.py | 2 +- docs/autopeptideml.md | 128 +++++++++++++++++++++--------------------- setup.py | 2 +- 3 files changed, 66 insertions(+), 66 deletions(-) diff --git a/autopeptideml/apml.py b/autopeptideml/apml.py index e8a621b..c34e92e 100644 --- a/autopeptideml/apml.py +++ b/autopeptideml/apml.py @@ -24,7 +24,7 @@ from .reps import RepEngineBase, PLMs, CLMs, FPs -__version__ = '2.0.8' +__version__ = '2.1.0' class AutoPeptideML: diff --git a/docs/autopeptideml.md b/docs/autopeptideml.md index c459ef9..8b0ff50 100644 --- a/docs/autopeptideml.md +++ b/docs/autopeptideml.md @@ -1,7 +1,7 @@ # `AutoPeptideML` — Main Pipeline Class **Module:** `autopeptideml.apml` -**Version:** 2.0.8 +**Version:** 2.1.0 ## Overview @@ -24,13 +24,13 @@ AutoPeptideML( Creates a timestamped subdirectory under `outputdir` and writes an initial `metadata/metadata.yml` file. -| Parameter | Type | Default | Description | -|---|---|---|---| -| `data` | `pd.DataFrame` or `List[str]` | — | Input data. Pass a DataFrame with sequence and label columns, or a plain list of sequences (all assumed positive). | -| `outputdir` | `str` | — | Base output directory. A timestamped sub-folder is created automatically. | -| `sequence_field` | `str` | `None` | Column name containing peptide sequences or SMILES strings. Required when `data` is a DataFrame. | -| `label_field` | `str` | `None` | Column name containing binary (`0`/`1`) or continuous labels. Required when `data` is a DataFrame. | -| `remove_duplicates` | `bool` | `True` | Drop rows with duplicate sequences before any processing. | +| Parameter | Type | Default | Description | +| ------------------- | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | +| `data` | `pd.DataFrame` or `List[str]` | — | Input data. Pass a DataFrame with sequence and label columns, or a plain list of sequences (all assumed positive). | +| `outputdir` | `str` | — | Base output directory. A timestamped sub-folder is created automatically. | +| `sequence_field` | `str` | `None` | Column name containing peptide sequences or SMILES strings. Required when `data` is a DataFrame. | +| `label_field` | `str` | `None` | Column name containing binary (`0`/`1`) or continuous labels. Required when `data` is a DataFrame. | +| `remove_duplicates` | `bool` | `True` | Drop rows with duplicate sequences before any processing. | **Output directory layout (created on init):** @@ -45,13 +45,13 @@ Creates a timestamped subdirectory under `outputdir` and writes an initial `meta ## Class Attributes -| Attribute | Type | Description | -|---|---|---| -| `df` | `pd.DataFrame` | Active working dataset. Extended with `apml-smiles` and `apml-seqs` columns during preprocessing. | -| `metadata` | `dict` | Run metadata written to YAML after every step. | -| `parts` | `dict` | Train / test partition index arrays (keys: `'train'`, `'test'`). Populated by `build_models`. | -| `x` | `dict[str, np.ndarray]` | Representation arrays, keyed by representation name. | -| `ensemble` | `VotingEnsemble` | Best trained ensemble model. Available after `build_models`. | +| Attribute | Type | Description | +| ---------- | ----------------------- | ------------------------------------------------------------------------------------------------- | +| `df` | `pd.DataFrame` | Active working dataset. Extended with `apml-smiles` and `apml-seqs` columns during preprocessing. | +| `metadata` | `dict` | Run metadata written to YAML after every step. | +| `parts` | `dict` | Train / test partition index arrays (keys: `'train'`, `'test'`). Populated by `build_models`. | +| `x` | `dict[str, np.ndarray]` | Representation arrays, keyed by representation name. | +| `ensemble` | `VotingEnsemble` | Best trained ensemble model. Available after `build_models`. | --- @@ -73,15 +73,15 @@ sample_negatives( Augments the dataset with negative samples drawn from a peptide database to reach the requested negative/positive ratio. Internally delegates to [`add_negatives_from_db`](negative_sampling.md#add_negatives_from_db). -| Parameter | Type | Default | Description | -|---|---|---|---| -| `target_db` | `str` or `pd.DataFrame` | — | Built-in database name (`'canonical'`, `'non-canonical'`, `'both'`) or a custom DataFrame. | -| `activities_to_exclude` | `List[str]` | `[]` | Column names flagging known active entries that must not appear as negatives. | -| `desired_ratio` | `float` | `1.0` | Target negatives-to-positives ratio. | -| `verbose` | `bool` | `True` | Print progress information. | -| `sample_by` | `str` | `'mw'` | Matching strategy. `'mw'` bins by molecular weight (requires RDKit); `'length'` bins by sequence length. | -| `n_jobs` | `int` | all CPUs | Number of parallel workers for feature computation. | -| `random_state` | `int` | `1` | Random seed for reproducibility. | +| Parameter | Type | Default | Description | +| ----------------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------- | +| `target_db` | `str` or `pd.DataFrame` | — | Built-in database name (`'canonical'`, `'non-canonical'`, `'both'`) or a custom DataFrame. | +| `activities_to_exclude` | `List[str]` | `[]` | Column names flagging known active entries that must not appear as negatives. | +| `desired_ratio` | `float` | `1.0` | Target negatives-to-positives ratio. | +| `verbose` | `bool` | `True` | Print progress information. | +| `sample_by` | `str` | `'mw'` | Matching strategy. `'mw'` bins by molecular weight (requires RDKit); `'length'` bins by sequence length. | +| `n_jobs` | `int` | all CPUs | Number of parallel workers for feature computation. | +| `random_state` | `int` | `1` | Random seed for reproducibility. | --- @@ -111,25 +111,25 @@ build_models( The main training entry-point. Internally calls `_preprocessing_data`, `_partitioning`, `_representing`, `_hpo`, and `_evaluating` in sequence. -| Parameter | Type | Default | Description | -|---|---|---|---| -| `task` | `str` | `'class'` | Task type. `'class'` for binary classification, `'reg'` for regression. | -| `ensemble` | `bool` | `False` | Build an ensemble over multiple representations. | -| `reps` | `str`, `List[str]`, or `Dict[str, RepEngineBase]` | `['ecfp-16']` | Representation(s) to compute. Shortcuts: `'ecfp'`, `'esm2-8m'`, `'one-hot'`, etc. Pass a dict to provide pre-built engine objects. See [Representations](repenginebase.md) for all options. | -| `models` | `str` or `List[str]` | all models | Model families to include in HPO. Supported: `'knn'`, `'svm'`, `'rf'`, `'gradboost'`, `'lightgbm'`, `'xgboost'`. | -| `split_strategy` | `str` | `'min'` | Data split strategy. `'random'` uses 80/20 random split; `'min'` uses Hestia similarity-based partitioning to minimise leakage. | -| `hestia_generator` | `HestiaGenerator` | `None` | Pre-computed Hestia generator to reuse existing partitions. | -| `model_configs` | `Dict[str, dict]` | `{}` | Custom hyperparameter search space overrides per model. | -| `partitions` | `Dict[str, np.ndarray]` | `None` | Pre-defined index arrays (`{'train': ..., 'test': ...}`). Skips Hestia partitioning. | -| `folds` | `List[Tuple[np.ndarray, np.ndarray]]` | `None` | Custom cross-validation folds as `(train_idx, val_idx)` pairs. | -| `n_folds_cv` | `int` | `5` | Number of cross-validation folds (used when `folds` is None). | -| `verbose` | `bool` | `True` | Print progress at each stage. | -| `n_trials` | `int` | `100` | Number of Optuna HPO trials. | -| `sim_args` | `SimArguments` | `None` | Custom Hestia similarity arguments. | -| `device` | `str` | `'cpu'` | Compute device for language model representations: `'cpu'`, `'cuda'`, or `'mps'`. | -| `random_state` | `int` | `1` | Global random seed. | -| `extra_x` | `np.ndarray` | `None` | Additional feature columns concatenated to every representation array. | -| `n_jobs` | `int` | all CPUs | Parallelism for preprocessing and partitioning. | +| Parameter | Type | Default | Description | +| ------------------ | ------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `task` | `str` | `'class'` | Task type. `'class'` for binary classification, `'reg'` for regression. | +| `ensemble` | `bool` | `False` | Build an ensemble over multiple representations. | +| `reps` | `str`, `List[str]`, or `Dict[str, RepEngineBase]` | `['ecfp-16']` | Representation(s) to compute. Shortcuts: `'ecfp'`, `'esm2-8m'`, `'one-hot'`, etc. Pass a dict to provide pre-built engine objects. See [Representations](repenginebase.md) for all options. | +| `models` | `str` or `List[str]` | all models | Model families to include in HPO. Supported: `'knn'`, `'svm'`, `'rf'`, `'gradboost'`, `'lightgbm'`, `'xgboost'`. | +| `split_strategy` | `str` | `'min'` | Data split strategy. `'random'` uses 80/20 random split; `'min'` uses Hestia similarity-based partitioning to minimise leakage. | +| `hestia_generator` | `HestiaGenerator` | `None` | Pre-computed Hestia generator to reuse existing partitions. | +| `model_configs` | `Dict[str, dict]` | `{}` | Custom hyperparameter search space overrides per model. | +| `partitions` | `Dict[str, np.ndarray]` | `None` | Pre-defined index arrays (`{'train': ..., 'test': ...}`). Skips Hestia partitioning. | +| `folds` | `List[Tuple[np.ndarray, np.ndarray]]` | `None` | Custom cross-validation folds as `(train_idx, val_idx)` pairs. | +| `n_folds_cv` | `int` | `5` | Number of cross-validation folds (used when `folds` is None). | +| `verbose` | `bool` | `True` | Print progress at each stage. | +| `n_trials` | `int` | `100` | Number of Optuna HPO trials. | +| `sim_args` | `SimArguments` | `None` | Custom Hestia similarity arguments. | +| `device` | `str` | `'cpu'` | Compute device for language model representations: `'cpu'`, `'cuda'`, or `'mps'`. | +| `random_state` | `int` | `1` | Global random seed. | +| `extra_x` | `np.ndarray` | `None` | Additional feature columns concatenated to every representation array. | +| `n_jobs` | `int` | all CPUs | Parallelism for preprocessing and partitioning. | --- @@ -216,32 +216,32 @@ After training, the output directory contains: The `reps` argument of `build_models` accepts the following short identifiers: -| Shortcut | Engine | Notes | -|---|---|---| -| `'ecfp'` | `RepEngineFP` | Defaults to radius 8, 1024 bits. Format: `ecfp--` | -| `'fcfp'` | `RepEngineFP` | Feature-class Morgan. Format: `fcfp--` | -| `'pepfunn'` | `RepEngineFP` | Requires `pepfunn` package. | -| `'one-hot'` | `RepEngineOnehot` | One-hot encoding of canonical sequences (max length 50). | -| `'esm2-8m'` | `RepEngineLM` | ESM-2 8M parameter model. | -| `'esm2-35m'` | `RepEngineLM` | ESM-2 35M parameter model. | -| `'esm2-150m'` | `RepEngineLM` | ESM-2 150M parameter model. | -| `'esm2-650m'` | `RepEngineLM` | ESM-2 650M parameter model. | -| `'esm2-3b'` | `RepEngineLM` | ESM-2 3B parameter model. | -| `'esm2-15b'` | `RepEngineLM` | ESM-2 15B parameter model. | -| `'prot-t5-xl'` | `RepEngineLM` | ProtT5-XL encoder. | -| `'ankh-base'` | `RepEngineLM` | ANKH base model. | -| `'molformer-xl'` | `RepEngineLM` | IBM MoLFormer-XL (SMILES-based). | -| `'chemberta-2'` | `RepEngineLM` | ChemBERTa 77M (SMILES-based). | -| `'peptideclm'` | `RepEngineLM` | PeptideCLM 23M (SMILES-based). Requires `smilesPE`. | +| Shortcut | Engine | Notes | +| ---------------- | ----------------- | ---------------------------------------------------------------- | +| `'ecfp'` | `RepEngineFP` | Defaults to radius 8, 1024 bits. Format: `ecfp--` | +| `'fcfp'` | `RepEngineFP` | Feature-class Morgan. Format: `fcfp--` | +| `'pepfunn'` | `RepEngineFP` | Requires `pepfunn` package. | +| `'one-hot'` | `RepEngineOnehot` | One-hot encoding of canonical sequences (max length 50). | +| `'esm2-8m'` | `RepEngineLM` | ESM-2 8M parameter model. | +| `'esm2-35m'` | `RepEngineLM` | ESM-2 35M parameter model. | +| `'esm2-150m'` | `RepEngineLM` | ESM-2 150M parameter model. | +| `'esm2-650m'` | `RepEngineLM` | ESM-2 650M parameter model. | +| `'esm2-3b'` | `RepEngineLM` | ESM-2 3B parameter model. | +| `'esm2-15b'` | `RepEngineLM` | ESM-2 15B parameter model. | +| `'prot-t5-xl'` | `RepEngineLM` | ProtT5-XL encoder. | +| `'ankh-base'` | `RepEngineLM` | ANKH base model. | +| `'molformer-xl'` | `RepEngineLM` | IBM MoLFormer-XL (SMILES-based). | +| `'chemberta-2'` | `RepEngineLM` | ChemBERTa 77M (SMILES-based). | +| `'peptideclm'` | `RepEngineLM` | PeptideCLM 23M (SMILES-based). Requires `smilesPE`. | --- ## Split Strategies -| Strategy | Description | -|---|---| -| `'random'` | 80/20 random split (no similarity awareness). | -| `'min'` | Uses [Hestia](https://github.com/IBM/Hestia-OOD) to compute similarity-based partitions and selects the least-leaky split. Recommended for trustworthy evaluation. | +| Strategy | Description | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `'random'` | 80/20 random split (no similarity awareness). | +| `'min'` | Uses [Hestia](https://github.com/IBM/Hestia-OOD) to compute similarity-based partitions and selects the least-leaky split. Recommended for trustworthy evaluation. | --- diff --git a/setup.py b/setup.py index b8d8e9e..76f475e 100644 --- a/setup.py +++ b/setup.py @@ -73,6 +73,6 @@ def get_files_in_dir(path: Path, base: Path) -> list: name='autopeptideml', packages=find_packages(exclude=['examples']), url='https://ibm.github.io/AutoPeptideML/', - version='2.0.8', + version='2.1.0', zip_safe=False, )