clusVarAnalysis: Tests association between clusters of samples and variables

Description

From a clustering of samples performed according to their contribution to each component, this function computes the chi-squared test of association between each variable level and the cluster, and summarizes the results in an HTML file.

Usage

clusVarAnalysis(icaSet, params, resClus, keepVar, keepComp, funClus = "", adjustBy = c("none", "component", "variable"), method = "BH", doPlot = FALSE, cutoff = params["pvalCutoff"], path = paste(resPath(params), "clus2var/", sep = ""), onlySign = TRUE, typeImage = "png", testBy = c("variable", "level"), filename)

Arguments

icaSet

An object of class IcaSet

params

An object of class MineICAParams providing the parameters of the analysis

resClus

A list of numeric vectors indexed by sample IDs, which specifies the sample clusters. There must be one clustering by component of icaSet. The names of the list must correspond to the component indices.

keepVar

The variable labels to be considered, i.e a subset of the variables of icaSet available in varLabels(icaSet).

keepComp

A subset of components available in indComp(icaSet) to be considered, if missing all components are used.

funClus

The name of the function used to perform the clustering (just for text in written files).

adjustBy

The way the p-values of the Wilcoxon and Kruskal-Wallis tests should be corrected for multiple testing: "none" if no p-value correction has to be done, "component" if the p-values have to be corrected by component, "variable" if the p-values have to be corrected by variable.

testBy

Chi-square tests of association can be performed either by "variable" (one test by variable, default) or by variable "level" (as many tests as there are annotation levels).

method

The correction method, see p.adjust for details, default if "BH" for Benjamini & Hochberg.

doPlot

If TRUE, the barplots showing the distribution of the annotation levels among the clusters are plotted and the results are provided in an HTML file 'cluster2annot.htm', else no plot is created.

cutoff

The threshold for statistical significance.

filename

File name for test results, if doPlot=TRUE will be an HTML file else will be a 'txt' file. If missing when doPlot=TRUE, will be "clusVar".

path

A directory _within resPath(params)_ where the outputs are saved if doPlot=TRUE, default is 'cluster2annot/'.

onlySign

If TRUE (default), only the significant results are plotted.

typeImage

The type of image file where each plot is saved.

Value

This function returns a list whose each element gives, for each component, the results of the association chi-squared tests between the clusters and the annotation levels.

Details

When doPlot=TRUE, this function writes an HTML file containing the results of the tests as a table of dimension 'variable levels x components' which contains the p-values of the tests. When a p-value is considered as significant according to the threshold cutoff, it is written in bold and filled with a link pointing to the corresponding barplot displaying the distribution of the clusters across the levels of the variables.

One image is created by plot and located into the sub-directory "plots/" of path. Each image is named by index-of-component_var.png

Examples

Run this code

## load an example of IcaSet
data(icaSetCarbayo)
## build object of class MineICAParams
params <- buildMineICAParams(resPath="carbayo/")

## cluster samples according to the columns of the mixing matrix A with kmeans in 2 groups
resClus <- clusterSamplesByComp(icaSet=icaSetCarbayo, params=params, funClus="kmeans",
                               clusterOn="A", nbClus=2)$clus

## specify directory for the function outputs (here same directory as the default one)
## this directory will be created by the function in resPath(params)
dir <- "clus2var/"

## compute chi-square tests of association, p-value are not adjusted (adjustBy="none"),
# test results are written in txt format (doPlot=FALSE and filename not missing)
resChi <- clusVarAnalysis(icaSet=icaSetCarbayo, params=params, resClus=resClus, funClus="kmeans",
                          adjustBy="none", doPlot=FALSE, path=dir, filename="clusVarTests")

## Not run: 
# ## compute chi-square tests of association, p-value are not adjusted (adjustBy="none"),
# # write results and plots in HTML files (doPlot=TRUE)
# resChi <- clusVarAnalysis(icaSet=icaSetCarbayo, params=params, resClus=resClus, funClus="kmeans",
#                           path=dir, adjustBy="none", doPlot=TRUE, filename="clusVarTests")
# 
# ## compute chi-square tests of association by only considering a subset of components and variables,
# # adjust p-values by component  (adjustBy="component"),
# # do not write results (doPlot=FALSE and filename is missing).
# resChi <- clusVarAnalysis(icaSet=icaSetCarbayo, params=params, resClus=resClus, keepComp = 1:10,
#                           keepVar=c("GENDER","STAGE"), funClus="kmeans", adjustBy="none",
#                           doPlot=FALSE)
# ## End(Not run)