PERCEPTION-shiny

From single-cell transcriptomics to precision oncology.

PERCEPTION (PERsonalized single-Cell Expression-based Planning for Treatments In ONcology) predicts patient response and resistance to cancer treatment using single-cell expression profiles. It trains elastic-net models on DepMap cell-line data, then applies them to patient single-cell data for clone-level drug sensitivity and patient-level response stratification.

Tutorial
15K+
DepMap Genes
Single-Cell
Resolution
44
Pretrained Drug Models

Pipeline — Where You Are

Status updates live as you load data, train and predict. Click any step to jump to it.

1
Load Data
Start here
2
Train
Pending
3
Predict
Pending
4
Visualize
Pending
Start: load data — or click Load Demo to try the whole pipeline instantly.

Data Status

Real-time overview of loaded data.

DepMap Reference
Not loaded
Expression Matrix
Not loaded
Clone Map (Seurat)
Not loaded
Clinical Response
Not loaded
Drug Models
Not loaded
Predictions
Not loaded

Key Features

DepMap Integration

Seamlessly load and cache DepMap cell line expression and drug response data for model training.

Elastic Net & Random Forest

Train drug response models using glmnet (elastic net) or random forest with cross-validated hyperparameter tuning.

Clone-Level Prediction

Predict drug sensitivity at single-cell clone resolution, then aggregate to patient-level response.

Rich Visualization

Generate UMAP plots, clone distribution stacks, ROC curves, and comprehensive patient response panels.

Citation & Repository

Original Paper

Sinha, S., Vegesna, R., Mukherjee, S. et al. PERCEPTION predicts patient response and resistance to treatment using single-cell transcriptomics of their tumors. Nat Cancer 5, 938-952 (2024).
DOI: 10.1038/s43018-024-00756-7

Original Codebase

github.com/ruppinlab/PERCEPTION (original Python implementation by Sinha et al.)

R Package Repository

github.com/WangLabCSU/PERCEPTIONx
Install with: remotes::install_github('WangLabCSU/PERCEPTIONx')

Upload Your Data

Try it out! Click the button below to load demo data (49 genes × 400 cells, 20 patients) and explore all features without uploading anything.
Expression Matrix

Single-cell expression matrix (genes × cells). Raw counts or normalized values. CSV / TSV / TXT / Excel / RDS format.

Header is auto-detected as the first row with ≥2 columns (gene / cell names); single-field title/comment rows above it are skipped. Avoid a multi-column title row above the header.

Format: rows = genes, columns = cells 
CELL_001  CELL_002  CELL_003
TP53      2.1       0.0       5.3
BRCA1     0.0       1.8       3.2
EGFR      4.7       2.1       0.0
Patient-Cell Mapping

File with columns: cell_id and patient_id (case-insensitive). Maps each cell (or clone) to its patient. In Clone-level mode the data is auto-prepared without clustering. CSV / TSV / TXT / Excel / RDS.

Header is auto-detected as the first row with ≥2 columns (cell_id / patient_id); single-field title/comment rows above it are skipped.

Format: cell_id + patient_id 
cell_id    patient_id
CELL_001   PAT_001
CELL_002   PAT_001
CELL_003   PAT_002
Format: cell_id + patient_id + count 
cell_id       patient_id   count
CLONE_001     PAT_001      450
CLONE_002     PAT_001      50
CLONE_003     PAT_002      300
count = real cell number per clone; proportions are then shown accurately. Without it, clone proportions fall back to equal (1/n).
Clinical Response

Patient response data for evaluation. File with columns: patient, response (Responder/Non-responder, case-insensitive). CSV / TSV / TXT / Excel / RDS.

Header is auto-detected as the first row with ≥2 columns (patient / response); single-field title/comment rows above it are skipped.

Format: patient + response 
patient    response
PAT_001    Responder
PAT_002    Non-responder
PAT_003    Responder
Clone Detection & Preprocessing

Run Seurat clustering to automatically detect transcriptional subclones, compute clone-level mean expression, rank-normalize the data, and build the clone abundance table required for prediction.

Method : UMAP (default) preserves global structure and is faster with large datasets; t-SNE emphasizes fine local neighborhoods and may reveal finer substructure at the cost of speed.
Resolution controls clustering granularity. Higher values produce more clones (finer subclones); lower values produce fewer, broader clones. Default 0.8 suits most datasets.
PCA Dims sets the number of principal components used for clustering. Higher values capture more biological signal but may include noise. Default 10 is standard for scRNA-seq.

Requires Expression Matrix and Patient-Cell Mapping loaded first. By default Seurat clusters cells into subclones.
Choose "Clone-level" in the Expression Matrix card to skip clustering. The data is then prepared automatically after upload.

Data Preview

Data Overview & Preview

Data Management

DepMap Data

Load DepMap reference datasets including bulk expression, single-cell expression, drug response (AUC), and cell line annotations. This is a filtered version derived from the original DepMap release used in the PERCEPTION article, with unused tables and objects removed for efficiency.

To download manually, visit GitHub Release .
Or load a pre-downloaded DepMap.RDS:
Pre-trained Models

Load pre-trained drug response models from the PERCEPTIONx GitHub Release repository. 44 models are available, each trained on DepMap bulk expression with Elastic Net regression and 3-fold cross-validation. Models are cached locally after first download.

To download manually, visit GitHub Release .
Or load a pre-downloaded model .RDS:
Loaded Models Management Active Inactive

Model Training

Train drug response models on DepMap bulk expression data. Models are built using elastic net (glmnet) or random forest with cross-validated hyperparameter tuning. Each candidate is validated on held-out bulk, pseudo-bulk, and single-cell expression; the best configuration is selected by single-cell validation performance.
Parameters
Drug & Cancer Type
Genes of Interest
Leave empty to use all genes from DepMap data (recommended for most users). Or enter specific gene symbols to restrict feature selection to a subset.
Model Configuration
Maximum 4 cores — hard cap for shared-server safety.
Training Results

Drug Response Prediction

Predict drug sensitivity at clone level using trained models, then aggregate to patient-level response using weighted averaging strategies. Viability semantics: higher viability = more resistant (less sensitive); lower viability = more sensitive (stronger drug killing).
Configuration
Sources
Prediction runs on the active models from the Data tab (Loaded Models Management) and the expression data prepared there. Load, upload or train models on the Data / Train tabs - every uploaded .RDS appears in the management list automatically.
Patient Aggregation
weighted_max : maximum clone viability weighted by clone proportion (recommended)
weighted_average : weighted average across all clones
min/max : most sensitive/resistant clone
Clone-Level Predictions
Predicted viability of every clone per drug (higher = more resistant).
Select model & expression sources, then click Run Prediction .
Patient-Level Predictions
Clone viabilities aggregated per patient (weighted_max).
Appears here after running prediction.

Visualization

Plot Gallery
Grey = required data not loaded yet.
Output
Width (%)
Height (%)
DPI (100-1200)

Reference Documentation

Detailed reference for data formats, parameters, and interpretation.
Sections
Guided Walkthroughs

New to the app? Pick a tour below. It opens as an interactive slideshow in the center of the screen.

Try the demo ~1 minute · no files needed

Load the built-in demo data, run the predictions, then draw and export the plots - nothing to upload or train.

Analyze your own data ~2 minutes · uploads required

Walk through uploading expression / mapping / response files, (optional) training, prediction and how to read the plots.

Detailed reference for every parameter and format sits in the sections below.

Supported Drugs

Find a compound, see if a model is ready, or train it yourself

This is the drug screen shipped with our DepMap data (PRISM): 1448 compounds , most of them research tool molecules rather than clinical drugs. The 44 pre-trained ones are clinically relevant and come with ready-made models. Any other compound can be trained on the Train tab once DepMap is loaded.

compound in the DepMap screen pre-trained demo
Data Requirements

What data you need and how to prepare it

DepMap Data

Downloaded and loaded via the Download & Load button on the Data tab (or a pre-downloaded .RDS upload). Includes bulk expression, single-cell expression, and drug response (AUC) data from DepMap.

Manual load
Expression Matrix

A gene x cell single-cell expression matrix. Raw counts or normalized values. Rank normalization is applied automatically during Seurat clustering.

User upload
Patient-Cell Mapping

File with columns: cell_id and patient_id (case-insensitive). Maps each cell to its patient. Clones are auto-detected via Seurat clustering. Accepts CSV / TSV / TXT / Excel / RDS.

User upload
Clinical Response

(Optional) File with columns: patient , response (Responder/Non-responder, case-insensitive). Required for ROC curves and boxplots. Accepts CSV / TSV / TXT / Excel / RDS.

Optional
Training Parameters

Configure your model training

Drug Name

Must match a drug in DepMap secondary_prism data (e.g. abemaciclib, erlotinib). Use the dropdown on the Data tab for the full list of 44 supported drugs.

Cancer Type

Filter cell lines by cancer type. Use PanCan for all cancer types, or specify e.g. Breast , Lung .

Exclude Cancer

Exclude specific cancer types from training. Set to PanCan to exclude none.

Genes of Interest

Gene symbols for feature selection. Leave empty to use all genes from DepMap (~15K). Should overlap with your scRNA data for prediction.

k_features

Number of top-ranked features (by Pearson correlation) to use. Default: 100. Higher = more features but slower.

Model Type

glmnet (elastic net, recommended) with 3-fold CV, or rf (random forest).

Patient Aggregation Modes

How clone-level predictions become patient-level

weighted_max Recommended

Weighted maximum across clones, emphasizing the most resistant clones (recommended).

weighted_average

Weighted average across all clones, weighted by clone proportion.

min

Takes the most sensitive clone's prediction (lowest viability, pessimistic).

max

Takes the most resistant clone's prediction (highest viability, optimistic).

Visualization Guide

Available plot types and their data requirements

Clone Distribution

Stacked bar chart showing clone proportions per patient.

Needs: Clones
Clone Viability Lollipop

Lollipop chart of predicted viability per clone.

Needs: Predictions + Clones
ROC Curve

Receiver Operating Characteristic curve for response prediction.

Needs: Patient Pred + Response
Response Boxplot

Boxplot comparing predicted viability between responders and non-responders.

Needs: Patient Pred + Response
Clone Identity

2D embedding (UMAP/t-SNE) colored by clone membership.

Needs: Clones + Embedding
Drug Viability

2D embedding (UMAP/t-SNE) colored by predicted drug viability.

Needs: Predictions + Embedding
Gene Expression

2D embedding (UMAP/t-SNE) colored by selected gene expression.

Needs: Predictions + Expression + Embedding
Frequently Asked Questions

Common questions and answers

How long does training take?
Training a single drug model typically takes 30 seconds to 5 minutes depending on the number of features and cores used. Using all genes (~15K) with k_features=100 is the default and works well.
Can I use my own bulk expression data?
Currently, PERCEPTIONx trains on DepMap data. You can use the trained model to predict on your own single-cell data after rank normalization.
What if my gene names don't match?
Gene symbols must match between training and prediction data. The app automatically intersects genes between DepMap and your expression matrix. Check for hyphen vs dot formatting (e.g. BRCA1 vs BRCA.1 ).
How do I preprocess my data?
Use rank_normalization_mat() to rank-normalize your expression matrix. This is the same preprocessing applied to DepMap data.
Should I specify Genes of Interest?
Leave it empty to use all ~15K genes from DepMap (recommended for most users). Specify a subset only if you want to restrict feature selection to known biomarkers.
Download fails for DepMap or models?
Enable the Mirror checkbox (default ON) to use mirror download. If still failing, download the files manually from GitHub Releases and use the file upload option.
Why doesn't the interface freeze during training / clustering / prediction?
All heavy computation (model training, Seurat clustering, prediction, plot math) runs in background worker processes , not in the interface. The UI polls and shows progress, so other pages stay responsive. If a worker ever stops unexpectedly, the app shows "Background worker stopped" instead of spinning forever — just submit again.
Citation

If you use this package, please cite both the package and the original PERCEPTION study:

Jia Ding. PERCEPTIONx: Personalized Drug Response Prediction from Single-Cell Transcriptomics. R package version 0.3.0 . https://github.com/WangLabCSU/PERCEPTIONx

Sinha, S., Vegesna, R., Mukherjee, S. et al. PERCEPTION predicts patient response and resistance to treatment using single-cell transcriptomics of their tumors. Nat Cancer 5, 938-952 (2024). DOI: 10.1038/s43018-024-00756-7