Development

About this vignette

This vignette deals with how to use the dimex package as a developer. See also the Get started and Configuration vignettes.

Installation

Clone the GitHub repository:

$ git clone https://github.com/UoMResearchIT/SPFFinalReport.git

Setup

For a development environment:

devtools

Ensure devtools is installed:
```
install.packages("devtools")
```

Ensure required packages are installed:

install.packages(c("cli", "DescTools", "dplyr", "ggplot2", "gridExtra",
                   "haven", "lubridate", "magrittr", "openair", "plyr",
                   "proxy", "purrr", "rappdirs", "raster", "readr",
                   "reshape2", "scales", "sf", "sp", "stringr",
                   "truncnorm", "yaml"))

See the Configuration vignette for configuration information.

Some useful dev commands

These commands should be executed from the R console.

(Note that when devtools is installed, the following commands are usually bound to keyboard shortcuts in RStudio; these are shown in the comments where applicable.)

Load the development version of the package:

# Ctrl/Cmd + Shift + L
devtools::load_all(".")

Run the automated test suite:

# Ctrl/Cmd + Shift + T
devtools::test(".")

Create package documentation:

# Ctrl/Cmd + Shift + D
devtools::document(roclets = c('rd', 'collate', 'namespace'))

Build the package vignettes:

devtools::build_vignettes()

Run a package check:

# Ctrl/Cmd + Shift + E
devtools::check()

Test the current file:

If you are using RStudio, this can be most easily achieved by setting a keyboard shortcut.

For example, in RStudio
- Go to Tools | Modify Keyboard Shortcuts…
- In the Filter… bar type ‘test’
- Locate the ‘Run a test’ Addin, select its Shortcut and type ‘Ctrl + T’ (or whatever your preferred key sequence is), then click Apply
This shortcut will now run devtools:::test_active_file().

Development configuration

Variables in `.Renviron`

You can specify environment variables to control whether to run the ‘high-level’ data tests (that is, the tests which check saved reference data against datasets produced by the running code).

These are slow – many of them take ~10 seconds to run – so they are skipped by default. To run them you need to set system environment variables in the .Renviron file at the root of the package directory:
```
DIMEX_RUN_ALL_HLDT=true  # Set to 'true' or 'false' (or do not specify)
DIMEX_RUN_HLDT_1*=true   # Set to 'true' or 'false' (or do not specify)
```
That is, either set DIMEX_RUN_ALL_HLDT=true, or for each test you wish to run, set the appropriate DIMEX_RUN_HLDT_1*=true, for example:
```
DIMEX_RUN_HLDT_1A=true
DIMEX_RUN_HLDT_1D=true
```
Note that if any of these environment variables does not exist, or is set to anything other than ‘true’, the corresponding high level data tests will not run.

In this way it is possible to run only the test relevant to what you are currently working on, whilst still running the rest of the test suite.

Use DIMEX_RUN_ALL_HLDT=true to run all the high-level data tests, irrespective of any DIMEX_RUN_HLDT_1* values. In other words, if DIMEX_RUN_ALL_HLDT=true it will override the individual settings. This can be useful after making some changes and checking an individual test, to then easily verify that all the high-level data tests still pass.

To temporarily set a specific high-level data test to run in the current R session, run (for e.g.):

# Set the high-level data test for step "1a" to run
Sys.setenv(DIMEX_RUN_HLDT_1A = "true")

To reverse this, do one of the following:

Sys.setenv(DIMEX_RUN_HLDT_1A = "false")
# Or:
Sys.unsetenv("DIMEX_RUN_HLDT_1A")

To temporarily set all the high-level data tests to run in the current R session, use:
```
Sys.setenv(DIMEX_RUN_ALL_HLDT = "true")
```
To reverse this, do one of the following:
```
Sys.setenv(DIMEX_RUN_ALL_HLDT = "false")
# Or:
Sys.unsetenv("DIMEX_RUN_ALL_HLDT")
```

Updating the config template

To update the config template, edit the function generate_cfg_template().

Note NB: After updating the config template, save an updated copy to the package config location by running:

write_cfg_template()

If you change the template, you will need to update user config files that have already been created.

There is currently no mechanism to convert the format of a user config file so until such time as this can be implemented, any local changes to a user config will need to be manually re-applied.