Functions now include a cache parameter

ipeaGIT · Sep 2, 2024 · 8235a1f · 8235a1f
1 parent a8b35b0
commit 8235a1f
Show file tree

Hide file tree

Showing 56 changed files with 471 additions and 96 deletions.
diff --git a/r-package/NEWS.md b/r-package/NEWS.md
@@ -3,6 +3,7 @@
 
 **Minor changes**
 
+- Functions now include a `cache` parameter that allows users to decide whehter to keep files in cache or to force downloading them again. At the moment, files are only cached during the R session, but this is a step toward future version of geobr that will be based on permanent caching.
 - Now using `curl::multi_download()` to download files in parallel
 - {geobr} now imports {fs} to use robust cross-platform file system operations
 - Removed dependency on the {httr} package

diff --git a/r-package/R/read_amazon.R b/r-package/R/read_amazon.R
@@ -8,6 +8,7 @@
 #' @param year Numeric. Year of the data in YYYY format. Defaults to `2012`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -18,7 +19,10 @@
 #' # Read Brazilian Legal Amazon
 #' a <- read_amazon(year = 2012)
 #'
-read_amazon <- function(year=2012, simplified=TRUE, showProgress=TRUE){
+read_amazon <- function(year = 2012,
+                        simplified = TRUE,
+                        showProgress = TRUE,
+                        cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="amazonia_legal", year=year, simplified=simplified)
@@ -30,7 +34,9 @@ read_amazon <- function(year=2012, simplified=TRUE, showProgress=TRUE){
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_biomes.R b/r-package/R/read_biomes.R
@@ -9,6 +9,7 @@
 #' @param year Numeric. Year of the data in YYYY format. Defaults to `2019`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -19,7 +20,10 @@
 #' # Read biomes
 #' b <- read_biomes(year = 2019)
 #'
-read_biomes <- function(year=2019, simplified=TRUE, showProgress=TRUE){
+read_biomes <- function(year = 2019,
+                        simplified = TRUE,
+                        showProgress = TRUE,
+                        cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="biomes", year=year, simplified=simplified)
@@ -28,7 +32,9 @@ read_biomes <- function(year=2019, simplified=TRUE, showProgress=TRUE){
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_capitals.R b/r-package/R/read_capitals.R
@@ -23,7 +23,8 @@
 #' # Read simple data.frame of state capitals
 #' capitals_df <- read_capitals(as_sf = FALSE)
 #'
-read_capitals <- function(as_sf = TRUE, showProgress = TRUE){
+read_capitals <- function(as_sf = TRUE,
+                          showProgress = TRUE){
 
   # check input
   if (!is.logical(as_sf)) { stop("'as_sf' must be of type 'logical'") }

diff --git a/r-package/R/read_census_tract.R b/r-package/R/read_census_tract.R
@@ -13,6 +13,7 @@
 #'             are separate data sets.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -35,7 +36,12 @@
 #' # Read all census tracts of the country at a given year
 #'   c <- read_census_tract(code_tract="all", year=2010)
 #'
-read_census_tract <- function(code_tract, year=2010, zone = "urban", simplified=TRUE, showProgress=TRUE){
+read_census_tract <- function(code_tract,
+                              year = 2010,
+                              zone = "urban",
+                              simplified = TRUE,
+                              showProgress = TRUE,
+                              cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="census_tract", year=year, simplified=simplified)
@@ -70,7 +76,9 @@ read_census_tract <- function(code_tract, year=2010, zone = "urban", simplified=
       file_url <- as.character(temp_meta$download_path)
 
       # download files
-      temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+      temp_sf <- download_gpkg(file_url = file_url,
+                               showProgress = showProgress,
+                               cache = cache)
 
       # check if download failed
       if (is.null(temp_sf)) { return(invisible(NULL)) }
@@ -105,7 +113,9 @@ read_census_tract <- function(code_tract, year=2010, zone = "urban", simplified=
 
         }
       # download files
-      sf <- download_gpkg(file_url, showProgress = showProgress)
+      sf <- download_gpkg(file_url = file_url,
+                               showProgress = showProgress,
+                               cache = cache)
 
       # check if download failed
       if (is.null(sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_comparable_areas.R b/r-package/R/read_comparable_areas.R
@@ -14,6 +14,7 @@
 #'        to `2010`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -30,7 +31,11 @@
 #' @examplesIf identical(tolower(Sys.getenv("NOT_CRAN")), "true")
 #'   amc <- read_comparable_areas(start_year=1970, end_year=2010)
 #'
-read_comparable_areas <- function(start_year=1970, end_year=2010, simplified=TRUE, showProgress=TRUE){
+read_comparable_areas <- function(start_year = 1970,
+                                  end_year = 2010,
+                                  simplified = TRUE,
+                                  showProgress = TRUE,
+                                  cache = TRUE){
 
   # tests
   years_available <- c(1872,1900,1911,1920,1933,1940,1950,1960,1970,1980,1991,2000,2010)
@@ -55,7 +60,9 @@ read_comparable_areas <- function(start_year=1970, end_year=2010, simplified=TRU
   file_url <- file_url[ file_url %like% target_year]
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_conservation_units.R b/r-package/R/read_conservation_units.R
@@ -8,6 +8,7 @@
 #' @param date Numeric. Date of the data in YYYYMM format. Defaults to `201909`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -18,7 +19,10 @@
 #' # Read conservation_units
 #' b <- read_conservation_units(date = 201909)
 #'
-read_conservation_units <- function(date=201909, simplified=TRUE, showProgress=TRUE){
+read_conservation_units <- function(date = 201909,
+                                    simplified = TRUE,
+                                    showProgress = TRUE,
+                                    cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="conservation_units", year=date, simplified=simplified)
@@ -27,7 +31,9 @@ read_conservation_units <- function(date=201909, simplified=TRUE, showProgress=T
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_country.R b/r-package/R/read_country.R
@@ -6,6 +6,7 @@
 #' @param year Numeric. Year of the data in YYYY format. Defaults to `2010`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -16,7 +17,10 @@
 #' # Read specific year
 #' br <- read_country(year = 2018)
 #'
-read_country <- function(year=2010, simplified=TRUE, showProgress=TRUE){
+read_country <- function(year = 2010,
+                         simplified = TRUE,
+                         showProgress = TRUE,
+                         cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="country", year=year, simplified=simplified)
@@ -28,7 +32,9 @@ read_country <- function(year=2010, simplified=TRUE, showProgress=TRUE){
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_disaster_risk_area.R b/r-package/R/read_disaster_risk_area.R
@@ -14,6 +14,7 @@
 #' @param year Numeric. Year of the data in YYYY format. Defaults to `2010`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -24,7 +25,10 @@
 #' # Read all disaster risk areas in an specific year
 #' d <- read_disaster_risk_area(year=2010)
 #'
-read_disaster_risk_area <- function(year=2010, simplified=TRUE, showProgress=TRUE){
+read_disaster_risk_area <- function(year = 2010,
+                                    simplified = TRUE,
+                                    showProgress = TRUE,
+                                    cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="disaster_risk_area", year=year, simplified=simplified)
@@ -33,7 +37,9 @@ read_disaster_risk_area <- function(year=2010, simplified=TRUE, showProgress=TRU
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_health_facilities.R b/r-package/R/read_health_facilities.R
@@ -20,6 +20,7 @@
 #' @param date Numeric. Date of the data in YYYYMM format. Defaults to `202303`,
 #'        which was the latest data available by the time of this update.
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -30,7 +31,9 @@
 #' # Read all health facilities of the whole country
 #' h <- read_health_facilities( date = 202303)
 #'
-read_health_facilities <- function(date = 202303, showProgress = TRUE){
+read_health_facilities <- function(date = 202303,
+                                   showProgress = TRUE,
+                                   cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="health_facilities", year=date, simplified=F)
@@ -39,7 +42,9 @@ read_health_facilities <- function(date = 202303, showProgress = TRUE){
     file_url <- as.character(temp_meta$download_path)
 
   # download files
-    temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+    temp_sf <- download_gpkg(file_url = file_url,
+                             showProgress = showProgress,
+                             cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_health_region.R b/r-package/R/read_health_region.R
@@ -13,6 +13,7 @@
 #'        regions data. If `TRUE`, the function downloads macro regions data.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -26,7 +27,11 @@
 #' # Read all macro health regions
 #' mhr <- read_health_region( year=2013, macro =TRUE)
 #'
-read_health_region <- function(year=2013, macro=FALSE, simplified=TRUE, showProgress=TRUE){
+read_health_region <- function(year = 2013,
+                               macro = FALSE,
+                               simplified = TRUE,
+                               showProgress = TRUE,
+                               cache = TRUE){
 
   if(!is.logical(macro)){stop(paste0("Parameter 'macro' must be either TRUE or FALSE"))}
 
@@ -41,7 +46,9 @@ read_health_region <- function(year=2013, macro=FALSE, simplified=TRUE, showProg
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_immediate_region.R b/r-package/R/read_immediate_region.R
@@ -12,6 +12,7 @@
 #'        immediate regions of the country.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -30,7 +31,11 @@
 #'   im <- read_immediate_region()
 #'   im <- read_immediate_region(code_immediate="all")
 #'
-read_immediate_region <- function(code_immediate="all", year=2019, simplified=TRUE, showProgress=TRUE){
+read_immediate_region <- function(code_immediate = "all",
+                                  year = 2019,
+                                  simplified = TRUE,
+                                  showProgress = TRUE,
+                                  cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="immediate_regions", year=year, simplified=simplified)
@@ -42,7 +47,9 @@ read_immediate_region <- function(code_immediate="all", year=2019, simplified=TR
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }

diff --git a/r-package/R/read_indigenous_land.R b/r-package/R/read_indigenous_land.R
@@ -11,6 +11,7 @@
 #' @param date Numeric. Date of the data in YYYYMM format. Defaults to `201907`.
 #' @template simplified
 #' @template showProgress
+#' @template cache
 #'
 #' @return An `"sf" "data.frame"` object
 #'
@@ -21,7 +22,10 @@
 #' # Read all indigenous land in an specific date
 #' i <- read_indigenous_land(date=201907)
 #'
-read_indigenous_land <- function(date=201907, simplified=TRUE, showProgress=TRUE){
+read_indigenous_land <- function(date = 201907,
+                                 simplified = TRUE,
+                                 showProgress = TRUE,
+                                 cache = TRUE){
 
   # Get metadata with data url addresses
   temp_meta <- select_metadata(geography="indigenous_land", year=date, simplified=simplified)
@@ -30,7 +34,9 @@ read_indigenous_land <- function(date=201907, simplified=TRUE, showProgress=TRUE
   file_url <- as.character(temp_meta$download_path)
 
   # download files
-  temp_sf <- download_gpkg(file_url, showProgress = showProgress)
+  temp_sf <- download_gpkg(file_url = file_url,
+                           showProgress = showProgress,
+                           cache = cache)
 
   # check if download failed
   if (is.null(temp_sf)) { return(invisible(NULL)) }