Calculate the Jensen-Shannon Divergence

This function calculates the Jensen-Shannon Divergence (JSD) in a SummarizedExperiment object.

# S4 method for ANY
calculateJSD(x, ...)

# S4 method for SummarizedExperiment
calculateJSD(
  x,
  assay.type = assay_name,
  assay_name = exprs_values,
  exprs_values = "counts",
  transposed = FALSE,
  ...
)

runJSD(x, BPPARAM = SerialParam(), chunkSize = nrow(x))

Arguments

x

a numeric matrix or a SummarizedExperiment.

...

optional arguments not used.

assay.type

a single character value for specifying which assay to use for calculation.

assay_name

a single character value for specifying which assay to use for calculation. (Please use assay.type instead. At some point assay_name will be disabled.)

exprs_values

a single character value for specifying which assay to use for calculation. (Please use assay.type instead.)

transposed

Logical scalar, is x transposed with cells in rows?

BPPARAM

A BiocParallelParam object specifying whether the JSD calculation should be parallelized.

chunkSize

an integer scalar, defining the size of data send to the individual worker. Only has an effect, if BPPARAM defines more than one worker. (default: chunkSize = nrow(x))

Value

a sample-by-sample distance matrix, suitable for NMDS, etc.

References

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

See also

http://en.wikipedia.org/wiki/Jensen-Shannon_divergence

Author

Susan Holmes susan@stat.stanford.edu. Adapted for phyloseq by Paul J. McMurdie. Adapted for mia by Felix G.M. Ernst

Examples

data(enterotype)
library(scater)
#> Loading required package: scuttle
#> Loading required package: ggplot2


jsd <- calculateJSD(enterotype)
class(jsd)
#> [1] "dist"
head(jsd)
#> [1] 0.1282428 0.1438455 0.1001081 0.2694086 0.2413318 0.2186908

enterotype <- runMDS(enterotype, FUN = calculateJSD, name = "JSD",
                     exprs_values = "counts")
head(reducedDim(enterotype))
#>                 [,1]        [,2]
#> AM.AD.1   -0.2993825 -0.14425004
#> AM.AD.2   -0.1876141 -0.13490508
#> AM.F10.T1 -0.1761079 -0.02830419
#> AM.F10.T2 -0.1508764 -0.06346108
#> DA.AD.1   -0.2822249 -0.11871798
#> DA.AD.1T  -0.3040909 -0.11856633
head(attr(reducedDim(enterotype),"eig"))
#> [1] 12.8663937  2.9088395  1.8794319  0.8494149  0.6543775  0.5578214
attr(reducedDim(enterotype),"GOF")
#> [1] 0.5602642 0.6867101