Configuration files

Many times we have a set of values used by a workflow that aren’t exactly data, but are values for parameters and arguments. These are typically stored in a configuration file which can come in a variety of standard formats. A common format is YAML which is a name-value pairing written in plain text, and it is easy work with in R.

An example configuration file

Here we have a small configuration file. It looks like this:

site_id: site_01
researcher: JPO
time: 2020-05-16T07:26:25 UTC
shade: 30.0
gps_codes:
- c
- q
- q

Most items have a simple name-value association such as shade = 30.0, while others have more complex associations like gps_codes = c("c", "q", "q").

Reading a configuration file

The yaml R package will read and write YAML files. In R the contents of the file become a named list.

cfg = yaml::read_yaml("data/guppy/site_01/site_01.yaml") 
str(cfg)

List of 5
 $ site_id   : chr "site_01"
 $ researcher: chr "JPO"
 $ time      : chr "2020-05-16T07:26:25 UTC"
 $ shade     : num 30
 $ gps_codes : chr [1:3] "c" "q" "q"

Note that items have been read as charcater (string) or number. Other data types are possibke but these two are the most common.

Modifying a configuration

You can update a value in the configuration. The following are all equivalent modifications.

cfg$shade = 25.0
cfg[["shade"]] = 25.0
cfg[[4]] = 25.0

You can add a name-value pairing.

cfg$alphabet = letters[1:5]
str(cfg)

List of 6
 $ site_id   : chr "site_01"
 $ researcher: chr "JPO"
 $ time      : chr "2020-05-16T07:26:25 UTC"
 $ shade     : num 25
 $ gps_codes : chr [1:3] "c" "q" "q"
 $ alphabet  : chr [1:5] "a" "b" "c" "d" ...

And then you can remove an element.

cfg$time = NULL
str(cfg)

List of 5
 $ site_id   : chr "site_01"
 $ researcher: chr "JPO"
 $ shade     : num 25
 $ gps_codes : chr [1:3] "c" "q" "q"
 $ alphabet  : chr [1:5] "a" "b" "c" "d" ...

Writing a configuration file

To write the configuration we can use the yaml R package again.

yaml::write_yaml(cfg, "~/my_test_config.yaml")

Tip

The easiest way to get a configuration going is to start a named list in R for your important items, and then save that to a YAML file. You can edit it as a text file to modify, add or remove elements.