Global 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
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
character. A vector of options to receive from
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.
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
"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.
fdroplevels etc.. Specifying
options(collapse_mask = c("fsubset", "ftransform", "fdroplevels")) before loading the package will make additional functions
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:
"fast-fun" adds the functions contained in the macro:
"fast-stat-fun" adds the functions contained in the macro:
"fast-trfm-fun" adds the functions contained in:
"all" turns on all of the above, and additionally exports a function
n() for use in
mutate, and masks
base::table() by the much faster
Since v1.8.8 it is also possible to pass
"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.
"all" are ambitious as they replace basic R functions like
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
max called inside
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
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.
"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 #>  2 #> #> $sort #>  TRUE #> #> $na.rm #>  FALSE #> get_collapse("nthreads") #>  2 # Resetting set_collapse(oldopts) rm(oldopts)