Skip to contents

Config

Toni Price

Last updated: 21 November, 2024

Source: vignettes/config.qmd

Background

This vignette describes how to configure the dimex package. See Get started for context.

For information about configuration that is relevant within a development environment, see Development.

There are two categories of configuration: localised (environment-dependent) and default package-level configuration which can be customised to a user’s circumstances if required.

Environment-dependent configuration values are specified via system environment variables, whilst package-level configuration values are specified via the config object.

System Environment Variables

.Renviron file

For localised configuration, system environment variables are specified in a file called .Renviron which, if in the default location, will be loaded automatically when you start an R session.

A user-specific .Renviron would typically be stored at:

  • Windows:
C:\Users\YourUsername\.Renviron
Ensure the file name is exactly ".Renviron" (without any file extension like
.txt)
  • Linux/macOS:
~/.Renviron

Create this file if necessary. From within R, the usethis package can do this for you:

# Create a new user-level .Renviron file, or open an existing one for editing
usethis::edit_r_environ("user")
# Or, as this is the default:
usethis::edit_r_environ()

Entries in a project-level .Renviron file, located in the working directory or project root, would take precedence over a user-specific file. Note that if such project-level file exists then it should be added to .gitignore and .Rbuildignore as it should not be committed to the source code repository or included with the package code. (The project .gitignore and .Rbuildignore contain such entries by default.)

The usethis package supports creation/editing of a project-level .Renviron file too:

# Create a new project-level .Renviron file, or open an existing one for editing
usethis::edit_r_environ("project")

NB Note that you will need to reload your .Renviron file for any changes to take effect. This can be achieved by doing one of the following:

  • Restart your R session

  • Reload .Renviron in a running R session with, e.g.

readRenviron("~/.Renviron")
(where you should replace "~/.Renviron" with the appropriate path to your
`.Renviron` file if it's not in your home directory)
  • A temporary alternative to reloading .Renviron is to manually override specific environment variables within the current R session:
Sys.setenv(VAR_NAME = "value")
This can be helpful for testing specific changes without modifying the
environment file.

Valid sys env variables

System environment variables for the dimex package start with ‘DIMEX_’.

Environment Variable name Description
main DIMEX_STORE Root path of the dimex Data and Output
ref DIMEX_STORE_REF Root path of the dimex ‘reference’ Data and Output

The config object

This configuration relates to package-level values which do not necessarily need customising, as long as a user’s data and output on their personal filesystem conforms to the expected structure.

If required, the configuration can be customised as it is stored on a per-user basis.

The config template

To create a default configuration for the first time and save it to your personal system, run:

The location of the saved configuration file is OS-specific. By default its directory is set according to your OS convention:

OS Default configuration directory
Windows C:/Users/Username/AppData/Local/R-dimex
Linux ~/.config/R-dimex
macOS ~/Library/Application Support/R-dimex

The dimex package expects to find a configuration file within this directory.

To update or recreate this config file, run:

write_user_cfg(overwrite = TRUE)

Though note that there is currently no conversion utility for existing config files so any custom changes would then need to be manually re-applied. Please make sure to back up your config file.

Default and custom config values

Defaults

[TODO: Describe defaults]

Custom

In general, defaults can be overridden by manually editing the config.

[TODO: Show examples of overriding the defaults]