SCRIPT

Single-cell Cis-regulatory Relationship Identifier based on Pre-Trained graph attention networks

Overview

Single-cell cis-regulatory relationships (CRRs) are essential for understanding the pathogenic mechanisms of disease-associated non-coding variants. Existing computational methods underperform in predicting single-cell CRRs due to overlooking causal biological principles and large-scale single-cell data. Here, we present SCRIPT (Single-cell *Cis-*regulatory Relationship Identifier based on Pre-Trained graph attention networks) that infers single-cell CRRs from transcriptomic and chromatin accessibility data. SCRIPT incorporates two key innovations: graph causal attention networks supported by empirical CRR evidence, and representation learning enhanced through pretraining on atlas-scale single-cell chromatin accessibility data. SCRIPT significantly outperforms state-of-the-art methods, achieving a mean AUC of 0.9 and a threefold improvement in predicting long-range CRRs (>100Kb). Applying SCRIPT to Alzheimer’s disease and schizophrenia, we establish a framework for prioritizing disease-causing variants and elucidating their functional effects in a cell-type-specific manner. By uncovering molecular genetic mechanisms undetected by existing computational methods, SCRIPT provides a roadmap for advancing genetic diagnosis and target discovery.

Installation

We recommend installing SCRIPT within a virtual environment. For Conda, use the following command to create and activate a dedicated environment:

conda create -n script python=3.10.6 && source activate script

Next, install the required dependencies with:

pip install torch==2.2.1 torchvision==0.17.1 torchaudio==2.2.1 --index-url https://download.pytorch.org/whl/cu121
pip install dgl -f https://data.dgl.ai/wheels/torch-2.2/cu121/repo.html
pip install -r requirements.txt

To extract the compressed files needed for the model:

gzip -d ./data/PO.txt.gz

Tutorial

Running SCRIPT in One Command

To run SCRIPT in a single command, use:

python main.py --file_atac ./example_data/input_data/example_scatac.h5ad --file_rna ./example_data/input_data/example_scrna.h5ad

By default, temporary files generated during the model run are stored in ./temp_path, and the result files are saved in ./res_path.

Users can also specify custom storage paths for the temporary files and result files:

python main.py --file_atac ./example_data/input_data/example_scatac.h5ad --file_rna ./example_data/input_data/example_scrna.h5ad --path_out ./res_path --path_tmp ./temp_path

Running SCRIPT in Separate Steps

The usage of SCRIPT contains three steps.

The first step is generation of training data. Users need to provide a pair of scATAC-seq and scRNA-seq datasets. The two datasets are from the same tissue, and their cell types need to be aligned.

You can run the following code to perform the first step:

python generate_training_data.py --file_atac ./example_data/input_data/example_scatac.h5ad --file_rna ./example_data/input_data/example_scrna.h5ad --path_out ./temp_path/output_data

The second step is the simulation of cis-transcriptional regulation. Users need to input the training data generated by the first step.

You can run the following code to perform the second step:

python transcription_simulation.py --path_in ./example_data/output_data --folder_ckpt ./temp_path/simulation_model

The third step is the calculation of single-cell regulation scores by attribution method. Users need to input the training data generated by the first step, the configures and paremeters of the simulation model trained in the second step.

You can run the following code to perform the third step:

python attribution.py --path_in ./temp_path/output_data --path_out ./res_path --config_simulation ./temp_path/simulation_model/args.pkl --model_simulation ../temp_path/simulation_model/best_model.pt

Single-cell regulation scores are saved in the '"./res_path" folder.