EMDomics Vignette
Sadhika Malladi and Daniel Schmolze
2022-11-01
Welcome
Welcome to the EMDomics package! This vignette will explain the functionality of the package through the creation and analysis of a toy data set.
Earth Mover’s Distance
EMDomics analyzes differences in genomics data between groups of samples. Typically the data will be gene expression levels from array- or sequence-based experiments, but other scenarios are possible. In a real two-class experiment, the groups might be test vs. control, sensitive vs. resistant, etc. In a multi-class experiment (i.e., more than two groups of patients), groups may be associated with patients (in the case of single cell measurements) or disease subtypes. Typically you’ll be analyzing differences across multiple genes, but we’ll start with a single gene to get a feel for how the Earth Mover’s Distance (EMD) algorithm works. Note also that this package includes functionality for Komolgorov-Smirnov (K-S) and Cramer von Mises (CVM) distribution comparison tests. To access these tests, use calculate_ks or calculate_cvm. The input and output syntax is the same as calculate_emd, with “emd” being replaced with “ks” or “cvm” when accessing output values.
Because this package is EMDomics we will go through functionality with calculations for EMD, but K-S and CVM can be accessed with ease by replacing the function name.
We’ll create a vector of expression data for 100 samples. We’ll assign the first 50 to group “A,” the next 20 to group “B,” and the final 30 to group “C.” We will create a vector of group labels that describes which group each of the samples is a part of. Note that the vector of labels must have names corresponding to the sample identifiers in the data:
We’ll take a quick look at the three distributions using ggplot:
We shouldn’t expect the three groups to look too different, since we’re just sampling from the normal distribution. Intuitively, the “work” required to transform any one distribution into another should be low. We can calculate the EMD score for this single gene using the function calculate_emd_gene:
## [1] 3.286667
Now we’ll modify the expression data for group A and see how the EMD score changes. We’ll randomly add or subtract 2 from each data point in group A:
Let’s again visualize the distributions and calculate the EMD score:
## [1] 6.673334
The EMD score is larger, reflecting the increased work needed to transform one distribution into another. Note that since we have three classes defined, we aren’t able to tell from the EMD score alone which two groups (or, potentially, all three groups) demonstrate differences in gene behavior. The composite EMD score in a multi-class analysis is the average of all the pairwise EMD scores. The pairwise EMD scores are computed by comparing all possible combinations of two of the classes. More information on multi-class analysis is in the next section.
Note that in a two-class analysis, a greater EMD score is directly indicative of a greater difference between the measurement distributions of the two classes.
Analyzing Significance
The EMD score increases as the distributions become increasingly dissimilar, but we have no framework for estimating the significance of a particular EMD score. EMDomics uses a permutation-based method to calculate a q-value that is interpreted analogously to a p-value. To access the full functionality of the package, we’ll use the function calculate_emd.
We’ll first create a matrix of gene expression data for 100 samples (tumors, patients, etc.) and 100 genes. We’ll just sample from the normal distribution for now. The first 50 samples will be our “group A,” second 20 will be “group B,” and the final 30 will be “group C.” Just as before, we will store these sample labels in a named vector associating group with sample identifier:
data <- matrix(rnorm(10000), nrow=100, ncol=100)
rownames(data) <- paste("gene", 1:100, sep="")
colnames(data) <- paste("sample", 1:100, sep="")
groupA.labels <- rep("A",50)
groupB.labels <- rep("B",20)
groupC.labels <- rep("C",30)
labels <- c(groupA.labels, groupB.labels, groupC.labels)
names(labels) <- colnames(data)
Now we can call calculate_emd. We’ll only use 10 permutations for the purposes of this vignette, but in actual experiments using at least 100 permutations is advised. For this example we will turn off parallel processing, but in general it should be enabled.
Most of the time, you’ll be interested in the emd matrix returned as a member of the return object:
## emd q-value
## gene1 1.500000 1.0000000
## gene2 2.186667 0.6060606
## gene3 3.050000 0.0000000
## gene4 1.600000 1.0000000
## gene5 3.000000 0.0000000
## gene6 1.980000 0.8909091
This matrix lists the emd score and the q-value for each gene in the data set. Because we’re not analyzing many genes and the data is randomly generated, there may be some significant q-values in the results simply by chance. We can order the emd matrix by q-value:
## emd q-value
## gene3 3.050000 0
## gene5 3.000000 0
## gene10 2.850000 0
## gene16 3.766667 0
## gene30 3.320000 0
## gene35 3.550000 0
Note the correlation of significant q-values with relatively large EMD scores.
In a multi-class analysis, it may not be enough to know that a gene behaves differently somehow among the defined classes. We may be interested in finding which two classes display a greater difference in gene behavior, or if all three classes are somehow different. The differences between each of the classes is defined in the pairwise.emd.table. Note that EMD is not directional, so all possible combinations, not permutations, of the class labels are used in the pairwise EMD score calculations. Each of the columns represents a pairwise comparison (e.g. Group A vs Group B), each row represents a gene, and the cell content is the EMD score quantifying the work required to transform the distribution of one group into the other.
## A vs B A vs C B vs C
## gene1 1.36 0.8666667 1.5000000
## gene2 1.09 2.1866667 1.9166666
## gene3 3.05 1.5666667 2.1499996
## gene4 1.60 1.0799999 0.9333333
## gene5 3.00 2.3800001 2.6333332
## gene6 1.98 1.8466667 1.4000000
Visualization
EMDomics includes a few visualization functions. The function plot_density will display the density distributions of each of the groups for a given gene, along with the EMD score. We can compare the gene with the largest EMD score and the gene with the smallest EMD score, for example:
Note that the EMD score is the average of the each of the pairwise EMD scores. This means that the smallest and largest EMD scores may have ambiguous meanings in a multi-class analysis. To understand how each class compares to the others, the pairwise.emd.table provides pairwise comparisons of gene behavior. These pairwise EMD scores will lend more insight into how the gene is similar or different across classes.
In a two-class analysis, the smallest score represents the gene that demonstrates the most similar behavior in both classes, and the largest score represents the gene that demonstrates the most different behavior in both classes.
We can plot a histogram of all the calculated EMD scores with the function plot_emdperms:
This plot can help intuitively understand the relative significance of an EMD score. For example, almost all the randomly permuted EMD scores are smaller than the largest calculated EMD score plotted above.
In a similar vein, the function plot_emdnull plots the null distribution (the median of the permuted EMD scores) for each gene vs. the calculated EMD score (the line x=y is superimposed in red):
Wrapping Up
This concludes the EMDomics vignette. For additional information, please consult the reference manual.
Session Info
## R version 4.2.1 (2022-06-23)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.5 LTS
##
## Matrix products: default
## BLAS: /home/biocbuild/bbs-3.16-bioc/R/lib/libRblas.so
## LAPACK: /home/biocbuild/bbs-3.16-bioc/R/lib/libRlapack.so
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_GB LC_COLLATE=C
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] EMDomics_2.28.0 ggplot2_3.3.6
##
## loaded via a namespace (and not attached):
## [1] highr_0.9 bslib_0.4.0 compiler_4.2.1
## [4] pillar_1.8.1 jquerylib_0.1.4 tools_4.2.1
## [7] emdist_0.3-2 digest_0.6.30 preprocessCore_1.60.0
## [10] jsonlite_1.8.3 evaluate_0.17 lifecycle_1.0.3
## [13] tibble_3.1.8 gtable_0.3.1 pkgconfig_2.0.3
## [16] rlang_1.0.6 cli_3.4.1 DBI_1.1.3
## [19] parallel_4.2.1 yaml_2.3.6 xfun_0.34
## [22] fastmap_1.1.0 withr_2.5.0 stringr_1.4.1
## [25] dplyr_1.0.10 knitr_1.40 generics_0.1.3
## [28] sass_0.4.2 vctrs_0.5.0 grid_4.2.1
## [31] tidyselect_1.2.0 glue_1.6.2 R6_2.5.1
## [34] fansi_1.0.3 BiocParallel_1.32.0 rmarkdown_2.17
## [37] farver_2.1.1 magrittr_2.0.3 matrixStats_0.62.0
## [40] codetools_0.2-18 scales_1.2.1 htmltools_0.5.3
## [43] CDFt_1.2 assertthat_0.2.1 colorspace_2.0-3
## [46] labeling_0.4.2 utf8_1.2.2 stringi_1.7.8
## [49] munsell_0.5.0 cachem_1.0.6