plotExprsVsTxLength {scater} | R Documentation

## Plot expression against transcript length

### Description

Plot mean expression values for all features in a SingleCellExperiment object against transcript length values.

### Usage

    plotExprsVsTxLength(object, tx_length = "median_feat_eff_len",
      length_is_assay = FALSE, exprs_values = "logcounts",
      log2_values = FALSE, colour_by = NULL, shape_by = NULL,
      size_by = NULL, by_exprs_values = exprs_values,
      by_show_single = FALSE, xlab = "Median transcript length",
      show_exprs_sd = FALSE, ...)

### Arguments

`object` | A SingleCellExperiment object.
`tx_length` | Transcript lengths for all features, to plot on the x-axis. If `length_is_assay=FALSE`, this can take any of the values described in `?"scater-vis-var"` for feature-level metadata; data in `assays(object)` will not be searched. Otherwise, if `length_is_assay=TRUE`, `tx_length` should be the name or index of an assay in `object`.
`length_is_assay` | Logical scalar indicating whether `tx_length` refers to an assay of `object` containing transcript lengths for all features in all cells.
`exprs_values` | A string or integer scalar specifying which assay in `assays(object)` to obtain expression values from.
`log2_values` | Logical scalar, specifying whether the expression values be transformed to the log2-scale for plotting (with an offset of 1 to avoid logging zeroes).
`colour_by` | Specification of a column metadata field or a feature to colour by, see `?"scater-vis-var"` for possible values.
`shape_by` | Specification of a column metadata field or a feature to shape by, see `?"scater-vis-var"` for possible values.
`size_by` | Specification of a column metadata field or a feature to size by, see `?"scater-vis-var"` for possible values.
`by_exprs_values` | A string or integer scalar specifying which assay to obtain expression values from, for use in point aesthetics - see `?"scater-vis-var"` for details.
`by_show_single` | Logical scalar specifying whether single-level factors should be used for point aesthetics, see `?"scater-vis-var"` for details.
`xlab` | String specifying the label for x-axis.
`show_exprs_sd` | Logical scalar indicating whether the standard deviation of expression values for each feature should be plotted.
`...` | Additional arguments for visualization, see `?"scater-plot-args"` for details.

### Details

If `length_is_assay=TRUE`, the median transcript length of each feature across all cells is used. This may be necessary if the effective transcript length differs across cells, e.g., as observed in the results from pseudo-aligners.

### Value

A ggplot object.

### Author(s)

Davis McCarthy, with modifications by Aaron Lun

### Examples

    data("sc_example_counts")
    data("sc_example_cell_info")
    rd <- DataFrame(gene_id = rownames(sc_example_counts),
        feature_id = paste("feature", rep(1:500, each = 4), sep = "_"),
        median_tx_length = rnorm(2000, mean = 5000, sd = 500),
        other = sample(LETTERS, 2000, replace = TRUE)
    )
    rownames(rd) <- rownames(sc_example_counts)
    example_sce <- SingleCellExperiment(
        assays = list(counts = sc_example_counts),
        colData = sc_example_cell_info, rowData = rd
    )
    example_sce <- normalize(example_sce)

    plotExprsVsTxLength(example_sce, "median_tx_length")
    plotExprsVsTxLength(example_sce, "median_tx_length", show_smooth = TRUE)
    plotExprsVsTxLength(example_sce, "median_tx_length", show_smooth = TRUE,
        colour_by = "other", show_exprs_sd = TRUE)

    ## using matrix of tx length values in assays(object)
    mat <- matrix(rnorm(ncol(example_sce) * nrow(example_sce), mean = 5000,
        sd = 500), nrow = nrow(example_sce))
    dimnames(mat) <- dimnames(example_sce)
    assay(example_sce, "tx_len") <- mat

    plotExprsVsTxLength(example_sce, "tx_len", show_smooth = TRUE,
        length_is_assay = TRUE, show_exprs_sd = TRUE)

    ## using a vector of tx length values
    plotExprsVsTxLength(example_sce,
        data.frame(rnorm(2000, mean = 5000, sd = 500)))

[Package scater version 1.12.2 Index]