ggcells {scater} | R Documentation

## Create a ggplot from a SingleCellExperiment

### Description

Create a base ggplot object from a SingleCellExperiment, the contents of which can be directly referenced in subsequent layers without prior specification.

### Usage

    ggcells(
      x,
      mapping = aes(),
      features = NULL,
      exprs_values = "logcounts",
      use_dimred = TRUE,
      use_altexps = FALSE,
      prefix_altexps = FALSE,
      check_names = TRUE,
      extract_mapping = TRUE,
      ...
    )

    ggfeatures(
      x,
      mapping = aes(),
      cells = NULL,
      exprs_values = "logcounts",
      check_names = TRUE,
      extract_mapping = TRUE,
      ...
    )

### Arguments

`x` | A SingleCellExperiment object. This is expected to have row names for `ggcells` and column names for `ggfeatures`.
`mapping` | A list containing aesthetic mappings, usually the output of `aes` or related functions.
`features` | Character vector specifying the features for which to extract expression profiles across cells. May also include features in alternative Experiments if permitted by `use_altexps`.
`exprs_values` | String or integer scalar indicating the assay to use to obtain expression values. Must refer to a matrix-like object with integer or numeric values.
`use_dimred` | Logical scalar indicating whether data should be extracted for dimensionality reduction results in `x`. Alternatively, a character or integer vector specifying the dimensionality reduction results to use.
`use_altexps` | Logical scalar indicating whether (meta)data should be extracted for alternative experiments in `x`. Alternatively, a character or integer vector specifying the alternative experiments to use.
`prefix_altexps` | Logical scalar indicating whether `altExp`-derived fields should be prefixed with the name of the alternative Experiment.
`check_names` | Logical scalar indicating whether the column names of the output data.frame should be made syntactically valid and unique.
`extract_mapping` | Logical scalar indicating whether `features` or `cells` should be automatically expanded to include variables referenced in `mapping`.
`...` | Further arguments to pass to ggplot.
`cells` | Character vector specifying the features for which to extract expression profiles across cells.

### Details

These functions generate a data.frame from the contents of a SingleCellExperiment and pass it to `ggplot`. Rows, columns or metadata fields in the `x` can then be referenced in subsequent ggplot2 commands.

`ggcells` treats cells as the data values so users can reference row names of `x` (if provided in `features`), column metadata variables and dimensionality reduction results. They can also reference row names and metadata variables for alternative Experiments.

`ggfeatures` treats features as the data values so users can reference column names of `x` (if provided in `cells`) and row metadata variables.

If `mapping` is supplied, the function will automatically expand `features` or `cells` for any features or cells requested in the mapping. This is convenient as features/cells do not have to specified twice (once in data.frame construction and again in later `geom` or `stat` layers). Developers may wish to turn this off with `extract_mapping=FALSE` for greater control.

### Value

A ggplot object containing the specified contents of `x`.

### Author(s)

Aaron Lun

### See Also

`makePerCellDF` and `makePerFeatureDF`, for the construction of the data.frame.

### Examples

    example_sce <- mockSCE()
    example_sce <- logNormCounts(example_sce)
    example_sce <- runPCA(example_sce)

    ggcells(example_sce, aes(x=PCA.1, y=PCA.2, color=Gene_0001)) +
        geom_point()

    ggcells(example_sce, aes(x=Mutation_Status, y=Gene_0001)) +
        geom_violin() +
        facet_wrap(~Cell_Cycle)

    rowData(example_sce)$GC <- runif(nrow(example_sce))
    ggfeatures(example_sce, aes(x=GC, y=Cell_001)) +
        geom_point() +
        stat_smooth()

[Package scater version 1.16.2 Index]