collapse-options.RdGlobal options affecting package operation. There are 2 kinds of options, those set using options (retrievable using getOption), and those set (to avoid the performance overhead of getOption()) using set_collapse() (retrievable using get_collapse()). The latter are implemented using an environment called .op contained in the package namespace.
set_collapse(...)
get_collapse(opts = NULL)either comma separated options, or a list of options. Currently only options nthreads = integer, na.rm = TRUE|FALSE, and sort = TRUE|FALSE (only for grouping and factor generation) are supported. These are added to .op.
character. A vector of options to receive from .op, or NULL for all options.
set_collapse() returns the old content of .op invisibly as a list. get_collapse(), if called with only one option, returns the value of the option, and otherwise a list.
options()option("collapse_unused_arg_action") regulates how generic functions (such as the Fast Statistical Functions) in the package react when an unknown argument is passed to a method. The default action is "warning" which issues a warning. Other options are "error", "message" or "none", whereby the latter enables silent swallowing of such arguments.
option("collapse_mask") can be used to create additional functions in the collapse namespace when loading the package, which will mask some existing base R and dplyr functions. In particular, collapse provides a large number of functions that start with 'f' e.g. fsubset, ftransform, fdroplevels etc.. Specifying options(collapse_mask = c("fsubset", "ftransform", "fdroplevels")) before loading the package will make additional functions subset, transform, and droplevels available to the user, and mask the corresponding base R functions when the package is attached. In general, all functions starting with 'f' can be passed to the option. There are also a couple of keywords that you can specify to add groups of functions, and 2 special functions:
"manip" adds data manipulation functions: fsubset, ftransform, ftransform<-, ftransformv, fcompute, fcomputev, fselect, fselect<-, fgroup_by, fgroup_vars, fungroup, fsummarise, fsummarize, fmutate, frename, findex_by, findex
"helper" adds the functions: fdroplevels, finteraction, funique, fnunique, fduplicated, fcount, fcountv, fquantile, frange, fdist, fnlevels, fnrow and fncol.
"fast-fun" adds the functions contained in the macro: .FAST_FUN.
"fast-stat-fun" adds the functions contained in the macro: .FAST_STAT_FUN.
"fast-trfm-fun" adds the functions contained in: setdiff(.FAST_FUN, .FAST_STAT_FUN).
"all" turns on all of the above, and additionally exports a function n() for use in summarise and mutate, and masks base::table() by the much faster qtab() function.
Since v1.8.8 it is also possible to pass "n" and "qtab" directly to the option.
Note that none of these options will impact internal collapse code, but they may change the way your programs run. "manip" is probably the safest option to start with.
Specifying "fast-fun", "fast-stat-fun", "fast-trfm-fun" or "all" are ambitious as they replace basic R functions like sum and max, introducing collapse's na.rm = TRUE default (which can now be changed using set_collapse) and different behavior for matrices and data frames. These options also change some internal macros so that base R functions like sum or max called inside fsummarise, fsummarize, fmutate or collap will also receive vectorized execution. In other words, if you put options(collapse_mask = "all") before loading the package, and you have a collapse-compatible line of dplyr code like wlddev |> group_by(region, income) |> summarise(across(PCGDP:POP, sum)), this will now receive fully optimized execution.
In General, this option is for your convenience, if you want to write visually more appealing code or you want to translate existing dplyr codes to collapse. Use with care!
option("collapse_export_F"), if set to TRUE, exports the lead operator F in the package namespace. The operator was exported by default until v1.9.0, but is now hidden inside the package due to too many problems with base::F. Alternatively, the operator can be accessed using collapse:::F.
option("collapse_nthreads"), option("collapse_na.rm") and option("collapse_sort") can be set before loading the package to initialize collapse with different defaults than nthreads = 1L, na.rm = TRUE and sort = TRUE (e.g. using an .Rprofile file). Once loaded, these options have no effect, and users need to use set_collapse() to change the argument defaults.
Options "collapse_mask" and "collapse_export_F" (and "collapse_nthreads", "collapse_na.rm") need to be set before the package is loaded, which means before any component of the package is accessed in any way, including the loading of packages that depend on collapse.
A safe way to set them is by using a .Rprofile file in your user or project directory (see also here, the user-level file is located at file.path(Sys.getenv("HOME"), ".Rprofile") and can be edited using file.edit(Sys.getenv("HOME"), ".Rprofile")), or by using a .fastverse configuration file in the project directory.
# Setting new values
oldopts = set_collapse(nthreads = 2, na.rm = FALSE)
# Getting the values
get_collapse()
#> $nthreads
#> [1] 2
#>
#> $sort
#> [1] TRUE
#>
#> $na.rm
#> [1] FALSE
#>
get_collapse("nthreads")
#> [1] 2
# Resetting
set_collapse(oldopts)
rm(oldopts)