Set your giscoR cache directory

Stores your cache_dir path on your local machine and loads it in future sessions. Use Sys.getenv("GISCO_CACHE_DIR") or gisco_detect_cache_dir() to find your cached path.

Usage

gisco_set_cache_dir(
  cache_dir = NULL,
  overwrite = FALSE,
  install = FALSE,
  verbose = TRUE
)

gisco_detect_cache_dir()

Arguments

cache_dir: A path to a cache directory. If NULL, the function stores cached files in a temporary directory (see base::tempdir()).
overwrite: If TRUE, overwrite an existing GISCO_CACHE_DIR that you already have on your local machine.
install: If TRUE, install the cache path on your local machine for use in future sessions. Defaults to FALSE. If cache_dir is FALSE, install is automatically set to FALSE.
verbose: A logical value indicating whether to display informational messages.

Value

gisco_set_cache_dir() invisibly returns a character string with the path to your cache_dir, but it is mainly called for its side effect.

gisco_detect_cache_dir() returns the path to the cache_dir used in this session.

Details

By default, when no cache cache_dir is set, the package uses a folder inside base::tempdir() (so files are temporary and are removed when the R session ends). To persist a cache across R sessions, use gisco_set_cache_dir(cache_dir, install = TRUE), which writes the chosen path to a small configuration file under tools::R_user_dir("giscoR", "config").

Note

In giscoR >= 1.0.0 the location of the configuration file has moved from rappdirs::user_config_dir("giscoR", "R") to tools::R_user_dir("giscoR", "config"). We have implemented a function that migrates previous configuration files from one location to another with a message. The message appears only once to inform you of the migration.

Caching strategies

Some files can be read from their online source without caching using the option cache = FALSE. Otherwise the source file is downloaded to your computer. giscoR implements the following caching options:

For occasional use, rely on the default tempdir()-based cache (no install).
Modify the cache for a single session by setting gisco_set_cache_dir(cache_dir = "a/path/here").
For reproducible workflows, install a persistent cache with gisco_set_cache_dir(cache_dir = "a/path/here", install = TRUE), which keeps the path across R sessions.
For caching specific files, use the cache_dir argument in the corresponding function. See example in gisco_get_nuts().

Sometimes cached files may be corrupt. In that case, try downloading the data by setting update_cache = TRUE in the corresponding function.

If you experience a download problem, try to download the corresponding file by another method and save it in your cache_dir. Use verbose = TRUE to debug the API query and gisco_detect_cache_dir() to identify your cached path.

Examples


# Do not run this. It modifies your current state.
# \dontrun{
my_cache <- gisco_detect_cache_dir()
#> ℹ /tmp/RtmpmpngxH/giscoR

# Set an example cache.
ex <- file.path(tempdir(), "example", "cachenew")
gisco_set_cache_dir(ex)
#> ℹ giscoR cache directory is /tmp/RtmpmpngxH/example/cachenew.
#> ℹ To install your `cache_dir` path for future sessions, run this function with `install` = TRUE.

gisco_detect_cache_dir()
#> ℹ /tmp/RtmpmpngxH/example/cachenew
#> [1] "/tmp/RtmpmpngxH/example/cachenew"

# Restore the initial cache.
gisco_set_cache_dir(my_cache)
#> ℹ giscoR cache directory is /tmp/RtmpmpngxH/giscoR.
#> ℹ To install your `cache_dir` path for future sessions, run this function with `install` = TRUE.
identical(my_cache, gisco_detect_cache_dir())
#> ℹ /tmp/RtmpmpngxH/giscoR
#> [1] TRUE
# }


gisco_detect_cache_dir()
#> ℹ /tmp/RtmpmpngxH/giscoR
#> [1] "/tmp/RtmpmpngxH/giscoR"