--- title: "deconvR : Simulation and Deconvolution of Omic Profiles" authors: - name: Irem B. Gunduz, Veronika Ebenal, Altuna Akalin output: BiocStyle::html_document: self_contained: yes toc: true toc_float: true toc_depth: 2 code_folding: show date: "`r Sys.Date()`" package: "`r pkg_ver('deconvR')`" vignette: > %\VignetteIndexEntry{deconvRVignette} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set(tidy = FALSE, cache = FALSE, dev = "png", message = FALSE, error = FALSE, warning = FALSE) BiocStyle::markdown() library(knitr) library(deconvR) library(doParallel) library(dplyr) cl <- parallel::makeCluster(2) doParallel::registerDoParallel(cl) ``` # Introduction Recent studies associated the differences of cell-type proportions may be correlated to certain phenotypes, such as cancer. Therefore, the demand for the development of computational methods to predict cell type proportions increased. Hereby, we developed `deconvR`, a collection of functions designed for analyzing deconvolution of the bulk sample(s) using an atlas of reference omic signature profiles and a user-selected model. We wanted to give users an option to extend their reference atlas. Users can create new reference atlases using `findSignatures` extend their atlas by adding more cell types. Additionally, we included `BSMeth2Probe` to make mapping whole-genome bisulfite sequencing data to their probe IDs easier. So users can map WGBS methylation data (as in **methylKit** or **GRanges** object format) to probe IDs, and the results of this mapping can be used as the bulk samples in the deconvolution. We also included a comprehensive DNA methylation atlas of 25 different cell types to use in the main function `deconvolute`. `deconvolute` allows the user to specify their desired deconvolution model (non-negative least squares regression, support vector regression, quadratic programming, or robust linear regression), and returns a dataframe which contains predicted cell-type proportions of bulk methylation profiles, as well as partial R-squared values for each sample. As an another option, users can generate a simulated table of a desired number of samples, with either user-specified or random origin proportions using `simulateCellMix`. `simulateCellMix` returns a second data frame called `proportions`, which contains the actual cell-type proportions of the simulated sample. It can be used for testing the accuracy of the deconvolution by comparing these actual proportions to the proportions predicted by `deconvolute`. `deconvolute` returns partial R-squares, to check if deconvolution brings advantages on top of the basic bimodal profiles. The reference matrix usually follows a bimodal distribution in the case of methylation, and taking the average of the rows of methylation matrix might give a pretty similar profile to the bulk methylation profile you are trying to deconvolute. If the deconvolution is advantageous, partial R-squared is expect to be high. # Installation The deconvR package can be installed from Bioconductor with: ``` {r eval=FALSE} if (!requireNamespace("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install("deconvR") ``` # Data ## Comprehensive Human Methylome Reference Atlas The comprehensive human methylome reference atlas created by Moss et al. ^[Moss, J. et al. (2018). Comprehensive human cell-type methylation atlas reveals origins of circulating cell-free DNA in health and disease. Nature communications, 9(1), 1-12. ] can be used as the reference atlas parameter for several functions in this package. This atlas was modified to remove duplicate CpG loci before being included in the package as the dataframe. The dataframe is composed of 25 human cell types and roughly 6000 CpG loci, identified by their Illumina Probe ID. For each cell type and CpG locus, a methylation value between 0 and 1 is provided. This value represents the fraction of methylated bases of the CpG locus. The atlas therefore provides a unique methylation pattern for each cell type and can be directly used as `reference` in `deconvolute` and `simulateCellMix`, and `atlas` in `findSignatures`. Below is an example dataframe to illustrate the `atlas` format. ``` {r, message = FALSE, output.lines=10} library(deconvR) data("HumanCellTypeMethAtlas") head(HumanCellTypeMethAtlas[,1:5]) ``` ## Illumina Infinium MethylationEPIC v1.0 B5 Manifest Probes (hg38) The **GRanges** object `IlluminaMethEpicB5ProbeIDs` contains the Illumina probe IDs of 400000 genomic loci (identified using the "seqnames", "ranges", and "strand" values). This object is based off of the Infinium MethylationEPIC v1.0 B5 Manifest data. Unnecessary columns were removed and rows were truncated to reduce file size before converting the file to a **GRanges** object. It can be used directly as `probe_id_locations` in `BSmeth2Probe`. ``` {r, message = FALSE, output.lines=10} data("IlluminaMethEpicB5ProbeIDs") head(IlluminaMethEpicB5ProbeIDs) ``` # Example Workflow For Whole Genome Bisulfate Sequencing Data ## Expanding Reference Atlas As mentioned in the introduction section, users can extend their reference atlas to incorporate new data. Or may combine different reference atlases to construct a more comprehensive one. This can be done using the `findSignatures` function. In this example, since we don't have any additional reference atlas, we will add simulated data as a new cell type to reference atlas for example purposes. First, ensure that `atlas` (the signature matrix to be extended) and `samples` (the new data to be added to the signature matrix) are compliant with the function requirements. Below illustrates the `samples` format. ``` {r, message = FALSE, output.lines=10} samples <- simulateCellMix(3,reference = HumanCellTypeMethAtlas)$simulated head(samples) ``` `sampleMeta` should include all sample names in `samples`, and specify the origins they should be mapped to when added to `atlas`. ``` {r, message = FALSE, output.lines=10} sampleMeta <- data.table("Experiment_accession" = colnames(samples)[-1], "Biosample_term_name" = "new cell type") head(sampleMeta) ``` Use `findSignatures` to extend the matrix. ``` {r, output.lines=10} extended_matrix <- findSignatures(samples = samples, sampleMeta = sampleMeta, atlas = HumanCellTypeMethAtlas) head(extended_matrix) ``` WGBS methylation data first needs to be mapped to probes using `BSmeth2Probe` before being deconvoluted. The methylation data `WGBS_data` in `BSmeth2Probe` may be either a **GRanges** object or a **methylKit** object. Format of `WGBS_data` as **GRanges** object: ``` {r, message = FALSE, output.lines=10} load(system.file("extdata", "WGBS_GRanges.rda", package = "deconvR")) head(WGBS_GRanges) ``` or as **methylKit** object: ``` {r, message = FALSE, output.lines=10} head(methylKit::methRead(system.file("extdata", "test1.myCpG.txt", package = "methylKit"), sample.id="test", assembly="hg18", treatment=1, context="CpG", mincov = 0)) ``` `probe_id_locations` contains information needed to map cellular loci to probe IDs ``` {r, message = FALSE, output.lines=10} data("IlluminaMethEpicB5ProbeIDs") head(IlluminaMethEpicB5ProbeIDs) ``` Use `BSmeth2Probe` to map WGBS data to probe IDs. ``` {r, output.lines=10} mapped_WGBS_data <- BSmeth2Probe(probe_id_locations = IlluminaMethEpicB5ProbeIDs, WGBS_data = WGBS_GRanges, multipleMapping = TRUE, cutoff = 10) head(mapped_WGBS_data) ``` This mapped data can now be used in `deconvolute`. Here we will deconvolute it using the previously extended signature matrix as the reference atlas. ``` {r} deconvolution <- deconvolute(reference = HumanCellTypeMethAtlas, bulk = mapped_WGBS_data) deconvolution$proportions ``` # Example Workflow For RNA Sequencing Data Here, we will use RNA-seq example data from the **granulator** package. We will only use small sample of data. Notice that we set an IDs column. In order to run `deconvR` functions, you have to set the `Gene names` colname as `IDs`. * Note: It is possible to use `simulateCellMix` to simulate bulk RNA-seq data and, it is also possible to use `findSignatures` to extend RNA-seq reference atlas. In this example, we won't extend the reference atlas or use a simulated data. ``` {r } library(granulator) #To load the data from granulator package load_ABIS() #Read the bulk RNA-seq data bulk_RNA <- bulkRNAseq_ABIS[1:50,] %>% as.data.frame() %>% mutate(IDs = rownames(bulkRNAseq_ABIS[1:50,])) %>% select("IDs", everything()) head(bulk_RNA[,1:5]) ``` ``` {r} #Read the reference RNAseq data reference_RNA <- sigMatrix_ABIS_S0 %>% as.data.frame() %>% mutate(IDs = rownames(sigMatrix_ABIS_S0))%>% select("IDs", everything()) head(reference_RNA[1:5]) ``` We will use `deconvolute` to deconvolute cell type proportions of the bulk samples to their origin proportions using a **quadric programming** model. ``` {r} deconv_RNA <- deconvR::deconvolute(reference = reference_RNA, bulk = bulk_RNA,model = "qp") ``` Then we can access the deconvoluted proportions of bulk sample profiles. ```{r } head(deconv_RNA$proportions) ``` # sessionInfo ```{r } sessionInfo() stopCluster(cl) ```