Package: gene-outlier-detection
N-of-1 Gene Outlier DetectionFor RNA-seq Expression DataThis package identifies outliers for gene expression data by building a consensus distribution from background datasets that are informed by an N-of-1 sample.
SeeModel Explanationfor more information, our paper inJCO, or ourpreprint.The model has undergone significant speed improvements and is no longer identical the model in the paper, but produces results that are essentially identical. Another benefit is the prior hyperparameters for each gene/dataset combination are now directly shared in the model whereas before they were approximated due to runtime.This workflow takes gene expression data as input and outputs the following:SAMPLE_UUID
├── _info
│   ├── _gelman-rubin.tsv
│   ├── _pearson_correlations.txt
│   ├── _pval_runs.tsv
│   └── _run_info.tsv
├── model.pkl
├── pvals.tsv
├── ranks.tsv
├── traceplot.png
├── weights.png
└── weights.tsvThe_infosubdirectory contains secondary information about the model run_gelman-rubin.tsv- TSV ofGelman-Rubin diagnosticfor every model parameter, including a median across parameters which should be about ~1.0._pearson_correlations.txt- Single column list of the Pearson correlation of gene p-values between runs (unless-dis provided)_pval_runs.tsv- Table of gene p-values as background datasets are added_run_info.tsv- TSV of software parameters for reproducibility and model runtimemodel.pkl— A python pickle of thePyMC3modelandtrace. Model must be run with--save-modelflag and can be retrieved viaimportpicklewithopen(pkl_path,'rb')asbuff:data=pickle.load(buff)model,trace=data['model'],data['trace']pvals.tsv— P-values for all genes the model was trained onranks.tsv— The median rank of all groups as measured by pairwise euclidean distancetraceplot.png— Traceplot from PyMC3 linear model coefficients and model errorweights.png— Boxplot of model weights for all background datasetsweights.tsv— Mean and SD of model weights as related to background datasetsQuickstartInstallpipinstall--pregene-outlier-detectionDownload the prerequisiteinputsRun the modeloutlier-detection--sample/data/tumor.hd5\--background/data/gtex.hd5\--nameTCGA-OR-A5KV-01\--gene-list/data/drug-genes.txt\--col-skip5Dependencies and InstallationThis workflow has been tested on ubuntu 18.04 and Mac OSX, but should also run on other unix based systems or under an Anaconda installation.Python 3.6Dockerif using the Docker version or Toil workflow versionHDF5 library (if inputs are in HDF5 format)conda install -c anaconda hdf5C++ / GCC compiler for PyMC3's TheanoYou have a couple optionsconda install theanoapt-get update && apt-get install -y libhdf5-serial-dev build-essential gccYoumayneed to modify your~/.theanorcto support larger bracket depth for this model.[gcc]
cxxflags = -fbracket-depth=1024Model ExplanationIn the following plate notation, G stands for Gene, and D stands for Dataset (background dataset).The core of our method is a Bayesian statistical model for the N-of-1 sample’s gene expression.
The model implicitly assumes that the sample’s gene expression can be approximated by a
convex mixture of the gene expression of the background datasets. The coefficients of this
mixture are shared across genes, much like a linear model in which each data point is the
vector of expressions for a gene across the background datasets. In addition, we model
expression for each gene from each background dataset as a random variable itself. This allows
us to incorporate statistical uncertainty from certain background sets’ small sample size directly
in the model without drowning out any background set’s contribution through poolingThe model can be explored using Markov chain Monte Carlo (MCMC) to obtain samples
fory(per gene) that approximate its posterior distribution. If we have an observed expression value for a
gene of interest (from the N-of-1 cancer sample), we can compare it to the sampled values. The
proportion of sampled values forythat are greater (or lesser) than the observed value is an
estimate of the posterior predictive p-value for this expression value. The posterior predictive
p-value can be seen as a measure of how much of an outlier the expression is given the
expectations of the comparison setThis model has been drastically improved for speed by leveraging PyMC3's vectorization
approach and replacing the problematic student-T sampling with a Normal distribution.
Another benefit is there is no longer any computational "hack" of pre-fitting the
student-T distributions as the expression values in the background are directly shared
between two R.V.s that model expression for each gene/dataset combination.
A graph of the new model, for 125 genes and 3 datasets with 48,500 values in the
background dataset is shown below:Defining InputsThe model requires twoSamplebyGenematrices, one containing the N-of-1 sample and one containing samples to use as the background comparison set.
Theyshouldboth contain the same set of genes and the background dataset must contain at least one metadata column with labels that differentiate groups (e.g. tissue, subtype, experiment, etc). Metadata columns need to be theleft-mostcolumns in the dataframe followed by all genes. This allows a simple heuristic (--col-skip) to designate where the genes start without needing the user to provide an additional input file.Here,tissueis one group that is used to differentiate the samples. We would run with--col-skip=5as there are 5 metadata columns before the start of the genes.Docker ContainerA Docker container containing the program can be executed as follows:dockerrun--rm-v$(pwd):/datajvivian/gene-outlier-detection\outlier-model\--sample/data/inputs/tumor.hd5\--background/data/inputs/gtex.hd5\--name=TCGA-OR-A5KV-01\--gene-list/data/inputs/drug-genes.txt\--out-dir/data/outputs/\--col-skip=5ArgumentsExplanation of arguments used when running the program.--sampleA path to the matrix (.tsv / .hd5) that contains the sample.--backgroundA path to the matrix that contains the background datasets and at least one column at the beginning used as the label vector for different groups in the background.--nameName of row in the sample matrix that corresponds to the desired sample to run.--out-dirOutput directory--gene-listSingle column file of genes for the model to train on and calcluate p-values for. After ~100-200 genes, it is better to split the genes into batches and run in parallel.--col-skipNumber of metadata columns to skip in background matrix. All columns after this number of columns should be genes with expression values.--groupName of the categorical column vector in the background matrix which distinguishes the different background datasets.--num-backgroundsMaximum number of background categorical groups to include in the model training. Model will run, starting with one background dataset, and iteratively adding more until the p-values converge ornum-backgroundsis met.--max-genesMaximum number of genes to run. I.e. if a gene list is provided, how many additional genes using ANOVA. Useful for improving beta coefficients if gene list does not contain enough tissue-specific genes. It is recommended to run the model withmax-genesset to a minimum of 10-20 more genes than exist in the--gene-list.--pval-convergence-cutoffP-value Pearson correlation cutoff to stop adding additional background datasets.--num-training-genesgiIf gene-list is empty, will use ANOVA to choose gene set. Not typically useful outside of testing.--tuneNumber of tuning steps to start MCMC sampling process. Default is 500, but 750 or 1,000 may be useful in circumstances where the model is having difficulty converging.--disable-iterThis flag disables iterative runs and runs one model with--num-backgrounds.--save-modelThis flag will save a serialized version of the model/trace. Useful for debugging or inspection of all model parameters.Toil-version of WorkflowAToilversion of the workflow is availablehere. This allows the model to be run on multiple samples at scale on a cluster or cloud computing cluster, but requires Python 2.7 andpip install pandas toil==3.19.0Toil is now Python 3 compliant, so this method of running the program isn't recommended until the Toil code has been updated.CitationIf you leverage this method in your research, please cite ourJCOpaper.Vivian, John, et al. "Bayesian Framework for Detecting 
Gene Expression Outliers in Individual Samples." 
JCO Clinical Cancer Informatics 4 (2020): 160-170.