mergeCloseModules: Merge close modules in gene expression data
In WGCNA: Weighted Correlation Network Analysis

mergeCloseModules

R Documentation

Merge close modules in gene expression data

Description

Merges modules in gene expression networks that are too close as measured by the correlation of their eigengenes.

Usage

mergeCloseModules(
 # input data
  exprData, colors,

  # Optional starting eigengenes
  MEs = NULL,

  # Optional restriction to a subset of all sets
  useSets = NULL,

  # If missing data are present, impute them?
  impute = TRUE,

  # Input handling options
  checkDataFormat = TRUE,
  unassdColor = if (is.numeric(colors)) 0 else "grey",

  # Options for eigengene network construction
  corFnc = cor, corOptions = list(use = 'p'),
  useAbs = FALSE,

  # Options for constructing the consensus
  equalizeQuantiles = FALSE,
  quantileSummary = "mean",
  consensusQuantile = 0,

  # Merging options
  cutHeight = 0.2,
  iterate = TRUE,

  # Output options
  relabel = FALSE,
  colorSeq = NULL,
  getNewMEs = TRUE,
  getNewUnassdME = TRUE,

  # Options controlling behaviour of the function
  trapErrors = FALSE,
  verbose = 1, indent = 0)

Arguments

`exprData`	Expression data, either a single data frame with rows corresponding to samples and columns to genes, or in a multi-set format (see `checkSets`). See `checkDataStructure` below.
`colors`	A vector (numeric, character or a factor) giving module colors for genes. The method only makes sense when genes have the same color label in all sets, hence a single vector.
`MEs`	If module eigengenes have been calculated before, the user can save some computational time by inputting them. `MEs` should have the same format as `exprData`. If they are not given, they will be calculated.
`useSets`	A vector of scalar allowing the user to specify which sets will be used to calculate the consensus dissimilarity of module eigengenes. Defaults to all given sets.
`impute`	Should missing values be imputed in eigengene calculation? If imputation is disabled, the presence of `NA` entries will cause the eigengene calculation to fail and eigengenes will be replaced by their hubgene approximation. See `moduleEigengenes` for more details.
`checkDataFormat`	If TRUE, the function will check `exprData` and `MEs` for correct multi-set structure. If single set data is given, it will be converted into a format usable for the function. If FALSE, incorrect structure of input data will trigger an error.
`unassdColor`	Specifies the string that labels unassigned genes. Module of this color will not enter the module eigengene clustering and will not be merged with other modules.
`corFnc`	Correlation function to be used to calculate correlation of module eigengenes.
`corOptions`	Can be used to specify options to the correlation function, in addition to argument `x` which is used to pass the actual data to calculate the correlation of.
`useAbs`	Specifies whether absolute value of correlation or plain correlation (of module eigengenes) should be used in calculating module dissimilarity.
`equalizeQuantiles`	Logical: should quantiles of the eigengene dissimilarity matrix be equalized ("quantile normalized")? The default is `FALSE` for reproducibility of old code; when there are many eigengenes (e.g., at least 50), better results may be achieved if quantile equalization is used.
`quantileSummary`	One of `"mean"` or `"median"`. Controls how a reference dissimilarity is computed from the input ones (using mean or median, respectively).
`consensusQuantile`	A number giving the desired quantile to use in the consensus similarity calculation (see details).
`cutHeight`	Maximum dissimilarity (i.e., 1-correlation) that qualifies modules for merging.
`iterate`	Controls whether the merging procedure should be repeated until there is no change. If FALSE, only one iteration will be executed.
`relabel`	Controls whether, after merging, color labels should be ordered by module size.
`colorSeq`	Color labels to be used for relabeling. Defaults to the standard color order used in this package if `colors` are not numeric, and to integers starting from 1 if `colors` is numeric.
`getNewMEs`	Controls whether module eigengenes of merged modules should be calculated and returned.
`getNewUnassdME`	When doing module eigengene manipulations, the function does not normally calculate the eigengene of the 'module' of unassigned ('grey') genes. Setting this option to `TRUE` will force the calculation of the unassigned eigengene in the returned newMEs, but not in the returned oldMEs.
`trapErrors`	Controls whether computational errors in calculating module eigengenes, their dissimilarity, and merging trees should be trapped. If `TRUE`, errors will be trapped and the function will return the input colors. If `FALSE`, errors will cause the function to stop.
`verbose`	Controls verbosity of printed progress messages. 0 means silent, up to (about) 5 the verbosity gradually increases.
`indent`	A single non-negative integer controlling indentation of printed messages. 0 means no indentation, each unit above that adds two spaces.

Details

This function merges input modules that are closely related. The similarities are measured by correlations of module eigengenes; a “consensus” measure is defined as the “consensus quantile” over the corresponding relationship in each set. Once the (dis-)similarity is calculated, average linkage hierarchical clustering of the module eigengenes is performed, the dendrogram is cut at the height cutHeight and modules on each branch are merged. The process is (optionally) repeated until no more modules are merged.

If, for a particular module, the module eigengene calculation fails, a hubgene approximation will be used.

The user should be aware that if a computational error occurs and trapErrors==TRUE, the returned list (see below) will not contain all of the components returned upon normal execution.

Value

If no errors occurred, a list with components

`colors`	Color labels for the genes corresponding to merged modules. The function attempts to mimic the mode of the input `colors`: if the input `colors` is numeric, character and factor, respectively, so is the output. Note, however, that if the fnction performs relabeling, a standard sequence of labels will be used: integers starting at 1 if the input `colors` is numeric, and a sequence of color labels otherwise (see `colorSeq` above).
`dendro`	Hierarchical clustering dendrogram (average linkage) of the eigengenes of the most recently computed tree. If `iterate` was set TRUE, this will be the dendrogram of the merged modules, otherwise it will be the dendrogram of the original modules.
`oldDendro`	Hierarchical clustering dendrogram (average linkage) of the eigengenes of the original modules.
`cutHeight`	The input cutHeight.
`oldMEs`	Module eigengenes of the original modules in the sets given by `useSets`.
`newMEs`	Module eigengenes of the merged modules in the sets given by `useSets`.
`allOK`	A boolean set to `TRUE`.