These functions are designed to calculate dissimilarities on data stored
within a
TreeSummarizedExperiment
object. For overlap, Unifrac, and Jensen-Shannon Divergence (JSD)
dissimilarities, the functions use mia internal functions, while for other
types of dissimilarities, they rely on vegdist
by default.
addDissimilarity(x, method, ...)
# S4 method for class 'SummarizedExperiment'
addDissimilarity(x, method = "bray", name = method, ...)
getDissimilarity(x, method, ...)
# S4 method for class 'SummarizedExperiment'
getDissimilarity(
x,
method = "bray",
assay.type = "counts",
niter = NULL,
transposed = FALSE,
...
)
# S4 method for class 'TreeSummarizedExperiment'
getDissimilarity(
x,
method = "bray",
assay.type = "counts",
niter = NULL,
transposed = FALSE,
...
)
# S4 method for class 'ANY'
getDissimilarity(x, method = "bray", niter = NULL, ...)TreeSummarizedExperiment
or matrix.
Character scalar. Specifies which dissimilarity to
calculate. (Default: "bray")
other arguments passed into avgdist,
vegdist, or into mia internal functions:
sample: The sampling depth in rarefaction.
(Default: min(rowSums2(x)))
dis.fun: Character scalar. Specifies the dissimilarity
function to be used.
tree.name: (Unifrac) Character scalar. Specifies the
name of the tree from rowTree(x) that is used in calculation.
Disabled when tree is specified. (Default: "phylo")
tree: (Unifrac) phylo. A phylogenetic tree used in
calculation. (Default: NULL)
weighted: (Unifrac) Logical scalar. Should use
weighted-Unifrac calculation?
Weighted-Unifrac takes into account the relative abundance of
species/taxa shared between samples, whereas unweighted-Unifrac only
considers presence/absence. Default is FALSE, meaning the
unweighted-Unifrac dissimilarity is calculated for all pairs of samples.
(Default: FALSE)
node.label (Unifrac) character vector. Used only if
x is a matrix. Specifies links between rows/columns and tips of
tree. The length must equal the number of rows/columns of x.
Furthermore, all the node labs must be present in tree.
chunkSize: (JSD) Integer scalar. Defines the size of
data send to the individual worker. Only has an effect, if BPPARAM
defines more than one worker. (Default: nrow(x))
BPPARAM: (JSD)
BiocParallelParam.
Specifies whether the calculation should be parallelized.
detection: (Overlap) Numeric scalar.
Defines detection threshold for absence/presence of features. Feature that
has abundance under threshold in either of samples, will be discarded when
evaluating overlap between samples. (Default: 0)
Character scalar. The name to be used to store the result
in metadata of the output. (Default: method)
Character scalar. Specifies which assay to use for
calculation. (Default: "counts")
The number of iterations performed. If NULL,
rarefaction is disabled. (Default: NULL)
Logical scalar. Specifies if x is transposed with
cells in rows. (Default: FALSE)
getDissimilarity returns a sample-by-sample dissimilarity matrix.
addDissimilarity returns x that includes dissimilarity matrix
in its metadata.
Overlap reflects similarity between sample-pairs. When overlap is calculated using relative abundances, the higher the value the higher the similarity is. When using relative abundances, overlap value 1 means that all the abundances of features are equal between two samples, and 0 means that samples have completely different relative abundances.
Unifrac is calculated with rbiom:unifrac().
If rarefaction is enabled, vegan:avgdist() is
utilized.
For JSD implementation: Susan Holmes susan@stat.stanford.edu. Adapted for phyloseq by Paul J. McMurdie. Adapted for mia by Felix G.M. Ernst
For unifrac dissimilarity: http://bmf.colorado.edu/unifrac/
See also additional descriptions of Unifrac in the following articles:
Lozupone, Hamady and Knight, “Unifrac - An Online Tool for Comparing Microbial Community Diversity in a Phylogenetic Context.”, BMC Bioinformatics 2006, 7:371
Lozupone, Hamady, Kelley and Knight, “Quantitative and qualitative (beta) diversity measures lead to different insights into factors that structure microbial communities.” Appl Environ Microbiol. 2007
Lozupone C, Knight R. “Unifrac: a new phylogenetic method for comparing microbial communities.” Appl Environ Microbiol. 2005 71 (12):8228-35.
For JSD dissimilarity: Jensen-Shannon Divergence and Hilbert space embedding. Bent Fuglede and Flemming Topsoe University of Copenhagen, Department of Mathematics http://www.math.ku.dk/~topsoe/ISIT2004JSD.pdf
library(mia)
library(scater)
#> Loading required package: scuttle
#> Loading required package: ggplot2
# load dataset
data(GlobalPatterns)
tse <- GlobalPatterns
### Overlap dissimilarity
tse <- addDissimilarity(tse, method = "overlap", detection = 0.25)
metadata(tse)[["overlap"]][1:6, 1:6]
#> CL3 CC1 SV1 M31Fcsw M11Fcsw M31Plmr
#> CL3 0.0 985499.5 692281 951745 1217896 466124
#> CC1 985499.5 0.0 848128 975408 1253552 626083
#> SV1 692281.0 848128.0 0 808197 1083470 493475
#> M31Fcsw 951745.0 975408.0 808197 0 1785250 1014236
#> M11Fcsw 1217896.5 1253551.5 1083470 1785250 0 1281626
#> M31Plmr 466124.0 626083.0 493475 1014236 1281626 0
### JSD dissimilarity
tse <- addDissimilarity(tse, method = "jsd")
metadata(tse)[["jsd"]][1:6, 1:6]
#> CL3 CC1 SV1 M31Fcsw M11Fcsw M31Plmr
#> CL3 0.0000000 0.2547080 0.5051481 0.6809263 0.6813418 0.6713074
#> CC1 0.2547080 0.0000000 0.4378036 0.6863213 0.6869444 0.6620168
#> SV1 0.5051481 0.4378036 0.0000000 0.6848186 0.6850675 0.6649845
#> M31Fcsw 0.6809263 0.6863213 0.6848186 0.0000000 0.2864774 0.6720375
#> M11Fcsw 0.6813418 0.6869444 0.6850675 0.2864774 0.0000000 0.6831013
#> M31Plmr 0.6713074 0.6620168 0.6649845 0.6720375 0.6831013 0.0000000
# Multi Dimensional Scaling applied to JSD dissimilarity matrix
tse <- runMDS(tse, FUN = getDissimilarity, method = "overlap",
assay.type = "counts")
metadata(tse)[["MDS"]][1:6, ]
#> NULL
### Unifrac dissimilarity
res <- getDissimilarity(tse, method = "unifrac", weighted = FALSE)
dim(as.matrix((res)))
#> [1] 26 26
tse <- addDissimilarity(tse, method = "unifrac", weighted = TRUE)
metadata(tse)[["unifrac"]][1:6, 1:6]
#> CL3 CC1 SV1 M31Fcsw M11Fcsw M31Plmr
#> CL3 0.0000000 0.2196313 0.3601371 0.8567702 0.8661073 0.5892417
#> CC1 0.2196313 0.0000000 0.3145117 0.8543620 0.8633159 0.5846985
#> SV1 0.3601371 0.3145117 0.0000000 0.8433292 0.8466807 0.6006535
#> M31Fcsw 0.8567702 0.8543620 0.8433292 0.0000000 0.3350245 0.7913482
#> M11Fcsw 0.8661073 0.8633159 0.8466807 0.3350245 0.0000000 0.8579621
#> M31Plmr 0.5892417 0.5846985 0.6006535 0.7913482 0.8579621 0.0000000