getCrossAssociation: Calculate correlations between features of two experiments.

In FelixErnst/mia: Microbiome analysis

Calculate correlations between features of two experiments.

Description

Calculate correlations between features of two experiments.

Usage

getCrossAssociation(x, ...)

## S4 method for signature 'MultiAssayExperiment'
getCrossAssociation(
  x,
  experiment1 = 1,
  experiment2 = 2,
  assay.type1 = assay_name1,
  assay_name1 = "counts",
  assay.type2 = assay_name2,
  assay_name2 = "counts",
  altexp1 = NULL,
  altexp2 = NULL,
  col.var1 = colData_variable1,
  colData_variable1 = NULL,
  col.var2 = colData_variable2,
  colData_variable2 = NULL,
  MARGIN = 1,
  method = c("kendall", "spearman", "categorical", "pearson"),
  mode = "table",
  p.adj.method = p_adj_method,
  p_adj_method = c("fdr", "BH", "bonferroni", "BY", "hochberg", "holm", "hommel", "none"),
  p.adj.threshold = p_adj_threshold,
  p_adj_threshold = NULL,
  cor.threshold = cor_threshold,
  cor_threshold = NULL,
  sort = FALSE,
  filter.self.cor = filter_self_correlations,
  filter_self_correlations = FALSE,
  verbose = TRUE,
  test.signif = test_significance,
  test_significance = FALSE,
  show.warnings = show_warnings,
  show_warnings = TRUE,
  paired = FALSE,
  ...
)

## S4 method for signature 'SummarizedExperiment'
getCrossAssociation(x, experiment2 = x, ...)

Arguments

x	A MultiAssayExperiment or SummarizedExperiment object.
...	Additional arguments: symmetric: A single boolean value for specifying if measure is symmetric or not. When symmetric = TRUE, associations are calculated only for unique variable-pairs, and they are assigned to corresponding variable-pair. This decreases the number of calculations in 2-fold meaning faster execution. (By default: symmetric = FALSE) association.fun: A function that is used to calculate (dis-)similarity between features. Function must take matrix as an input and give numeric values as an output. Adjust method and other parameters correspondingly. Supported functions are, for example, stats::dist and vegan::vegdist.
experiment1	A single character or numeric value for selecting the experiment 1 from experiments(x) of MultiassayExperiment object. (By default: experiment1 = 1)
experiment2	A single character or numeric value for selecting the experiment 2 fromexperiments(x) of MultiAssayExperiment object or altExp(x) of TreeSummarizedExperiment object. Alternatively, experiment2 can also be TreeSE object when x is TreeSE object. (By default: experiment2 = 2 when x is MAE and experiment2 = x when x is TreeSE)
assay.type1	A single character value for selecting the assay of experiment 1 to be transformed. (By default: assay.type1 = "counts")
assay_name1	Deprecated. Use assay.type1 instead.
assay.type2	A single character value for selecting the assay of experiment 2 to be transformed. (By default: assay.type2 = "counts")
assay_name2	Deprecated. Use assay.type2 instead.
altexp1	A single numeric or character value specifying alternative experiment from the altExp of experiment 1. If NULL, then the experiment is itself and altExp option is disabled. (By default: altexp1 = NULL)
altexp2	A single numeric or character value specifying alternative experiment from the altExp of experiment 2. If NULL, then the experiment is itself and altExp option is disabled. (By default: altexp2 = NULL)
col.var1	A character value specifying column(s) from colData of experiment 1. If col.var1 is used, assay.type1 is disabled. (By default: col.var1 = NULL)
colData_variable1	Deprecated. Use col.var1 instead.
col.var2	A character value specifying column(s) from colData of experiment 2. If col.var2 is used, assay.type2 is disabled. (By default: col.var2 = NULL)
colData_variable2	Deprecated. Use col.var2 instead.
MARGIN	A single numeric value for selecting if association are calculated row-wise / for features (1) or column-wise / for samples (2). Must be 1 or 2. (By default: MARGIN = 1)
method	A single character value for selecting association method ('kendall', pearson', or 'spearman' for continuous/numeric; 'categorical' for discrete) (By default: method = "kendall")
mode	A single character value for selecting output format Available formats are 'table' and 'matrix'. (By default: mode = "table")
p.adj.method	A single character value for selecting adjustment method of p-values. Passed to p.adjust function. (By default: p.adj.method = "fdr")
p_adj_method	Deprecated. Use p.adj.method isntead.
p.adj.threshold	A single numeric value (from 0 to 1) for selecting adjusted p-value threshold for filtering. (By default: p.adj.threshold = NULL)
p_adj_threshold	Deprecated. Use p.dj.threshold instead.
cor.threshold	A single numeric absolute value (from 0 to 1) for selecting correlation threshold for filtering. (By default: cor.threshold = NULL)
cor_threshold	Deprecated. Use cor.threshold instead.
sort	A single boolean value for selecting whether to sort features or not in result matrices. Used method is hierarchical clustering. (By default: sort = FALSE)
filter.self.cor	A single boolean value for selecting whether to filter out correlations between identical items. Applies only when correlation between experiment itself is tested, i.e., when assays are identical. (By default: filter.self.cor = FALSE)
filter_self_correlations	Deprecated. Use filter.self.cor instead.
verbose	A single boolean value for selecting whether to get messages about progress of calculation.
test.signif	A single boolean value for selecting whether to test statistical significance of associations. (By default: test.signif = FALSE)
test_significance	Deprecated. Use test.signif instead.
show.warnings	A single boolean value for selecting whether to show warnings that might occur when correlations and p-values are calculated.
show_warnings	Deprecated. use show.warnings instead.
paired	A single boolean value for specifying if samples are paired or not. colnames must match between twp experiments. paired is disabled when MARGIN = 1. (By default: paired = FALSE)

Details

The function getCrossAssociation calculates associations between features of two experiments. By default, it not only computes associations but also tests their significance. If desired, setting test.signif to FALSE disables significance calculation.

We recommend the non-parametric Kendall's tau as the default method for association analysis. Kendall's tau has desirable statistical properties and robustness at lower sample sizes. Spearman rank correlation can provide faster solutions when running times are critical.

Value

This function returns associations in table or matrix format. In table format, returned value is a data frame that includes features and associations (and p-values) in columns. In matrix format, returned value is a one matrix when only associations are calculated. If also significances are tested, then returned value is a list of matrices.

Author(s)

Leo Lahti and Tuomas Borman. Contact: microbiome.github.io

Examples

data(HintikkaXOData)
mae <- HintikkaXOData

# Subset so that less observations / quicker to run, just for example
mae[[1]] <- mae[[1]][1:20, 1:10]
mae[[2]] <- mae[[2]][1:20, 1:10]
# Several rows in the counts assay have a standard deviation of zero
# Remove them, since they do not add useful information about cross-association
mae[[1]] <- mae[[1]][rowSds(assay(mae[[1]])) > 0, ]
# Transform data
mae[[1]] <- transformAssay(mae[[1]], method = "rclr")

# Calculate cross-correlations
result <- getCrossAssociation(mae, method = "pearson", assay.type2 = "nmr")
# Show first 5 entries
head(result, 5)

# Use altExp option to specify alternative experiment from the experiment
altExp(mae[[1]], "Phylum") <- agglomerateByRank(mae[[1]], rank = "Phylum")
# Transform data
altExp(mae[[1]], "Phylum") <- transformAssay(altExp(mae[[1]], "Phylum"), method = "relabundance")
# When mode = "matrix", the return value is a matrix
result <- getCrossAssociation(mae, experiment2 = 2, 
                                        assay.type1 = "relabundance", assay.type2 = "nmr",
                                        altexp1 = "Phylum", 
                                        method = "pearson", mode = "matrix")
# Show first 5 entries
head(result, 5)

# If test.signif = TRUE, then getCrossAssociation additionally returns 
# significances
# filter.self.cor = TRUE filters self correlations
# p.adj.threshold can be used to filter those features that do not
# have any correlations whose p-value is lower than the threshold
result <- getCrossAssociation(mae[[1]], experiment2 = mae[[1]], method = "pearson",
                                         filter.self.cor = TRUE,
                                         p.adj.threshold = 0.05,
                                         test.signif = TRUE)
# Show first 5 entries
head(result, 5)
                                        
# Returned value is a list of matrices
names(result)

# Calculate Bray-Curtis dissimilarity between samples. If dataset includes
# paired samples, you can use paired = TRUE.
result <- getCrossAssociation(mae[[1]], mae[[1]], MARGIN = 2, paired = FALSE,
                                        association.fun = vegan::vegdist, 
                                        method = "bray")
                                        

# If experiments are equal and measure is symmetric (e.g., taxa1 vs taxa2 == taxa2 vs taxa1),
# it is possible to speed-up calculations by calculating association only for unique
# variable-pairs. Use "symmetric" to choose whether to measure association for only
# other half of of variable-pairs.
result <- getCrossAssociation(mae, experiment1 = "microbiota", 
                                 experiment2 = "microbiota", 
                                 assay.type1 = "counts", 
                                 assay.type2 = "counts",
                                 symmetric = TRUE)

# For big data sets, the calculations might take a long time.
# To speed them up, you can take a random sample from the data. 
# When dealing with complex biological problems, random samples can be 
# enough to describe the data. Here, our random sample is 30 % of whole data.
sample_size <- 0.3
tse <- mae[[1]]
tse_sub <- tse[ sample( seq_len( nrow(tse) ), sample_size * nrow(tse) ), ]
result <- getCrossAssociation(tse_sub)

# It is also possible to choose variables from colData and calculate association
# between assay and sample metadata or between variables of sample metadata
mae[[1]] <- estimateDiversity(mae[[1]])
# colData_variable works similarly to assay.type. Instead of fetching an assay
# named assay.type from assay slot, it fetches a column named colData_variable
# from colData.
result <- getCrossAssociation(mae[[1]], assay.type1 = "counts", 
                                 col.var2 = c("shannon", "coverage"),
                                 test.signif = TRUE)
                                        

FelixErnst/mia documentation built on June 19, 2024, 3:51 a.m.