ZairaChem trains structure-activity (QSAR) models straight from data files without manual feature engineering. Give it a labelled dataset and it will:
- Featurize the molecules with a curated set of Ersilia descriptor models.
- Train and pool per-descriptor models into a single consensus predictor.
- Predict activities for new molecules and produce a report with plots and metrics.
ZairaChem requires Docker to be installed and running.
The quickest way to install ZairaChem is the interactive installer. It sets up a Python environment, installs ZairaChem, pulls the Docker base images, and (optionally) fetches the default Ersilia models:
git clone https://github.com/ersilia-os/zairachem-docker
cd zairachem-docker
bash install.shRun bash install.sh --help for non-interactive flags.
Check the install (this also prints a Docker readiness line):
zairachem --helpTrain a model and predict, using the example data shipped in example/, one set per task:
classification (DILI, columns smiles,dili) and regression (ESOL aqueous solubility, columns
smiles,logS). Each has 380 molecules to train (*_train.csv) and 95 to predict
(*_test_smiles.csv, smiles only; *_test.csv has their labels). Make sure Docker is running first.
# Classification
zairachem fit -i example/classification_train.csv -m example_classification_model
zairachem predict -i example/classification_test_smiles.csv -m example_classification_model -o classification_predictions
# Regression (the task is detected from the target; -c / -r force it)
zairachem fit -i example/regression_train.csv -m example_regression_model
zairachem predict -i example/regression_test_smiles.csv -m example_regression_model -o regression_predictionsThe regression set is a seeded 475-molecule sample (380 / 95 split) of the ESOL / Delaney solubility
benchmark from MoleculeNet; logS is the measured log solubility in mol/L.
| Command | Description |
|---|---|
zairachem fit |
Train a QSAR model from a labelled CSV (runs every step below). |
zairachem predict |
Predict activities for new molecules with a trained model. |
zairachem setup |
Standardize and prepare the input molecules. |
zairachem describe |
Compute molecular descriptors for each featurizer. |
zairachem treat |
Impute and scale the descriptor matrix. |
zairachem estimate |
Train the per-descriptor base estimators. |
zairachem pool |
Combine the per-descriptor estimators into a consensus. |
zairachem report |
Render the plots, tables and HTML report. |
zairachem finish |
Assemble final outputs and clean up intermediate data. |
A run stops the Ersilia model servers it started when it ends (a server that was already running,
for example one served with ersilia serve, is left alone, and servers left by a killed run are
stopped by the next one); zairachem stop removes them all.
Run zairachem <command> --help for its options. setup creates a model directory (-m) from the
input CSV; the later step commands (describe to finish) each run one stage on it.
By default fit uses a curated set of Ersilia descriptors (-f to choose your own). A descriptor
with no published transformer is skipped at setup. The default Mol-JEPA (eos9q2i) is licensed for
non-commercial use only; pass -f without it to exclude it.
results/output.csv has one row per molecule:
| Column | Meaning |
|---|---|
score |
Pooled rank against 50,000 drug-like molecules (lazyqsar): 0.50 top 10%, 0.65 top 1%, 0.75 top 0.1%. |
similarity |
Mean Tanimoto similarity to the 5 nearest training molecules (predict only). |
spread |
Standard deviation of the per-descriptor predictions (predict only); high means the descriptors disagree. |
label |
The true value, when the input has one. |
results/output_table.csv follows the input rows and adds the input SMILES, InChIKey, the pooled
probability (proba), the 0/1 call (rank ≥ 0.65), the per-descriptor probabilities
(proba_<eos_id>) and the 2-D projections.
A regression model (fit -r) predicts the value itself, so there is no rank, no call and no
cutoffs.json. output.csv carries value in place of score (plus similarity, spread and
label as above), output_table.csv adds the lower/upper conformal interval and the
per-descriptor values (value_<eos_id>), and performance_table.csv is one row per model with R²,
RMSE, MAE and the Pearson and Spearman correlations.
docs/regression.md covers what a regression run does and does not produce, and why.
When the input measures a compound more than once, setup records how far those repeats
disagreed (inputs/replicates.json). That spread is the assay's own reproducibility and the
scale a regression model's RMSE has to be read against; the fit summary and the report both
show it.
A predict run records how many of the molecules it was given the model had already been
trained on (inputs/train_overlap.json), and says so in the summary and the report. The
similarity column cannot: it averages a molecule's nearest other training molecules, so a
molecule that was in the training set scores like its neighbourhood. For those rows the model
is recalling a label rather than predicting one, which is easy to mistake for accuracy when
the screening library overlaps the training set.
results/cutoffs.json gives each named cutoff as a probability and as a rank, the scale of score:
screening (the call: rank 0.65), kappa (Cohen's kappa on the training out-of-fold scores),
balanced (each descriptor's balanced-accuracy cutoff) and default (0.5).
results/performance_table.csv has the metrics of the pooled model and of each descriptor at each
of them.
Nearly all of a fit is lazy-qsar training one model per descriptor, and --evaluate refits the
pipeline once per fold. docs/scale.md has the measured step costs, what has to
fit in memory, what gets written to disk, and the two limits a large run meets: Butina splits are
skipped above 10,000 molecules, and pre-screening scores a sample above 25,000 rows.
lazy-qsar positions every prediction (rank) against a fixed library of 50,000 molecules, so each
descriptor a fit trains needs that library featurized with it. A classification fit downloads the
published matrices for the descriptors it trains into ~/zairachem/rank_reference/ (up to about 2 GB
for the default featurizers; ZAIRACHEM_HOME moves the folder). One that is not published (e.g. a
custom featurizer) is computed on its model server and cached there, so later fits reuse it. A
regression fit has no rank, so it downloads nothing.
The Ersilia Open Source Initiative is a tech-nonprofit organization fueling sustainable research in the Global South. Ersilia's main asset is the Ersilia Model Hub, an open-source repository of AI/ML models for antimicrobial drug discovery.
ZairaChem is developed in collaboration with the H3D Centre in Cape Town, South Africa.
