repository·main·Indexed 21 days ago
https://github.com/astrazeneca/chemicalxA deep learning library for drug pair scoring tasks, including drug-drug interaction, polypharmacy side effect, and synergy prediction. It provides integrated benchmark datasets (such as Drugbank DDI and TwoSides), data loaders, and state-of-the-art neural network architectures. The library includes a high-level pipeline for orchestrating model training and evaluation, supporting both SMILES string-based techniques and neural message passing-based models.
ChemicalX is a deep learning library designed for drug pair scoring tasks, specifically focusing on:
The library provides:
The TwoSides benchmark dataset in ChemicalX is a subsample of the original TwoSides dataset, processed as follows:
BatchGenerator using instances of DrugFeatureSet, ContextFeatureSet, and LabeledTriples. The BatchGenerator produces DrugPairBatch instances, which act as custom data classes containing the drug and context features for each batch.ChemicalX uses specialized feature sets to manage molecular and biological data:
UserDict object that enables fast retrieval of molecular graphs and drug-level features (like Morgan fingerprints). It provides get_feature_matrix and get_molecules class methods to batch drugs and molecular graphs using drug identifiers. Molecule-level features are returned as torch.FloatTensor matrices, and molecular graphs are returned as torchdrug.PackedGraph objects.UserDict object used to store biological or chemical context-specific feature vectors as torch.FloatTensor instances, keyed by context identifiers.The LabeledTriples class is a wrapper around pandas DataFrames that manages labeled drug pairs where labels are context-specific. It supports:
train_test_split class method.Drug pair scoring models in ChemicalX inherit from torch.nn.Module. Every model implements two key methods:
unpack: Used to unpack the DrugPairBatch object.forward: Performs the forward pass to make predictions and return propensities for the drug pairs in the batch.Models include sensible default parameters for hyperparameters that are not dependent on the specific dataset.
The Drugbank DDI benchmark dataset used in ChemicalX is derived from the Therapeutic Data Commons. It is structured as follows:
You can use the chemicalx.pipeline function to orchestrate the training and evaluation of drug pair scoring models. The pipeline requires a dataset and a model instance. It supports various data arguments to configure feature extraction and training arguments to control the learning process. After running the pipeline, you can use the returned results object to summarize performance metrics (like AUC-ROC) or save the model and metadata to disk.
from chemicalx import pipeline
from chemicalx.models import DeepSynergy
from chemicalx.data import DrugCombDB
model = DeepSynergy(context_channels=112, drug_channels=256)
dataset = DrugCombDB()
results = pipeline(
dataset=dataset,
model=model,
# Data arguments
batch_size=5120,
context_features=True,
drug_features=True,
drug_molecules=False,
# Training arguments
epochs=100,
)
# Outputs information about the AUC-ROC, etc. to the console.
results.summarize()
# Save the model, losses, evaluation, and other metadata.
results.save("~/test_results/")You can manage your ChemicalX installation using standard pip commands.
To upgrade an existing installation to the latest version, use the --upgrade flag. To verify which version is currently installed in your environment, use pip freeze and filter for chemicalx.
# Upgrade ChemicalX
$ pip install chemicalx --upgrade
# Check current version
$ pip freeze | grep chemicalxChemicalX requires specific prerequisites, particularly from PyTorch Geometric. If you are using PyTorch 1.10.0, you must install the compatible torch-scatter binaries, torchdrug, and then chemicalx.
Replace ${CUDA} in the command below with cpu, cu102, or cu111 to match your specific PyTorch/CUDA installation.
$ pip install torch-scatter -f https://pytorch-geometric.com/whl/torch-1.10.0+${CUDA}.html
$ pip install torchdrug
$ pip install chemicalxTo perform inference (scoring), set the model to evaluation mode using model.eval(). Update the BatchGenerator.labeled_triples attribute with your test set.
Iterate through the generator, making predictions on batch.context_features, batch.drug_features_left, and batch.drug_features_right. To associate predictions with their original data, attach the prediction values to the batch.identifiers DataFrame. Finally, use pandas.concat() to combine the results from all batches into a single DataFrame.
import pandas as pd
model.eval()
generator.labeled_triples = test
predictions = []
for batch in generator:
prediction = model(batch.context_features,
batch.drug_features_left,
batch.drug_features_right)
prediction = prediction.detach().cpu().numpy()
identifiers = batch.identifiers
identifiers["prediction"] = prediction
predictions.append(identifiers)
predictions = pd.concat(predictions)The pipeline function provides a high-level abstraction for the complete lifecycle of a ChemicalX model. Given a dataset and a model, the pipeline handles training, score generation, and evaluation metric calculation.
from chemicalx import pipeline
from chemicalx.models import DeepSynergy
from chemicalx.data import DrugCombDB
model = DeepSynergy(context_channels=112,
drug_channels=256)
dataset = DrugCombDB()
results = pipeline(dataset=dataset,
model=model,
batch_size=1024,
context_features=True,
drug_features=True,
drug_molecules=False,
labels=True,
epochs=100)
results.summarize()
results.save("~/test_results/")