applySCE {SingleCellExperiment} | R Documentation

## 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 `lapply`ing 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

[Package SingleCellExperiment version 1.16.0 Index]