search

JDACS4C-IMPROVE / DrugCell

A visible neural network model for drug response prediction
MIT License
0 stars 2 forks source link

readme

DrugCell: a visible neural network model for drug response prediction

DrugCell is an interpretable neural network-based model that predicts cell response to a wide range of drugs. Unlike fully-connected neural networks, connectivity of neurons in the DrugCell mirrors a biological hierarchy (e.g. Gene Ontology), so that the information travels only between subsystems (or pathways) with known hierarchical relationship during the model training. This feature of the framework allows for identification of subsystems in the hierarchy that are important to the model's prediction, warranting further investigation on underlying biological mechanisms of cell response to treatments.

Requirements

conda>=23.5

IMPROVE PROJECT INSTRUCTIONS

The improve project IMPROVE Projectrequires standarized interfaces for data preprocessing, training and inference, follow the code for drugcell in DrugCell

Installation

The IMPROVE project is currently using the develop branch

Using Conda

Create environment

conda env create -f drugcell_conda.yml

Activate the environment

conda activate drugcell_python

Download Drugcell

git clone -b develop https://github.com/JDACS4C-IMPROVE/DrugCell.git
cd DrugCell

Install Torch for CUDA and CANDLE package

python3 -m pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 torchaudio==0.12.1 torchmetrics==0.11.1 --extra-index-url https://download.pytorch.org/whl/cu113
python3 -m pip install git+https://github.com/ECP-CANDLE/candle_lib@develop

**Example usuage without container (running DrugCell)***

Preprocess (optional)

bash preprocess.sh  $CUDA_VISIBLE_DEVICES $CANDLE_DATA_DIR

Training

bash train.sh $CUDA_VISIBLE_DEVICES $CANDLE_DATA_DIR

Testing

bash infer.sh $CUDA_VISIBLE_DEVICES $CANDLE_DATA_DIR

Using pip [RECOMMENDED]

pip install --upgrade pip
python3 -m pip install torch==1.12.1+cu113 torchvision==0.13.1+cu113 torchaudio==0.12.1 torchmetrics==0.11.1 --extra-index-url https://download.pytorch.org/whl/cu113
python3 -m pip install networkx
python3 -m pip install git+https://github.com/ECP-CANDLE/candle_lib@develop
git clone -b develop https://github.com/JDACS4C-IMPROVE/DrugCell.git
cd DrugCell
python3 -m pip install -r requirements.txt
chmod a+x *.sh
chmod a+x *.py
sh train.sh 1 data

Example usage with container

Model definition file 'DrugCell.def' is located in here

git clone -b develop https://github.com/JDACS4C-IMPROVE/Singularity.git
cd Singularity

Build Singularity

singularity build --fakeroot DrugCell.sif definitions/DrugCell.def

Execute with container

singularity exec --nv DrugCell.sif train.sh $CUDA_VISIBLE_DEVICES $CANDLE_DATA_DIR

AUTHORS NOTES:

DrugCell release v1.0

DrugCell v1.0 was trained using (cell line, drug) pairs, but it can be generalized to estimate response of any cells to any drugs if:

  1. The feature vector of cell is built as a binary vector representing mutational status of 3,008 genes (the list of index and name of the genes is provided in gene2ind.txt).
  2. The feature vector of drug is encoded into a binary vector of length 2,048 using Morgan Fingerprint (radius = 2). We also provide the pre-computed feature vectors for 684 drugs in our training data (drug2fingerprint.txt).

Pre-trained DrugCell v1.0 model and the drug response data for 509,294 (cell line, drug) pairs used to train the model is shared in http://drugcell.ucsd.edu/downloads.

Required input files:

  1. Cell feature files: gene2ind.txt, cell2ind.txt, cell2mutation.txt
    • gene2ind.txt: make sure you are using gene2ind.txt file provided in this repository.
    • cell2ind.txt: a tab-delimited file where the 1st column is index of cells and the 2nd column is the name of cells (genotypes).
    • cell2mutation.txt: a comma-delimited file where each row has 3,008 binary values indicating each gene is mutated (1) or not (0). The column index of each gene should match with those in gene2ind.txt file. The line number should match with the indices of cells in cell2ind.txt file.
  2. Drug feature files: drug2ind, drug2fingerprints
    • drug2ind.txt: a tab-delimited file where the 1st column is index of drug and the 2nd column is identification of each drug (e.g., SMILES representation or name). The identification of drugs should match to those in drug2fingerprint.txt file.
    • drug2fingerprint.txt: a comma-delimited file where each row has 2,048 binary values which would form , when combined, a Morgan Fingerprint representation of each drug. The line number of should match with the indices of drugs in drug2ind.txt file.
  3. Test data file: _drugcelltest.txt
    • A tab-delimited file containing all data points that you want to estimate drug response for. The 1st column is identification of cells (genotypes) and the 2nd column is identification of drugs.

To load a pre-trained model used for analyses in our manuscript and make prediction for (cell, drug) pairs of your interest, execute the following:

  1. Make sure you have gene2ind.txt, cell2ind.txt, cell2mutation.txt, drug2ind.txt, drug2fingerprint.txt, and your file containing test data in proper format (examples are provided in data and sample folder)

  2. Cell feature files: gene2ind.txt, cell2ind.txt, cell2mutation.txt

    • A detailed description about the contents of the files is given in DrugCell release v1.0 section.

  3. Drug feature files: drug2ind.txt, drug2fingerprints.txt

    • A detailed description about the contents of the files is given in DrugCell release v1.0 section.

  4. Training data file: _drugcelltrain.txt

    • A tab-delimited file containing all data points that you want to use to train the model. The 1st column is identification of cells (genotypes), the 2nd column is identification of drugs and the 3rd column is an observed drug response in a floating number. The current version of the DrugCell code utilizes a loss function better suited for a regression problem (Minimum Squared Error; MSE), and we recommend using the code to train a regressor rather a classifier.

  5. Validation data file: _drugcellval.txt

    • A tab-delimited file that in the same format as the training data. DrugCell training script would evaluate the model trained in each iteration using the data contained in this file. The performance of the model on the validation data may be used as an early termination condition.

  6. Ontology (hierarchy) file: _drugcellont.txt

    • A tab-delimited file that contains the ontology (hierarchy) that defines the structure of a branch of a DrugCell model that encodes the genotypes. The first column is always a term (subsystem or pathway), and the second column is a term or a gene. The third column should be set to "default" when the line represents a link between terms, "gene" when the line represents an annotation link between a term and a gene. The following is an example describing a sample hierarchy.

     GO:0045834 GO:0045923  default
 GO:0045834 GO:0043552  default
 GO:0045923 AKT2    gene
 GO:0045923 IL1B    gene
 GO:0043552 PIK3R4  gene
 GO:0043552 SRC gene
 GO:0043552 FLT1    gene
    • Example of the file (_drugcellont.txt) is provided in data folder.

There are a few optional parameters that you can provide in addition to the input files:

  1. -model: a name of directory where you want to store the trained models. The default is set to "MODEL" in the current working directory.

  2. _-genotypehiddens: a number of neurons to assign each subsystem in the hierarchy. The default is set to 6.

  3. _-drughiddens: a string listing the number of neurons for the drug-encoding branch of DrugCell. The number should be delimited by comma. The default value is "100,50,6", and with the default option, the drug branch of the resulting DrugCell model will be a fully-connected neural network with 3 layers consisting of 100, 50, and 6 neurons.

  4. _-finalhiddens: the number of neurons in the top layer of DrugCell that combines the genotype-encoding and the drug-encoding branches. The default is 6.

  5. -epoch: the number of epoch to run during the training phase. The default is set to 300.

  6. -batchsize: the size of each batch to process at a time. The deafult is set to 5000. You may increase this number to speed up the training process within the memory capacity of your GPU server.

  7. -cuda: the ID of GPU unit that you want to use for the model training. The default setting is to use GPU 0.

Finally, to train a DrugCell model, execute a command line similar to the example provided in _sample/commandlinecuda.sh:

Example data files in sample directory

There are three subsets of our training data provided as toy example: drugcell_train.txt, drugcell_test.txt and drugcell_val.txt have 10,000, 1,000, and 1,000 (cell line, drug) pairs along with the corresponding drug response (area under the dose-response curve).