README Template
This document provides a structured template for creating a README file for IMPROVE models. Following this template ensures that your model repository is well-documented and easily accessible to researchers and developers.
Below is a standardized example README for a GraphDRP model. Replace placeholders with your model-specific details.
# GraphDRP
This repository demonstrates how to use the [IMPROVE library v0.1.0](https://jdacs4c-improve.github.io/docs/v0.1.0-alpha/) for building a drug response prediction (DRP) model using GraphDRP, and provides examples with the benchmark [cross-study analysis (CSA) dataset](https://web.cels.anl.gov/projects/IMPROVE_FTP/candle/public/improve/benchmarks/single_drug_drp/benchmark-data-pilot1/csa_data/).
This version, tagged as `v0.1.0-2024-09-27`, introduces a new API which is designed to encourage broader adoption of IMPROVE and its curated models by the research community.
## Dependencies
Installation instructions are detialed below in [Step-by-step instructions](#step-by-step-instructions).
Conda `yml` file [conda_wo_candle.yml](./conda_wo_candle.yml)
ML framework:
+ [Torch](https://pytorch.org/) - deep learning framework for building the prediction model
+ [Pytorch_geometric](https://github.com/rusty1s/pytorch_geometric) - graph neural networks (GNN)
IMPROVE dependencies:
+ [IMPROVE tag v0.1.0-2024-09-27](https://github.com/JDACS4C-IMPROVE/IMPROVE/tree/v0.1.0-2024-09-27)
## Dataset
Benchmark data for cross-study analysis (CSA) can be downloaded from this [site](https://web.cels.anl.gov/projects/IMPROVE_FTP/candle/public/improve/benchmarks/single_drug_drp/benchmark-data-pilot1/csa_data/).
The data tree is shown below:
```
csa_data/raw_data/
├── splits
│ ├── CCLE_all.txt
│ ├── CCLE_split_0_test.txt
│ ├── CCLE_split_0_train.txt
│ ├── CCLE_split_0_val.txt
│ ├── CCLE_split_1_test.txt
│ ├── CCLE_split_1_train.txt
│ ├── CCLE_split_1_val.txt
│ ├── ...
│ ├── GDSCv2_split_9_test.txt
│ ├── GDSCv2_split_9_train.txt
│ └── GDSCv2_split_9_val.txt
├── x_data
│ ├── cancer_copy_number.tsv
│ ├── cancer_discretized_copy_number.tsv
│ ├── cancer_DNA_methylation.tsv
│ ├── cancer_gene_expression.tsv
│ ├── cancer_miRNA_expression.tsv
│ ├── cancer_mutation_count.tsv
│ ├── cancer_mutation_long_format.tsv
│ ├── cancer_mutation.parquet
│ ├── cancer_RPPA.tsv
│ ├── drug_ecfp4_nbits512.tsv
│ ├── drug_info.tsv
│ ├── drug_mordred_descriptor.tsv
│ └── drug_SMILES.tsv
└── y_data
└── response.tsv
```
Note that `./_original_data` contains data files that were used to train and evaluate the GraphDRP for the original paper.
## Model scripts and parameter file
+ `graphdrp_preprocess_improve.py` - takes benchmark data files and transforms into files for trianing and inference
+ `graphdrp_train_improve.py` - trains the GraphDRP model
+ `graphdrp_infer_improve.py` - runs inference with the trained GraphDRP model
+ `model_params_def.py` - definitions of parameters that are specific to the model
+ `graphdrp_params.txt` - default parameter file (parameter values specified in this file override the defaults)
# Step-by-step instructions
### 1. Clone the model repository and checkout the branch (or tag)
```bash
git clone git@github.com:JDACS4C-IMPROVE/GraphDRP.git
cd GraphDRP
git checkout v0.1.0-2024-09-27
```
### 2. Set computational environment
Option 1: create conda env using `yml`
```bash
conda env create -f conda_env.yml
```
Option 2: use [conda_env_py37.sh](./conda_env_py37.sh)
### 3. Run `setup_improve.sh`.
```bash
source setup_improve.sh
```
This will:
1. Download cross-study analysis (CSA) benchmark data into `./csa_data/`.
2. Clone IMPROVE repo (and checkout `v0.1.0-2024-09-27`) outside the GraphDRP model repo
3. Set up `PYTHONPATH` (adds IMPROVE repo).
### 4. Preprocess CSA benchmark data (_raw data_) to construct model input data (_ML data_)
```bash
python graphdrp_preprocess_improve.py --input_dir ./csa_data/raw_data --output_dir exp_result
```
Preprocesses the CSA data and creates train, validation (val), and test datasets.
Generates:
* three model input data files: `train_data.pt`, `val_data.pt`, `test_data.pt`
* three tabular data files, each containing the drug response values (i.e. AUC) and corresponding metadata: `train_y_data.csv`, `val_y_data.csv`, `test_y_data.csv`
```
exp_result
├── param_log_file.txt
├── processed
│ ├── test_data.pt
│ ├── train_data.pt
│ └── val_data.pt
├── test_y_data.csv
├── train_y_data.csv
├── val_y_data.csv
└── x_data_gene_expression_scaler.gz
```
### 5. Train GraphDRP model
```bash
python graphdrp_train_improve.py --input_dir exp_result --output_dir exp_result
```
Trains GraphDRP using the model input data: `train_data.pt` (training), `val_data.pt` (for early stopping).
Generates:
* trained model: `model.pt`
* predictions on val data (tabular data): `val_y_data_predicted.csv`
* prediction performance scores on val data: `val_scores.json`
```
exp_result
├── history.csv
├── model.pt
├── param_log_file.txt
├── processed
│ ├── test_data.pt
│ ├── train_data.pt
│ └── val_data.pt
├── test_y_data.csv
├── train_y_data.csv
├── val_scores.json
├── val_y_data.csv
├── val_y_data_predicted.csv
└── x_data_gene_expression_scaler.gz
```
### 6. Run inference on test data with the trained model
```bash
python graphdrp_infer_improve.py --input_data_dir exp_result --input_model_dir exp_result --output_dir exp_result --calc_infer_score true
```
Evaluates the performance on a test dataset with the trained model.
Generates:
* predictions on test data (tabular data): `test_y_data_predicted.csv`
* prediction performance scores on test data: `test_scores.json`
```
exp_result
├── history.csv
├── model.pt
├── param_log_file.txt
├── processed
│ ├── test_data.pt
│ ├── train_data.pt
│ └── val_data.pt
├── test_scores.json
├── test_y_data.csv
├── test_y_data_predicted.csv
├── train_y_data.csv
├── val_scores.json
├── val_y_data.csv
├── val_y_data_predicted.csv
└── x_data_gene_expression_scaler.gz
```