An equivalent to dplyr::select() that works on the genotype column
of a gen_tibble, using the mini-grammar available for tidyselect. The
select-like evaluation only has access to the names of the loci (i.e. it
can select only based on names, not summary statistics of those loci; look
at select_loci_if() for that feature.
Usage
select_loci(.data, .sel_arg, .engine = c("auto", "tidyselect"))Arguments
- .data
a
gen_tibble- .sel_arg
one unquoted expression, using the mini-grammar of
dplyr::select()to select loci. Variable names can be used as if they were positions in the data frame, so expressions like x:y can be used to select a range of variables.- .engine
how the selection is resolved: "auto" (the default) resolves the common selections described in Details directly, and leaves the others to
tidyselect; "tidyselect" always usestidyselect, which is slow and memory hungry with millions of loci.
Details
Note that the select_loci verb does not modify the backing FBM files,
but rather it subsets the list of loci to be used stored in the gen_tibble.
For large datasets (millions of loci), select loci with dplyr::all_of()
or dplyr::any_of(), with helpers that match names (such as
dplyr::starts_with() or dplyr::everything()), with numeric positions
written as numbers (e.g. 1:100 or -c(1, 5)), with a function call
that gives positions or names (e.g. which(...), sample(...) or
sort(x)), or with a variable that holds positions or names (e.g.
select_loci(x, idx)), each optionally negated with - or !. These
selections are resolved directly, which is much faster and uses much less
memory than the general tidyselect machinery, which has to create an R
symbol for every locus name (and R never frees symbols). As in
tidyselect, a locus with the same name as the variable is selected
instead of the value of the variable, and selecting with a variable gives
the deprecation warning of tidyselect: prefer all_of(idx), which can
not be confused with a locus named idx. Other expressions (e.g.
combinations such as c(all_of(x), starts_with("rs")), or bare loci
names) still work, but are slow and memory hungry on very large datasets.
To always use tidyselect (e.g. if a selection is not resolved as
tidyselect would resolve it), set .engine = "tidyselect".
Examples
example_gt <- load_example_gt("gen_tbl")
# Select loci by name
example_gt_subset <- example_gt %>%
select_loci(all_of(c("rs1", "rs2", "rs3")))
show_loci(example_gt_subset)
#> # A tibble: 3 × 7
#> big_index name chromosome position genetic_dist allele_ref allele_alt
#> <int> <chr> <fct> <int> <dbl> <chr> <chr>
#> 1 1 rs1 chr1 3 0 A T
#> 2 2 rs2 chr1 5 0 T C
#> 3 3 rs3 chr1 65 0 C NA
# Select loci by index
example_gt_subset <- example_gt %>% select_loci(all_of(c(4, 2, 1)))
show_loci(example_gt_subset)
#> # A tibble: 3 × 7
#> big_index name chromosome position genetic_dist allele_ref allele_alt
#> <int> <chr> <fct> <int> <dbl> <chr> <chr>
#> 1 4 rs4 chr1 343 0 G C
#> 2 2 rs2 chr1 5 0 T C
#> 3 1 rs1 chr1 3 0 A T
# Always use tidyselect to resolve the selection
example_gt_subset <- example_gt %>%
select_loci(all_of(c(4, 2, 1)), .engine = "tidyselect")
