applySCE: Applying over parts of a SingleCellExperiment

In drisso/SingleCellExperiment: S4 Classes for Single Cell Data

Applying over parts of a SingleCellExperiment

Description

Apply a function over the main and alternative Experiments of a SingleCellExperiment.

Usage

applySCE(
  X,
  FUN,
  WHICH = altExpNames(X),
  ...,
  MAIN.ARGS = list(),
  ALT.ARGS = list(),
  SIMPLIFY = TRUE
)

Arguments

X	A SingleCellExperiment object.
FUN	A function to apply to each Experiment.
WHICH	A character or integer vector containing the names or positions of alternative Experiments to loop over.
...	Further (named) arguments to pass to all calls to FUN.
MAIN.ARGS	A named list of arguments to pass to FUN for the main Experiment only. Alternatively NULL, in which case the function is not applied to the main Experiment.
ALT.ARGS	A named list where each entry is named after an alternative Experiment and contains named arguments to use in FUN for that Experiment.
SIMPLIFY	Logical scalar indicating whether the output should be simplified to a single SingleCellExperiment.

Details

The behavior of this function is equivalent to creating a list containing X as the first entry and altExps(X) in the subsequent entries, and then lapplying over this list with FUN and the specified arguments. In this manner, users can easily apply the same function to all the Experiments (main and alternative) in a SingleCellExperiment object.

Arguments in ... are passed to all calls to FUN. Arguments in MAIN.ARGS are only used in the call to FUN on the main Experiment. Arguments in ALT.ARGS are passed to the call to FUN on the alternative Experiment of the same name. For the last two, any arguments therein will override arguments of the same name in ....

By default, looping is performed over all alternative Experiments, but the order and identities can be changed by setting WHICH. Values of WHICH should be unique if any simplification of the output is desired. If MAIN.ARGS=NULL, the main Experiment is ignored and the function is only applied to the alternative Experiments.

The default of SIMPLIFY=TRUE is intended as a user-level convenience when all calls to FUN return a SingleCellExperiment with the same number of columns, and WHICH itself contains no more than one reference to each alternative Experiment in x. Under these conditions, the results are collated into a single SingleCellExperiment for easier downstream manipulation.

Value

In most cases or when SIMPLIFY=FALSE, a list is returned containing the output of FUN applied to each Experiment. If MAIN.ARGS is not NULL, the first entry corresponds to the result generated from the main Experiment; all other results are generated according to the entries specified in WHICH and are named accordingly.

If SIMPLIFY=TRUE and certain conditions are fulfilled, a SingleCellExperiment is returned where the results of FUN are mapped to the relevant main or alternative Experiments. This mirrors the organization of Experiments in X.

Developer note

When using this function inside other functions, developers should set SIMPLIFY=FALSE to guarantee consistent output for arbitrary WHICH. If simplification is necessary, the output of this function can be explicitly passed to simplifyToSCE, typically with warn.level=3 to throw an appropriate error if simplification is not possible.

Author(s)

Aaron Lun

See Also

simplifyToSCE, which is used when SIMPLIFY=TRUE.

altExps, to manually extract the alternative Experiments for operations.

Examples

ncells <- 10
u <- matrix(rpois(200, 5), ncol=ncells)
sce <- SingleCellExperiment(assays=list(counts=u))
altExp(sce, "BLAH") <- SingleCellExperiment(assays=list(counts=u*10))
altExp(sce, "WHEE") <- SingleCellExperiment(assays=list(counts=u/10))

# Here, using a very simple function that just 
# computes the mean of the input for each cell.
FUN <- function(y, multiplier=1) {
    colMeans(assay(y)) * multiplier
}

# Applying over all of the specified parts of 'sce'.
applySCE(sce, FUN=FUN)

# Adding general arguments.
applySCE(sce, FUN=FUN, multiplier=5)

# Adding custom arguments.
applySCE(sce, FUN=FUN, MAIN.ARGS=list(multiplier=5))
applySCE(sce, FUN=FUN, ALT.ARGS=list(BLAH=list(multiplier=5)))

# Skipping Experiments.
applySCE(sce, FUN=FUN, MAIN.ARGS=NULL) # skipping the main
applySCE(sce, FUN=FUN, WHICH=NULL) # skipping the alternatives

drisso/SingleCellExperiment documentation built on Nov. 12, 2024, 7:01 a.m.