IMU KRT classifier

An ML-based classifier designed for classifying HPV(+) HNSCC subtypes with gene expression data. This classifier is trained by five different ML algorithms (random forest, k-nearest neighbors, naive bayes, SVM, and elastic-net logistic regression) and the subtype result is decided by a majority vote (Ensemble).

Quickstart

Once the environment is set up (see Installation), the end-to-end demo runs in three commands from the repo root:

# 1. Activate the environment
conda activate IMUKRTclassifier

# 2. Preprocess raw counts -> log2CPM matrix (no batch correction, demo data)
Rscript ./R_script/preprocessing.R \
    ./demo_data/all_samples_2536.count 0 not NULL 0 ./demo_data/ ./R_script/

# 3. Run the classifier on the log2CPM matrix
python3 ./python_script/IMU_KRT_classifier.py \
    -dir ./python_script \
    -PCA 1 \
    -log2cpmmatrix ./demo_data/all_samples_2536_logcpm.csv \
    -output_dir ./

If you already have a log2CPM matrix, skip step 2 and go straight to step 3. See the sections below for argument details and batch-effect options.

environment requirements:

classifier:

python 3.8
sklearn 1.2.2
pandas 1.3.4
numpy 1.19.2
seaborn 0.9.0

preprocessing:

R 4.0
edgeR
org.Hs.eg.db
RUVSeq
sva
ggplot2
data.table rjson
HGNChelper 0.8.1
dplyr 1.0.9

installation

make sure R is available and we provide a conda yml file for linux-based system.

conda install -n IMUKRTclassifier --file install_and_logic/IMUKRT_environment.yml

conda activate IMUKRTclassifier

R preprocessing part

The R preprocessing can assist user to generate the log2cpmmatrix, user can input either comma or tab separate raw count file, in the meanwhile, they can choose to remove batch effect for genes' raw count (i.e. FFPE samples which perplexed by RNA degradation). The gene column can be entrez gene id, gene symbol or ensemble gene id. The batch effect removal is implemented by combat, if you choose combat, you can provide your own meta file with batch effect you want to remove within your own samples. We highly recommend you include our FF 18 samples since it can be used as an evaluation for the classifier results.

script arguments:

usage: fileinput[absolute path],cpmornot[0,1],batchremovalornot (best provide raw count) [combat,not],batch_effect_file [either input a NULL or a directory to files store batcheffect],includeFF18ornot[0,1],output_directory[absolute path] directory_save_needed_file[absolute path]

example usage:

user input count without any batch effect batch_effect_removal

Rscript ./R_script/preprocessing.R ./demo_data/all_samples_2536.count 0 not NULL 0 ./demo_data/ ./R_script/

user provide their meta to remove batch effect but not include our FF samples

Rscript ./R_script/preprocessing.R ./demo_data/all_samples_2536.count 0 combat ./demo_data/2536_count.meta 0 ./demo_data/ ./R_script/

python classifier part

input:

A log2cpm matrix csv file row as genes and column as samples. Can be generated from preprocessing

output:

A heatmap of representative genes, PCA plots with predicted results colored, table with sample ID and predicted results and majority vote results.

example usage:

python3 ./python_script/IMU_KRT_classifier.py -dir ./python_script -PCA 1 -log2cpmmatrix ./demo_data/all_samples_2536_logcpm.csv -output_dir ./

more detailed arguments information is available by checking:

python3 IMU_KRT_classifier.py --help

The web version and code for this classifier is available at:

https://github.com/psnehal/IMUKRTclassifierDjango

https://hpv-hnscc-subtypeclassifier.dcmb.med.umich.edu/