Nesting creates a list-column of data frames; unnesting flattens it back out into regular columns. Nesting is implicitly a summarising operation: you get one row for each group defined by the non-nested columns. This is useful in conjunction with other summaries that work with whole datasets, most notably models.
Learn more in vignette("nest").
# S3 method for SpatialExperiment
nest(.data, ..., .names_sep = NULL)Arguments
- .data
A data frame.
- ...
<
tidy-select> Columns to nest; these will appear in the inner data frames.Specified using name-variable pairs of the form
new_col = c(col1, col2, col3). The right hand side can be any valid tidyselect expression.If not supplied, then
...is derived as all columns not selected by.by, and will use the column name from.key.![[Deprecated]](figures/lifecycle-deprecated.svg)
:
previously you could write df %>% nest(x, y, z). Convert todf %>% nest(data = c(x, y, z)).- .names_sep
If
NULL, the default, the inner names will come from the former outer names. If a string, the new inner names will use the outer names withnames_sepautomatically stripped. This makesnames_seproughly symmetric between nesting and unnesting.
Value
tidySpatialExperiment_nested
Details
If neither ... nor .by are supplied, nest() will nest all variables,
and will use the column name supplied through .key.
New syntax
tidyr 1.0.0 introduced a new syntax for nest() and unnest() that's
designed to be more similar to other functions. Converting to the new syntax
should be straightforward (guided by the message you'll receive) but if
you just need to run an old analysis, you can easily revert to the previous
behaviour using nest_legacy() and unnest_legacy() as follows:
Grouped data frames
df %>% nest(data = c(x, y)) specifies the columns to be nested; i.e. the
columns that will appear in the inner data frame. df %>% nest(.by = c(x, y)) specifies the columns to nest by; i.e. the columns that will remain in
the outer data frame. An alternative way to achieve the latter is to nest()
a grouped data frame created by dplyr::group_by(). The grouping variables
remain in the outer data frame and the others are nested. The result
preserves the grouping of the input.
Variables supplied to nest() will override grouping variables so that
df %>% group_by(x, y) %>% nest(data = !z) will be equivalent to
df %>% nest(data = !z).
You can't supply .by with a grouped data frame, as the groups already
represent what you are nesting by.
Examples
example(read10xVisium)
#>
#> rd10xV> dir <- system.file(
#> rd10xV+ file.path("extdata", "10xVisium"),
#> rd10xV+ package = "SpatialExperiment")
#>
#> rd10xV> sample_ids <- c("section1", "section2")
#>
#> rd10xV> samples <- file.path(dir, sample_ids, "outs")
#>
#> rd10xV> list.files(samples[1])
#> [1] "raw_feature_bc_matrix" "spatial"
#>
#> rd10xV> list.files(file.path(samples[1], "spatial"))
#> [1] "scalefactors_json.json" "tissue_lowres_image.png"
#> [3] "tissue_positions_list.csv"
#>
#> rd10xV> file.path(samples[1], "raw_feature_bc_matrix")
#> [1] "/home/runner/work/_temp/Library/SpatialExperiment/extdata/10xVisium/section1/outs/raw_feature_bc_matrix"
#>
#> rd10xV> (spe <- read10xVisium(samples, sample_ids,
#> rd10xV+ type = "sparse", data = "raw",
#> rd10xV+ images = "lowres", load = FALSE))
#> # A SpatialExperiment-tibble abstraction: 99 × 7
#> # Features = 50 | Cells = 99 | Assays = counts
#> .cell in_tissue array_row array_col sample_id pxl_col_in_fullres
#> <chr> <lgl> <int> <int> <chr> <int>
#> 1 AAACAACGAATAGTTC-1 FALSE 0 16 section1 2312
#> 2 AAACAAGTATCTCCCA-1 TRUE 50 102 section1 8230
#> 3 AAACAATCTACTAGCA-1 TRUE 3 43 section1 4170
#> 4 AAACACCAATAACTGC-1 TRUE 59 19 section1 2519
#> 5 AAACAGAGCGACTCCT-1 TRUE 14 94 section1 7679
#> 6 AAACAGCTTTCAGAAG-1 FALSE 43 9 section1 1831
#> 7 AAACAGGGTCTATATT-1 FALSE 47 13 section1 2106
#> 8 AAACAGTGTTCCTGGG-1 FALSE 73 43 section1 4170
#> 9 AAACATGGTGAGAGGA-1 FALSE 62 0 section1 1212
#> 10 AAACATTTCCCGGATT-1 FALSE 61 97 section1 7886
#> # ℹ 89 more rows
#> # ℹ 1 more variable: pxl_row_in_fullres <int>
#>
#> rd10xV> # base directory 'outs/' from Space Ranger can also be omitted
#> rd10xV> samples2 <- file.path(dir, sample_ids)
#>
#> rd10xV> (spe2 <- read10xVisium(samples2, sample_ids,
#> rd10xV+ type = "sparse", data = "raw",
#> rd10xV+ images = "lowres", load = FALSE))
#> # A SpatialExperiment-tibble abstraction: 99 × 7
#> # Features = 50 | Cells = 99 | Assays = counts
#> .cell in_tissue array_row array_col sample_id pxl_col_in_fullres
#> <chr> <lgl> <int> <int> <chr> <int>
#> 1 AAACAACGAATAGTTC-1 FALSE 0 16 section1 2312
#> 2 AAACAAGTATCTCCCA-1 TRUE 50 102 section1 8230
#> 3 AAACAATCTACTAGCA-1 TRUE 3 43 section1 4170
#> 4 AAACACCAATAACTGC-1 TRUE 59 19 section1 2519
#> 5 AAACAGAGCGACTCCT-1 TRUE 14 94 section1 7679
#> 6 AAACAGCTTTCAGAAG-1 FALSE 43 9 section1 1831
#> 7 AAACAGGGTCTATATT-1 FALSE 47 13 section1 2106
#> 8 AAACAGTGTTCCTGGG-1 FALSE 73 43 section1 4170
#> 9 AAACATGGTGAGAGGA-1 FALSE 62 0 section1 1212
#> 10 AAACATTTCCCGGATT-1 FALSE 61 97 section1 7886
#> # ℹ 89 more rows
#> # ℹ 1 more variable: pxl_row_in_fullres <int>
#>
#> rd10xV> # tabulate number of spots mapped to tissue
#> rd10xV> cd <- colData(spe)
#>
#> rd10xV> table(
#> rd10xV+ in_tissue = cd$in_tissue,
#> rd10xV+ sample_id = cd$sample_id)
#> sample_id
#> in_tissue section1 section2
#> FALSE 28 27
#> TRUE 22 22
#>
#> rd10xV> # view available images
#> rd10xV> imgData(spe)
#> DataFrame with 2 rows and 4 columns
#> sample_id image_id data scaleFactor
#> <character> <character> <list> <numeric>
#> 1 section1 lowres #### 0.0510334
#> 2 section2 lowres #### 0.0510334
spe |>
nest(data = -sample_id)
#> # A tibble: 2 × 2
#> sample_id data
#> <chr> <list>
#> 1 section1 <SptlExpr[,50]>
#> 2 section2 <SptlExpr[,49]>