Skip to content

Workflow Overview

ligand-classification is organized around one repeatable flow:

  1. Generate processed feature tables from a raw SMILES CSV.
  2. Describe one or more datasets in YAML.
  3. Train configured models through nested cross-validation.
  4. Save pipelines, metrics, dataset summaries, and logs.
  5. Reuse trained artifacts for evaluation and batch prediction.

Repository layout

Path Purpose
src/cli/ User-facing commands for feature generation, exploration, training, evaluation, and prediction.
src/training/ Dataset preparation, pipeline assembly, model registry, search helpers, logging, and summaries.
src/features/ RDKit descriptor helpers, Morgan fingerprints, kekulization, and DeepPK API glue.
src/evaluation/metrics.py Shared metric calculations used by training and evaluation.
configs/ Canonical training configs plus hyperparameter grids.
docs/ MkDocs content for the GitHub Pages site.
tests/ Regression coverage for dataset prep, CLIs, metrics, and training bookkeeping.

Canonical example path

The refreshed docs use the psychlight_a example data already checked into the repo:

  • Raw input: data/example/raw/psychlight_a.csv
  • Generated outputs: data/example/processed/psychlight_a/
  • Starter config: configs/train.yaml

That flow matches the current process_features output names:

  • psychlight_a_descriptors.csv
  • psychlight_a_mordred.csv
  • psychlight_a_morgan.csv
  • psychlight_a_dpk.csv when DeepPK is enabled
  • psychlight_a_deeppk_extra.csv when DeepPK returns unmatched rows

What the training pipeline records

Each training run can produce:

  • A pipeline-steps overview CSV in the configured log root.
  • Timestamped model files under training.outputs.model_dir/<dataset>/<date>/<hash>/.
  • Per-model metrics YAML files under training.outputs.metrics_dir/<dataset>/<date>/<hash>/.
  • A dataset summary YAML and CSV in the metrics directory.
  • A dataset log text file under training.outputs.log_dir/<dataset>/<date>/<hash>/.
  • The shared ledger models/tracking/training_runs.csv, regardless of training.outputs.log_dir.

Backward-compatibility note

Some checked-in processed descriptor exports in this repo still use *_rdkit.csv. Those are legacy artifacts from an older filename convention. The current CLI writes *_descriptors.csv, and the starter configs now follow that current behavior.