Summarize SummarizedExperiment

Usage

# S3 method for class 'SummarizedExperiment'
summarise(.data, ..., .retain = c("auto", "ungrouped", "none"))

Arguments

.data: a SummarizedExperiment object,
...: expressions to summarize the object
.retain: This argument controls how rowData() or colData() is retained after summarizing. When "auto" (the default), .retain behavior depends on the groupings of .data. When exactly one dimension is grouped, "auto" behaves like "ungrouped-dim", and "none" otherwise. When "ungrouped-dim", the ungrouped dimension's data are retained in the resulting SummarizedExperiment object and scalar outputs are recycled to the length of the ungrouped dimension. When "none", all outputs are expected to be scalar and only computed values are retained in rowData() and colData()

Value

an object inheriting SummarizedExperiment class

Examples


# outputs in assay context may be either
# length 1, or the length of the ungrouped
# dimension while .retain = "auto"/"ungrouped-dim"
se_simple |>
  group_by(rows(direction)) |>
  summarise(col_sums = colSums(counts),
            sample = sample(1:20, 1L))
#> class: SummarizedExperiment 
#> dim: 2 4 
#> metadata(1): group_data
#> assays(2): col_sums sample
#> rownames: NULL
#> rowData names(1): direction
#> colnames(4): col_1 col_2 col_3 col_4
#> colData names(2): sample condition

# .retain = "none" will drop ungrouped dimensions and
# outputs of assay context should be length 1.
se_simple |>
  group_by(rows(direction)) |>
  summarise(col_sums = list(colSums(counts)),
            .retain = "none")
#> class: SummarizedExperiment 
#> dim: 2 1 
#> metadata(1): group_data
#> assays(1): col_sums
#> rownames: NULL
#> rowData names(1): direction
#> colnames: NULL
#> colData names(0):

# using an `across()` function will help
# nest ungrouped dimensions
se_simple |>
  group_by(rows(direction)) |>
  summarise(col_sums = list(colSums(counts)),
            cols(across(everything(), list)),
             .retain = "none")
#> class: SummarizedExperiment 
#> dim: 2 1 
#> metadata(1): group_data
#> assays(1): col_sums
#> rownames: NULL
#> rowData names(1): direction
#> colnames: NULL
#> colData names(2): sample condition