coseqRun {coseq} | R Documentation

## Co-expression analysis

### Description

Function for primary code to perform co-expression analysis, with or without data transformation, using mixture models. The output of `coseqRun` is an S4 object of class `coseqResults`.

### Usage

    coseqRun(
      y,
      K,
      conds = NULL,
      normFactors = "TMM",
      model = "kmeans",
      transformation = "logclr",
      subset = NULL,
      meanFilterCutoff = 50,
      modelChoice = ifelse(model == "kmeans", "DDSE", "ICL"),
      parallel = FALSE,
      BPPARAM = bpparam(),
      seed = NULL,
      ...
    )

### Arguments

`y` | (n x q) matrix of observed counts for n observations (genes) and q variables (samples). In nearly all cases, n > q.
`K` | Number of clusters (a single value or a vector of values)
`conds` | Vector of length q defining the condition (treatment group) for each variable (column) in `y`
`normFactors` | The type of estimator to be used to normalize for differences in library size: (“`TC`” for total count, “`UQ`” for upper quantile, “`Med`” for median, “`DESeq`” for the normalization method in the DESeq package, and “`TMM`” for the TMM normalization method (Robinson and Oshlack, 2010). Can also be a vector (of length q) containing pre-estimated library size estimates for each sample, or “`none`” if no normalization is required.
`model` | Type of mixture model to use (“`Poisson`” or “`Normal`”), or alternatively “`kmeans`” for a K-means algorithm
`transformation` | Transformation type to be used: “`voom`”, “`logRPKM`” (if `geneLength` is provided by user), “`arcsin`”, “`logit`”, “`logMedianRef`”, “`profile`”, “`logclr`”, “`clr`”, “`alr`”, “`ilr`”, or “`none`”
`subset` | Optional vector providing the indices of a subset of genes that should be used for the co-expression analysis (i.e., row indices of the data matrix `y`. For the generic function `coseq`, the results of a previously run differential analysis may be used to select a subset of genes on which to perform the co-expression analysis. If this is desired, `subset.index` can also be an object of class DESeqResults (from the `results` function in `DESeq2`).
`meanFilterCutoff` | Value used to filter low mean normalized counts if desired (by default, set to a value of 50)
`modelChoice` | Criterion used to select the best model. For Gaussian mixture models, “`ICL`” (integrated completed likelihood criterion) is currently supported. For Poisson mixture models, “`ICL`”, “`BIC`” (Bayesian information criterion), and a non-asymptotic criterion calibrated via the slope heuristics using either the “`DDSE`” (data-driven slope estimation) or “`Djump`” (dimension jump) approaches may be used. See the `HTSCluster` package documentation for more details about the slope heuristics approaches.
`parallel` | If `FALSE`, no parallelization. If `TRUE`, parallel execution using BiocParallel (see next argument `BPPARAM`). A note on running in parallel using BiocParallel: it may be advantageous to remove large, unneeded objects from the current R environment before calling the function, as it is possible that R's internal garbage collection will copy these files while running on worker nodes.
`BPPARAM` | Optional parameter object passed internally to `bplapply` when `parallel=TRUE`. If not specified, the parameters last registered with `register` will be used.
`seed` | If desired, an integer defining the seed of the random number generator. If `NULL`, a random seed is used.
`...` | Additional optional parameters.

### Value

An S4 object of class `coseqResults` whose assays contain a `SimpleList` object, where each element in the list corresponds to the conditional probabilities of cluster membership for each gene in each model. Meta data (accessible via `metatdata` include the `model` used (either `Normal` or `Poisson`), the `transformation` used on the data, the transformed data using to estimate model (`tcounts`), the normalized profiles for use in plotting (`y_profiles`), and the normalization factors used in the analysis (`normFactors`).

### Author(s)

Andrea Rau

### Examples

    ## Simulate toy data, n = 300 observations
    set.seed(12345)
    countmat <- matrix(runif(300*4, min=0, max=500), nrow=300, ncol=4)
    countmat <- countmat[which(rowSums(countmat) > 0),]
    conds <- rep(c("A","B","C","D"), each=2)

    ## Run the K-means for K = 2,3,4 with logCLR transformation
    ## The following are equivalent:
    run <- coseqRun(y=countmat, K=2:15)
    run <- coseq(object=countmat, K=2:15, transformation="logclr", model="kmeans")

    ## Run the Normal mixture model for K = 2,3,4 with arcsine transformation
    ## The following are equivalent:
    run <- coseqRun(y=countmat, K=2:4, iter=5, transformation="arcsin", model="Normal")
    run <- coseq(object=countmat, K=2:4, iter=5, transformation="arcsin", model="Normal")

[Package coseq version 1.18.0 Index]