groups2contrasts: Define experimental contrasts from sample groups

In jmw86069/splicejam: Analysis and Visualization of Gene Splice Variants and Transcriptome Data

Define experimental contrasts from sample groups

Description

Define experimental contrasts from sample groups

Usage

groups2contrasts(
  iFactors,
  groupColumns = NULL,
  iSamples = NULL,
  iDesign = NULL,
  factorOrder = NULL,
  omitGrep = "[-,]",
  maxDepth = 2,
  currentDepth = 1,
  factorSep = "_",
  contrastSep = "-",
  renameFirstDepth = TRUE,
  returnDesign = FALSE,
  removePairs = NULL,
  makeUnique = TRUE,
  addContrastNamesDF = NULL,
  preControlTerms = NULL,
  verbose = FALSE,
  ...
)

Arguments

iFactors	vector of sample groups with one entry per sample, or data.frame whose colnames are experimental factors, and rows are samples.
groupColumns	character vector or NULL, to define an optional subset of colnames when iFactors is a data.frame.
iSamples	character vector or NULL, optionally used to subset the sample identifiers used in subsequent steps. Note that only groups and contrasts that contain samples will be defined.
iDesign	optional numeric design matrix, an optional method of defining sample-to-group mapping.
factorOrder	integer vector, optionally used to define the order of factor contrasts when there are multiple experimental factors. It can be helpful to force a secondary factor to be compared before a primary factor especially in two-way contrasts. Note that factorOrder refers to the columns (factors) and not the factor levels (not column values).
omitGrep	character grep pattern used to exclude secondary factors from contrasts, mainly used internally by this function.
maxDepth	integer value, the maximum number of factor "depth" to define contrasts, for example maxDepth=2 will define two-way contrasts, maxDepth=1 will only define one-way contrasts.
currentDepth	integer value used internally by groups2contrasts() for iterative operations.
factorSep, contrastSep	character values used as delimiter in factor and contrast names, respectively.
renameFirstDepth	logical used internally for iterative calls to groups2contrasts().
returnDesign	logical indicating whether to return the full set of design (iDesign), contrast (iContrasts) matrices, in addition to the contrastNames data.frame.
removePairs	list of pairwise vectors of factors which should not be compared, or NULL to include all comparisons. The values in each vector should be factor levels that should not be compared. When the vector contains only one value, it removes contrasts where that factor is not changed, which is relevant when there are two or more factors.
makeUnique	logical indicating whether to make output contrasts unique.
addContrastNamesDF	data.frame or NULL, optionally used to append to the calculated contrastNames data.frame, useful to add custom contrasts.
preControlTerms	character vector or NULL, optionally used to help define factor order, for example preControlTerms=c("WT") would help order "WT" before "KO" when defining control factor levels, so the resulting contrasts would become "KO-WT". This vector should contain the factor levels that should be used as the preferred control term in each contrast, where the earlier terms are preferred.
verbose	logical indicating whether to print verbose output.
...	additional arguments are ignored.

Details

This function is intended to define statistical contrasts that compare one factor at a time. For two-factor designs, it will create two-way contrasts, defined as the contrast of pairwise contrasts.

Input can be a character vector of group names, where by default each factor is separated by an underscore "_". An example might be:

iFactors <- c("Control_Wildtype", "Control_Knockout", "Treated_Wildtype", "Treated_Knockout")

In that case, there are two factors. The first factor contains factor levels c("Control", "Treated"), and the second factor contains factor levels c("Wildtype", "Knockout").

Input can also be a data.frame (or compatible table-like object including data.table and tibble). Each column is considered a factor. From the example above, we can create a data.frame using jamba::rbindList(), see the Examples for more detail.

jamba::rbindList(strsplit(iFactors, "_"))

Lastly, if the input is a named vector, or a data.frame with rownames,

This function will change any "-" in a factor name to "." prior to detecting valid contrasts. Note that groups2contrasts() does not call base::make.names() because that function too aggressively converts characters to ".". If data must be compliant with the rules used by base::make.names(), run that function prior to calling groups2contrasts().

Value

list of data matrices: iDesign numeric design matrix; iContrasts numeric contrast matrix; contrastNames data.frame showing the full factor breakdown, with colnames "contrastName" which shows a text contrast suitable for use in limma::makeContrasts(). When returnDesign=FALSE the output is only the contrastNames data.frame.

See Also

Other jam RNA-seq functions: assignGRLexonNames(), closestExonToJunctions(), combineGRcoverage(), defineDetectedTx(), detectedTxInfo(), exoncov2polygon(), flattenExonsBy(), getGRcoverageFromBw(), internal_junc_score(), makeTx2geneFromGtf(), make_ref2compressed(), prepareSashimi(), runDiffSplice(), sortSamples(), spliceGR2junctionDF()

Other jam design functions: curateDFtoDF(), curateVtoDF()

Examples

# first define a vector of sample groups
iGroups <- jamba::nameVector(paste(rep(c("WT", "KO"), each=6),
   rep(c("Control", "Treated"), each=3),
   sep="_"));
iGroups <- factor(iGroups, levels=unique(iGroups));
iGroups;

iDesignL <- groups2contrasts(iGroups, returnDesign=TRUE);
iDesignL$iDesign;
iDesignL$iContrasts;

# now you can visualize the samples used in each contrast
iDesignL$iDesign %*%  iDesignL$iContrasts;

# you can adjust the order of factor levels per comparison
groups2contrasts(as.character(iGroups))$contrastName

# make "WT" the first control term
groups2contrasts(as.character(iGroups), preControlTerms=c("WT"), factorOrder=2:1)$contrastName

# prevent comparisons of WT to WT, or KO to KO
groups2contrasts(as.character(iGroups),
   removePairs=list(c("WT"), c("KO")))

# input as a data.frame with ordered factor levels
iFactors <- data.frame(Genotype=factor(c("WT","WT","KO","KO"),
   levels=c("WT","KO")),
   Treatment=factor(c("Treated","Control"),
      levels=c("Control","Treated")))
iFactors;
groups2contrasts(iFactors)


# Again remove WT-WT and KO-KO contrasts
groups2contrasts(iFactors,
   removePairs=list(c("WT"), c("KO")))

jmw86069/splicejam documentation built on Nov. 4, 2024, 10:53 a.m.