Merge pull request #14 from adamhsparks/example_data

DESCRIPTION

@@ -3,7 +3,7 @@ Package: read.abares
 Title: Provides simple downloading, parsing and importing of Australian
     Bureau of Agricultural and Resource Economics and Sciences (ABARES)
     data sources
-Version: 0.1.0
+Version: 1.0.0
 Authors@R: c(
     person("Adam H.", "Sparks", , "[email protected]", role = c("cre", "aut"),
            comment = c(ORCID = "0000-0002-0061-8359")),

NAMESPACE

@@ -3,31 +3,31 @@
 S3method(print,read.abares.agfd.nc.files)
 S3method(print,read.abares.soil.thickness.files)
 export(clear_cache)
-export(get_aagis_regions)
-export(get_abares_trade)
-export(get_abares_trade_regions)
 export(get_agfd)
-export(get_est_by_perf_cat)
-export(get_est_by_size)
-export(get_estimates_by_performance_category)
-export(get_estimates_by_size)
-export(get_hist_nat_est)
-export(get_hist_reg_est)
-export(get_hist_sta_est)
-export(get_historical_forecast)
-export(get_historical_forecast_database)
-export(get_historical_national_estimates)
-export(get_historical_regional_estimates)
-export(get_historical_state_estimates)
 export(get_soil_thickness)
 export(inspect_cache)
 export(plot)
 export(print_agfd_nc_file_format)
 export(print_soil_thickness_metadata)
+export(read_aagis_regions)
+export(read_abares_trade)
+export(read_abares_trade_regions)
 export(read_agfd_dt)
 export(read_agfd_stars)
 export(read_agfd_terra)
 export(read_agfd_tidync)
+export(read_est_by_perf_cat)
+export(read_est_by_size)
+export(read_estimates_by_performance_category)
+export(read_estimates_by_size)
+export(read_hist_nat_est)
+export(read_hist_reg_est)
+export(read_hist_sta_est)
+export(read_historical_forecast)
+export(read_historical_forecast_database)
+export(read_historical_national_estimates)
+export(read_historical_regional_estimates)
+export(read_historical_state_estimates)
 export(read_soil_thickness_stars)
 export(read_soil_thickness_terra)
 importFrom(data.table,":=")

NEWS.md

@@ -1,3 +1,49 @@
+# read.abares 1.0.0
+
+## Major changes
+
+* Rename functions that both download and read files into active R session from `get_` to `read_` to avoid confusion with functions that only fetch data and have separate `read_` functions
+
+* Adds new function, `print_agfd_nc_file_format()` to provide details on the AGFD NetCDF files' contents
+
+* Uses Geopackages for {sf} objects rather than .Rds, faster and smaller file sizes when caching
+
+* Checks and corrects the geometries of the AAGIS Regions shapefile upon import and applies to the cached object if applicable
+
+## Bug fixes
+
+* No longer checks the length of a Boolean vector when checking the number of files in the cache before proceeding with removing them
+
+* Fixes bugs in `get_agfd()` when creating the directories for saving the downloaded file
+
+* Fixes bug in `get_aagis_regions()` when creating the cached object file
+
+* Fixes "URL" field in DESCRIPTION file, thanks @mpadge
+
+## Minor changes
+
+* Improved documentation
+
+  * All data sets now have an `@source` field that points to the file being provided
+
+  *  All data sets now have an `@references` field that points to references for the data
+
+* Code linting thanks to [{flint}](https://flint.etiennebacher.com)
+
+* Use {httr2} to handle downloads
+
+  * Increase timeout values to deal with stubborn long-running file downloads
+
+* Use {brio} to write downloads to disk
+
+* Use {httptest2} to help test downloads
+
+* Gracefully handle errors when AGFD zip files are corrupted on download, provide the user with an informative message and remove corrupted download
+
+* Tests are run in parallel for quicker testing
+
+* {sf} operations are now quiet when reading data where possible
+
 # read.abares 0.1.0
 
 - Submission to rOpenSci for [peer code review](https://github.com/ropensci/software-review/issues)

R/get_agfd.R

@@ -1,5 +1,5 @@
 
-#' Fetch Australian Gridded Farm Data
+#' Get Australian Gridded Farm Data for Local Use
 #'
 #' Downloads The Australian Gridded Farm Data (\acronym{AGFD}) data and unzips
 #'  the compressed files to NetCDF for importing.
@@ -265,7 +265,7 @@ print_agfd_nc_file_format <- function() {
   cli::cat_line()
   cli::cli_dl(
     c(
-      "{.strong CRS}" = "EPSG:4326 - WGS 84 – Geographic",
+      "{.strong CRS}" = "EPSG:4326 - WGS 84 - Geographic",
       "{.strong Extent}" = "111.975 -44.525 156.275 -9.975",
       "{.strong Unit}" = "Degrees",
       "{.strong Width}" = "886",

R/get_soil_thickness.R

@@ -1,4 +1,5 @@
-#' Download Soil Thickness for Australian Areas of Intensive Agriculture of Layer 1
+
+#' Get Soil Thickness for Australian Areas of Intensive Agriculture of Layer 1 for Local Use
 #'
 #' @param cache `Boolean` Cache the soil thickness data files after download
 #' using `tools::R_user_dir()` to identify the proper directory for storing

R/globals.R

@@ -2,8 +2,8 @@
 
 utils::globalVariables(c(
   "Year_month", # <.download_abares_trade>
-  "Month_issued", # <get_historical_forecast_database>
   "lat", # <read_agfd_dt>
   "lon", # <read_agfd_dt>
+  "Month_issued", # <read_historical_forecast_database>
   NULL
 ))

R/get_aagis_regions.R → R/read_aagis_regions.R

@@ -1,5 +1,5 @@
 
-#' Get AAGIS Region Mapping Files
+#' Read AAGIS Region Mapping Files
 #'
 #' Download, cache and import the Australian Agricultural and Grazing
 #'  Industries Survey (\acronym{AAGIS} regions geospatial shapefile. Upon
@@ -14,7 +14,7 @@
 #'  closing of the \R session.
 #'
 #' @examplesIf interactive()
-#' aagis <- get_aagis_regions()
+#' aagis <- read_aagis_regions()
 #'
 #' plot(aagis)
 #'
@@ -27,7 +27,7 @@
 #' @autoglobal
 #' @export
 
-get_aagis_regions <- function(cache = TRUE) {
+read_aagis_regions <- function(cache = TRUE) {
   aagis <- .check_existing_aagis(cache)
   if (is.null(aagis)) {
     aagis <- .download_aagis_shp(cache)

R/get_abares_trade.R → R/read_abares_trade.R

@@ -1,4 +1,5 @@
-#' Get Data From the ABARES Trade Dashboard
+
+#' Read Data From the ABARES Trade Dashboard
 #'
 #' Fetches and imports  \acronym{ABARES} trade data.
 #'
@@ -13,7 +14,7 @@
 #'  and the files are deleted upon closing of the \R session.
 #'
 #' @examplesIf interactive()
-#' trade <- get_abares_trade()
+#' trade <- read_abares_trade()
 #'
 #' trade
 #'
@@ -24,7 +25,7 @@
 #' @autoglobal
 #' @export
 
-get_abares_trade <- function(cache = TRUE) {
+read_abares_trade <- function(cache = TRUE) {
   abares_trade_rds <- file.path(.find_user_cache(),
                                 "abares_trade_dir/abares_trade.rds")
 

R/get_abares_trade_regions.R → R/read_abares_trade_regions.R

@@ -1,4 +1,4 @@
-#' Get ABARES Trade Data Regions From the ABARES Trade Dashboard
+#' Read ABARES Trade Data Regions From the ABARES Trade Dashboard
 #'
 #' Fetches and imports  \acronym{ABARES} trade regions data.
 #'
@@ -13,7 +13,7 @@
 #'  `tempdir()` and the files are deleted upon closing of the \R session.
 #'
 #' @examplesIf interactive()
-#' trade_regions <- get_abares_trade_regions()
+#' trade_regions <- read_abares_trade_regions()
 #'
 #' trade_regions
 #'
@@ -25,7 +25,7 @@
 #' @autoglobal
 #' @export
 
-get_abares_trade_regions <- function(cache = TRUE) {
+read_abares_trade_regions <- function(cache = TRUE) {
   trade_regions <- .check_existing_trade_regions(cache)
   if (!is.null(trade_regions)) {
     return(trade_regions[])

R/get_estimates_by_performance_category.R → R/read_estimates_by_performance_category.R

@@ -1,5 +1,5 @@
 
-#' Get Estimates by Size From ABARES
+#' Read Estimates by Size From ABARES
 #'
 #' @return A [data.table::data.table] object
 #' @export
@@ -9,12 +9,12 @@
 #' @autoglobal
 #' @examplesIf interactive()
 #'
-#'  get_estimates_by_performance_category()
+#'  read_estimates_by_performance_category()
 #'
 #'  # or shorter
-#'  get_est_by_perf_cat()
+#'  read_est_by_perf_cat()
 #'
-get_estimates_by_performance_category <- get_est_by_perf_cat <- function() {
+read_estimates_by_performance_category <- read_est_by_perf_cat <- function() {
 
   f <- file.path(tempdir(), "fdp-BySize-ByPerformance.csv")
 
@@ -27,5 +27,5 @@ get_estimates_by_performance_category <- get_est_by_perf_cat <- function() {
 }
 
 #' @export
-#' @rdname get_estimates_by_performance_category
-get_est_by_perf_cat <- get_estimates_by_performance_category
+#' @rdname read_estimates_by_performance_category
+read_est_by_perf_cat <- read_estimates_by_performance_category

R/get_estimates_by_size.R → R/read_estimates_by_size.R

@@ -1,5 +1,5 @@
 
-#' Get Estimates by Size From ABARES
+#' Read Estimates by Size From ABARES
 #'
 #' @note
 #' Columns are renamed and reordered for consistency.
@@ -13,12 +13,12 @@
 #' @export
 #' @examplesIf interactive()
 #'
-#' get_estimates_by_size()
+#' read_estimates_by_size()
 #'
 #' # or shorter
-#' get_est_by_size()
+#' read_est_by_size()
 #'
-get_estimates_by_size <- get_est_by_size <- function() {
+read_estimates_by_size <- read_est_by_size <- function() {
 
   f <- file.path(tempdir(), "fdp-beta-performance-by-size.csv")
 
@@ -35,5 +35,5 @@ get_estimates_by_size <- get_est_by_size <- function() {
 }
 
 #' @export
-#' @rdname get_estimates_by_size
-get_est_by_size <- get_estimates_by_size
+#' @rdname read_estimates_by_size
+read_est_by_size <- read_estimates_by_size

R/get_historical_forecast_database.R → R/read_historical_forecast_database.R

@@ -1,5 +1,5 @@
 
-#' Get Historical Forecast Database From ABARES
+#' Read Historical Forecast Database From ABARES
 #'
 #' # Data Dictionary
 #' The resulting object will contain the following fields.
@@ -26,21 +26,21 @@
 #' The "Month_issued" column is converted from a character string to a numeric
 #'  value representing the month of year, _e.g._, "March" is converted to `3`.
 #'
-#' @source <https://daff.ent.sirsidynix.net.au/client/en_AU/search/asset/1031941/0>
 #' @references <https://www.agriculture.gov.au/abares/research-topics/agricultural-outlook/historical-forecasts#:~:text=About%20the%20historical%20agricultural%20forecast,relevant%20to%20Australian%20agricultural%20markets>
+#' @source <https://daff.ent.sirsidynix.net.au/client/en_AU/search/asset/1031941/0>
 #'
-#' @return A [data.table::data.table] object.
+#' @return A [data.table::data.table] object
 #'
 #' @autoglobal
 #' @export
 #' @examplesIf interactive()
 #'
-#' get_historical_forecast_database()
+#' read_historical_forecast_database()
 #'
 #' # or shorter
-#' get_historical_forecast()
+#' read_historical_forecast()
 #'
-get_historical_forecast_database <- function() {
+read_historical_forecast_database <- function() {
 
   f <- file.path(tempdir(), "historical_db.xlsx")
 
@@ -110,5 +110,5 @@ get_historical_forecast_database <- function() {
 }
 
 #' @export
-#' @rdname get_historical_forecast_database
-get_historical_forecast <- get_historical_forecast_database
+#' @rdname read_historical_forecast_database
+read_historical_forecast <- read_historical_forecast_database

R/get_historical_national_estimates.R → R/read_historical_national_estimates.R

@@ -1,5 +1,5 @@
 
-#' Get Historical National Estimates from ABARES
+#' Read Historical National Estimates from ABARES
 #'
 #' @note
 #' Columns are renamed for consistency with other \acronym{ABARES} products
@@ -14,12 +14,12 @@
 #' @export
 #' @examplesIf interactive()
 #'
-#'  get_historical_national_estimates()
+#'  read_historical_national_estimates()
 #'
 #'  # or shorter
-#'  get_hist_nat_est()
+#'  read_hist_nat_est()
 #'
-get_historical_national_estimates <- function() {
+read_historical_national_estimates <- function() {
 
   f <- file.path(tempdir(), "fdp-beta-national-historical.csv")
 
@@ -34,5 +34,5 @@ get_historical_national_estimates <- function() {
 }
 
 #' @export
-#' @rdname get_historical_national_estimates
-get_hist_nat_est <- get_historical_national_estimates
+#' @rdname read_historical_national_estimates
+read_hist_nat_est <- read_historical_national_estimates

R/get_historical_regional_estimates.R → R/read_historical_regional_estimates.R

@@ -1,5 +1,5 @@
 
-#' Get Historical Regional Estimates from ABARES
+#' Read Historical Regional Estimates from ABARES
 #'
 #' @note
 #' Columns are renamed for consistency with other \acronym{ABARES} products
@@ -13,12 +13,12 @@
 #' @source <https://www.agriculture.gov.au/sites/default/files/documents/fdp-regional-historical.csv>
 #' @export
 #' @examplesIf interactive()
-#'  get_historical_regional_estimates()
+#'  read_historical_regional_estimates()
 #'
 #'  # or shorter
-#'  get_hist_reg_est()
+#'  read_hist_reg_est()
 #'
-get_historical_regional_estimates <- get_hist_reg_est <-  function() {
+read_historical_regional_estimates <- read_hist_reg_est <-  function() {
 
   f <- file.path(tempdir(), "fdp-beta-regional-historical.csv")
 
@@ -39,5 +39,5 @@ get_historical_regional_estimates <- get_hist_reg_est <-  function() {
 }
 
 #' @export
-#' @rdname get_historical_regional_estimates
-get_hist_reg_est <- get_historical_regional_estimates
+#' @rdname read_historical_regional_estimates
+read_hist_reg_est <- read_historical_regional_estimates