pycomsia

A Python implementation of CoMSIA (Comparative Molecular Similarity Indices Analysis) 3D-QSAR: it turns a set of pre-aligned ligands with measured activities into a PLS model relating molecular interaction fields to potency.

What this version can do

• CoMSIA fields — steric, electrostatic, hydrophobic, H-bond donor and H-bond acceptor similarity-index fields on a configurable grid.
• PLS modelling — leave-one-out component selection, train/test split metrics (R²train, Q²LOO, R²test), and per-field contribution fractions.
• Visualisation — field plots, coefficient contour plots, and a PyMOL session (.pse) of all ligands with the contour surfaces; optionally load a protein to map unexplored (excluded) binding-site volume.
• Prediction — score a separate prediction set, or a "prospective" set with no activities (predictions written back as SD tags).
• Model persistence (this fork) — save a trained model and reload it to predict new pre-aligned compounds without rebuilding (pycomsia.model_persistence.PyCoMSIAModel).
• Sequential learning (this fork) — cumulative within-target model building over successive compound batches, with retroactive scoring (PyCoMSIAModel.sequential_build / retroactive_r2).

Input requirement: molecules must be supplied in an SDF, pre-aligned into a common coordinate frame, with the activity stored as an SD property (e.g. pIC50). Prediction reuses the model's grid, so molecules to be predicted must be aligned into the same frame as the training set.

Installation

pip install -e .          # from the repository root (editable install)
# optional extras for 3D visualisation / PyMOL sessions:
#   pyvista, pymol-open-source

Quick start (command line)

pycomsia -t train.sdf -a pIC50 -o results            # build + full report
pycomsia -t train.sdf -a pIC50 -o results \
         -p test.sdf -P protein.pdb \                # prediction set + excluded volume
         --save-model model_A.pkl                    # also persist the model

Key options: -t training SDF (required), -a activity tag (required), -o output dir (required), -p prediction SDF, -P protein (PDB/mmCIF), -f field set, -n PLS components, -m/--save-model path to persist the model.

Python API: load → train → save → load → predict

from pycomsia.model_persistence import PyCoMSIAModel

# 1. LOAD DATA + TRAIN
#    `build` reads the pre-aligned SDF, computes the fields on a grid, selects
#    the PLS component count by leave-one-out CV, and fits the model.
model = PyCoMSIAModel.build("train.sdf", activity_tag="pIC50")
print(model.metrics)     # {'r2_train':…, 'q2_loo':…, 'r2_test':…, 'n_components':…, …}

# 2. SAVE  (bundles the grid, field selection, scalers, column mask and PLS model)
model.save("model_A.pkl")

# 3. LOAD  (later, in a fresh process — no rebuild)
model = PyCoMSIAModel.load("model_A.pkl")

# 4. PREDICT new, pre-aligned compounds (aligned to the training frame)
preds = model.predict("new_compounds.sdf")
#   -> pandas DataFrame: columns  name, smiles, predicted[, actual if tagged]
preds.to_csv("predictions.csv", index=False)

Sequential (incremental) within-target learning

Add each new batch of compounds and rebuild, keeping every pass on disk:

from pycomsia.model_persistence import PyCoMSIAModel, retroactive_r2

# pass k trains on increments 1..k; each pass saved as seq_pass{k}.pkl
models = PyCoMSIAModel.sequential_build(
    ["batch1.sdf", "batch2.sdf", "batch3.sdf"], activity_tag="pIC50",
    work_dir="runs/", save_prefix="models/seq",
)
latest = PyCoMSIAModel.load("models/seq_pass3.pkl")   # reload newest, predict
latest.predict("new_compounds.sdf")

# retroactive check: does the larger, later model still predict earlier holdouts?
R = retroactive_r2(models, ["T1.sdf", "T2.sdf", "T3.sdf"], activity_tag="pIC50")

Note: PLS is a batch method (no warm-start), so each sequential pass re-fits a fresh model on all data accumulated so far.

Copyright

Copyright (c) 2026, jscheen

Acknowledgements

Project based on the Computational Molecular Science Python Cookiecutter version 1.11.