Package 'fastverse'

The fastverse

Description

The fastverse is an extensible suite of R packages, developed independently by various people, that jointly contribute to the objectives of:

1. Speeding up R through heavy use of compiled code (C, C++, Fortran)

2. Enabling more complex statistical and data manipulation operations in R

3. Reducing the number of dependencies required for advanced computing in R

Inspired by the tidyverse package, the fastverse package is a flexible package loader and manager that allows users to put together their own 'verses' of packages and load them with library(fastverse).

fastverse installs 4 core packages (data.table, collapse, kit and magrittr) that provide native C/C++ code of proven quality, work well together, and enable complex statistical computing and data manipulation - with only Rcpp as an additional dependency.

fastverse also allows users to freely (and permanently) extend or reduce the number of packages in the fastverse. An overview of high-performing packages for various common tasks is provided in the README file. An overview of the package and the different ways to extend the fastverse is provided in the vignette.

Functions in the fastverse Package

Functions to extend or reduce the number of packages in the fastverse - either for the session or permanently - and to restore defaults.

fastverse_extend()
fastverse_detach()
fastverse_reset()

Function to display conflicts for fastverse packages (or any other attached packages)

fastverse_conflicts()

Function to update fastverse packages (and dependencies) and install (missing) packages

fastverse_update()
fastverse_install()

Utilities to retrieve the names of fastverse packages (and dependencies), their update status, and produce a situation report

fastverse_packages()
fastverse_deps()
fastverse_sitrep()

Function to create a fully separate extensible meta-package/verse like fastverse

fastverse_child()

fastverse Options

• options(fastverse.quiet = TRUE) will disable all automatic messages (including conflict reporting) when calling library(fastvsers), fastverse_extend, fastverse_update(install = TRUE) and fastverse_install.

• options(fastverse.styling = FALSE) will disable all styling applied to text printed to the console.

• options(fastverse.extend = c(...)) can be set before calling library(fastvsers) to extend the fastverse with some packages for the session. The same can be done with the fastverse_extend function after library(fastvsers), which will also populate options("fastverse.extend").

• options(fastverse.install = TRUE) can be set before library(fastverse) to install any missing packages beforehand. See also fastverse_install.

fastverse Harmonizations

There are 3 internal clashes between collapse::funique and kit::funique, collapse::fduplicated and kit::fduplicated, and collapse::fdroplevels and data.table::fdroplevels. The collapse versions take precedence in all cases as they provide greater performance.

---

Create a new (descendant) verse of packages

Description

Creates and installs a fully customizable descendant verse of packages that is itself extensible and inherits 90% of the functionality of the fastverse package.

Usage

fastverse_child(
  name,
  title,
  pkg,
  maintainer,
  version = "0.1.0",
  dir = ".",
  theme = c("fastverse", "tidyverse"),
  install = TRUE,
  keep.dir = TRUE,
  ...
)

Arguments

name	character. The name of the child-verse e.g. 'myMLverse'.
title	character. The title of the child-verse e.g. 'My Machine Learning Verse'.
pkg	character. A vector of core packages for the new verse.
maintainer	character. A quoted person statement giving the package maintainer. If you do not intend to substantially modify the code of the resulting source package, role = "cre" is appropriate. See Examples.
version	character. A quoted version number for the new package.
dir	character. The directory in which a source directory dir/name for the package will be created.
theme	character. Set the colour-theme for text printed to the console. The options are "fastverse" or "tidyverse".
install	logical. TRUE installs the package using install.packages(dir/name, repos = NULL, type = "source", ...).
keep.dir	logical. FALSE will remove the source directory (dir/name) again after installation.
...	further arguments to install.packages.

Details

This function creates and installs a source package according to the users specification. For that it downloads the 'child' branch of the GitHub repository, which was specifically set up to produce a new verse, unzips it into a source directory, and substitutes the user inputs into the files. The package is then installed from source, and (optionally) the source directory is removed again.

fastverse children inherit 90% of the functionality of the fastverse package: they are not permanently globally extensible and can not bear children themselves, but can be configured for projects (using a .name config file) and extended in the session. Use of this function requires an internet connection but no additional R packages (like devtools, remotes or roxygen2).

Value

fastverse_child returns NULL invisibly.

See Also

fastverse_extend, fastverse

Examples

## Not run: 

fastverse_child(
  name = "tsverse", 
  title = "Time Series Package Verse", 
  pkg = c("xts", "roll", "zoo", "tsbox", "urca", "tseries", "tsutils", "forecast"), 
  maintainer = 'person("GivenName", "FamilyName", role = "cre", email = "[email protected]")',
  dir = "C:/Users/.../Documents", 
  theme = "tidyverse")

## End(Not run)

---

Conflicts between the fastverse and other packages

Description

This function lists all the conflicts among fastverse packages and between fastverse packages and other attached packages. It can also be used to check conflicts for any other attached packages.

Usage

fastverse_conflicts(pkg = fastverse_packages())

Arguments

pkg	character. A vector of packages to check conflicts for. The default is all fastverse packages.

Details

There are 3 internal conflicts in the core fastverse which are not displayed by fastverse_conflicts():

• collapse::funique and collapse::fdupliacted mask kit::funique and kit::fduplicated. If both packages are detached, collapse is attached after kit. In general, the collapse versions are faster and a bit more versatile. The kit versions are also very fast and additionally supports matrices!

• collapse::fdroplevels masks data.table::fdroplevels. The former is faster and supports arbitrary data structures, whereas the latter has options to exclude certain levels from being dropped.

Value

An object of class 'fastverse_conflicts': A named list of character vectors where the names are the conflicted objects, and the content are the names of the package namespaces containing the object, in the order they appear on the search path.

See Also

fastverse

Examples

# Check conflicts between fastverse packages and all attached packages
fastverse_conflicts()

# Check conflicts among all attached packages
fastverse_conflicts(rm_stub(search()[-1], "package:"))

---

List all fastverse dependencies

Description

Lists all fastverse dependencies and the local and repository (e.g. CRAN) versions of packages and dependencies.

Usage

fastverse_deps(
  pkg = fastverse_packages(),
  recursive = FALSE,
  repos = getOption("repos"),
  include.self = FALSE,
  check.deps = TRUE
)

Arguments

pkg	character vector of packages to check dependencies and versions of. The default is all fastverse packages.
recursive	logical. TRUE recursively determines all packages required to operate these packages. FALSE will only list the packages and their direct dependencies.
repos	character vector. Base URL(s) of the repositories to use, e.g., the URL of a CRAN mirror such as "https://cloud.r-project.org". The macro .fastverse_repos contains the URL of the fastverse r-universe server to check/install the development version of packages.
include.self	logical. TRUE also includes the fastverse package and checks against the repository version.
check.deps	logical. FALSE will not determine dependencies but only display the update status of packages in pkg.

Value

A data frame giving the package names, the repository and local version, and a logical variable stating whether the local version is behind the repository version.

See Also

fastverse_sitrep, fastverse

---

Detach (fastverse) packages

Description

Detaches (fastverse) packages, removing them from the search path.

Usage

fastverse_detach(
  ...,
  unload = FALSE,
  force = FALSE,
  include.self = TRUE,
  session = FALSE,
  permanent = FALSE
)

Arguments

...	comma-separated package names, quoted or unquoted, or vectors of package names. If left empty, all packages returned by fastverse_packages are detached.
unload	logical. TRUE also unloads the packages using detach(name, unload = TRUE).
force	logical. should a fastverse package be detached / unloaded even though other attached packages depend on it?
include.self	logical. TRUE also includes the fastverse package - only applicable if ... is left empty.
session	logical. TRUE also removes the packages from options("fastverse.extend"), so they will not be attached again with library(fastverse) in the current session. If ... is left empty and include.self = TRUE, this will clear all fastverse options set for the session.
permanent	logical. if ... are used to detach certain packages, permament = TRUE will disable them being loaded the next time the fastverse is loaded. This is implemented via a config file saved to the package directory. Core fastverse packages can also be detached in this way. To add a package again use extend_fastverse(..., permanent = TRUE). The config file can be removed with fastverse_reset.

Value

fastverse_detach returns NULL invisibly.

See Also

fastverse_extend, fastverse

---

Extend the fastverse

Description

Loads additional packages as part of the fastverse. By default only for the session, but extensions can be saved up to reinstallation/updating of the fastverse package.

Usage

fastverse_extend(
  ...,
  install = FALSE,
  permanent = FALSE,
  check.conflicts = !isTRUE(getOption("fastverse.quiet")),
  topics = NULL,
  repos = getOption("repos")
)

Arguments

...	comma-separated package names, quoted or unquoted, or vectors of package names.
install	logical. Install packages not available?
permanent	logical. Should packages be saved and included when library(fastverse) is called next time? Implemented via a config file saved to the package directory. The file will be removed if the fastverse is reinstalled, and can be removed without reinstallation using fastverse_reset. Packages can be removed from the config file using fastverse_detach(..., permanent = TRUE).
check.conflicts	logical. Should conflicts between extension packages and attached packages be checked?
topics	depreciated argument used to bulk-attach or install suggested extension packages prior to v0.3.0.
repos	character vector. Base URL(s) of the repositories to use, e.g., the URL of a CRAN mirror such as "https://cloud.r-project.org". The macro .fastverse_repos contains the URL of the fastverse r-universe server to check/install the development version of packages.

Details

The fastverse can be extended using a free choice of packages. An overview of high-performing packages for various tasks is provided in the README file.

When the fastverse is extended calling fastverse_extend(...), the packages that are not attached are attached, but conflicts are checked for all specified packages. If permanent = FALSE, an options("fastverse.extend") is set which stores these extension packages, regardless of whether they were already attached or not. When calling fastverse_packages, fastverse_deps, fastverse_conflicts, fastverse_update, fastverse_sitrep or fastverse_detach, these packages are included as part of the fastverse. This is also the case if permanent = TRUE, with the only difference that instead of populating the option, a file is saved to the package directory such that the packages are also loaded (as part of the core fastverse) when calling library(fastverse) in the next session. To extend the fastverse for the current session when it is not yet loaded, users can also set options(fastverse.extend = c(...)), where c(...) is a character vector of package names, before calling library(fastverse).

Value

fastverse_extend returns NULL invisibly.

See Also

fastverse_detach, fastverse

Examples

# fastverse_extend(xts, stringi, fasttime)

---

Install (missing) fastverse packages

Description

This function (by default) checks if any fastverse package is missing and installs the missing package(s). The development versions of fastverse packages can also be installed from r-universe. The link to the repository is contained in the .fastverse_repos macro.

Usage

fastverse_install(
  ...,
  only.missing = TRUE,
  install = TRUE,
  repos = getOption("repos")
)

Arguments

...	comma-separated package names, quoted or unquoted, or vectors of package names. If left empty, all packages returned by fastverse_packages are checked.
only.missing	logical. TRUE only installs packages that are unavailable. FALSE installs all packages, even if they are available.
install	logical. TRUE will proceed to install packages, whereas FALSE (recommended) will print the installation command asking you to run it in a clean R session.
repos	character vector. Base URL(s) of the repositories to use, e.g., the URL of a CRAN mirror such as "https://cloud.r-project.org". The macro .fastverse_repos contains the URL of the fastverse r-universe server to check/install the development version of packages.

Value

fastverse_install returns NULL invisibly.

Note

There is also the possibility to set options(fastverse.install = TRUE) before library(fastverse), which will call fastverse_install() before loading any packages to make sure all packages are available. If you are using a .fastverse configuration file inside a project (see vignette), you can also place _opt_fastverse.install = TRUE before the list of packages in that file.

See Also

fastverse_update, fastverse

---

List all packages in the fastverse

Description

Core packages are first fetched from a project-level configuration file (if found), else from a global configuration file (if found), otherwise the standard set of core packages is returned. In addition, if extensions = TRUE, any packages used to extend the fastverse for the current session (fetched from getOption("fastverse.extend")) are also returned.

Usage

fastverse_packages(extensions = TRUE, include.self = TRUE)

Arguments

extensions	logical. TRUE appends the set of core packages with all packages found in options("fastverse.extend").
include.self	logical. Include the fastverse package in the list?

Value

A character vector of package names.

See Also

fastverse_extend, fastverse

Examples

fastverse_packages()

---

Reset the fastverse to defaults

Description

Calling this function will remove global configuration files and (default) clear all package options. Attached packages will not be detached, and configuration files for projects (as discussed in the vignette) will not be removed.

Usage

fastverse_reset(options = TRUE)

Arguments

options

logical. TRUE also clears all fastverse options.

Value

fastverse_reset returns NULL invisibly.

See Also

fastverse_extend, fastverse

---

Get a situation report on the fastverse

Description

This function gives a quick overview of the version of R and all fastverse packages (including availability updates for packages) and indicates whether any global or project-level configuration files are used (as described in more detail the vignette).

Usage

fastverse_sitrep(...)

Arguments

...	arguments other than pkg passed to fastverse_deps.

Value

fastverse_sitrep returns NULL invisibly.

See Also

fastverse_deps, fastverse

---

Update fastverse packages

Description

This will check all fastverse packages (and their dependencies) for updates and (optionally) install those updates.

Usage

fastverse_update(..., install = FALSE, repos = getOption("repos"))

Arguments

...	arguments passed to fastverse_deps.
install	logical. TRUE will proceed to install outdated packages, whereas FALSE (recommended) will print the installation command asking you to run it in a clean R session.
repos	character vector. Base URL(s) of the repositories to use, e.g., the URL of a CRAN mirror such as "https://cloud.r-project.org". The macro .fastverse_repos contains the URL of the fastverse r-universe server to check/install the development version of packages.

Value

fastverse_update returns NULL invisibly.

See Also

fastverse_deps, fastverse

Examples

## Not run: 
## Update from CRAN
fastverse_update()

## Update from R-Universe (development versions)
fastverse_update(repos = .fastverse_repos)

## End(Not run)

---

Utilities

Description

Checks if packages are installed or attached.

Usage

is_attached(x)

is_installed(x)

Arguments

x	character. A vector of package names.

Value

A named logical vector.

---