Setup and configuration • pviem

1 Introduction

This vignette describes how to set up and configure the pviem package. Read the documentation in this order: vignette("setup"), vignette("data"), vignette("pviem"), and then vignette("workflow").

2 Installation and loading

The package is currently distributed via GitHub. Example installation options are shown below. Use build_vignettes = TRUE to build vignettes during installation and dependencies = TRUE to install required packages.

## install.packages("devtools")
## From CRAN (not yet available)
# install.packages("pviem")
## Latest stable release from GitHub
# devtools::install_github("SACEMA/pviem", build_vignettes = TRUE, dependencies = TRUE)
## Development branch
# devtools::install_github("SACEMA/pviem@dev", build_vignettes = TRUE, dependencies = TRUE)
## Specific tag or release (replace <tag> with an available release tag)
# devtools::install_github("SACEMA/pviem@<tag>", build_vignettes = TRUE, dependencies = TRUE)

After installation, load the package as usual. For faster sampling you can enable parallel processing with the furrr package; set an appropriate plan (for example, multisession) before running estimation routines.

library(pviem)
# library(furrr)
# plan(multisession, workers = min(4L, availableCores()))

3 Configuration

The package stores session-wide settings (column mappings, time settings, etc.) in an internal configuration. You must initialize these settings before running analyses. Three helpers are provided:

config_pviem(): Set or update the global configuration for the current R session. Use this for persistent settings.
with_config(): Temporarily override configuration values for the duration of a code block; the original configuration is restored afterwards.
local_config(): Temporarily override configuration within a local scope (e.g., inside a function or a local() call); the original configuration is restored when the scope exits.

Both with_config() and local_config() use scoped changes (see ?withr::withr for details). The package also provides get_pviem_config() to inspect the active configuration.

Below are examples that demonstrate common configuration tasks. Adjust column names and arguments to match your data.

# Inspect current configuration
get_pviem_config()
#> $admin
#> [1] "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

# Set (or reset) the global configuration
config_pviem(
  admin = "dist_code",
  year = "year",
  month = "month",
  birth = "live_births",
  monthly = FALSE
)

# Inspect to confirm
get_pviem_config()
#> $admin
#> [1] "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

The previous configuration is equivalent to the default settings, so you can omit the call to config_pviem() if you are using the default column names and time settings. However, if your datasets use different column names or if you want to enable monthly data handling, you will need to call config_pviem() with the appropriate arguments.

# Enable monthly data handling
config_pviem(monthly = TRUE)

get_pviem_config()
#> $admin
#> [1] "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] TRUE

# Use multiple administrative columns (hierarchical IDs)
config_pviem(admin = c("prov_code", "dist_code"))

get_pviem_config()
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

Note: config_pviem() updates the global configuration and resets any unspecified parameters to their default values. Use with_config() or local_config() when you need temporary or scoped changes.

# Temporarily override settings with with_config()
with_config(
  list(year = "record_year"),
  {
    # run analyses using the temporary configuration here
    get_pviem_config()
  }
)
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "record_year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

get_pviem_config() # original configuration restored
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

# Temporarily override settings within a local scope
local({
  local_config(list(birth = "births"))
  # run analyses using the temporary configuration here
  get_pviem_config()
})
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "births"
#> 
#> $monthly
#> [1] FALSE

get_pviem_config() # original configuration restored
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

# Example use inside a function
my_analysis_function <- function() {
  local_config(list(year = "record_year", month = "record_month"))
  # scoped analysis here
  get_pviem_config()
}
my_analysis_function()
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "record_year"
#> 
#> $month
#> [1] "record_month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

get_pviem_config()
#> $admin
#> [1] "prov_code" "dist_code"
#> 
#> $year
#> [1] "year"
#> 
#> $month
#> [1] "month"
#> 
#> $birth
#> [1] "live_births"
#> 
#> $monthly
#> [1] FALSE

Scoped configuration functions modify only the parameters you specify and leave the rest unchanged. If the active configuration is incomplete or invalid, downstream functions will fail, including data validation, which is essential for ensuring that inputs are correctly formatted (see vignette("data")).