Get the path of the cache folder

Returns the path of the cache folder, where the package saves results on disk for reuse. By default, cacs_isochrone(), cacs_acs_prefetch(), and cacs_intersect_weight() each save their results in a subfolder of it (isochrone, acs, and intersect), and a later call that matches an earlier one reads the saved result instead of computing or downloading it again. The help page of each function says what must match.

Usage

cacs_cache_dir(create = FALSE)

Arguments

create

A logical value. If FALSE (the default), the path is returned without creating the folder. If TRUE, the folder is created, together with any missing parent folders, when it does not exist, and an error is given if it cannot be created.

Value

A string giving the path of the cache folder.

Details

The cache folder is the first of these that is set and not empty:

1. the option catchmentACS.cache_dir;

2. the environment variable CACS_CACHE_DIR;

3. a folder named catchmentACS inside the temporary folder of the R session (see tempdir()), which R deletes when the session ends.

The folder is worked out again at every call, so a change to the option or the environment variable takes effect at once.

How saved results are checked

Each saved result is an .rds file with a checksum file (.fingerprint) next to it. When a saved result is read, its checksum is computed again and compared with the one in the checksum file. If the checksum file is missing or not in the expected form, if the .rds file cannot be read, or if the checksums differ, both files are deleted and the result is computed or downloaded again. When saved American Community Survey (ACS) data are read, cacs_acs_prefetch() also warns if they look incomplete.

A cache folder that lasts between sessions

Results saved in the default folder are deleted when the R session ends. To keep them for later sessions, set the option or the environment variable to a folder that lasts, for example with this line in the R startup file (see Startup):

options(catchmentACS.cache_dir = tools::R_user_dir("catchmentACS", "cache"))

tools::R_user_dir() gives a folder for the cache files of one package, inside the user's cache folder for R; where that is depends on the operating system.

A cache folder outside the temporary folder of the session is tidied once per session, the first time a result is read from it or saved in it while the cache is on. These files are deleted:

• results not used for 30 days, with their checksum and GeoPackage files. Reading a saved result counts as using it. The option catchmentACS.cache_max_age_days sets another number of days, and Inf keeps results however old they are. Its value when the folder is first used in the session is the one that counts, so set it in the R startup file next to catchmentACS.cache_dir, for example options(catchmentACS.cache_max_age_days = 90); a value that is not a single positive number counts as 30;

• GeoPackage files as old as that without a result;

• files left by an interrupted write, and results or checksum files without their partner, when they are more than a day old.

Only files named the way the package names its saved files, in the subfolders isochrone, acs, acs_test, and intersect, are deleted.

Versions 0.5.1 and earlier saved results in the user cache folder of the operating system: ~/Library/Caches/catchmentACS on macOS, ~/.cache/catchmentACS on Linux, and catchmentACS/catchmentACS/Cache inside the folder named by the environment variable LOCALAPPDATA on Windows. The package no longer reads or deletes that folder; delete it yourself if it is not needed.

See also

Other cache and configuration: cacs_cache_status(), cacs_clear_cache(), cacs_get_cache_state(), cacs_set_cache()

Examples

# The path of the cache folder, without creating the folder
cacs_cache_dir(create = FALSE)
#> [1] "/tmp/RtmpMhGiu5/catchmentACS"