Download and load GADM-DOSE geometries — getDOSE

This function downloads and loads GADM-DOSE geometries from a remote source. The geometries are stored in a temporary directory by default, or in a user-specified location if provided. The uncompressed geometries file is approximately 769 MB.

Usage

getDOSE_geom(path = NULL, countries = NULL, download = FALSE, cache = FALSE)

Arguments

path: Optional character string specifying where to store the files. If NULL (default), uses tempdir(). Cannot be combined with cache = TRUE.
countries: Optional vector of ISO3C country codes to filter geometries. If NULL (default), all available geometries are returned.
download: Logical indicating whether to download without confirmation. Default is FALSE, which will prompt for confirmation in interactive sessions. Set to TRUE to skip confirmation.
cache: Logical. If TRUE, stores the downloaded geometries in a persistent per-user cache directory (see subincomeR_cache_dir()) so they are reused across R sessions. Default is FALSE, which stores the files in tempdir() for the current session only.

Value

An sf object containing the GADM-DOSE geometries, or NULL (invisibly, with an informative message) if the geometries could not be downloaded or read, for example when there is no internet connection, the remote resource is temporarily unavailable, or the download was canceled by the user.

Examples

# \donttest{
# Load all geometries with download confirmation
geom_all <- getDOSE_geom()
#> 
#> The GADM-DOSE geometries file is approximately 769 MB when uncompressed.
#> 
#> Downloading GADM-DOSE geometries...
#> Download successful
#> Extracting files...
#> 
#> Geometries saved in /tmp/RtmpkJOxQH

# Load geometries with automatic download
geom_auto <- getDOSE_geom(download = TRUE)
#> 
#> Geometries saved in /tmp/RtmpkJOxQH

# Load geometries for specific countries
geom_subset <- getDOSE_geom(
  countries = c("USA", "CAN", "MEX"),
  download = TRUE
)
#> 
#> Geometries saved in /tmp/RtmpkJOxQH
# }

if (FALSE) { # \dontrun{
# Store the geometries in a persistent cache to avoid re-downloading
# the ~769 MB file in every R session
geom_cached <- getDOSE_geom(download = TRUE, cache = TRUE)
} # }