diff --git a/DESCRIPTION b/DESCRIPTION index 62235345..45eaadce 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: amadeus Title: AMADEUS: A Machine for Data, Environments, and User Setup for common environmental and climate health datasets -Version: 0.2.0 +Version: 0.3.0 Authors@R: c( person("Mitchell", "Manware", role = c("aut", "ctb"), comment = c(ORCID = "0009-0003-6440-6106")), person("Insang", "Song", role = c("aut", "ctb"), comment = c(ORCID = "0000-0001-8732-3256")), @@ -10,14 +10,15 @@ Authors@R: c( ) Description: A Mechanism/Machine for Data, Environments, and User Setup package for health and climate research. It is fully tested, versioned, and open source and open access. Depends: R (>= 4.1.0) -Imports: dplyr, sf, sftime, stats, terra, methods, data.table, httr, rvest, exactextractr, utils, stringi, testthat (>= 3.0.0), parallelly, stars, future, future.apply, tidyr, rlang, rstac, nhdplusTools, archive, collapse, devtools +Imports: dplyr, sf, sftime, stats, terra, methods, data.table, httr, rvest, exactextractr, utils, stringi, testthat (>= 3.0.0), parallelly, stars, future, future.apply, tidyr, rlang, rstac, nhdplusTools, archive, collapse, Rdpack Suggests: covr, withr, knitr, rmarkdown, lwgeom, FNN, doRNG +RdMacros: Rdpack Encoding: UTF-8 VignetteBuilder: knitr, rmarkdown Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.1 +RoxygenNote: 7.3.2 Config/Needs/website: tidyverse/tidytemplate Config/testhat/edition: 3 License: MIT + file LICENSE URL: https://github.com/NIEHS/amadeus, -https://niehs.github.io/amadeus/ +BugReports: https://github.com/NIEHS/amadeus/issues diff --git a/NAMESPACE b/NAMESPACE index 2595c1ff..0c610087 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -18,6 +18,7 @@ export(calc_narr) export(calc_nei) export(calc_nlcd) export(calc_prepare_locs) +export(calc_return_locs) export(calc_sedac_groads) export(calc_sedac_population) export(calc_sedc) @@ -45,8 +46,7 @@ export(download_huc) export(download_koppen_geiger) export(download_merra2) export(download_modis) -export(download_narr_monolevel) -export(download_narr_p_levels) +export(download_narr) export(download_nei) export(download_nlcd) export(download_olm) @@ -69,9 +69,10 @@ export(generate_date_sequence) export(generate_time_sequence) export(is_date_proper) export(list_stac_files) +export(narr_variable) export(process_aqs) -export(process_bluemarble) -export(process_bluemarble_corners) +export(process_blackmarble) +export(process_blackmarble_corners) export(process_collection) export(process_conformity) export(process_covariates) @@ -122,6 +123,7 @@ import(rvest) import(sf) import(sftime) import(stars) +importFrom(Rdpack,reprompt) importFrom(archive,archive_extract) importFrom(collapse,rowbind) importFrom(data.table,.SD) @@ -165,6 +167,7 @@ importFrom(rstac,read_items) importFrom(rstac,read_stac) importFrom(sf,st_as_sf) importFrom(sf,st_as_sfc) +importFrom(sf,st_bbox) importFrom(sf,st_crs) importFrom(sf,st_drop_geometry) importFrom(sf,st_geometry) @@ -212,6 +215,7 @@ importFrom(terra,vect) importFrom(terra,vector_layers) importFrom(testthat,expect_true) importFrom(tidyr,pivot_wider) +importFrom(tools,file_path_sans_ext) importFrom(utils,download.file) importFrom(utils,head) importFrom(utils,read.csv) diff --git a/R/calculate_covariates.R b/R/calculate_covariates.R index 3c1f03b2..efd2cbc5 100644 --- a/R/calculate_covariates.R +++ b/R/calculate_covariates.R @@ -22,7 +22,7 @@ #' - [`calc_koppen_geiger`]: `"koppen-geiger"`, `"koeppen-geiger"`, `"koppen"` #' - [`calc_ecoregion`]: `"ecoregion"`, `"ecoregions"` #' - [`calc_temporal_dummies`]: `"dummies"` -#' - [`calc_hms`]: `"hms"`, `"noaa"`, `"smoke"` +#' - [`calc_hms`]: `"hms"`, `"smoke"` #' - [`calc_gmted`]: `"gmted"` #' - [`calc_narr`]: `"narr"` #' - [`calc_geos`]: `"geos"`, `"geos_cf"` @@ -34,8 +34,19 @@ #' - [`calc_merra2`]: `"merra"`, `"MERRA"`, `"merra2"`, `"MERRA2"` #' - [`calc_gridmet`]: `"gridMET"`, `"gridmet"` #' - [`calc_terraclimate`]: `"terraclimate"`, `"TerraClimate"` -#' @returns Calculated covariates. Mainly data.frame object. +#' @return Calculated covariates as a data.frame or SpatVector object #' @author Insang Song +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_covariates( +#' covariate = "narr", +#' from = narr, # derived from process_covariates() example +#' locs = loc, +#' locs_id = "id", +#' geom = FALSE +#' ) +#' } #' @export # nolint end calc_covariates <- @@ -44,7 +55,7 @@ calc_covariates <- "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "sedac_groads", "groads", "roads", - "ecoregions", "ecoregion", "hms", "noaa", "smoke", + "ecoregions", "ecoregion", "hms", "smoke", "gmted", "narr", "geos", "sedac_population", "population", "nlcd", "merra", "merra2", "gridmet", "terraclimate", @@ -68,7 +79,6 @@ calc_covariates <- koppen = calc_koppen_geiger, narr = calc_narr, nlcd = calc_nlcd, - noaa = calc_hms, smoke = calc_hms, hms = calc_hms, sedac_groads = calc_sedac_groads, @@ -120,16 +130,13 @@ calc_covariates <- #' @param locs sf/SpatVector. Unique locs. Should include #' a unique identifier field named `locs_id` #' @param locs_id character(1). Name of unique identifier. -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @seealso [`process_koppen_geiger`] -#' @returns a data.frame object -#' @note The returned `data.frame` object contains a +#' @return a data.frame or SpatVector object +#' @note The returned object contains a #' `$description` column to represent the temporal range covered by the #' dataset. For more information, see #' . @@ -142,6 +149,16 @@ calc_covariates <- #' @importFrom terra coltab #' @importFrom terra merge #' @importFrom methods is +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_koppen_geiger( +#' from = kg, # derived from process_koppen_geiger() example +#' locs = loc, +#' locs_id = "id", +#' geom = FALSE +#' ) +#' } #' @export # locs (locs), from (from), locs_id (id_col), variables calc_koppen_geiger <- @@ -226,10 +243,18 @@ calc_koppen_geiger <- names(kg_extracted)[1] <- locs_id if (geom) { names(kg_extracted)[2:3] <- c("geometry", "description") + sites_return <- calc_return_locs( + covar = kg_extracted, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) + #### return data.frame + return(sites_return) } else { names(kg_extracted)[2] <- "description" + return(kg_extracted) } - return(kg_extracted) } @@ -251,12 +276,9 @@ calc_koppen_geiger <- #' Maximum possible value is `2^31 - 1`. Only valid when #' `mode = "exact"`. #' See [`exactextractr::exact_extract`] for details. -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param nthreads integer(1). Number of threads to be used #' @param ... Placeholders. #' @note NLCD is available in U.S. only. Users should be aware of @@ -267,7 +289,7 @@ calc_koppen_geiger <- #' but uses more memory as it will account for the partial overlap #' with the buffer. #' @seealso [`process_nlcd`] -#' @returns a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom utils read.csv #' @importFrom methods is #' @importFrom terra rast @@ -284,6 +306,17 @@ calc_koppen_geiger <- #' @importFrom future plan multicore sequential #' @importFrom future.apply future_Map #' @importFrom collapse rowbind +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_nlcd( +#' from = nlcd, # derived from process_nlcd() example +#' locs = loc, +#' locs_id = "id", +#' mode = "exact", +#' geom = FALSE +#' ) +#' } #' @export calc_nlcd <- function(from, locs, @@ -356,8 +389,8 @@ calc_nlcd <- function(from, class_query <- "value" # ratio of each nlcd class per buffer bufs_polx <- bufs_pol[terra::ext(from), ] |> - sf::st_as_sf() |> - sf::st_geometry() + sf::st_as_sf() + nlcd_at_bufs <- future.apply::future_Map( function(i) { exactextractr::exact_extract( @@ -366,9 +399,10 @@ calc_nlcd <- function(from, fun = "frac", force_df = TRUE, progress = FALSE, + append_cols = locs_id, max_cells_in_memory = max_cells ) - }, seq_len(length(bufs_polx)), + }, seq_len(nrow(bufs_polx)), future.seed = TRUE ) nlcd_at_bufs <- collapse::rowbind(nlcd_at_bufs, fill = TRUE) @@ -402,7 +436,12 @@ calc_nlcd <- function(from, } else { names(new_data_vect)[1:2] <- c(locs_id, "time") } - calc_check_time(covar = new_data_vect, POSIXt = FALSE) + new_data_vect <- calc_return_locs( + covar = new_data_vect, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) future::plan(future::sequential) return(new_data_vect) } @@ -419,20 +458,28 @@ calc_nlcd <- function(from, #' @param locs sf/SpatVector. Unique locs. Should include #' a unique identifier field named `locs_id` #' @param locs_id character(1). Name of unique identifier. -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @seealso [`process_ecoregion`] -#' @returns a data.frame object with dummy variables and attributes of: +#' @return a data.frame or SpatVector object object with dummy variables and +#' attributes of: #' - `attr(., "ecoregion2_code")`: Ecoregion lv.2 code and key #' - `attr(., "ecoregion3_code")`: Ecoregion lv.3 code and key #' @author Insang Song #' @importFrom terra extract #' @importFrom data.table year +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_ecoregion( +#' from = ecoregion, # derived from process_ecoregion() example +#' locs = loc, +#' locs_id = "id", +#' geom = FALSE +#' ) +#' } #' @export calc_ecoregion <- function( @@ -495,14 +542,16 @@ calc_ecoregion <- paste0("1997 - ", data.table::year(Sys.Date())), df_lv2, df_lv3 ) - if (geom) { - names(locs_ecoreg)[3] <- "description" - } else { - names(locs_ecoreg)[2] <- "description" - } - attr(locs_ecoreg, "ecoregion2_code") <- sort(unique(from$L2_KEY)) - attr(locs_ecoreg, "ecoregion3_code") <- sort(unique(from$L3_KEY)) - return(locs_ecoreg) + locs_return <- calc_return_locs( + covar = locs_ecoreg, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) + names(locs_return)[2] <- "description" + attr(locs_return, "ecoregion2_code") <- sort(unique(from$L2_KEY)) + attr(locs_return, "ecoregion3_code") <- sort(unique(from$L3_KEY)) + return(locs_return) } @@ -521,6 +570,9 @@ calc_ecoregion <- #' @param max_cells integer(1). Maximum number of cells to be read at once. #' Higher values will expedite processing, but will increase memory usage. #' Maximum possible value is `2^31 - 1`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' See [`exactextractr::exact_extract`] for details. #' @param ... Placeholders. #' @description The function operates at MODIS/VIIRS products @@ -533,10 +585,10 @@ calc_ecoregion <- #' the file names at users' discretion. #' @seealso #' * Preprocessing: [process_modis_merge()], [process_modis_swath()], -#' [process_bluemarble()] +#' [process_blackmarble()] #' * Parallelization: [calc_modis_par()] #' @author Insang Song -#' @returns A data.frame object. +#' @return a data.frame or SpatVector object. #' @importFrom terra extract #' @importFrom terra project #' @importFrom terra vect @@ -545,6 +597,20 @@ calc_ecoregion <- #' @importFrom methods is #' @importFrom sf st_as_sf #' @importFrom sf st_drop_geometry +#' @examples +#' \dontrun{ +#' locs <- data.frame(lon = -78.8277, lat = 35.95013, id = "001") +#' calc_modis_daily( +#' from = mod06l2_warp, +#' locs = locs, +#' locs_id = "id", +#' radius = 0, +#' date = "2024-01-01", +#' name_extracted = "cloud_fraction_0", +#' fun_summary = "mean", +#' max_cells = 3e7 +#' ) +#' } #' @export calc_modis_daily <- function( from = NULL, @@ -555,6 +621,7 @@ calc_modis_daily <- function( name_extracted = NULL, fun_summary = "mean", max_cells = 3e7, + geom = FALSE, ... ) { if (!methods::is(locs, "SpatVector")) { @@ -615,9 +682,38 @@ calc_modis_daily <- function( name_range <- seq(ncol(extracted) - name_offset + 1, ncol(extracted), 1) colnames(extracted)[name_range] <- name_extracted extracted$time <- as.POSIXlt(date) - calc_check_time(covar = extracted, POSIXt = TRUE) + if (geom) { + # convert to base date, as terra::vect does not like class "POSIXlt" + extracted$time <- as.Date.POSIXlt(extracted$time) + # location ID with geometry + locs_geom_id <- suppressMessages(calc_prepare_locs( + from = from, + locs = locs, + locs_id = locs_id, + radius = radius, + geom = geom + )[[2]] + ) + # merge + extracted_merge <- merge( + locs_geom_id, + extracted, + by = locs_id + ) + # re-convert to POSIXlt after creating the vect + extracted_merge$time <- as.POSIXlt(extracted_merge$time) + extracted_return <- calc_return_locs( + covar = extracted_merge, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) + } else { + calc_check_time(covar = extracted, POSIXt = TRUE) + extracted_return <- extracted + } gc() - return(extracted) + return(extracted_return) } @@ -632,7 +728,7 @@ calc_modis_daily <- function( #' @param name_covariates character. Name header of covariates. #' e.g., `"MOD_NDVIF_0_"`. #' The calculated covariate names will have a form of -#' '{name_covariates}{zero-padded buffer radius in meters}', +#' "\code{\{name_covariates\}\{zero-padded buffer radius in meters\}}", #' e.g., 'MOD_NDVIF_0_50000' where 50 km radius circular buffer #' was used to calculate mean NDVI value. #' @param subdataset Indices, names, or search patterns for subdatasets. @@ -651,6 +747,9 @@ calc_modis_daily <- function( #' Higher values will expedite processing, but will increase memory usage. #' Maximum possible value is `2^31 - 1`. #' See [`exactextractr::exact_extract`] for details. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Arguments passed to `preprocess`. #' @description `calc_modis_par` essentially runs [`calc_modis_daily`] function #' in each thread (subprocess). Based on daily resolution, each day's workload @@ -676,14 +775,14 @@ calc_modis_daily <- function( #' e.g., `"^LST_"` #' * `process_modis_swath()`: Subdataset names. #' e.g., `c("Cloud_Fraction_Day", "Cloud_Fraction_Night")` -#' * `process_bluemarble()`: Subdataset number. +#' * `process_blackmarble()`: Subdataset number. #' e.g., for VNP46A2 product, 3L. #' Dates with less than 80 percent of the expected number of tiles, #' which are determined by the mode of the number of tiles, are removed. #' Users will be informed of the dates with insufficient tiles. #' The result data.frame will have an attribute with the dates with #' insufficient tiles. -#' @returns A data.frame with an attribute: +#' @return A data.frame or SpatVector with an attribute: #' * `attr(., "dates_dropped")`: Dates with insufficient tiles. #' Note that the dates mean the dates with insufficient tiles, #' not the dates without available tiles. @@ -700,7 +799,7 @@ calc_modis_daily <- function( #' Also, for preprocessing, please refer to: #' * [`process_modis_merge()`] #' * [`process_modis_swath()`] -#' * [`process_bluemarble()`] +#' * [`process_blackmarble()`] #' @importFrom methods is #' @importFrom sf st_as_sf #' @importFrom sf st_drop_geometry @@ -712,6 +811,23 @@ calc_modis_daily <- function( #' @importFrom future cluster #' @importFrom future.apply future_lapply #' @importFrom parallelly availableWorkers +#' @examples +#' \dontrun{ +#' locs <- data.frame(lon = -78.8277, lat = 35.95013, id = "001") +#' locs <- terra::vect(locs, geom = c("lon", "lat"), crs = "EPSG:4326") +#' calc_modis_par( +#' from = +#' list.files("./data", pattern = "VNP46A2.", full.names = TRUE), +#' locs = locs, +#' locs_id = "site_id", +#' radius = c(0L, 1000L), +#' preprocess = process_modis_merge, +#' name_covariates = "cloud_fraction_0", +#' subdataset = "Cloud_Fraction", +#' fun_summary = "mean", +#' nthreads = 1 +#' ) +#' } #' @export calc_modis_par <- function( @@ -727,11 +843,12 @@ calc_modis_par <- package_list_add = NULL, export_list_add = NULL, max_cells = 3e7, + geom = FALSE, ... ) { if (!is.function(preprocess)) { stop("preprocess should be one of process_modis_merge, -process_modis_swath, or process_bluemarble.") +process_modis_swath, or process_blackmarble.") } # read all arguments # nolint start @@ -751,6 +868,7 @@ process_modis_swath, or process_bluemarble.") summary_available_mode <- as.numeric(names(summary_available_mode)) summary_available_insuf <- which(summary_available < floor(summary_available_mode * 0.8)) + if (length(summary_available_insuf) > 0) { dates_insuf <- as.Date(dates_available[summary_available_insuf], "%Y%j") @@ -836,7 +954,8 @@ process_modis_swath, or process_bluemarble.") fun_summary = fun_summary, name_extracted = name_radius, radius = radius[k], - max_cells = max_cells + max_cells = max_cells, + geom = FALSE ) ) if (inherits(extracted, "try-error")) { @@ -867,9 +986,22 @@ process_modis_swath, or process_bluemarble.") future.seed = TRUE ) calc_results <- do.call(dplyr::bind_rows, calc_results) - attr(calc_results, "dates_dropped") <- dates_insuf + if (geom) { + # merge + calc_results_return <- merge( + locs, + calc_results, + by = locs_id + ) + if ("sf" %in% class(calc_results_return)) { + calc_results_return <- terra::vect(calc_results_return) + } + } else { + calc_results_return <- calc_results + } + attr(calc_results_return, "dates_dropped") <- dates_insuf Sys.sleep(1L) - return(calc_results) + return(calc_results_return) } @@ -882,20 +1014,33 @@ process_modis_swath, or process_bluemarble.") #' @param locs_id character(1). Unique site identifier column name. #' Default is `"site_id"`. #' @param year integer. Year domain to dummify. -#' Default is \code{seq(2018L, 2022L)} +#' Default is \code{seq(2018L, 2022L)}. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. -#' @returns a data.frame object +#' @return a data.frame or SpatVector object #' @author Insang Song #' @importFrom methods is #' @importFrom data.table year #' @importFrom data.table month #' @importFrom data.table as.data.table +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_temporal_dummies( +#' locs = loc, +#' locs_id = "id", +#' year = seq(2018L, 2022L) +#' ) +#' } #' @export calc_temporal_dummies <- function( locs, locs_id = "site_id", year = seq(2018L, 2022L), + geom = FALSE, ... ) { if (!methods::is(locs, "data.frame")) { @@ -950,7 +1095,15 @@ calc_temporal_dummies <- dt_month_dum, dt_wday_dum ) - return(locs_dums) + + # geom + locs_return <- calc_return_locs( + covar = locs_dums, + POSIXt = TRUE, + geom = geom, + crs = "EPSG:4326" + ) + return(locs_return) } @@ -964,7 +1117,10 @@ calc_temporal_dummies <- #' Distance at which the source concentration is reduced to #' `exp(-3)` (approximately -95 %) #' @param target_fields character(varying). Field names in characters. -#' @returns a data.frame (tibble) object with input field names with +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` +#' @return a data.frame (tibble) or SpatVector object with input field names with #' a suffix \code{"_sedc"} where the sums of EDC are stored. #' Additional attributes are attached for the EDC information. #' - `attr(result, "sedc_bandwidth")``: the bandwidth where @@ -1018,7 +1174,8 @@ calc_sedc <- locs = NULL, locs_id = NULL, sedc_bandwidth = NULL, - target_fields = NULL + target_fields = NULL, + geom = FALSE ) { if (!methods::is(locs, "SpatVector")) { locs <- try(terra::vect(locs)) @@ -1091,10 +1248,25 @@ The result may not be accurate.\n", names(res_sedc)[idx_air] <- sprintf("%s_%05d", names(res_sedc)[idx_air], sedc_bandwidth) - attr(res_sedc, "sedc_bandwidth") <- sedc_bandwidth - attr(res_sedc, "sedc_threshold") <- sedc_bandwidth * 2 - calc_check_time(covar = res_sedc, POSIXt = TRUE) - return(res_sedc) + if (geom) { + res_sedc <- merge( + terra::as.data.frame(locs, geom = "WKT")[, c("site_id", "geometry")], + res_sedc, + "site_id" + ) + } + + res_sedc_return <- calc_return_locs( + covar = res_sedc, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) + + attr(res_sedc_return, "sedc_bandwidth") <- sedc_bandwidth + attr(res_sedc_return, "sedc_threshold") <- sedc_bandwidth * 2 + + return(res_sedc_return) } @@ -1111,9 +1283,12 @@ The result may not be accurate.\n", #' Default is `"site_id"`. #' @param radius Circular buffer radius. #' Default is \code{c(1000, 10000, 50000)} (meters) +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @author Insang Song, Mariana Kassien -#' @returns a data.frame object +#' @return a data.frame or SpatVector object #' @note U.S. context. #' @seealso [`calc_sedc`], [`process_tri`] #' @importFrom terra vect @@ -1131,12 +1306,23 @@ The result may not be accurate.\n", #' @importFrom dplyr group_by #' @importFrom dplyr ungroup #' @importFrom dplyr summarize +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_tri( +#' from = tri, # derived from process_tri() example +#' locs = loc, +#' locs_id = "id", +#' radius = c(1e3L, 1e4L, 5e4L) +#' ) +#' } #' @export calc_tri <- function( from = NULL, locs, locs_id = "site_id", radius = c(1e3L, 1e4L, 5e4L), + geom = FALSE, ... ) { if (!methods::is(locs, "SpatVector")) { @@ -1165,21 +1351,31 @@ calc_tri <- function( from = from, locs_id = locs_id, sedc_bandwidth = x, - target_fields = tri_cols + target_fields = tri_cols, + geom = FALSE ) return(locs_tri_s) }, list_radius ) + # bind element data.frames into one df_tri <- Reduce(function(x, y) dplyr::full_join(x, y), list_locs_tri) if (nrow(df_tri) != nrow(locs)) { df_tri <- dplyr::left_join(as.data.frame(locs), df_tri) } + + df_tri_return <- calc_return_locs( + covar = df_tri, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) + # read attr - df_tri$time <- as.integer(attr(from, "tri_year")) - calc_check_time(covar = df_tri, POSIXt = FALSE) - return(df_tri) + df_tri_return$time <- as.integer(attr(from, "tri_year")) + + return(df_tri_return) } @@ -1188,19 +1384,32 @@ calc_tri <- function( #' @param locs sf/SpatVector. Locations at NEI values are joined. #' @param locs_id character(1). Unique site identifier column name. #' Unused but kept for compatibility. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @author Insang Song, Ranadeep Daw #' @seealso [`process_nei`] -#' @returns a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom methods is #' @importFrom terra project #' @importFrom terra intersect +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_nei( +#' from = nei, # derived from process_nei example, +#' locs = loc, +#' locs_id = "id" +#' ) +#' } #' @export calc_nei <- function( from = NULL, locs = NULL, locs_id = "site_id", + geom = FALSE, ... ) { if (!methods::is(locs, "SpatVector")) { @@ -1213,8 +1422,14 @@ calc_nei <- function( locs_re <- terra::project(locs, terra::crs(from)) locs_re <- terra::intersect(locs_re, from) locs_re <- as.data.frame(locs_re) - calc_check_time(covar = locs_re, POSIXt = FALSE) - return(locs_re) + + locs_return <- calc_return_locs( + covar = locs_re, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) + return(locs_return) } @@ -1231,74 +1446,71 @@ calc_nei <- function( #' containing identifier for each unique coordinate location. #' @param radius integer(1). Circular buffer distance around site locations. #' (Default = 0). +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @seealso [process_hms()] #' @author Mitchell Manware -#' @return a data.frame object -#' @importFrom terra vect -#' @importFrom terra as.data.frame -#' @importFrom terra time -#' @importFrom terra extract -#' @importFrom terra nlyr -#' @importFrom terra crs +#' @return a data.frame or SpatVector object +#' @importFrom terra vect as.data.frame time extract crs +#' @importFrom tidyr pivot_wider +#' @importFrom dplyr all_of +#' @importFrom stats setNames +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_hms( +#' from = hms, # derived from process_hms() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' geom = FALSE +#' ) +#' } #' @export calc_hms <- function( from, locs, locs_id = NULL, radius = 0, + geom = FALSE, ...) { #### check for null parameters check_for_null_parameters(mget(ls())) #### from == character indicates no wildfire smoke plumes are present - #### return 0 for all locs and dates - if ("character" %in% class(from)) { - cat(paste0( + #### return 0 for all densities, locs and dates + if (is.character(from)) { + message(paste0( "Inherited list of dates due to absent smoke plume polygons.\n" )) - skip_extraction <- NULL - skip_variable <- from[1] - skip_dates <- from[2:length(from)] - skip_sites_id <- data.frame(data.frame(locs)[, locs_id]) - for (s in seq_along(skip_dates)) { - skip_extraction_date <- cbind( - skip_sites_id, - as.Date( - skip_dates[s], - format = "%Y%m%d" - ), - as.integer(0) - ) - colnames(skip_extraction_date) <- c( - locs_id, - "time", - paste0( - skip_variable, - "_", - radius - ) - ) - skip_extraction <- rbind( - skip_extraction, - skip_extraction_date - ) - } - cat(paste0( - "Returning ", - tolower(skip_variable), - " smoke plume covariates.\n" - )) - return(skip_extraction) + skip_df <- data.frame(as.POSIXlt(from), 0, 0, 0) + colnames(skip_df) <- c( + "time", + paste0("light_", radius), + paste0("medium_", radius), + paste0("heavy_", radius) + ) + skip_merge <- merge(locs, skip_df) + skip_return <- calc_return_locs( + skip_merge, + POSIXt = TRUE, + geom = geom, + crs = "EPSG:4326" + ) + return(skip_return) } #### prepare locations list sites_list <- calc_prepare_locs( from = from, locs = locs, locs_id = locs_id, - radius = radius + radius = radius, + geom = geom ) sites_e <- sites_list[[1]] sites_id <- sites_list[[2]] + #### generate date sequence for missing polygon patch date_sequence <- generate_date_sequence( date_start = as.Date( @@ -1311,108 +1523,145 @@ calc_hms <- function( ), sub_hyphen = FALSE ) - #### empty location data.frame - sites_extracted <- NULL - for (r in seq_len(nrow(from))) { - #### select data layer - data_layer <- from[r] - layer_date <- as.Date( - data_layer$Date, - format = "%Y%m%d" - ) - layer_name <- data_layer$Density - cat(paste0( - "Calculating ", - tolower( - as.character( - layer_name - ) - ), - " covariates for ", - layer_date, - "...\n" + + ### split date_sequence by 30 days + date_sequence_split <- + split(date_sequence, ceiling(seq_along(date_sequence) / 30)) + return_list <- vector("list", length(date_sequence_split)) + + ### extract layer data at sites + for (i in seq_along(date_sequence_split)) { + message(paste0( + "Calculating smoke intensity covariates for date range: ", + date_sequence_split[[i]][1], + " to ", + date_sequence_split[[i]][length(date_sequence_split[[i]])] )) - #### extract layer data at sites - sites_extracted_layer <- as.integer( - terra::relate( - sites_e, - data_layer, - "intersects" - ) + + ### Full SPT + data_template <- expand.grid( + id = sites_id[[locs_id]], + time = date_sequence_split[[i]] ) + data_template <- stats::setNames(data_template, c(locs_id, "time")) + from_sub <- from[from$Date %in% date_sequence_split[[i]], ] + + ## Extract values + sites_extracted_layer <- + terra::extract(from_sub, sites_e) + sites_extracted_layer$id.y <- + unlist(sites_e[[locs_id]])[sites_extracted_layer$id.y] + names(sites_extracted_layer)[ + names(sites_extracted_layer) == "id.y" + ] <- locs_id + sites_extracted_layer$value <- 1L + + # remove duplicates + sites_extracted_layer <- unique(sites_extracted_layer) + #### merge with site_id and date - sites_extracted_layer <- cbind( - sites_id, - layer_date, - sites_extracted_layer - ) - #### define column names - colnames(sites_extracted_layer) <- c( - locs_id, - "time", - paste0( - tolower( - layer_name - ), - "_", - radius + sites_extracted_layer <- + tidyr::pivot_wider( + data = sites_extracted_layer, + names_from = "Density", + values_from = "value", + id_cols = dplyr::all_of(c(locs_id, "Date")) ) + + # Fill in missing columns + levels_acceptable <- c("Light", "Medium", "Heavy") + # Detect missing columns + col_tofill <- + setdiff(levels_acceptable, names(sites_extracted_layer)) + # Fill zeros + if (length(col_tofill) > 0) { + sites_extracted_layer[col_tofill] <- 0L + } + col_order <- c(locs_id, "Date", levels_acceptable) + sites_extracted_layer <- sites_extracted_layer[, col_order] + sites_extracted_layer <- + stats::setNames( + sites_extracted_layer, + c(locs_id, "time", levels_acceptable) + ) + + binary_colname <- + paste0(tolower(levels_acceptable), "_", sprintf("%05d", radius)) + # sites_extracted_layer$time <- as.Date(sites_extracted_layer$time) + sites_extracted_layer <- + stats::setNames( + sites_extracted_layer, + c(locs_id, "time", binary_colname) + ) + + # Filling NAs to 0 (explicit integer) + # sites_extracted_layer[is.na(sites_extracted_layer)] <- 0L + + # Join full space-time pairs with extracted data + site_extracted <- merge( + data_template, + sites_extracted_layer, + by = c(locs_id, "time"), + all.x = TRUE ) - #### merge with empty sites_extracted - sites_extracted <- rbind( - sites_extracted, - sites_extracted_layer - ) + # append list with the extracted data.frame + return_list[[i]] <- site_extracted } - #### check for missing dates (missing polygons) - if (!(identical(date_sequence, sort(unique(from$Date))))) { - cat(paste0( - "Detected absent smoke plume polygons.\n" - )) - missing_dates <- date_sequence[ - which(!(date_sequence %in% from$Date)) - ] - ### - for (m in seq_along(missing_dates)) { - missing_date <- as.Date( - missing_dates[m], - format = "%Y%m%d" - ) - cat(paste0( - "Smoke plume polygons absent for date ", - missing_date, - ". Returning 0 (smoke plumes absent).\n" - )) - missing_data <- cbind( - sites_id, - missing_date, - 0 + + ### Merge data.frame in list + sites_extracted <- do.call(rbind, return_list) + + #### define column names + colname_common <- c(locs_id, "time", binary_colname) + if (geom) { + sites_extracted <- + merge(sites_extracted, + sites_id, + by = locs_id) + sites_extracted <- + stats::setNames( + sites_extracted, + c(colname_common, "geometry") ) - colnames(missing_data) <- colnames(sites_extracted) - sites_extracted <- rbind( + } else { + sites_extracted <- + stats::setNames( sites_extracted, - missing_data + colname_common ) - } } - #### coerce binary to integer - sites_extracted[, 3] <- as.integer(sites_extracted[, 3]) + # Filling NAs to 0 (explicit integer) + sites_extracted[is.na(sites_extracted)] <- 0L + + # Messaging + timevals <- sites_extracted[["time"]] + intensities <- sites_extracted[, binary_colname] + intensities <- apply(intensities, 1, sum) + time_allzero <- unique(timevals[intensities == 0]) + time_allzero_c <- paste(time_allzero, collapse = "\n") + message(paste0( + "No intersecting smoke plume polygons for date(s):\n", + time_allzero_c + )) + #### date to POSIXct sites_extracted$time <- as.POSIXct(sites_extracted$time) #### order by date sites_extracted_ordered <- as.data.frame( sites_extracted[order(sites_extracted$time), ] ) - cat(paste0( - "Returning ", - layer_name, - " covariates.\n" - )) - calc_check_time(covar = sites_extracted_ordered, POSIXt = TRUE) + message("Returning smoke intensity covariates.") + sites_extracted_ordered <- calc_return_locs( + covar = sites_extracted, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame return(sites_extracted_ordered) } + #' Calculate elevation covariates #' @description #' Extract elevation values at point locations. Returns a \code{data.frame} @@ -1428,22 +1677,31 @@ calc_hms <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders #' @author Mitchell Manware #' @seealso [`process_gmted()`] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom terra as.data.frame #' @importFrom terra time #' @importFrom terra extract #' @importFrom terra nlyr #' @importFrom terra crs +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_gmted( +#' from = gmted, # derived from process_gmted() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_gmted <- function( from, @@ -1514,9 +1772,14 @@ calc_gmted <- function( sites_extracted[, 3] <- as.numeric(sites_extracted[, 3]) names(sites_extracted) <- c(locs_id, "time", variable_name) } - calc_check_time(covar = sites_extracted, POSIXt = FALSE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } @@ -1535,22 +1798,31 @@ calc_gmted <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders #' @author Mitchell Manware #' @seealso [`process_narr`] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom terra as.data.frame #' @importFrom terra time #' @importFrom terra extract #' @importFrom terra nlyr #' @importFrom terra crs +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_narr( +#' from = narr, # derived from process_narr() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_narr <- function( from, @@ -1592,9 +1864,14 @@ calc_narr <- function( level = narr_level, ... ) - calc_check_time(covar = sites_extracted, POSIXt = TRUE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } @@ -1613,16 +1890,13 @@ calc_narr <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @author Mitchell Manware #' @seealso [process_geos()] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom terra buffer #' @importFrom terra as.data.frame @@ -1630,6 +1904,18 @@ calc_narr <- function( #' @importFrom terra extract #' @importFrom terra nlyr #' @importFrom terra crs +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_geos( +#' from = geos, # derived from process_geos() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_geos <- function( from, @@ -1663,9 +1949,14 @@ calc_geos <- function( level = 2, ... ) - calc_check_time(covar = sites_extracted, POSIXt = TRUE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } #' Calculate population density covariates @@ -1682,17 +1973,26 @@ calc_geos <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders #' @author Mitchell Manware #' @seealso [process_sedac_population()] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom methods is +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_sedac_population( +#' from = pop, # derived from process_sedac_population() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_sedac_population <- function( from, @@ -1717,7 +2017,7 @@ calc_sedac_population <- function( names(from), "_" )[[1]] - cat( + message( paste0( "Calculating population covariates for ", name_split[4], @@ -1746,9 +2046,14 @@ calc_sedac_population <- function( time_type = "year", ... ) - calc_check_time(covar = sites_extracted, POSIXt = FALSE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } @@ -1768,12 +2073,9 @@ calc_sedac_population <- function( #' (Default = 1000). #' @param fun function(1). Function used to summarize the length of roads #' within sites location buffer (Default is `sum`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. # nolint start #' @note Unit is km / sq km. The returned `data.frame` object contains a @@ -1782,7 +2084,7 @@ calc_sedac_population <- function( # nolint end #' @author Insang Song #' @seealso [`process_sedac_groads`] -#' @return a data.frame object with three columns. +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom stats aggregate #' @importFrom stats setNames @@ -1794,6 +2096,18 @@ calc_sedac_population <- function( #' @importFrom terra expanse #' @importFrom terra linearUnits #' @importFrom methods is +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_sedac_groads( +#' from = groads, # derived from process_sedac_groads() example +#' locs = loc, +#' locs_id = "id", +#' radius = 1000, +#' fun = "sum", +#' geom = FALSE +#' ) +#' } #' @export calc_sedac_groads <- function( from = NULL, @@ -1858,7 +2172,14 @@ calc_sedac_groads <- function( #### reorder from_clip_reorder <- from_clip[, c(1, 4, 2, 3)] } - return(from_clip_reorder) + sites_return <- calc_return_locs( + covar = from_clip_reorder, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) + #### return data.frame + return(sites_return) } #' Calculate meteorological and atmospheric covariates @@ -1875,16 +2196,13 @@ calc_sedac_groads <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders #' @author Mitchell Manware #' @seealso [calc_geos()], [process_merra2()] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom terra buffer #' @importFrom terra as.data.frame @@ -1892,6 +2210,18 @@ calc_sedac_groads <- function( #' @importFrom terra extract #' @importFrom terra nlyr #' @importFrom terra crs +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_merra2( +#' from = merra2, # derived from process_merra2() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_merra2 <- function( from, @@ -1933,9 +2263,14 @@ calc_merra2 <- function( level = merra2_level, ... ) - calc_check_time(covar = sites_extracted, POSIXt = TRUE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } #' Calculate gridMET covariates @@ -1951,22 +2286,31 @@ calc_merra2 <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @author Mitchell Manware #' @seealso [`process_gridmet()`] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom terra as.data.frame #' @importFrom terra time #' @importFrom terra extract #' @importFrom terra nlyr #' @importFrom terra crs +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_gridmet( +#' from = gridmet, # derived from process_gridmet() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_gridmet <- function( from, @@ -1999,9 +2343,14 @@ calc_gridmet <- function( time_type = "date", ... ) - calc_check_time(covar = sites_extracted, POSIXt = TRUE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } #' Calculate TerraClimate covariates @@ -2018,12 +2367,9 @@ calc_gridmet <- function( #' (Default = 0). #' @param fun character(1). Function used to summarize multiple raster cells #' within sites location buffer (Default = `mean`). -#' @param geom logical(1). Should the geometry of `locs` be returned in the -#' `data.frame`? Default is `FALSE`. If `geom = TRUE` and `locs` contain -#' polygon geometries, the `$geometry` column in the returned data frame may -#' make the `data.frame` difficult to read due to long geometry strings. The -#' coordinate reference system of the `$geometry` is the coordinate -#' reference system of `from`. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` #' @param ... Placeholders. #' @note #' TerraClimate data has monthly temporal resolution, so the `$time` column @@ -2031,13 +2377,25 @@ calc_gridmet <- function( #' 201801). #' @author Mitchell Manware #' @seealso [`process_terraclimate()`] -#' @return a data.frame object +#' @return a data.frame or SpatVector object #' @importFrom terra vect #' @importFrom terra as.data.frame #' @importFrom terra time #' @importFrom terra extract #' @importFrom terra nlyr #' @importFrom terra crs +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' calc_terraclimate( +#' from = terraclimate, # derived from process_terraclimate() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' } #' @export calc_terraclimate <- function( from = NULL, @@ -2070,11 +2428,17 @@ calc_terraclimate <- function( time_type = "yearmonth", ... ) - calc_check_time(covar = sites_extracted, POSIXt = FALSE) + sites_return <- calc_return_locs( + covar = sites_extracted, + POSIXt = FALSE, + geom = geom, + crs = terra::crs(from) + ) #### return data.frame - return(data.frame(sites_extracted)) + return(sites_return) } +# nolint start #' Calculate temporally lagged covariates #' @description #' The \code{calc_lagged()} function calculates daily temporal lagged covariates @@ -2086,6 +2450,9 @@ calc_terraclimate <- function( #' @param lag integer(1). Number of lag days. #' @param time_id character(1). Column containing time values. #' @param locs_id character(1). Name of unique identifier. +#' @param geom logical(1). Should the function return a `SpatVector`? +#' Default is `FALSE`. The coordinate reference system of the `SpatVector` is +#' that of `from.` To return as a `SpatVector`, `from` must also be a `SpatVector` #' @seealso [calc_covariates()] #' @note #' In order to calculate temporally lagged covariates, `from` must contain at @@ -2099,20 +2466,58 @@ calc_terraclimate <- function( #' lag, buffer radius format adopted in \code{calc_setcolumns()}. #' @return a `data.frame` object #' @importFrom dplyr lag +#' @importFrom dplyr select +#' @examples +#' \dontrun{ +#' loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +#' terracliamte_covar <- calc_terraclimate( +#' from = terraclimate, # derived from process_terraclimate() example +#' locs = loc, +#' locs_id = "id", +#' radius = 0, +#' fun = "mean", +#' geom = FALSE +#' ) +#' calc_lagged( +#' from = terracliamte_covar, +#' locs_id = "id", +#' date = c("2023-01-02", "2023-01-10"), +#' lag = 1, +#' time_id = "time" +#' ) +#' } +# nolint end #' @export calc_lagged <- function( from, date, lag, locs_id, - time_id = "time") { + time_id = "time", + geom = FALSE) { + #### check years + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] + #### geom and from + if (geom && !("SpatVector" %in% class(from))) { + stop( + paste0( + "To return with geometry, `from` must be a `SpatVector` object.\n" + ) + ) + } #### check input data types + if ("SpatVector" %in% class(from)) { + from_full <- terra::as.data.frame(from, geom = "WKT") + geoms <- unique(from_full[, c(locs_id, "geometry")]) + from <- from_full |> dplyr::select(-"geometry") + } stopifnot(methods::is(from, "data.frame")) #### check if time_id is not null stopifnot(!is.null(time_id)) #### return from if lag == 0 if (lag == 0) { - cat("`lag` set to 0. Returning `from`.\n") + message("`lag` set to 0. Returning `from`.\n") return(from) } #### extract times @@ -2160,6 +2565,14 @@ calc_lagged <- function( #### merge with other locations variables_merge <- rbind(variables_merge, variables_return_date) } - calc_check_time(covar = variables_merge, POSIXt = TRUE) - return(variables_merge) + if (geom) { + variables_merge <- merge(variables_merge, geoms) + } + variables_return <- calc_return_locs( + covar = variables_merge, + POSIXt = TRUE, + geom = geom, + crs = terra::crs(from) + ) + return(variables_return) } diff --git a/R/calculate_covariates_auxiliary.R b/R/calculate_covariates_auxiliary.R index 39b63d0f..fa3e38a7 100644 --- a/R/calculate_covariates_auxiliary.R +++ b/R/calculate_covariates_auxiliary.R @@ -11,8 +11,9 @@ #' padded to 5 digits. If provided a buffer radius greater than 5 digits, #' \code{calc_setcolumns()} will expand to the number of digits. (ie. buffer #' radius of 100km = CCC_CCCCC_I_100000). -#' @param from data.frame(1). Calculated covariates as returned from -#' \code{calc_covariates()} or a source specific covariate function. +#' @param from data.frame(1) or SpatVector(1). Calculated covariates as +#' returned from \code{calc_covariates()} or a source specific covariate +#' function. #' @param lag integer(1). Temporal lag. #' @param dataset character(1). Covariate parent dataset. #' @param locs_id character(1). Column containing identifier for each unique @@ -26,7 +27,7 @@ calc_setcolumns <- function( dataset, locs_id) { #### check from is data.frame - stopifnot(is.data.frame(from)) + stopifnot(class(from) %in% c("data.frame", "SpatVector")) #### original names names_from <- colnames(from) #### copy @@ -188,7 +189,7 @@ calc_message <- function( ) } } - cat(return_message) + message(return_message) } #' Prepare extraction locations @@ -482,7 +483,7 @@ calc_worker <- function( ) } #### finish message - cat( + message( paste0( "Returning extracted covariates.\n" ) @@ -490,3 +491,52 @@ calc_worker <- function( #### return data.frame return(data.frame(sites_extracted)) } + +#' Prepare covariates for return +#' @description +#' Check the time column for proper class and, if `geom = TRUE`, +#' transform `data.frame` into a `SpatVector` object. +#' @param covar data.frame(1). Calculated covariates `data.frame`. +#' @param POSIXt logical(1). Should the time values in `covar` be of class +#' `POSIXt`? If `FALSE`, the time values will be checked for integer class +#' (year and year-month). +#' @param geom logical(1). Should `covar` be returned as a +#' `data.frame`? Default is `FALSE`. +#' @param crs terra::crs(1). Coordinate reference system (inherited from +#' `from`). +#' @importFrom terra vect +#' @keywords auxiliary +#' @author Mitchell Manware +#' @export +# nolint start +calc_return_locs <- function( + covar, + POSIXt = TRUE, + geom, + crs +) { + # time value check + if ("time" %in% names(covar)) { + calc_check_time(covar = covar, POSIXt = POSIXt) + } + # nolint end + # if geom, convert to and return SpatVector + if (geom) { + if ("geometry" %in% names(covar)) { + covar_return <- terra::vect( + covar, + geom = "geometry", + crs = crs + ) + } else if (all(c("lon", "lat") %in% names(covar))) { + covar_return <- terra::vect( + covar, + geom = c("lon", "lat"), + crs = crs + ) + } + return(covar_return) + } else { + return(data.frame(covar)) + } +} diff --git a/R/download.R b/R/download.R index 8d2e3442..950d0f3a 100644 --- a/R/download.R +++ b/R/download.R @@ -23,9 +23,7 @@ #' * \code{\link{download_gmted}}: `"gmted"`, `"GMTED"` #' * \code{\link{download_koppen_geiger}}: `"koppen"`, `"koppengeiger"` #' * \code{\link{download_merra2}}: "merra2", `"merra"`, `"MERRA"`, `"MERRA2"` -#' * \code{\link{download_narr_monolevel}}: `"narr_monolevel"`, `"monolevel"` -#' * \code{\link{download_narr_p_levels}}: `"narr_p_levels"`, `"p_levels"`, -#' `"plevels"` +#' * \code{\link{download_narr}}: `"narr"` #' * \code{\link{download_nlcd}}: `"nlcd"`, `"NLCD"` #' * \code{\link{download_hms}}: `"noaa"`, `"smoke"`, `"hms"` #' * \code{\link{download_sedac_groads}}: `"sedac_groads"`, `"groads"` @@ -37,15 +35,27 @@ #' * \code{\link{download_gridmet}}: `"gridMET"`, `"gridmet"` #' * \code{\link{download_terraclimate}}: `"TerraClimate"`, `"terraclimate"` #' @returns NULL +#' @examples +#' \dontrun{ +#' download_data( +#' dataset_name = "narr", +#' variables = "weasd", +#' year = c(2023, 2023), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_commands = TRUE +#' ) +#' } #' @export download_data <- function( dataset_name = c("aqs", "ecoregion", "ecoregions", "geos", "gmted", "koppen", - "koppengeiger", "merra2", "merra", "narr_monolevel", - "modis", "narr_p_levels", "nlcd", "noaa", "sedac_groads", - "sedac_population", "groads", "population", "plevels", - "p_levels", "monolevel", "hms", "smoke", "tri", "nei", + "koppengeiger", "merra2", "merra", + "modis", "narr", "nlcd", "noaa", "sedac_groads", + "sedac_population", "groads", "population", + "hms", "smoke", "tri", "nei", "gridmet", "terraclimate", "huc", "cropscape", "cdl", "prism", "olm", "openlandmap"), directory_to_save = NULL, @@ -67,11 +77,7 @@ download_data <- koppengeiger = download_koppen_geiger, merra2 = download_merra2, merra = download_merra2, - narr_monolevel = download_narr_monolevel, - monolevel = download_narr_monolevel, - narr_p_levels = download_narr_p_levels, - p_levels = download_narr_p_levels, - plevels = download_narr_p_levels, + narr = download_narr, nlcd = download_nlcd, noaa = download_hms, smoke = download_hms, @@ -117,16 +123,12 @@ download_data <- #' @param parameter_code integer(1). length of 5. #' EPA pollutant parameter code. For details, please refer to #' [AQS parameter codes](https://aqs.epa.gov/aqsweb/documents/codetables/parameters.html) -# nolint end #' @param resolution_temporal character(1). #' Name of column containing POC values. #' Currently, no value other than `"daily"` works. #' @param url_aqs_download character(1). #' URL to the AQS pre-generated datasets. -#' @param year_start integer(1). length of 4. -#' Start year for downloading data. -#' @param year_end integer(1). length of 4. -#' End year for downloading data. +#' @param year character(2). length of 4 each. Start/end years for downloading data. #' @param directory_to_save character(1). Directory to save data. Two #' sub-directories will be created for the downloaded zip files ("/zip_files") #' and the unzipped data files ("/data_files"). @@ -145,13 +147,28 @@ download_data <- #' @author Mariana Kassien, Insang Song, Mitchell Manware #' @returns NULL; Zip and/or data files will be downloaded and stored in #' \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_usepa2023airdata}{amadeus} +#' @examples +#' \dontrun{ +#' download_aqs( +#' parameter_code = 88101, +#' resolution_temporal = "daily", +#' year = c(2022, 2023), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } +# nolint end #' @export download_aqs <- function( parameter_code = 88101, resolution_temporal = "daily", - year_start = 2018, - year_end = 2022, + year = c(2018, 2022), url_aqs_download = "https://aqs.epa.gov/aqsweb/airdata/", directory_to_save = NULL, acknowledgement = FALSE, @@ -164,13 +181,16 @@ download_aqs <- download_permit(acknowledgement = acknowledgement) #### 2. check for null parameters check_for_null_parameters(mget(ls())) + #### check years + stopifnot(length(year) == 2) + year <- year[order(year)] #### 3. directory setup directory_original <- download_sanitize_path(directory_to_save) directories <- download_setup_dir(directory_original, zip = TRUE) directory_to_download <- directories[1] directory_to_save <- directories[2] #### 4. define year sequence - year_sequence <- seq(year_start, year_end, 1) + year_sequence <- seq(year[1], year[2], 1) #### 5. build URLs download_urls <- sprintf( paste(url_aqs_download, @@ -186,12 +206,13 @@ download_aqs <- if (!(check_url_status(download_urls[1]))) { stop(paste0( "Invalid year returns HTTP code 404. ", - "Check `year_start` parameter.\n" + "Check `year` parameter.\n" )) } #### 5. build download file name download_names <- sprintf( - paste(directory_to_download, + paste( + directory_to_download, "aqs_", resolution_temporal, "_", @@ -221,7 +242,7 @@ download_aqs <- "aqs_", parameter_code, "_", - year_start, "_", year_end, + year[1], "_", year[2], "_", resolution_temporal, "_curl_commands.txt" @@ -300,6 +321,18 @@ download_aqs <- #' @returns NULL; Zip and/or data files will be downloaded and stored in #' \code{directory_to_save}. #' @importFrom utils download.file +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{article_omernik2014ecoregions}{amadeus} +#' @examples +#' \dontrun{ +#' download_ecoregion( +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_ecoregion <- function( epa_certificate_path = @@ -360,7 +393,8 @@ download_ecoregion <- function( download_sink(commands_txt) if (!file.exists(download_name)) { #### 10. concatenate and print download commands to "..._wget_commands.txt" - #### cat command only if file does not already exist + #### cat command only file does not already exist or + #### if size does not match URL size cat(download_command) } #### 11. finish "...curl_commands.txt" file @@ -397,12 +431,9 @@ download_ecoregion <- function( #' @description #' The \code{download_geos()} function accesses and downloads various #' atmospheric composition collections from [NASA's Global Earth Observing System (GEOS) model](https://gmao.gsfc.nasa.gov/GEOS_systems/). -# nolint end #' @param collection character(1). GEOS-CF data collection file name. -#' @param date_start character(1). length of 10. Start date for downloading -#' data. Format YYYY-MM-DD (ex. September 1, 2023 = `"2023-09-01"`). -#' @param date_end character(1). length of 10. End date for downloading data. -#' Format YYYY-MM-DD (ex. September 1, 2023 = `"2023-09-01"`). +#' @param date character(2). length of 10 each. Start/end date for downloading data. +#' Format "YYYY-MM-DD" (ex. January 1, 2018 = `"2018-01-01"`). #' @param directory_to_save character(1). Directory to save data. #' Sub-directories will be created within \code{directory_to_save} for each #' GEOS-CF collection. @@ -416,9 +447,25 @@ download_ecoregion <- function( #' Remove (\code{TRUE}) or keep (\code{FALSE}) #' the text file containing download commands. #' @author Mitchell Manware, Insang Song -#' @return NULL; netCDF (.nc4) files will be stored in a +#' @returns NULL; netCDF (.nc4) files will be stored in a #' collection-specific folder within \code{directory_to_save}. +#' @importFrom utils download.file +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{keller_description_2021}{amadeus} +#' @examples +#' \dontrun{ +#' download_geos( +#' collection = "aqc_tavg_1hr_g1440x721_v1", +#' date = c("2024-01-01", "2024-01-05"), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export +# nolint end # nolint start: cyclocomp download_geos <- function( collection = @@ -427,8 +474,7 @@ download_geos <- function( "met_tavg_1hr_g1440x721_x1", "xgc_tavg_1hr_g1440x721_x1", "chm_inst_1hr_g1440x721_p23", "met_inst_1hr_g1440x721_p23" ), - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2018-01-01", "2018-01-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -437,6 +483,9 @@ download_geos <- function( download_permit(acknowledgement = acknowledgement) #### 2. check for null parameters check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### 3. directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) @@ -444,8 +493,8 @@ download_geos <- function( collection <- match.arg(collection, several.ok = TRUE) #### 5. define date sequence date_sequence <- generate_date_sequence( - date_start, - date_end, + date[1], + date[2], sub_hyphen = TRUE ) #### 7. define URL base @@ -454,9 +503,9 @@ download_geos <- function( commands_txt <- paste0( directory_to_save, "geos_", - date_start, + date[1], "_", - date_end, + date[2], "_wget_commands.txt" ) download_sink(commands_txt) @@ -507,7 +556,7 @@ download_geos <- function( file.remove(commands_txt) stop(paste0( "Invalid date returns HTTP code 404. ", - "Check `date_start` parameter.\n" + "Check `date` parameter.\n" )) } } @@ -578,6 +627,20 @@ download_geos <- function( # nolint end #' @returns NULL; Zip and/or data files will be downloaded and stored in #' \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{danielson_global_2011}{amadeus} +#' @examples +#' \dontrun{ +#' download_gmted( +#' statistic = "Breakline Emphasis", +#' resolution = "7.5 arc-seconds", +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_gmted <- function( statistic = c( @@ -701,10 +764,8 @@ download_gmted <- function( #' The \code{download_merra2()} function accesses and downloads various #' meteorological and atmospheric collections from [NASA's Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2) model](https://gmao.gsfc.nasa.gov/reanalysis/MERRA-2/). #' @param collection character(1). MERRA-2 data collection file name. -#' @param date_start character(1). length of 10. Start date for downloading -#' data. Format YYYY-MM-DD (ex. September 1, 2023 is `"2023-09-01"`). -#' @param date_end character(1). length of 10. End date for downloading data. -#' Format YYYY-MM-DD (ex. September 1, 2023 is `"2023-09-01"`). +#' @param date character(2). length of 10 each. Start/end date for downloading data. +#' Format "YYYY-MM-DD" (ex. January 1, 2018 = `"2018-01-01"`). #' @param directory_to_save character(1). Directory to save data. #' @param acknowledgement logical(1). By setting \code{TRUE} the #' user acknowledges that the data downloaded using this function may be very @@ -716,8 +777,114 @@ download_gmted <- function( #' Remove (\code{TRUE}) or keep (\code{FALSE}) #' the text file containing download commands. #' @author Mitchell Manware, Insang Song -#' @return NULL; netCDF (.nc4) files will be stored in a +#' @returns NULL; netCDF (.nc4) files will be stored in a #' collection-specific folder within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_gmao_merra-inst1_2d_asm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-inst1_2d_int_Nx}{amadeus} +#' \insertRef{data_gmao_merra-inst1_2d_lfo_Nx}{amadeus} +#' \insertRef{data_gmao_merra-inst3_3d_asm_Np}{amadeus} +#' \insertRef{data_gmao_merra-inst3_3d_aer_Nv}{amadeus} +#' \insertRef{data_gmao_merra-inst3_3d_asm_Nv}{amadeus} +#' \insertRef{data_gmao_merra-inst3_3d_chm_Nv}{amadeus} +#' \insertRef{data_gmao_merra-inst3_3d_gas_Nv}{amadeus} +#' \insertRef{data_gmao_merra-inst3_2d_gas_Nx}{amadeus} +#' \insertRef{data_gmao_merra-inst6_3d_ana_Np}{amadeus} +#' \insertRef{data_gmao_merra-inst6_3d_ana_Nv}{amadeus} +#' \insertRef{data_gmao_merra-statD_2d_slv_Nx_m}{amadeus} +#' \insertRef{data_gmao_merra-statD_2d_slv_Nx_d}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_adg_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_aer_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_chm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_csp_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_flx_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_int_Nx}{amadeus} +#' \insertRef{pawson_merra-2_2020}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_lnd_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_ocn_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_rad_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg1_2d_slv_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_mst_Ne}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_trb_Ne}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_nav_Ne}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_cld_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_mst_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_rad_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_tdt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_trb_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_udt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_odt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_qdt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_asm_Nv}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_cld_Nv}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_mst_Nv}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_3d_rad_Nv}{amadeus} +#' \insertRef{data_gmao_merra-tavg3_2d_glc_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instM_2d_asm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instM_2d_int_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instM_2d_lfo_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instM_2d_gas_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instM_3d_asm_Np}{amadeus} +#' \insertRef{data_gmao_merra-instM_3d_ana_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_adg_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_aer_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_chm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_csp_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_flx_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_int_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_lfo_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_lnd_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_ocn_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_rad_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_slv_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_2d_glc_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_cld_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_mst_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_rad_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_tdt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_trb_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_udt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_odt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgM_3d_qdt_Np}{amadeus} +#' \insertRef{data_gmao_merra-const_2d_asm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instU_2d_asm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instU_2d_int_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instU_2d_lfo_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instU_2d_gas_Nx}{amadeus} +#' \insertRef{data_gmao_merra-instU_3d_asm_Np}{amadeus} +#' \insertRef{data_gmao_merra-instU_3d_ana_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_adg_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_aer_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_chm_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_csp_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_flx_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_int_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_lfo_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_lnd_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_ocn_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_rad_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_slv_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_2d_glc_Nx}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_cld_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_mst_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_rad_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_tdt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_trb_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_udt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_odt_Np}{amadeus} +#' \insertRef{data_gmao_merra-tavgU_3d_qdt_Np}{amadeus} +#' @examples +#' \dontrun{ +#' download_merra2( +#' collection = "inst1_2d_int_Nx", +#' date = c("2024-01-01", "2024-01-05"), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export # nolint end # nolint start: cyclocomp @@ -737,8 +904,7 @@ download_merra2 <- function( "tavg3_3d_qdt_Np", "tavg3_3d_asm_Nv", "tavg3_3d_cld_Nv", "tavg3_3d_mst_Nv", "tavg3_3d_rad_Nv", "tavg3_2d_glc_Nx" ), - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2018-01-01", "2018-01-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -748,6 +914,9 @@ download_merra2 <- function( #### directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### check for null parameters check_for_null_parameters(mget(ls())) #### check if collection is recognized @@ -804,8 +973,8 @@ download_merra2 <- function( } #### define date sequence date_sequence <- generate_date_sequence( - date_start, - date_end, + date[1], + date[2], sub_hyphen = TRUE ) #### define year + month sequence @@ -814,9 +983,9 @@ download_merra2 <- function( commands_txt <- paste0( directory_to_save, "merra2_", - date_start, + date[1], "_", - date_end, + date[2], "_wget_commands.txt" ) download_sink(commands_txt) @@ -870,7 +1039,7 @@ download_merra2 <- function( if (!(check_url_status(base_url))) { stop(paste0( "Invalid date returns HTTP code 404. ", - "Check `date_start` parameter.\n" + "Check `date` parameter.\n" )) } } @@ -972,7 +1141,7 @@ download_merra2 <- function( download_name_metadata, "\n" ) - if (!file.exists(download_name)) { + if (!file.exists(download_name_metadata)) { #### cat command only if file does not already exist cat(download_command_metadata) } @@ -1000,15 +1169,13 @@ download_merra2 <- function( # nolint end: cyclocomp # nolint start -#' Download meteorological data (monolevel) +#' Download meteorological data #' @description -#' The \code{download_narr_monolevel} function accesses and downloads monolevel meteorological data from [NOAA's North American Regional Reanalysis (NARR) model](https://psl.noaa.gov/data/gridded/data.narr.html). "Monolevel" variables contain a single value for the entire atmospheric column (ie. Variable: Convective cloud cover; Level: Entire atmosphere considered as a single layer), or represent a specific altitude associated with the variable (ie. Variable: Air temperature; Level: 2 m). +#' The \code{download_narr} function accesses and downloads daily meteorological data from [NOAA's North American Regional Reanalysis (NARR) model](https://psl.noaa.gov/data/gridded/data.narr.html). +#' @note "Pressure levels" variables contain variable values at 29 atmospheric levels, ranging from 1000 hPa to 100 hPa. All pressure levels data will be downloaded for each variable. #' @param variables character. Variable(s) name acronym. See [List of Variables in NARR Files](https://ftp.cpc.ncep.noaa.gov/NARR/fixed/merged_land_AWIP32corrected.pdf) #' for variable names and acronym codes. -#' @param year_start integer(1). length of 4. Start of year range for -#' downloading data. -#' @param year_end integer(1). length of 4. End of year range for downloading -#' data. +#' @param year character(2). length of 4 each. Start/end years for downloading data. #' @param directory_to_save character(1). Directory(s) to save downloaded data #' files. #' @param acknowledgement logical(1). By setting \code{TRUE} the @@ -1021,14 +1188,28 @@ download_merra2 <- function( #' Remove (\code{TRUE}) or keep (\code{FALSE}) #' the text file containing download commands. #' @author Mitchell Manware, Insang Song -#' @return NULL; netCDF (.nc) files will be stored in a variable-specific -#' folder within \code{directory_to_save}. +#' @returns NULL; netCDF (.nc) files will be stored in +#' \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{mesinger_north_2006}{amadeus} +#' @examples +#' \dontrun{ +#' download_narr( +#' variables = c("weasd", "omega"), +#' year = c(2022, 2023), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export # nolint end -download_narr_monolevel <- function( +# nolint start: cyclocomp +download_narr <- function( variables = NULL, - year_start = 2022, - year_end = 2022, + year = c(2018, 2022), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -1037,24 +1218,30 @@ download_narr_monolevel <- function( download_permit(acknowledgement = acknowledgement) #### 2. check for null parameters check_for_null_parameters(mget(ls())) + #### check years + stopifnot(length(year) == 2) + year <- year[order(year)] #### 3. directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) - #### 4. define years sequence - if (any(nchar(year_start) != 4, nchar(year_end) != 4)) { - stop("year_start and year_end should be 4-digit integers.\n") + #### 4. define years and months sequence + if (any(nchar(year[1]) != 4, nchar(year[2]) != 4)) { + stop("years should be 4-digit integers.\n") } - years <- seq(year_start, year_end, 1) + stopifnot( + all( + seq(year[1], year[2], 1) %in% + seq(1979, as.numeric(substr(Sys.Date(), 1, 4)), 1) + ) + ) + years <- seq(year[1], year[2], 1) #### 5. define variables variables_list <- as.vector(variables) - #### 6. define URL base - base <- - "https://psl.noaa.gov/thredds/fileServer/Datasets/NARR/Dailies/monolevel/" #### 7. initiate "..._curl_commands.txt" commands_txt <- paste0( directory_to_save, - "narr_monolevel_", - year_start, "_", year_end, + "narr_", + year[1], "_", year[2], "_curl_commands.txt" ) download_sink(commands_txt) @@ -1062,169 +1249,31 @@ download_narr_monolevel <- function( for (v in seq_along(variables_list)) { variable <- variables_list[v] folder <- paste0(directory_to_save, variable, "/") + # implement variable sorting function + base <- narr_variable(variable)[[1]] + months <- narr_variable(variable)[[2]] if (!dir.exists(folder)) { dir.create(folder, recursive = TRUE) } for (y in seq_along(years)) { - year <- years[y] - url <- paste0( - base, - variable, - ".", - year, - ".nc" - ) - if (y == 1) { - if (!(check_url_status(url))) { - sink() - file.remove(commands_txt) - stop(paste0( - "Invalid year returns HTTP code 404. ", - "Check `year_start` parameter.\n" - )) - } - } - destfile <- paste0( - directory_to_save, - variable, - "/", - variable, - ".", - year, - ".nc" - ) - command <- paste0( - "curl -s -o ", - destfile, - " --url ", - url, - "\n" - ) - if (!file.exists(destfile)) { - #### cat command only if file does not already exist - cat(command) - } - } - } - #### 9. finish "..._curl_commands.txt" - sink() - #### 10. build system command - system_command <- paste0( - ". ", - commands_txt, - "\n" - ) - #### 11. download data - download_run( - download = download, - system_command = system_command - ) - #### 12. remove command text file - download_remove_command( - commands_txt = commands_txt, - remove = remove_command - ) -} - -# nolint start -#' Download meteorological data (pressure levels) -#' @description -#' The \code{download_narr_p_levels} function accesses and downloads pressure levels meteorological data from [NOAA's North American Regional Reanalysis (NARR) model](https://psl.noaa.gov/data/gridded/data.narr.html). "Pressure levels" variables contain variable values at 29 atmospheric levels, ranging from 1000 hPa to 100 hPa. All pressure levels data will be downloaded for each variable. -#' @param variables character. Variable(s) name acronym. See [List of Variables in NARR Files](https://ftp.cpc.ncep.noaa.gov/NARR/fixed/merged_land_AWIP32corrected.pdf) -#' for variable names and acronym codes. -#' @param year_start integer(1). length of 4. Start of year range for -#' downloading data. -#' @param year_end integer(1). length of 4. End of year range for downloading -#' data. -#' @param directory_to_save character(1). Directory(s) to save downloaded data -#' files. -#' @param acknowledgement logical(1). By setting \code{TRUE} the -#' user acknowledges that the data downloaded using this function may be very -#' large and use lots of machine storage and memory. -#' @param download logical(1). \code{FALSE} will generate a *.txt file -#' containing all download commands. By setting \code{TRUE} the function -#' will download all of the requested data files. -#' @param remove_command logical(1). -#' Remove (\code{TRUE}) or keep (\code{FALSE}) -#' the text file containing download commands. -#' @author Mitchell Manware, Insang Song -#' @return NULL; netCDF (.nc) files will be stored in -#' \code{directory_to_save}. -#' @export -# nolint end -# nolint start: cyclocomp -download_narr_p_levels <- function( - variables = NULL, - year_start = 2022, - year_end = 2022, - directory_to_save = NULL, - acknowledgement = FALSE, - download = FALSE, - remove_command = FALSE) { - #### 1. check for data download acknowledgement - download_permit(acknowledgement = acknowledgement) - #### 2. check for null parameters - check_for_null_parameters(mget(ls())) - #### 3. directory setup - download_setup_dir(directory_to_save) - directory_to_save <- download_sanitize_path(directory_to_save) - #### 4. define years sequence - years <- seq(year_start, year_end, 1) - #### 5. define months sequence - months <- sprintf("%02d", seq(1, 12, by = 1)) - - #### 6. define variables - variables_list <- as.vector(variables) - #### 7. define URL base - base <- - "https://psl.noaa.gov/thredds/fileServer/Datasets/NARR/Dailies/pressure/" - #### 8. initiate "..._curl_commands.txt" - commands_txt <- paste0( - directory_to_save, - "narr_p_levels_", - year_start, - "_", - year_end, - "_curl_commands.txt" - ) - download_sink(commands_txt) - #### 9. concatenate download commands to "..._curl_commands.txt" - for (v in seq_along(variables_list)) { - variable <- variables_list[v] - folder <- paste0(directory_to_save, variable, "/") - if (!dir.exists(folder)) { - dir.create(folder, recursive = TRUE) - } - for (y in seq_along(years)) { - year <- years[y] + year_l <- years[y] for (m in seq_along(months)) { - month <- months[m] url <- paste0( base, variable, ".", - year, - month, + year_l, + months[m], ".nc" ) - if (m == 1) { - if (!(check_url_status(url))) { - sink() - file.remove(commands_txt) - stop(paste0( - "Invalid year returns HTTP code 404. ", - "Check `year_start` parameter.\n" - )) - } - } destfile <- paste0( directory_to_save, variable, "/", variable, ".", - year, - month, + year_l, + months[m], ".nc" ) command <- paste0( @@ -1234,28 +1283,28 @@ download_narr_p_levels <- function( url, "\n" ) - #### cat command only if file does not already exist if (!file.exists(destfile)) { - #### cat command only if file does not already exist + #### cat command if file does not already exist or if local file size + #### and the HTTP length (url file size) do not match cat(command) } } } } - #### 10. finish "..._curl_commands.txt" + #### 9. finish "..._curl_commands.txt" sink() - #### 11. build system command + #### 10. build system command system_command <- paste0( ". ", commands_txt, "\n" ) - #### 12. download data + #### 11. download data download_run( download = download, system_command = system_command ) - #### 13. Remove command file + #### 12. remove command text file download_remove_command( commands_txt = commands_txt, remove = remove_command @@ -1293,6 +1342,21 @@ download_narr_p_levels <- function( #' @author Mitchell Manware, Insang Song #' @returns NULL; Zip and/or data files will be downloaded and stored in #' respective sub-directories within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{dewitz_national_2023}{amadeus} +#' \insertRef{dewitz_national_2024}{amadeus} +#' @examples +#' \dontrun{ +#' download_nlcd( +#' collection = "Coterminous United States", +#' year = 2021, +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_nlcd <- function( collection = "Coterminous United States", @@ -1437,6 +1501,20 @@ download_nlcd <- function( #' @author Mitchell Manware, Insang Song #' @returns NULL; Zip and/or data files will be downloaded and stored in #' respective sub-directories within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_ciesin2013groads}{amadeus} +#' @examples +#' \dontrun{ +#' download_sedac_groads( +#' data_region = "Americas", +#' data_format = "Shapefile", +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_sedac_groads <- function( data_region = c("Americas", "Global", "Africa", "Asia", "Europe", "Oceania East", "Oceania West"), @@ -1516,7 +1594,7 @@ download_sedac_groads <- function( download_sink(commands_txt) if (!file.exists(download_name)) { #### 12. concatenate and print download command to "..._curl_commands.txt" - #### cat command only if file does not already exist + #### cat command if file does not already exist or is incomplete cat(download_command) } #### 13. finish "..._curl_commands.txt" file @@ -1581,6 +1659,21 @@ download_sedac_groads <- function( # nolint end #' @returns NULL; Zip and/or data files will be downloaded and stored in #' respective sub-directories within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_ciesin2017gpwv4}{amadeus} +#' @examples +#' \dontrun{ +#' download_sedac_population( +#' data_resolution = "30 second", +#' data_format = "GeoTIFF", +#' year = "2020", +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_sedac_population <- function( data_resolution = "60 minute", @@ -1611,7 +1704,7 @@ download_sedac_population <- function( #### 7. 30 second resolution not available for all years if (year == "totpop" && resolution == "30_sec") { resolution <- "2pt5_min" - cat(paste0( + message(paste0( "30 second resolution not available for all years. Returning", " highest (2.5 minute) resolution.\n" )) @@ -1624,7 +1717,7 @@ download_sedac_population <- function( format <- "tif" } else { format <- "nc" - cat(paste0( + message(paste0( "Data for all years is only available in netCDF format. ", "Data will be downloaded as netCDF.\n" )) @@ -1635,7 +1728,7 @@ download_sedac_population <- function( format <- "asc" } else { format <- "nc" - cat(paste0( + message(paste0( "Data for all years is only available in netCDF format. ", "Data will be downloaded as netCDF.\n" )) @@ -1693,7 +1786,7 @@ download_sedac_population <- function( download_sink(commands_txt) if (!file.exists(download_name)) { #### 13. concatenate and print download command to "..._curl_commands.txt" - #### cat command only if file does not already exist + #### cat command if file does not already exist or is incomplete cat(download_command) } #### 14. finish "..._curl_commands.txt" file @@ -1732,12 +1825,9 @@ download_sedac_population <- function( #' @description #' The \code{download_hms()} function accesses and downloads #' wildfire smoke plume coverage data from [NOAA's Hazard Mapping System Fire and Smoke Product](https://www.ospo.noaa.gov/Products/land/hms.html#0). -# nolint end #' @param data_format character(1). "Shapefile" or "KML". -#' @param date_start character(1). length of 10. Start date for downloading -#' data. Format YYYY-MM-DD (ex. September 1, 2023 is `"2023-09-01"`). -#' @param date_end character(1). length of 10. End date for downloading data. -#' Format YYYY-MM-DD (ex. September 10, 2023 is `"2023-09-10"`). +#' @param date character(2). length of 10 each. Start/end date for downloading data. +# nolint end #' @param directory_to_save character(1). Directory to save data. If #' `data_format = "Shapefile"`, two sub-directories will be created for the #' downloaded zip files ("/zip_files") and the unzipped shapefiles @@ -1761,14 +1851,27 @@ download_sedac_population <- function( #' @importFrom utils head #' @importFrom utils tail #' @author Mitchell Manware, Insang Song -##' @returns NULL; Zip and/or data files will be downloaded and stored in +#' @returns NULL; Zip and/or data files will be downloaded and stored in #' respective sub-directories within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{web_HMSabout}{amadeus} +#' @examples +#' \dontrun{ +#' download_hms( +#' data_format = "Shapefile", +#' date = c("2024-01-01", "2024-01-05"), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export # nolint start: cyclocomp download_hms <- function( data_format = "Shapefile", - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2018-01-01", "2018-01-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -1779,6 +1882,9 @@ download_hms <- function( download_permit(acknowledgement = acknowledgement) #### 2. check for null parameters check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### 3. directory setup directory_original <- download_sanitize_path(directory_to_save) directories <- download_setup_dir(directory_original, zip = TRUE) @@ -1793,8 +1899,8 @@ download_hms <- function( } #### 5. define date sequence date_sequence <- generate_date_sequence( - date_start, - date_end, + date[1], + date[2], sub_hyphen = TRUE ) #### 6. define URL base @@ -1840,7 +1946,7 @@ download_hms <- function( file.remove(commands_txt) stop(paste0( "Invalid date returns HTTP code 404. ", - "Check `date_start` parameter.\n" + "Check `date` parameter.\n" )) } } @@ -1886,7 +1992,7 @@ download_hms <- function( #### 13. end if data_format == "KML" if (data_format == "KML") { unlink(directory_to_download, recursive = TRUE) - cat(paste0("KML files cannot be unzipped.\n")) + message(paste0("KML files cannot be unzipped.\n")) return(TRUE) } #### 14. unzip downloaded zip files @@ -1936,6 +2042,22 @@ download_hms <- function( #' @author Mitchell Manware, Insang Song #' @returns NULL; Zip and/or data files will be downloaded and stored in #' respective sub-directories within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{article_beck2023koppen}{amadeus} +#' \insertRef{article_beck2018present}{amadeus} +#' @examples +#' \dontrun{ +#' download_koppen_geiger( +#' data_resolution = "0.0083", +#' time_period = "Present", +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } +# nolint end #' @export download_koppen_geiger <- function( data_resolution = c("0.0083", "0.083", "0.5"), @@ -1964,7 +2086,10 @@ download_koppen_geiger <- function( #### 7. define data resolution data_resolution <- gsub("\\.", "p", data_resolution) #### 8 define download URL - download_url <- "https://s3-eu-west-1.amazonaws.com/pfigshare-u-files/12407516/Beck_KG_V1.zip" + download_url <- paste0( + "https://s3-eu-west-1.amazonaws.com/", + "pfigshare-u-files/12407516/Beck_KG_V1.zip" + ) #### 9 build download file name download_name <- paste0( directory_to_download, @@ -1996,7 +2121,7 @@ download_koppen_geiger <- function( download_sink(commands_txt) if (!file.exists(download_name)) { #### 12. concatenate and print download command to "..._wget_commands.txt" - #### cat command only if file does not already exist + #### cat command if file does not already exist or is incomplete cat(download_command) } sink() @@ -2033,18 +2158,16 @@ download_koppen_geiger <- function( #' Download MODIS product files -# nolint end +# nolint start #' @description Need maintenance for the directory path change #' in NASA EOSDIS. This function first retrieves the all hdf download links #' on a certain day, then only selects the relevant tiles from the retrieved #' links. Download is only done at the queried horizontal-vertical tile number #' combinations. An exception is MOD06_L2 product, which is produced #' every five minutes every day. -#' @note \code{date_start} and \code{date_end} should be in the same year. +#' @note Both dates in \code{date} should be in the same year. #' Directory structure looks like -#' input/modis/raw/\{version\}/\{product\}/\{year\}/\{day_of_year\} -#' Please note that \code{date_start} and \code{date_end} are -#' ignored if \code{product == 'MOD06_L2'}. +#' input/modis/raw/\{version\}/\{product\}/\{year\}/\{day_of_year\}. #' @param product character(1). #' One of `c("MOD09GA", "MOD11A1", "MOD06_L2", "MCD19A2", "MOD13A2", "VNP46A2")` #' @param version character(1). Default is `"61"`, meaning v061. @@ -2057,10 +2180,9 @@ download_koppen_geiger <- function( #' trying running the function. #' @param mod06_links character(1). CSV file path to MOD06_L2 download links #' from NASA LPDAAC. Default is `NULL`. -#' @param date_start character(1). length of 10. Start date for downloading -#' data. Format YYYY-MM-DD (ex. September 1, 2023 is `"2023-09-01"`). -#' @param date_end character(1). length of 10. End date for downloading data. -#' Format YYYY-MM-DD (ex. September 1, 2023 is `"2023-09-01"`). +#' @param date character(2). length of 10 each. Start/end date for downloading data. +#' Format "YYYY-MM-DD" (ex. January 1, 2018 = `"2018-01-01"`). Note: ignored if +#' \code{product == "MOD06_L2"}. #' @param directory_to_save character(1). Directory to save data. #' @param acknowledgement logical(1). By setting \code{TRUE} the #' user acknowledges that the data downloaded using this function may be very @@ -2070,8 +2192,60 @@ download_koppen_geiger <- function( #' the text file containing download commands. #' @author Mitchell Manware, Insang Song #' @import rvest -#' @return NULL; HDF (.hdf) files will be stored in +#' @returns NULL; HDF (.hdf) files will be stored in #' \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_mcd19a22021}{amadeus} +#' \insertRef{data_mod06l2_2017}{amadeus} +#' \insertRef{data_mod09ga2021}{amadeus} +#' \insertRef{data_mod11a12021}{amadeus} +#' \insertRef{data_mod13a22021}{amadeus} +#' \insertRef{article_roman2018vnp46}{amadeus} +# nolint end +#' @examples +#' \dontrun{ +#' # example with MOD0GA product +#' download_modis( +#' product = "MOD09GA", +#' version = "61", +#' horizontal_tiles = c(8, 10), +#' vertical_tiles = c(4, 5), +#' date = c("2024-01-01", "2024-01-10"), +#' nasa_earth_data_token = readLines("~/pre_generated_token.txt"), +#' directory_to_save = "./data/mod09ga", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' # example with MOD06_L2 product +#' download_modis( +#' product = "MOD06_L2", +#' version = "61", +#' horizontal_tiles = c(8, 10), +#' vertical_tiles = c(4, 5), +#' mod06_links = "~/LAADS_query.2024-07-15T12_17.csv", +#' date = c("2024-01-01", "2024-01-10"), +#' nasa_earth_data_token = readLines("~/pre_generated_token.txt"), +#' directory_to_save = "./data/mod06l2", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' # example with VNP46A2 product +#' download_modis( +#' product = "VNP46A2", +#' version = "61", +#' horizontal_tiles = c(8, 10), +#' vertical_tiles = c(4, 5), +#' date = c("2024-01-01", "2024-01-10"), +#' nasa_earth_data_token = readLines("~/pre_generated_token.txt"), +#' directory_to_save = "./data/vnp46a2", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_modis <- function( product = c( @@ -2083,8 +2257,7 @@ download_modis <- function( vertical_tiles = c(3, 6), mod06_links = NULL, nasa_earth_data_token = NULL, - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2023-09-01", "2023-09-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -2094,6 +2267,9 @@ download_modis <- function( #### 2. directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### 3. check for NASA earth data token if (is.null(nasa_earth_data_token)) { @@ -2102,9 +2278,9 @@ download_modis <- function( #### 4. check for product product <- match.arg(product) - if (substr(date_start, 1, 4) != substr(date_end, 1, 4)) { + if (substr(date[1], 1, 4) != substr(date[2], 1, 4)) { if (product != "MOD06_L2") { - stop("date_start and date_end should be in the same year.\n") + stop("dates should be in the same year.\n") } } @@ -2161,7 +2337,7 @@ download_modis <- function( mod06l2_url_template <- paste0(mod06l2_url1, mod06l2_url2, mod06l2_url3) mod06l2_full <- - sprintf(mod06l2_url_template, date_start, date_end) + sprintf(mod06l2_url_template, date[1], date[2]) if (is.null(mod06_links)) { stop(paste( @@ -2224,7 +2400,7 @@ download_modis <- function( #### filter commands to non-existing files download_command <- download_command[ which( - !file.exists(download_name) + !file.exists(paste0(directory_to_save, download_name)) ) ] @@ -2256,12 +2432,12 @@ download_modis <- function( #### 11. define date sequence date_sequence <- generate_date_sequence( - date_start, - date_end, + date[1], + date[2], sub_hyphen = FALSE ) # In a certain year, list all available dates - year <- as.character(substr(date_start, 1, 4)) + year <- as.character(substr(date[1], 1, 4)) filedir_year_url <- paste0( ladsurl, @@ -2284,8 +2460,8 @@ download_modis <- function( date_sequence <- list_available_d[!is.na(list_available_d)] date_sequence_i <- as.integer(date_sequence) # Queried dates to integer range - date_start_i <- as.integer(strftime(date_start, "%j")) - date_end_i <- as.integer(strftime(date_end, "%j")) + date_start_i <- as.integer(strftime(date[1], "%j")) + date_end_i <- as.integer(strftime(date[2], "%j")) date_range_julian <- seq(date_start_i, date_end_i) date_sequence_in <- (date_sequence_i %in% date_range_julian) @@ -2301,9 +2477,9 @@ download_modis <- function( directory_to_save, product, "_", - date_start, + date[1], "_", - date_end, + date[2], "_wget_commands.txt" ) @@ -2352,7 +2528,9 @@ download_modis <- function( #### filter commands to non-existing files download_command <- download_command[ which( - !file.exists(download_name) + !file.exists( + paste0(directory_to_save, download_name) + ) ) ] @@ -2388,9 +2566,8 @@ download_modis <- function( #' Download toxic release data #' @description #' The \code{download_tri()} function accesses and downloads toxic release data from the [U.S. Environmental Protection Agency's (EPA) Toxic Release Inventory (TRI) Program](https://www.epa.gov/toxics-release-inventory-tri-program/find-understand-and-use-tri). +#' @param year character(2). length of 4 each. Start/end years for downloading data. # nolint end -#' @param year_start integer(1). length of 4. Start year for downloading data. -#' @param year_end integer(1). length of 4. End year for downloading data. #' @param directory_to_save character(1). Directory to download files. #' @param acknowledgement logical(1). By setting \code{TRUE} the #' user acknowledges that the data downloaded using this function may be very @@ -2403,10 +2580,22 @@ download_modis <- function( #' @author Mariana Kassien, Insang Song #' @returns NULL; Comma-separated value (CSV) files will be stored in #' \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{web_usepa2024tri}{amadeus} +#' @examples +#' \dontrun{ +#' download_tri( +#' year = c(2020L, 2021L), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_tri <- function( - year_start = 2018L, - year_end = 2022L, + year = c(2018L, 2022L), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -2417,10 +2606,13 @@ download_tri <- function( #### 2. directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) + #### check years + stopifnot(length(year) == 2) + year <- year[order(year)] #### 3. define measurement data paths url_download <- "https://data.epa.gov/efservice/downloads/tri/mv_tri_basic_download/" - year_sequence <- seq(year_start, year_end, 1) + year_sequence <- seq(year[1], year[2], 1) download_urls <- sprintf( paste(url_download, "%.0f", "_US/csv", sep = ""), year_sequence @@ -2446,7 +2638,7 @@ download_tri <- function( commands_txt <- paste0( directory_to_save, "TRI_", - year_start, "_", year_end, + year[1], "_", year[2], "_", Sys.Date(), "_curl_commands.txt" @@ -2483,7 +2675,7 @@ download_tri <- function( #' 'extdata/cacert_gaftp_epa.pem' under the package installation path. #' @param certificate_url character(1). URL to certificate file. See notes for #' details. -#' @param year_target Available years of NEI data. +#' @param year Available years of NEI data. #' Default is \code{c(2017L, 2020L)}. #' @param directory_to_save character(1). Directory to save data. Two #' sub-directories will be created for the downloaded zip files ("/zip_files") @@ -2511,6 +2703,19 @@ download_tri <- function( #' certificate updates in the future. #' @returns NULL; Zip and/or data files will be downloaded and stored in #' respective sub-directories within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{web_usepa2024nei}{amadeus} +#' @examples +#' \dontrun{ +#' download_nei( +#' year = c(2017L, 2020L), +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export download_nei <- function( epa_certificate_path = @@ -2518,7 +2723,7 @@ download_nei <- function( package = "amadeus"), certificate_url = "http://cacerts.digicert.com/DigiCertGlobalG2TLSRSASHA2562020CA1-1.crt", - year_target = c(2017L, 2020L), + year = c(2017L, 2020L), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -2546,19 +2751,13 @@ download_nei <- function( "2020nei_onroad_byregion.zip") download_urls <- paste0( - sprintf(url_download_base, year_target), + sprintf(url_download_base, year), url_download_remain ) download_names_file <- c("2017neiApr_onroad_byregions.zip", "2020nei_onroad_byregion.zip") download_names <- paste0(directory_to_download, download_names_file) - #### filter commands to non-existing files - download_urls <- download_urls[ - which( - !file.exists(download_names) - ) - ] #### 4. build download command download_commands <- paste0("wget --ca-certificate=", @@ -2568,12 +2767,17 @@ download_nei <- function( " -O ", download_names, "\n") - + #### filter commands to non-existing files + download_commands <- download_commands[ + which( + !file.exists(download_names) + ) + ] #### 5. initiate "..._curl_commands.txt" commands_txt <- paste0( directory_original, "NEI_AADT_", - paste(year_target, collapse = "-"), + paste(year, collapse = "-"), "_", Sys.Date(), "_wget_commands.txt" @@ -2712,6 +2916,20 @@ download_nei <- function( #' @returns NULL; GeoTIFF (.tif) files will be stored in #' \code{directory_to_save}. #' @seealso [list_stac_files] +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_hengl2023openlandmap}{amadeus} +#' @examples +#' \dontrun{ +#' download_olm( +#' product = "no2_s5p.l3.trop.tmwm", +#' format = "tif", +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export # nolint end download_olm <- function( @@ -2808,12 +3026,19 @@ download_olm <- function( #' Default is \code{FALSE}. Not working for this function since HUC data is in 7z format. #' @returns NULL. Downloaded files will be stored in \code{directory_to_save}. #' @author Insang Song +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{data_usgs2023nhd}{amadeus} #' @examples #' \dontrun{ -#' download_huc("Lower48", "Seamless", "/data" -#' acknowledgement = TRUE, -#' download = TRUE, -#' unzip = TRUE) +#' download_huc( +#' region = "Lower48", +#' type = "Seamless", +#' directory_to_save = "./data", +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) #' } #' @export # @importFrom archive archive_extract @@ -2954,10 +3179,12 @@ download_huc <- #' @examples #' \dontrun{ #' download_cropscape( -#' 2020, "~/data", +#' year = 2020, +#' source = "USDA", +#' directory_to_save = "./data", #' acknowledgement = TRUE, #' download = TRUE, -#' unzip = TRUE +#' remove_command = TRUE #' ) #' } #' @importFrom archive archive_extract @@ -3097,6 +3324,9 @@ download_cropscape <- function( #' @author Insang Song #' @returns NULL; .bil (normals) or single grid files depending on the format #' choice will be stored in \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{article_daly2000prism}{amadeus} #' @examples #' \dontrun{ #' download_prism( @@ -3104,7 +3334,7 @@ download_cropscape <- function( #' element = "ppt", #' data_type = "ts", #' format = "nc", -#' directory_to_save = "~/data", +#' directory_to_save = "./data", #' acknowledgement = TRUE, #' download = TRUE, #' remove_command = TRUE @@ -3215,10 +3445,7 @@ download_prism <- function( #' @param variables character(1). Variable(s) name(s). See [gridMET Generate Wget File](https://www.climatologylab.org/wget-gridmet.html) #' for variable names and acronym codes. (Note: variable "Burning Index" has code "bi" and variable #' "Energy Release Component" has code "erc"). -#' @param year_start integer(1). length of 4. Start of year range for -#' downloading data. -#' @param year_end integer(1). length of 4. End of year range for downloading -#' data. +#' @param year character(2). length of 4 each. Start/end years for downloading data. #' @param directory_to_save character(1). Directory(s) to save downloaded data #' files. #' @param acknowledgement logical(1). By setting \code{TRUE} the @@ -3231,14 +3458,27 @@ download_prism <- function( #' Remove (\code{TRUE}) or keep (\code{FALSE}) #' the text file containing download commands. #' @author Mitchell Manware -#' @return NULL; netCDF (.nc) files will be stored in a variable-specific +#' @returns NULL; netCDF (.nc) files will be stored in a variable-specific #' folder within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{article_abatzoglou2013development}{amadeus} +#' @examples +#' \dontrun{ +#' download_gridmet( +#' variables = "Precipitation", +#' year = c(2023, 2024), +#' directory_to_save = "./data" +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export # nolint end download_gridmet <- function( variables = NULL, - year_start = 2022, - year_end = 2022, + year = c(2018, 2022), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -3247,14 +3487,17 @@ download_gridmet <- function( download_permit(acknowledgement = acknowledgement) #### check for null parameters check_for_null_parameters(mget(ls())) + #### check years + stopifnot(length(year) == 2) + year <- year[order(year)] #### directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) #### define years sequence - if (any(nchar(year_start) != 4, nchar(year_end) != 4)) { - stop("year_start and year_end should be 4-digit integers.\n") + if (any(nchar(year[1]) != 4, nchar(year[1]) != 4)) { + stop("years should be 4-digit integers.\n") } - years <- seq(year_start, year_end, 1) + years <- seq(year[1], year[2], 1) #### define variables variables_list <- process_variable_codes( variables = variables, @@ -3266,7 +3509,7 @@ download_gridmet <- function( commands_txt <- paste0( directory_to_save, "gridmet_", - year_start, "_", year_end, + year[1], "_", year[2], "_curl_commands.txt" ) download_sink(commands_txt) @@ -3278,12 +3521,12 @@ download_gridmet <- function( dir.create(folder) } for (y in seq_along(years)) { - year <- years[y] + year_l <- years[y] url <- paste0( base, variable, "_", - year, + year_l, ".nc" ) if (y == 1) { @@ -3292,7 +3535,7 @@ download_gridmet <- function( file.remove(commands_txt) stop(paste0( "Invalid year returns HTTP code 404. ", - "Check `year_start` parameter.\n" + "Check `year` parameter.\n" )) } } @@ -3302,7 +3545,7 @@ download_gridmet <- function( "/", variable, "_", - year, + year_l, ".nc" ) command <- paste0( @@ -3344,10 +3587,7 @@ download_gridmet <- function( #' The \code{download_terraclimate} function accesses and downloads climate and water balance data from the [University of California Merced Climatology Lab's TerraClimate dataset](https://www.climatologylab.org/terraclimate.html). #' @param variables character(1). Variable(s) name(s). See [TerraClimate Direct Downloads](https://climate.northwestknowledge.net/TERRACLIMATE/index_directDownloads.php) #' for variable names and acronym codes. -#' @param year_start integer(1). length of 4. Start of year range for -#' downloading data. -#' @param year_end integer(1). length of 4. End of year range for downloading -#' data. +#' @param year character(2). length of 4 each. Start/end years for downloading data. #' @param directory_to_save character(1). Directory(s) to save downloaded data #' files. #' @param acknowledgement logical(1). By setting \code{TRUE} the @@ -3360,14 +3600,27 @@ download_gridmet <- function( #' Remove (\code{TRUE}) or keep (\code{FALSE}) #' the text file containing download commands. #' @author Mitchell Manware, Insang Song -#' @return NULL; netCDF (.nc) files will be stored in a variable-specific +#' @returns NULL; netCDF (.nc) files will be stored in a variable-specific #' folder within \code{directory_to_save}. +#' @importFrom Rdpack reprompt +#' @references +#' \insertRef{article_abatzoglou2018terraclimate}{amadeus} +#' @examples +#' \dontrun{ +#' download_terraclimate( +#' variables = "Precipitation", +#' year = c(2023, 2024), +#' directory_to_save = "./data" +#' acknowledgement = TRUE, +#' download = TRUE, +#' remove_command = TRUE +#' ) +#' } #' @export # nolint end download_terraclimate <- function( variables = NULL, - year_start = 2022, - year_end = 2022, + year = c(2018, 2022), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -3376,14 +3629,17 @@ download_terraclimate <- function( download_permit(acknowledgement = acknowledgement) #### check for null parameters check_for_null_parameters(mget(ls())) + #### check years + stopifnot(length(year) == 2) + year <- year[order(year)] #### directory setup download_setup_dir(directory_to_save) directory_to_save <- download_sanitize_path(directory_to_save) #### define years sequence - if (any(nchar(year_start) != 4, nchar(year_end) != 4)) { - stop("year_start and year_end should be 4-digit integers.\n") + if (any(nchar(year[1]) != 4, nchar(year[2]) != 4)) { + stop("years should be 4-digit integers.\n") } - years <- seq(year_start, year_end, 1) + years <- seq(year[1], year[2], 1) #### define variables variables_list <- process_variable_codes( variables = variables, @@ -3396,7 +3652,7 @@ download_terraclimate <- function( commands_txt <- paste0( directory_to_save, "terraclimate_", - year_start, "_", year_end, + year[1], "_", year[2], "_curl_commands.txt" ) download_sink(commands_txt) @@ -3408,12 +3664,12 @@ download_terraclimate <- function( dir.create(folder) } for (y in seq_along(years)) { - year <- years[y] + year_l <- years[y] url <- paste0( base, variable, "_", - year, + year_l, ".nc" ) if (y == 1) { @@ -3422,7 +3678,7 @@ download_terraclimate <- function( file.remove(commands_txt) stop(paste0( "Invalid year returns HTTP code 404. ", - "Check `year_start` parameter.\n" + "Check `year` parameter.\n" )) } } @@ -3432,7 +3688,7 @@ download_terraclimate <- function( "/", variable, "_", - year, + year_l, ".nc" ) command <- paste0( diff --git a/R/download_auxiliary.R b/R/download_auxiliary.R index 2aa019a8..3aaa1ce7 100644 --- a/R/download_auxiliary.R +++ b/R/download_auxiliary.R @@ -108,11 +108,11 @@ download_run <- function( download = FALSE, system_command = NULL) { if (download == TRUE) { - cat(paste0("Downloading requested files...\n")) + message(paste0("Downloading requested files...\n")) system(command = system_command) - cat(paste0("Requested files have been downloaded.\n")) + message(paste0("Requested files have been downloaded.\n")) } else { - cat(paste0("Skipping data download.\n")) + message(paste0("Skipping data download.\n")) return(NULL) } } @@ -167,15 +167,15 @@ download_unzip <- directory_to_unzip, unzip = TRUE) { if (!unzip) { - cat(paste0("Downloaded files will not be unzipped.\n")) + message(paste0("Downloaded files will not be unzipped.\n")) return(NULL) } - cat(paste0("Unzipping files...\n")) + message(paste0("Unzipping files...\n")) unzip(file_name, exdir = directory_to_unzip ) - cat(paste0( + message(paste0( "Files unzipped and saved in ", directory_to_unzip, ".\n" @@ -201,12 +201,12 @@ download_remove_zips <- download_name) { #### remove zip files if (remove) { - cat(paste0("Removing download files...\n")) + message(paste0("Removing download files...\n")) file.remove(download_name) # oftentimes zipfiles are stored in zip_files under # directory_to_save in download functions. unlink(dirname(dirname(download_name)), recursive = TRUE) - cat(paste0("Download files removed.\n")) + message(paste0("Download files removed.\n")) } } @@ -222,6 +222,9 @@ download_remove_zips <- check_for_null_parameters <- function( parameters) { + if ("extent" %in% names(parameters)) { + parameters <- parameters[-grep("extent", names(parameters))] + } parameters_status <- any(unlist(lapply(parameters, is.null))) if (parameters_status) { stop(paste0("One or more parameters are NULL\n")) @@ -374,7 +377,7 @@ extract_urls <- function( commands = commands, position = NULL) { if (is.null(position)) { - cat(paste0("URL position in command is not defined.\n")) + message(paste0("URL position in command is not defined.\n")) return(NULL) } urls <- sapply( @@ -403,7 +406,7 @@ check_urls <- function( size = NULL, method = c("HEAD", "GET", "SKIP")) { if (is.null(size)) { - cat(paste0("URL sample size is not defined.\n")) + message(paste0("URL sample size is not defined.\n")) return(NULL) } if (length(urls) < size) { @@ -411,7 +414,7 @@ check_urls <- function( } method <- match.arg(method) if (method == "SKIP") { - cat(paste0("Skipping HTTP status check...\n")) + message(paste0("Skipping HTTP status check...\n")) return(NULL) } else { url_sample <- sample(urls, size, replace = FALSE) @@ -428,7 +431,6 @@ check_urls <- function( #' @description #' Implement directory, file, and download URL unit tests. #' @param directory_to_save directory to test saving -#' @param directory_to_download directory to test download #' @param commands_path file path with download commands #' @param url_status logical vector for URL status = 200 #' @importFrom testthat expect_true @@ -436,15 +438,9 @@ check_urls <- function( #' @keywords internal #' @export test_download_functions <- function( - directory_to_download = NULL, directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) { - # test that directory_to_download exists - # skip test if directory_to_download is default (NULL) - if (!(is.null(directory_to_download))) { - testthat::expect_true(dir.exists(directory_to_download)) - } # test that directory_to_save exists testthat::expect_true(dir.exists(directory_to_save)) # test that commands_path exists @@ -520,3 +516,59 @@ list_stac_files <- return(list_assets) } + +#' Sort NOAA NARR variables +#' @description +#' Determine whether a NOAA NARR variable selected for download is a +#' monolevel or pressure level variable. Monolevel variables are derived +#' from https://downloads.psl.noaa.gov/Datasets/NARR/Dailies/monolevel/, +#' and pressure level variables are derived from +#' https://downloads.psl.noaa.gov//Datasets/NARR/Dailies/pressure/. +#' @param variable character(1). User-selected NARR variable +#' @returns list with URL base and vector of months (blank for monolevel) +#' @keywords auxiliary +#' @export +narr_variable <- function(variable) { + stopifnot(length(variable) == 1) + mono <- c( + "acpcp", "air.2m", "air.sfc", "albedo", "apcp", + "bgrun", "bmixl.hl1", "cape", "ccond", "cdcon", + "cdlyr", "cfrzr", "cicep", "cin", "cnwat", + "crain", "csnow", "dlwrf", "dpt.2m", "dswrf", + "evap", "gflux", "hcdc", "hgt.tropo", "hlcy", + "hpbl", "lcdc", "lftx4", "lhtfl", "mcdc", + "mconv.hl1", "mslet", "mstav", "pevap", "pottmp.hl1", + "pottmp.sfc", "prate", "pres.sfc", "pres.tropo", "prmsl", + "pr_wtr", "rcq", "rcs", "rcsol", "rct", + "rhum.2m", "shtfl", "shum.2m", "snod", "snohf", + "snom", "snowc", "soilm", "ssrun", "tcdc", + "tke.hl1", "ulwrf.ntat", "ulwrf.sfc", "ustm", "uswrf.ntat", + "uswrf.sfc", "uwnd.10m", "veg", "vis", "vstm", + "vvel.hl1", "vwnd.10m", "vwsh.tropo", "wcconv", "wcinc", + "wcuflx", "wcvflx", "weasd", "wvconv", "wvinc", + "wvuflx", "wvvflx" + ) + pressure <- c("air", "hgt", "omega", "shum", "tke", "uwnd", "vwnd") + soil <- c("soill", "soilw", "tsoil") + base <- "https://psl.noaa.gov/thredds/fileServer/Datasets/NARR/Dailies/" + if (variable %in% mono) { + base <- paste0(base, "monolevel/") + months <- "" + } else { + months <- sprintf("%02d", seq(1, 12, by = 1)) + if (variable %in% pressure) { + base <- paste0(base, "pressure/") + } else if (variable %in% soil) { + base <- paste0(base, "subsurface/") + } else { + stop( + paste0( + "Selected variable \"", + variable, + "\" is not available.\n" + ) + ) + } + } + return(list(base, months)) +} diff --git a/R/process.R b/R/process.R index adce2480..d578b7f1 100644 --- a/R/process.R +++ b/R/process.R @@ -13,7 +13,7 @@ #' @seealso #' - [`process_modis_swath`]: `"modis_swath"` #' - [`process_modis_merge`]: `"modis_merge"` -#' - [`process_bluemarble`]: `"bluemarble"` +#' - [`process_blackmarble`]: `"blackmarble"` #' - [`process_koppen_geiger`]: `"koppen-geiger"`, `"koeppen-geiger"`, `"koppen"` #' - [`process_ecoregion`]: `"ecoregion"`, `"ecoregions"` #' - [`process_nlcd`]: `"nlcd"` @@ -36,13 +36,22 @@ #' @returns `SpatVector`, `SpatRaster`, `sf`, or `character` depending on #' covariate type and selections. #' @author Insang Song +#' @examples +#' \dontrun{ +#' narr <- process_covariates( +#' covariate = "narr", +#' date = c("2023-01-01", "2023-01-10"), +#' variable = "weasd", +#' path = "./data/weasd" +#' ) +#' } #' @export # nolint end process_covariates <- function( covariate = c("modis_swath", "modis_merge", "koppen-geiger", - "bluemarble", + "blackmarble", "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "hms", "smoke", @@ -65,7 +74,7 @@ process_covariates <- what_to_run <- switch(covariate, modis_merge = process_modis_merge, modis_swath = process_modis_swath, - bluemarble = process_bluemarble, + blackmarble = process_blackmarble, ecoregion = process_ecoregion, ecoregions = process_ecoregion, koppen = process_koppen_geiger, @@ -143,6 +152,8 @@ process_covariates <- #' @returns A character object that conforms to the regular #' expression. Details of regular expression in R can be found in [regexp]. #' @seealso [calc_modis_par] +#' @examples +#' process_modis_sds(product = "MOD09GA") #' @export # previously modis_prefilter_sds process_modis_sds <- @@ -204,6 +215,15 @@ process_modis_sds <- #' @importFrom terra nlyr #' @importFrom terra tapp #' @importFrom terra is.rotated +#' @examples +#' \dontrun{ +#' mod09ga_flatten <- process_flatten_sds( +#' path = +#' list.files("./data", pattern = "MOD09GA.", full.names = TRUE)[1], +#' subdataset = process_modis_sds("MOD09GA"), +#' fun_agg = "mean" +#' ) +#' } #' @export # previously modis_aggregate_sds process_flatten_sds <- @@ -279,6 +299,16 @@ the input then flatten it manually.") #' @seealso [`download_data`] #' @author Insang Song #' @returns a `SpatRaster` object +#' @examples +#' \dontrun{ +#' mod09ga_merge <- process_modis_merge( +#' path = +#' list.files("./data", pattern = "MOD09GA.", full.names = TRUE), +#' date = "2024-01-01", +#' subdataset = "sur_refl_b01_1", +#' fun_agg = "mean" +#' ) +#' } #' @export # nolint end # previously modis_get_vrt @@ -327,21 +357,23 @@ process_modis_merge <- function( # nolint start -#' Process Blue Marble corners +#' Process Black Marble corners #' @description -#' Tile corner generator for Blue Marble products. +#' Tile corner generator for Black Marble products. #' @param hrange integer(2). Both should be in 0-35. #' @param vrange integer(2). Both should be in 0-17. -#' @description Blue Marble products are in HDF5 format and are read without +#' @description Black Marble products are in HDF5 format and are read without #' georeference with typical R geospatial packages. #' This function generates a `data.frame` of corner coordinates for assignment. #' @returns `data.frame` with xmin, xmax, ymin, and ymax fields #' @author Insang Song #' @references -#' - [Wang, Z. (2022). Blue Marble User Guide (Version 1.3). NASA.](https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document%20Archive/Science%20Data%20Product%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf) +#' - [Wang, Z. (2022). Black Marble User Guide (Version 1.3). NASA.](https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document%20Archive/Science%20Data%20Product%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf) +#' @examples +#' process_blackmarble_corners(hrange = c(1, 2), vrange = c(1, 2)) #' @export # nolint end -process_bluemarble_corners <- +process_blackmarble_corners <- function( hrange = c(5, 11), vrange = c(3, 6) @@ -381,15 +413,15 @@ process_bluemarble_corners <- # nolint start -#' Assign VIIRS Blue Marble products corner coordinates to retrieve a merged raster +#' Assign VIIRS Black Marble products corner coordinates to retrieve a merged raster #' @description This function will return a `SpatRaster` object with -#' georeferenced h5 files of Blue Marble product. Referencing corner coordinates +#' georeferenced h5 files of Black Marble product. Referencing corner coordinates #' are necessary as the original h5 data do not include such information. #' @param path character. Full paths of h5 files. #' @param date character(1). Date to query. #' @param tile_df data.frame. Contains four corner coordinates in fields named #' `c("xmin", "xmax", "ymin", "ymax")`. -#' See [`process_bluemarble_corners`] to generate a valid object for this argument. +#' See [`process_blackmarble_corners`] to generate a valid object for this argument. #' @param subdataset integer(1). Subdataset number to process. #' Default is 3L. #' @param crs character(1). terra::crs compatible CRS. @@ -400,20 +432,32 @@ process_bluemarble_corners <- #' @seealso #' * [`terra::describe`] #' * [`terra::merge`] -#' * [`process_bluemarble_corners`] +#' * [`process_blackmarble_corners`] #' @references -#' - [Wang, Z. (2022). Blue Marble User Guide (Version 1.3). NASA.](https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document%20Archive/Science%20Data%20Product%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf) +#' - [Wang, Z. (2022). Black Marble User Guide (Version 1.3). NASA.](https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document%20Archive/Science%20Data%20Product%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf) #' @importFrom terra rast #' @importFrom terra ext #' @importFrom terra crs #' @importFrom terra merge +#' @examples +#' \dontrun{ +#' vnp46a2 <- process_blackmarble( +#' path = +#' list.files("./data", pattern = "VNP46A2.", full.names = TRUE), +#' date = "2024-01-01", +#' tile_df = +#' process_blackmarble_corners(hrange = c(8, 10), vrange = c(4, 5)) +#' subdataset = 3L, +#' crs = "EPSG:4326" +#' ) +#' } #' @export # previously modis_preprocess_vnp46 # nolint end -process_bluemarble <- function( +process_blackmarble <- function( path = NULL, date = NULL, - tile_df = process_bluemarble_corners(), + tile_df = process_blackmarble_corners(), subdataset = 3L, crs = "EPSG:4326", ... @@ -486,6 +530,23 @@ process_bluemarble <- function( #' @seealso [`terra::rectify`] #' @importFrom stars st_warp #' @importFrom stars read_stars +#' @examples +#' \dontrun{ +#' mod06l2_warp <- process_modis_warp( +#' path = paste0( +#' "HDF4_EOS:EOS_SWATH:", +#' list.files( +#' "./data/mod06l2", +#' full.names = TRUE, +#' pattern = ".hdf" +#' )[1], +#' ":mod06:Cloud_Fraction" +#' ), +#' cellsize = 0.1, +#' threshold = 0.4, +#' crs = 4326 +#' ) +#' } #' @export # previously modis_warp_stars process_modis_warp <- @@ -548,6 +609,20 @@ process_modis_warp <- #' @importFrom stars st_mosaic #' @importFrom terra values #' @importFrom terra sprc +#' @examples +#' \dontrun{ +#' mod06l2_swath <- process_modis_swath( +#' path = list.files( +#' "./data/mod06l2", +#' full.names = TRUE, +#' pattern = ".hdf" +#' ), +#' date = "2024-01-01", +#' subdataset = "Cloud_Fraction", +#' suffix = ":mod06:", +#' resolution = 0.05 +#' ) +#' } #' @export # nolint end # previously modis_mosaic_mod06 @@ -640,29 +715,33 @@ process_modis_swath <- } - -# Process downloaded raw data - #' Process climate classification data #' @description #' The \code{process_koppen_geiger()} function imports and cleans raw climate #' classification data, returning a single `SpatRaster` object. #' @param path character(1). Path to Koppen-Geiger #' climate zone raster file -#' @param year data year. Not applicable for this function. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @returns a `SpatRaster` object #' @author Insang Song #' @importFrom terra rast +#' @examples +#' \dontrun{ +#' kg <- process_koppen_geiger( +#' path = "./data/koppen_geiger_data.tif" +#' ) +#' } #' @export process_koppen_geiger <- function( path = NULL, - year = NULL, + extent = NULL, ... ) { # import data - kg_rast <- terra::rast(path) + kg_rast <- terra::rast(path, win = extent) # identify time period period <- strsplit( names(kg_rast), @@ -690,8 +769,15 @@ process_koppen_geiger <- #' @returns a `SpatRaster` object #' @author Eva Marques, Insang Song #' @importFrom utils read.csv -#' @importFrom terra rast -#' @importFrom terra metags +#' @importFrom tools file_path_sans_ext +#' @importFrom terra rast metags +#' @examples +#' \dontrun{ +#' nlcd <- process_nlcd( +#' path = "./data/", +#' year = 2021 +#' ) +#' } #' @export process_nlcd <- function( @@ -717,6 +803,12 @@ process_nlcd <- pattern = paste0("nlcd_", year, "_.*.(tif|img)$"), full.names = TRUE ) + # check if name without extension is duplicated + nlcd_file_base <- basename(nlcd_file) + nlcd_file_base <- tools::file_path_sans_ext(nlcd_file_base) + if (any(duplicated(nlcd_file_base))) { + stop("Duplicated NLCD files are detected. Please remove duplicates.") + } if (length(nlcd_file) == 0) { stop("NLCD data not available for this year.") } @@ -731,6 +823,8 @@ process_nlcd <- #' The [`process_ecoregion`] function imports and cleans raw ecoregion #' data, returning a `SpatVector` object. #' @param path character(1). Path to Ecoregion Shapefiles +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @note The function will fix Tukey's bridge in Portland, ME. #' This fix will ensure that the EPA air quality monitoring sites @@ -740,10 +834,17 @@ process_nlcd <- #' @importFrom terra vect #' @importFrom sf st_read st_crs st_as_sfc st_transform st_intersects st_union #' @importFrom data.table year +#' @examples +#' \dontrun{ +#' ecoregion <- process_ecoregion( +#' path = "./data/epa_ecoregion.gpkg" +#' ) +#' } #' @export process_ecoregion <- function( path = NULL, + extent = NULL, ... ) { ecoreg <- sf::st_read(path) @@ -767,7 +868,12 @@ process_ecoregion <- "1997 - ", data.table::year(Sys.time()) ) ecoreg <- terra::vect(ecoreg) - return(ecoreg) + if (!is.null(extent)) { + ecoreg_crop <- terra::crop(ecoreg, extent) + return(ecoreg_crop) + } else { + return(ecoreg) + } } @@ -779,6 +885,8 @@ process_ecoregion <- #' @param path character(1). Path to the directory with TRI CSV files #' @param year integer(1). Single year to select. #' @param variables integer. Column index of TRI data. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @author Insang Song, Mariana Kassien #' @returns a `SpatVector` object (points) in `year` @@ -804,12 +912,21 @@ process_ecoregion <- #' @importFrom dplyr summarize #' @importFrom tidyr pivot_wider #' @importFrom stats setNames +#' @examples +#' \dontrun{ +#' tri <- process_tri( +#' path = "./data", +#' year = 2020, +#' variables = c(1, 13, 12, 14, 20, 34, 36, 47, 48, 49) +#' ) +#' } # nolint end #' @export process_tri <- function( path = NULL, year = 2018, variables = c(1, 13, 12, 14, 20, 34, 36, 47, 48, 49), + extent = NULL, ... ) { @@ -866,8 +983,12 @@ process_tri <- function( crs = "EPSG:4269", # all are NAD83 keepgeom = TRUE) attr(spvect_tri, "tri_year") <- year - - return(spvect_tri) + if(!is.null(extent)) { + tri_final <- apply_extent(spvect_tri, extent) + return(tri_final) + } else { + return(spvect_tri) + } } # nolint end @@ -899,6 +1020,14 @@ process_tri <- function( #' @importFrom data.table .SD #' @importFrom data.table fread #' @importFrom data.table rbindlist +#' @examples +#' \dontrun{ +#' nei <- process_nei( +#' path = "./data", +#' county = system.file("gpkg/nc.gpkg", package = "sf"), +#' year = 2017 +#' ) +#' } #' @export # nolint end process_nei <- function( @@ -973,10 +1102,11 @@ process_nei <- function( } # nolint start -#' Process unique U.S. EPA AQS sites +#' Process U.S. EPA AQS daily CSV data #' @description #' The \code{process_aqs()} function cleans and imports raw air quality -#' monitoring sites, returning a single `SpatVector` or sf object. +#' monitoring sites from pre-generated daily CSV files, returning a single +#' `SpatVector` or `sf` object. #' `date` is used to filter the raw data read from csv files. #' Filtered rows are then processed according to `mode` argument. #' Some sites report multiple measurements per day with and without @@ -986,11 +1116,15 @@ process_nei <- function( #' @param path character(1). Directory path to daily measurement data. #' @param date character(2). Start and end date. #' Should be in `"YYYY-MM-DD"` format and sorted. -#' @param mode character(1). One of "full" (all dates * all locations) -#' or "sparse" (date-location pairs with available data) or -#' "location" (unique locations). +#' @param mode character(1). One of +#' * "date-location" (all dates * all locations) +#' * "available-data" (date-location pairs with available data) +#' * "location" (unique locations). #' @param data_field character(1). Data field to extract. #' @param return_format character(1). `"terra"` or `"sf"` or `"data.table"`. +#' @param extent numeric(4). Spatial extent of the resulting object. +#' The order should be `c(xmin, xmax, ymin, ymax)`. +#' The coordinate system should be WGS84 (EPSG:4326). #' @param ... Placeholders. #' @seealso #' * [`download_aqs()`] @@ -1003,16 +1137,27 @@ process_nei <- function( #' @importFrom sf st_as_sf #' @importFrom dplyr group_by ungroup filter mutate select distinct #' @note Choose `date` and `mode` values with caution. -#' The function may return a massive data.table, resulting in -#' a long processing time or even a crash. +#' The function may return a massive data.table depending on the time range, +#' resulting in a long processing time or even a crash if data is too large +#' for your computing environment to process. +#' @examples +#' \dontrun{ +#' aqs <- process_aqs( +#' path = "./data/aqs_daily_example.csv", +#' date = c("2022-12-01", "2023-01-31"), +#' mode = "full", +#' return_format = "terra" +#' ) +#' } #' @export process_aqs <- function( path = NULL, date = c("2018-01-01", "2022-12-31"), - mode = c("full", "sparse", "location"), + mode = c("date-location", "available-data", "location"), data_field = "Arithmetic.Mean", return_format = c("terra", "sf", "data.table"), + extent = NULL, ... ) { mode <- match.arg(mode) @@ -1072,7 +1217,7 @@ process_aqs <- dplyr::mutate(time = Date.Local) |> dplyr::ungroup() col_sel <- c("site_id", "Longitude", "Latitude", "Datum") - if (mode != "sparse") { + if (mode != "available-data") { sites_v <- unique(sites[, col_sel]) } else { col_sel <- append(col_sel, "Event.Type") @@ -1086,7 +1231,7 @@ process_aqs <- sites_vdup <- sites_v |> dplyr::group_by(site_id, time) |> dplyr::filter(dplyr::n() > 1) |> - dplyr::filter(Event.Type == "Excluded") |> + dplyr::filter(!!dplyr::sym("Event.Type") == "Excluded") |> dplyr::ungroup() sites_v <- dplyr::anti_join( @@ -1118,7 +1263,7 @@ process_aqs <- final_sites <- final_sites[, grep("Datum", names(final_sites), invert = TRUE), with = FALSE] - if (mode == "full") { + if (mode == "date-location") { final_sites <- split(date_sequence, date_sequence) |> lapply(function(x) { @@ -1128,7 +1273,7 @@ process_aqs <- }) final_sites <- data.table::rbindlist(final_sites, fill = TRUE) } - if (mode == "sparse") { + if (mode == "available-data") { final_sites <- unique(final_sites) } @@ -1151,6 +1296,13 @@ process_aqs <- ), data.table = final_sites ) + if (!is.null(extent)) { + if (return_format == "data.table") { + warning("Extent is not applicable for data.table. Returning data.table...\n") + return(final_sites) + } + final_sites <- apply_extent(final_sites, extent) + } return(final_sites) } @@ -1161,23 +1313,36 @@ process_aqs <- #' The \code{process_secac_population()} function imports and cleans raw #' population density data, returning a single `SpatRaster` object. #' @param path character(1). Path to GeoTIFF (.tif) or netCDF (.nc) file. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @author Mitchell Manware #' @return a `SpatRaster` object #' @importFrom terra rast +#' @examples +#' \dontrun{ +#' pop <- process_sedac_population( +#' path = "./data/sedac_population_example.tif" +#' ) +#' } #' @export # nolint end process_sedac_population <- function( path = NULL, + extent = NULL, ...) { if (substr(path, nchar(path) - 2, nchar(path)) == ".nc") { - cat(paste0("netCDF functionality for SEDAC data is under construction.\n")) + message( + paste0( + "netCDF functionality for SEDAC data is under construction.\n" + ) + ) return() } #### check for variable check_for_null_parameters(mget(ls())) #### import data - data <- terra::rast(path) + data <- terra::rast(path, win = extent) #### identify names names_raw <- names(data) #### create new names @@ -1198,7 +1363,7 @@ process_sedac_population <- function( "_", split2[3] ) - cat(paste0( + message(paste0( "Cleaning ", process_sedac_codes( paste0( @@ -1225,6 +1390,8 @@ process_sedac_population <- function( #' The \code{process_sedac_groads()} function imports and cleans raw road data, #' returning a single `SpatVector` object. #' @param path character(1). Path to geodatabase or shapefiles. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @note U.S. context. The returned `SpatVector` object contains a #' `$description` column to represent the temporal range covered by the @@ -1232,10 +1399,17 @@ process_sedac_population <- function( #' @author Insang Song #' @returns a `SpatVector` object #' @importFrom terra vect +#' @examples +#' \dontrun{ +#' groads <- process_sedac_groads( +#' path = "./data/groads_example.shp" +#' ) +#' } #' @export # nolint end process_sedac_groads <- function( path = NULL, + extent = NULL, ...) { #### check for variable check_for_null_parameters(mget(ls())) @@ -1243,7 +1417,7 @@ process_sedac_groads <- function( stop("Input is not in expected format.\n") } #### import data - data <- terra::vect(path) + data <- terra::vect(path, extent = extent) #### time period data$description <- "1980 - 2010" return(data) @@ -1258,18 +1432,20 @@ process_sedac_groads <- function( #' @param date character(2). length of 10 each. #' Start/end date of downloaded data. #' Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). -#' @param variable character(1). "Light", "Medium", or "Heavy". #' @param path character(1). Directory with downloaded NOAA HMS data files. +#' @param extent numeric(4) or SpatExtent giving the extent of the output +#' if `NULL` (default), the entire data is returned #' @param ... Placeholders. #' @note #' \code{process_hms()} will return a character object if there are no wildfire #' smoke plumes present for the selected dates and density. The returned -#' character will contain the selected density value and the sequence of dates +#' character will contain the density value and the sequence of dates #' for which no wildfire smoke plumes were detected (see "Examples"). +#' If multiple density polygons overlap, the function will return the +#' highest density value. #' @examples -#' process_hms( +#' hms <- process_hms( #' date = c("2018-12-30", "2019-01-01"), -#' variable = "Light", #' path = "../tests/testdata/hms/" #' ) # nolint end @@ -1278,16 +1454,20 @@ process_sedac_groads <- function( #' @importFrom terra vect #' @importFrom terra aggregate #' @importFrom terra subset +#' @importFrom stats na.omit #' @export process_hms <- function( date = c("2018-01-01", "2018-01-01"), - variable = c("Light", "Medium", "Heavy"), path = NULL, + extent = NULL, ...) { #### directory setup path <- download_sanitize_path(path) #### check for variable check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### identify file paths paths <- list.files( path, @@ -1324,19 +1504,17 @@ process_hms <- function( #### process data data_return <- terra::vect() for (d in seq_along(data_paths)) { - data_date <- terra::vect(data_paths[d]) + data_date <- terra::vect(data_paths[d], extent = extent) data_date_p <- terra::project( data_date, "EPSG:4326" ) #### subset to density of interest - data_density <- data_date_p[ - tolower(data_date_p$Density) == tolower(variable) - ] + data_density <- data_date_p + #### absent polygons (ie. December 31, 2018) if (nrow(data_density) == 0) { - cat(paste0( - variable, + message(paste0( " smoke plume polygons absent for date ", as.Date( dates_of_interest[d], @@ -1350,57 +1528,85 @@ process_hms <- function( data_return <- rbind(data_return, data_missing) } else { date <- as.Date( - substr( - data_density$Start[1], - 1, - 7 - ), + substr(data_density$Start[1], 1, 7), format = "%Y%j" ) - cat(paste0( - "Cleaning ", - tolower(variable), - " data for date ", - date, - "...\n" + message(paste0( + "Cleaning smoke data for date ", + date[1], + "..." )) #### zero buffer to avoid self intersection data_0_buffer <- terra::buffer( data_density, width = 0 ) + # add dummy polygons + poly_dummy <- + "POLYGON((-180 -86,-179.99 -86,-179.99 -85.99,-180 -85.99,-180 -86))" + poly_dummy <- terra::vect(poly_dummy) + poly_dummy <- rbind(poly_dummy, poly_dummy, poly_dummy) + poly_dummy <- terra::set.crs(poly_dummy, terra::crs(data_0_buffer)) + poly_dummy$Density <- c("Heavy", "Medium", "Light") + poly_dummy$.hmsdummy <- 1 + data_0_buffer_a <- rbind(data_0_buffer, poly_dummy) + data_0_buffer_a$.hmsdummy <- + ifelse( + is.nan(data_0_buffer_a$.hmsdummy), + NA, + data_0_buffer_a$.hmsdummy + ) #### aggregate polygons data_aggregate <- terra::aggregate( - data_0_buffer, + data_0_buffer_a, by = "Density", dissolve = TRUE ) - #### factorize - data_aggregate$Date <- paste0( - gsub( - "-", - "", - date + + # Density index sorting to Heavy-Medium-Light + sort_index <- data_aggregate$Density + sort_index <- + match( + c("Heavy", "Medium", "Light"), + sort_index ) - ) + sort_index <- stats::na.omit(sort_index) + data_aggregate <- data_aggregate[sort_index, ] + + # union polygons. Heavy-Medium-Light are 1, 2, 3, respectively. + data_aggregate <- terra::union(data_aggregate) + data_aggregate$indx <- + as.numeric( + paste0( + data_aggregate$id_1, + data_aggregate$id_2, + data_aggregate$id_3 + ) + ) + # cut integers into three classes, assign labels + data_aggregate$Density <- + cut( + data_aggregate$indx, + c(0, 10, 100, 1000), + labels = c("Light", "Medium", "Heavy"), + right = FALSE + ) + # reaggregate to dissolve polygons + data_aggregate <- terra::aggregate(data_aggregate, by = "Density") + data_aggregate$Date <- date + #### factorize #### select "Density" and "Date" - data_aggregate <- data_aggregate[ - seq_len(nrow(data_aggregate)), c("Density", "Date") - ] - #### apply date format - data_aggregate$Date <- as.Date( - data_aggregate$Date, - format = "%Y%m%d" - ) + data_aggregate <- data_aggregate[, c("Density", "Date")] #### merge with other data data_return <- rbind(data_return, data_aggregate) + reext <- terra::ext(c(-180, 180, -65, 85)) + data_return <- terra::crop(data_return, reext) } } #### if no polygons if (nrow(data_return) == 0) { - cat(paste0( - variable, - " smoke plume polygons absent from ", + message(paste0( + "Smoke plume polygons absent from ", as.Date( dates_of_interest[1], format = "%Y%m%d" @@ -1412,13 +1618,11 @@ process_hms <- function( ), ". Returning vector of dates.\n" )) - no_polygon_return <- c(variable, as.character(dates_no_polygon)) + no_polygon_return <- c(as.character(dates_no_polygon)) return(no_polygon_return) } else if (nrow(data_return) > 0) { - cat(paste0( - "Returning daily ", - tolower(variable), - " data from ", + message(paste0( + "Returning daily smoke data from ", as.Date( dates_of_interest[1], format = "%Y%m%d" @@ -1448,6 +1652,8 @@ process_hms <- function( #' * Resolution options: "30 arc-seconds", "15 arc-seconds", "7.5 arc-seconds" #' @param path character(1). Directory with downloaded GMTED "*_grd" #' folder containing .adf files. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @author Mitchell Manware #' @note @@ -1456,10 +1662,18 @@ process_hms <- function( #' @return a `SpatRaster` object #' @importFrom terra rast #' @importFrom terra varnames +#' @examples +#' \dontrun{ +#' gmted <- process_gmted( +#' variable = c("Breakline Emphasis", "7.5 arc-seconds"), +#' path = "./data/be75_grd" +#' ) +#' } #' @export process_gmted <- function( variable = NULL, path = NULL, + extent = NULL, ...) { #### directory setup path <- download_sanitize_path(path) @@ -1486,7 +1700,7 @@ process_gmted <- function( resolution = TRUE, invert = FALSE ) - cat(paste0( + message(paste0( "Cleaning ", statistic, " data at ", @@ -1515,7 +1729,7 @@ process_gmted <- function( ) data_path <- data_paths[grep("(_grd$|w001001.adf)", data_paths)] #### import data - data <- terra::rast(data_path) + data <- terra::rast(data_path, win = extent) #### layer name names(data) <- paste0( "elevation_", @@ -1552,6 +1766,8 @@ process_gmted <- function( #' @param variable character(1). Variable name acronym. See [List of Variables in NARR Files](https://ftp.cpc.ncep.noaa.gov/NARR/fixed/merged_land_AWIP32corrected.pdf) #' for variable names and acronym codes. #' @param path character(1). Directory with downloaded netCDF (.nc) files. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @note #' Layer names of the returned `SpatRaster` object contain the variable acronym, @@ -1562,17 +1778,29 @@ process_gmted <- function( #' @importFrom terra time #' @importFrom terra subset #' @importFrom stringi stri_pad +#' @examples +#' \dontrun{ +#' narr <- process_narr( +#' date = c("2022-01-01", "2022-01-10"), +#' variable = "weasd", +#' path = "./data/weasd" +#' ) +#' } #' @export # nolint end process_narr <- function( date = c("2023-09-01", "2023-09-01"), variable = NULL, path = NULL, + extent = NULL, ...) { #### directory setup path <- download_sanitize_path(path) #### check for variable check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### identify file paths data_paths <- list.files( path, @@ -1635,8 +1863,8 @@ process_narr <- function( data_full <- terra::rast() for (p in seq_along(data_paths_ym)) { #### import data - data_year <- terra::rast(data_paths_ym[p]) - cat(paste0( + data_year <- terra::rast(data_paths_ym[p], win = extent) + message(paste0( "Cleaning ", variable, " data for ", @@ -1668,7 +1896,7 @@ process_narr <- function( #### check for mono or pressure levels if (grepl("level", names(data_year)[1])) { #### pressure levels data - cat(paste0("Detected pressure levels data...\n")) + message(paste0("Detected pressure levels data...\n")) days <- sapply( strsplit( names(data_year), @@ -1715,7 +1943,7 @@ process_narr <- function( ) } else { #### mono level data - cat(paste0("Detected monolevel data...\n")) + message(paste0("Detected monolevel data...\n")) names(data_year) <- paste0( variable, "_", @@ -1743,7 +1971,7 @@ process_narr <- function( ) %in% date_sequence ) ) - cat(paste0( + message(paste0( "Returning daily ", variable, " data from ", @@ -1769,6 +1997,8 @@ process_narr <- function( #' @param date character(2). length of 10. Format "YYYY-MM-DD". #' @param variable character(1). GEOS-CF variable name(s). #' @param path character(1). Directory with downloaded netCDF (.nc4) files. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @note #' Layer names of the returned `SpatRaster` object contain the variable, @@ -1780,16 +2010,28 @@ process_narr <- function( #' @importFrom terra varnames #' @importFrom terra crs #' @importFrom terra subset +#' @examples +#' \dontrun{ +#' geos <- process_geos( +#' date = c("2024-01-01", "2024-01-10"), +#' variable = "O3", +#' path = "./data/aqc_tavg_1hr_g1440x721_v1" +#' ) +#' } #' @export process_geos <- function(date = c("2018-01-01", "2018-01-01"), variable = NULL, path = NULL, + extent = NULL, ...) { #### directory setup path <- download_sanitize_path(path) #### check for variable check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### identify file paths paths <- list.files( path, @@ -1823,7 +2065,7 @@ process_geos <- source = "geos", collection = TRUE ) - cat( + message( paste0( "Identified collection ", collection, @@ -1840,7 +2082,7 @@ process_geos <- source = "geos", datetime = TRUE ) - cat(paste0( + message(paste0( "Cleaning ", variable, " data for ", @@ -1919,7 +2161,7 @@ process_geos <- } #### set coordinate reference system terra::crs(data_return) <- "EPSG:4326" - cat(paste0( + message(paste0( "Returning hourly ", variable, " data from ", @@ -1938,129 +2180,6 @@ process_geos <- return(data_return) } - - - - -#' Process GEOS-CF and MERRA2 collection codes -#' @description -#' Identify the GEOS-CF or MERRA2 collection based on the file path. -#' @param path character(1). File path to data file. -#' @param source character(1). "geos" for GEOS-CF or "merra2" for MERRA2 -#' @param collection logical(1). Identifies and returns collection -#' name(s) based on provided file path(s). -#' @param date logical(1). Identifies and returns date sequence (YYYYMMDD) based -#' on provided file path(s). -#' @param datetime logical(1). Identifies and returns date time sequence -#' (YYYYMoMoDDHHMiMi) based on provided file path(s). -#' @keywords auxillary -#' @return character -#' @export -process_collection <- - function( - path, - source, - collection = FALSE, - date = FALSE, - datetime = FALSE) { - #### check for more than one true - parameters <- c(collection, date, datetime) - if (length(parameters[parameters == TRUE]) > 1) { - stop( - paste0( - "Select one of 'collection', 'date', or 'datetime'.\n" - ) - ) - } - #### source names - geos <- c("geos", "GEOS", "geos-cf", "GEOS-CF") - merra2 <- c("merra", "merra2", "MERRA", "MERRA2") - #### string split point - if (source %in% merra2) { - code <- "MERRA2_400." - } else if (source %in% geos) { - code <- "GEOS-CF.v01.rpl." - } - #### split full file path based on unique GEOS-CF character - split_source <- unlist( - strsplit( - path, - code - ) - ) - #### split file path into collection, datetime, and "nc4" - split_period <- unlist( - strsplit( - split_source[ - which( - endsWith(split_source, ".nc4") - ) - ], - "\\." - ) - ) - #### remove "nc4" - split_wo_nc4 <- split_period[!split_period == "nc4"] - #### return merra2 collection information - if (source %in% merra2) { - #### return only collection name - if (collection == TRUE) { - return(split_wo_nc4[1]) - } - #### return date sequence - if (date == TRUE) { - return(split_wo_nc4[2]) - } - } - #### create data frame - split_df <- data.frame( - split_wo_nc4[ - which( - !(endsWith( - split_wo_nc4, - "z" - )) - ) - ], - split_wo_nc4[ - which( - endsWith( - split_wo_nc4, - "z" - ) - ) - ] - ) - #### colnames - colnames(split_df) <- c("collection", "datetime") - #### return only collection name - if (collection == TRUE) { - return(split_df$collection) - } - #### return date sequence - if (date == TRUE) { - split_dates <- substr( - split_df$datetime, - 1, - 8 - ) - return(split_dates) - } - #### return datetime sequence - if (datetime == TRUE) { - split_datetime <- gsub( - "_", - "", - gsub( - "z", - "", - split_df$datetime - ) - ) - return(split_datetime) - } - } - #' Process meteorological and atmospheric data #' @description #' The \code{process_merra2()} function imports and cleans raw atmospheric @@ -2068,6 +2187,8 @@ process_collection <- #' @param date character(2). length of 10. Format "YYYY-MM-DD". #' @param variable character(1). MERRA2 variable name(s). #' @param path character(1). Directory with downloaded netCDF (.nc4) files. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @note #' Layer names of the returned `SpatRaster` object contain the variable, @@ -2081,16 +2202,28 @@ process_collection <- #' @importFrom terra names #' @importFrom terra crs #' @importFrom terra subset +#' @examples +#' \dontrun{ +#' merra2 <- process_merra2( +#' date = c("2024-01-01", "2024-01-10"), +#' variable = "CPT", +#' path = "./data/inst1_2d_int_Nx" +#' ) +#' } #' @export process_merra2 <- function(date = c("2018-01-01", "2018-01-01"), variable = NULL, path = NULL, + extent = NULL, ...) { #### directory setup path <- download_sanitize_path(path) #### check for variable check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### identify file paths paths <- list.files( path, @@ -2124,7 +2257,7 @@ process_merra2 <- source = "merra2", collection = TRUE ) - cat( + message( paste0( "Identified collection ", collection, @@ -2135,13 +2268,13 @@ process_merra2 <- data_return <- terra::rast() for (p in seq_along(data_paths)) { #### import .nc4 data - data_raw <- terra::rast(data_paths[p]) + data_raw <- terra::rast(data_paths[p], win = extent) data_date <- process_collection( data_paths[p], source = "merra2", date = TRUE ) - cat( + message( paste0( "Cleaning ", variable, @@ -2214,7 +2347,7 @@ process_merra2 <- ) } terra::crs(data_return) <- "EPSG:4267" - cat(paste0( + message(paste0( "Returning hourly ", variable, " data from ", @@ -2246,6 +2379,9 @@ process_merra2 <- #' for variable names and acronym codes. (Note: variable "Burning Index" has code "bi" and variable #' "Energy Release Component" has code "erc"). #' @param path character(1). Directory with downloaded netCDF (.nc) files. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded +#' @param ... Placeholders. #' @note #' Layer names of the returned `SpatRaster` object contain the variable acronym, #' and date. @@ -2254,14 +2390,27 @@ process_merra2 <- #' @importFrom terra rast #' @importFrom terra time #' @importFrom terra subset +#' @examples +#' \dontrun{ +#' gridmet <- process_gridmet( +#' date = c("2023-01-01", "2023-01-10"), +#' variable = "Precipitation", +#' path = "./data/pr" +#' ) +#' } #' @export # nolint end process_gridmet <- function( date = c("2023-09-01", "2023-09-01"), variable = NULL, - path = NULL) { + path = NULL, + extent = NULL, + ...) { #### directory setup path <- download_sanitize_path(path) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] #### check for variable check_for_null_parameters(mget(ls())) variable_checked <- process_variable_codes( @@ -2310,8 +2459,8 @@ process_gridmet <- function( data_full <- terra::rast() for (p in seq_along(data_paths)) { #### import data - data_year <- terra::rast(data_paths[p]) - cat(paste0( + data_year <- terra::rast(data_paths[p], win = extent) + message(paste0( "Cleaning daily ", variable_checked, " data for year ", @@ -2364,7 +2513,7 @@ process_gridmet <- function( ) %in% date_sequence ) ) - cat(paste0( + message(paste0( "Returning daily ", variable_checked_long, " data from ", @@ -2394,6 +2543,9 @@ process_gridmet <- function( #' @param variable character(1). Variable name or acronym code. See [TerraClimate Direct Downloads](https://climate.northwestknowledge.net/TERRACLIMATE/index_directDownloads.php) #' for variable names and acronym codes. #' @param path character(1). Directory with downloaded netCDF (.nc) files. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded +#' @param ... Placeholders. #' @note #' Layer names of the returned `SpatRaster` object contain the variable acronym, year, #' and month. @@ -2405,16 +2557,29 @@ process_gridmet <- function( #' @importFrom terra rast #' @importFrom terra time #' @importFrom terra subset +#' @examples +#' \dontrun{ +#' terraclimate <- process_terraclimate( +#' date = c("2023-01-01", "2023-01-10"), +#' variable = "Precipitation", +#' path = "./data/ppt" +#' ) +#' } #' @export # nolint end process_terraclimate <- function( date = c("2023-09-01", "2023-09-01"), variable = NULL, - path = NULL) { + path = NULL, + extent = NULL, + ...) { #### directory setup path <- download_sanitize_path(path) #### check for variable check_for_null_parameters(mget(ls())) + #### check dates + stopifnot(length(date) == 2) + date <- date[order(as.Date(date))] variable_checked <- process_variable_codes( variables = variable, source = "terraclimate" @@ -2468,8 +2633,8 @@ process_terraclimate <- function( data_full <- terra::rast() for (p in seq_along(data_paths)) { #### import data - data_year <- terra::rast(data_paths[p]) - cat(paste0( + data_year <- terra::rast(data_paths[p], win = extent) + message(paste0( "Cleaning monthly ", variable_checked_long, " data for ", @@ -2512,7 +2677,7 @@ process_terraclimate <- function( ) %in% ymoi ) ) - cat(paste0( + message(paste0( "Returning monthly ", variable_checked_long, " data from ", @@ -2562,6 +2727,8 @@ process_terraclimate <- function( #' @param huc_level character(1). Field name of HUC level #' @param huc_header character(1). The upper level HUC code header to extract #' lower level HUCs. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Arguments passed to `nhdplusTools::get_huc()` #' @returns a `SpatVector` object #' @seealso [`nhdplusTools::get_huc`] @@ -2601,6 +2768,7 @@ process_huc <- layer_name = NULL, huc_level = NULL, huc_header = NULL, + extent = NULL, ... ) { # exclude the coverage due to write permission related to memoization @@ -2635,7 +2803,13 @@ process_huc <- ) } - hucpoly <- try(terra::vect(path, query = querybase)) + hucpoly <- try( + terra::vect( + path, + query = querybase, + extent = extent + ) + ) } return(hucpoly) } @@ -2648,6 +2822,8 @@ process_huc <- #' returning a single `SpatRaster` object. #' @param path character giving CropScape data path #' @param year numeric giving the year of CropScape data used +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @description Reads CropScape file of selected `year`. #' @returns a `SpatRaster` object @@ -2655,11 +2831,19 @@ process_huc <- #' @importFrom utils read.csv #' @importFrom terra rast #' @importFrom terra metags +#' @examples +#' \dontrun{ +#' cropscape <- process_cropscape( +#' path = "./data/cropscape_example.tif", +#' year = 2020 +#' ) +#' } #' @export process_cropscape <- function( path = NULL, year = 2021, + extent = NULL, ... ) { # check inputs @@ -2680,7 +2864,7 @@ process_cropscape <- } else { cdl_file <- path } - cdl <- terra::rast(cdl_file) + cdl <- terra::rast(cdl_file, win = extent) terra::metags(cdl) <- c(year = year) return(cdl) } @@ -2696,6 +2880,8 @@ process_cropscape <- #' @param time character(1). PRISM time name. #' Should be character in length of 2, 4, 6, or 8. #' "annual" is acceptable. +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @description Reads time series or 30-year normal PRISM data. #' @returns a `SpatRaster` object with metadata of time and element. @@ -2704,6 +2890,14 @@ process_cropscape <- #' @importFrom utils read.csv #' @importFrom terra rast #' @importFrom terra metags +#' @examples +#' \dontrun{ +#' prism <- process_prism( +#' path = "./data/PRISM_ppt_stable_4kmM3_202104_nc.nc", +#' element = "ppt", +#' time = "202104" +#' ) +#' } #' @export # nolint start process_prism <- @@ -2711,6 +2905,7 @@ process_prism <- path = NULL, element = NULL, time = NULL, + extent = NULL, ... ) { # check inputs @@ -2739,7 +2934,7 @@ process_prism <- } else { prism_file <- path } - prism <- terra::rast(prism_file) + prism <- terra::rast(prism_file, win = extent) terra::metags(prism) <- c(time = time, element = element) return(prism) } @@ -2748,20 +2943,32 @@ process_prism <- #' Process OpenLandMap data #' @param path character giving OpenLandMap data path +#' @param extent numeric(4) or SpatExtent giving the extent of the raster +#' if `NULL` (default), the entire raster is loaded #' @param ... Placeholders. #' @returns a `SpatRaster` object #' @author Insang Song #' @importFrom terra rast +#' @examples +#' \dontrun{ +#' olm <- process_olm( +#' path = paste0( +#' "./data/no2_s5p.l3.trop.tmwm.p50_p90_2km_a_", +#' "20180501_20221130_go_epsg.4326_v20221219.tif" +#' ) +#' ) +#' } #' @export process_olm <- function( path = NULL, + extent = NULL, ... ) { # check inputs if (!is.character(path) || is.null(path)) { stop("path is not a character.") } - olm <- terra::rast(path) + olm <- terra::rast(path, win = extent) return(olm) } diff --git a/R/process_auxiliary.R b/R/process_auxiliary.R index 851dd70e..216fb44c 100644 --- a/R/process_auxiliary.R +++ b/R/process_auxiliary.R @@ -344,7 +344,7 @@ process_locs_vector <- ) { #### detect SpatVector if (methods::is(locs, "SpatVector")) { - cat( + message( paste0( "Detected `SpatVector` (", terra::geomtype(locs), @@ -354,11 +354,11 @@ process_locs_vector <- sites_v <- locs #### detect sf object } else if (methods::is(locs, "sf")) { - cat("Detected `sf` extraction locations...\n") + message("Detected `sf` extraction locations...\n") sites_v <- terra::vect(locs) ### detect data.frame object } else if (methods::is(locs, "data.frame")) { - cat("Detected `data.frame` extraction locations...\n") + message("Detected `data.frame` extraction locations...\n") #### columns if (any(!(c("lon", "lat") %in% colnames(locs)))) { stop(paste0( @@ -496,11 +496,13 @@ process_variable_codes <- return(variables) } else { if (all(tolower(variables) %in% names_codes[, 1]) == TRUE) { - codes_return <- do.call( - code_function, - list(tolower(variables), invert = FALSE) + codes_return <- lapply( + tolower(variables), + function(var) { + do.call(code_function, list(var, invert = FALSE)) + } ) - return(as.vector(codes_return)) + return(as.vector(unlist(codes_return))) } else { stop( paste0( @@ -536,3 +538,29 @@ is_date_proper <- function( \"YYYY-MM-DD\".\n", names(argnames)[2])) } } + + +#' Apply extent to the processed data +#' @description +#' User-defined extent is used to filter the data. +#' @param data sf/terra object. +#' @param extent numeric(4). Extent to filter the data. +#' Should be ordered as c(xmin, xmax, ymin, ymax). +#' @param geom character(1 or 2). Geometry type for if `data` is `data.frame`. +#' One of "geometry" or c("lon", "lat"). +#' @importFrom sf st_as_sfc st_bbox st_crs +#' @importFrom terra ext +#' @returns sf/terra object with the extent applied. +#' @keywords internal +apply_extent <- + function(data, extent, geom) { + extent <- terra::ext(extent) + if (inherits(data, "sf")) { + extent <- sf::st_as_sfc(sf::st_bbox(extent)) + sf::st_crs(extent) <- sf::st_crs(data) + } else if (inherits(data, "data.frame")) { + data <- terra::vect(data, geom = geom, crs = "EPSG:4326") + } + data <- data[extent, ] + return(data) + } diff --git a/README.md b/README.md index 43e5694c..4e26c63f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# amadeus +# amadeus [![R-CMD-check](https://github.com/NIEHS/amadeus/actions/workflows/check-standard.yaml/badge.svg)](https://github.com/NIEHS/amadeus/actions/workflows/check-standard.yaml) [![cov](https://NIEHS.github.io/amadeus/badges/coverage.svg)](https://github.com/NIEHS/amadeus/actions) @@ -12,15 +12,15 @@ `amadeus` is not yet available from CRAN, but it can be installed with the `devtools`, `remotes`, or `pak` packages. -``` +```r devtools::install_github("NIEHS/amadeus") ``` -``` +```r remotes::install_github("NIEHS/amadeus") ``` -``` +```r pak::pak("NIEHS/amadeus") ``` @@ -31,49 +31,58 @@ To add or edit functionality for new data sources or datasets, open a [Pull requ Utilize [Issues](https://github.com/NIEHS/amadeus/issues) to notify the authors of bugs, questions, or recommendations. Identify each issue with the appropriate label to help ensure a timely response.
- +
## Download `download_data` accesses and downloads raw geospatial data from a variety of open source data repositories. The function is a wrapper that calls source-specific download functions, each of which account for the source's unique combination of URL, file naming conventions, and data types. Download functions cover the following sources: -| Source | Data Type | Genre | -| :--- | :--- | :--- | -| [Climatology Lab TerraClimate](https://www.climatologylab.org/terraclimate.html) | netCDF | Climate, Water | -| [Climatology Lab GridMet](https://www.climatologylab.org/gridmet.html) | netCDF | Meteorology | -| [Köppen-Geiger Climate Classification (Beck et al., 2018)](https://www.nature.com/articles/sdata2018214) | GeoTIFF | Climate Classification | -| [MRLC Consortium National Land Cover Database (NLCD)](https://www.mrlc.gov/data) | GeoTIFF | Land Use | -| [NASA Moderate Resolution Imaging Spectroradiometer (MODIS)](https://modis.gsfc.nasa.gov/data/) | HDF | Atmosphere, Meteorology, Land Use, Satellite | -| [NASA Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2)](https://www.nature.com/articles/sdata2018214) | netCDF | Atmosphere, Meteorology | -| [NASA SEDAC UN WPP-Adjusted Population Density](https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-density-adjusted-to-2015-unwpp-country-totals-rev11) | GeoTIFF, netCDF | Population | -| [NASA SEDAC Global Roads Open Access Data Set](https://sedac.ciesin.columbia.edu/data/set/groads-global-roads-open-access-v1/data-download) | Shapefile, Geodatabase | Roadways | -| [NASA Goddard Earth Observing System Composition Forcasting (GEOS-CF)](https://gmao.gsfc.nasa.gov/GEOS_systems/) | netCDF | Atmosphere, Meteorology | -| [NOAA Hazard Mapping System Fire and Smoke Product](https://www.ospo.noaa.gov/Products/land/hms.html#0) | Shapefile, KML | Wildfire Smoke | -| [NOAA NCEP North American Regional Reanalysis (NARR)](https://psl.noaa.gov/data/gridded/data.narr.html) | netCDF | Atmosphere, Meteorology | -| [US EPA Air Data Pre-Generated Data Files](https://aqs.epa.gov/aqsweb/airdata/download_files.html) | CSV | Air Pollution | +| Data Source | File Type | Data Genre | +| :---- | :-- | :--- | +| [Climatology Lab TerraClimate](https://www.climatologylab.org/terraclimate.html) | netCDF | Meteorology | +| [Climatology Lab GridMet](https://www.climatologylab.org/gridmet.html) | netCDF | Climate
Water | +| [Köppen-Geiger Climate Classification](https://www.nature.com/articles/sdata2018214) | GeoTIFF | Climate Classification | +| [MRLC[^1] Consortium National Land Cover Database (NLCD)](https://www.mrlc.gov/data) | GeoTIFF | Land Use | +| [NASA[^2] Moderate Resolution Imaging Spectroradiometer (MODIS)](https://modis.gsfc.nasa.gov/data/) | HDF | Atmosphere
Meteorology
Land Use
Satellite | +| [NASA Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2)](https://www.nature.com/articles/sdata2018214) | netCDF | Atmosphere
Meteorology | +| [NASA SEDAC[^3] UN WPP-Adjusted Population Density](https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-density-adjusted-to-2015-unwpp-country-totals-rev11) | GeoTIFF
netCDF | Population | +| [NASA SEDAC Global Roads Open Access Data Set](https://sedac.ciesin.columbia.edu/data/set/groads-global-roads-open-access-v1/data-download) | Shapefile
Geodatabase | Roadways | +| [NASA Goddard Earth Observing System Composition Forcasting (GEOS-CF)](https://gmao.gsfc.nasa.gov/GEOS_systems/) | netCDF | Atmosphere
Meteorology | +| [NOAA Hazard Mapping System Fire and Smoke Product](https://www.ospo.noaa.gov/Products/land/hms.html#0) | Shapefile
KML | Wildfire Smoke | +| [NOAA NCEP[^4] North American Regional Reanalysis (NARR)](https://psl.noaa.gov/data/gridded/data.narr.html) | netCDF | Atmosphere
Meteorology | +| [OpenGeoHub Foundation OpenLandMap](https://opengeohub.org/about-openlandmap/) | GeoTIFF | Climate
Elevation
Soil
Land Use
Satellite | +| [Parameter Elevation Regression on Independent Slopes Model (PRISM)](https://elibrary.asabe.org/abstract.asp??JID=3&AID=3101&CID=t2000&v=43&i=6&T=1) | BIL
ASCII | Climate | +| [US EPA[^5] Air Data Pre-Generated Data Files](https://aqs.epa.gov/aqsweb/airdata/download_files.html) | CSV | Air Pollution | | [US EPA Ecoregions](https://www.epa.gov/eco-research/ecoregion) | Shapefile | Climate Regions | -| [USGS Global Multi-resolution Terrain Elevation Data (GMTED2010)](https://www.usgs.gov/coastal-changes-and-impacts/gmted2010) | ESRI ASCII Grid | Elevation | +| [US EPA National Emissions Inventory (NEI)](https://www.epa.gov/air-emissions-inventories) | CSV | Emissions | +| [US EPA Toxic Release Inventory (TRI) Program](https://www.epa.gov/toxics-release-inventory-tri-program/tri-basic-data-files-calendar-years-1987-present) | CSV | Chemicals
Pollution | +| [USGS[^6] Global Multi-resolution Terrain Elevation Data (GMTED2010)](https://www.usgs.gov/coastal-changes-and-impacts/gmted2010) | ESRI ASCII Grid | Elevation | +| [USGS National Hydrography Dataset (NHD)](https://www.sciencebase.gov/catalog/item/4f5545cce4b018de15819ca9) | Geopackage
Geodatabase | Hydrography | - -See the "download_data and NASA EarthData Account" vignette for a detailed description of source-specific download functions. +See the "[download_data](https://niehs.github.io/amadeus/articles/download_functions.html)" vignette for a detailed description of source-specific download functions. Example use of `download_data` using NOAA NCEP North American Regional Reanalysis's (NARR) "weasd" (Daily Accumulated Snow at Surface) variable. +```r +directory <- "/ EXAMPLE / FILE / PATH /" +download_data( + dataset_name = "narr", + year = c(2022, 2022), + variable = "weasd", + directory_to_save = directory, + acknowledgement = TRUE, + download = TRUE +) +``` ``` -> directory <- "/ EXAMPLE / FILE / PATH /" -> download_data( -+ dataset_name = "narr_monolevel", -+ year_start = 2022, -+ year_end = 2022, -+ variable = "weasd", -+ directory_to_save = directory, -+ acknowledgement = TRUE, -+ download = TRUE -+ ) Downloading requested files... Requested files have been downloaded. -> list.files(paste0(directory, "weasd")) +``` +```r +list.files(paste0(directory, "weasd")) +``` +``` [1] "weasd.2022.nc" ``` @@ -85,17 +94,24 @@ To avoid errors when using `process_covariates`, **do not edit the raw downloade Example use of `process_covariates` using the downloaded "weasd" data. +```r +weasd <- process_covariates( + covariate = "narr", + date = c("2022-01-01", "2022-01-05"), + variable = "weasd", + path = paste0(directory, "weasd"), + extent = NULL +) +``` ``` -> weasd <- process_covariates( -+ covariate = "narr", -+ date = c("2022-01-01", "2022-01-05"), -+ variable = "weasd", -+ path = paste0(directory, "weasd") -+ ) Cleaning weasd data for January, 2022... Detected monolevel data... Returning daily weasd data from 2022-01-01 to 2022-01-05. -> weasd +``` +```r +weasd +``` +``` class : SpatRaster dimensions : 277, 349, 5 (nrow, ncol, nlyr) resolution : 32462.99, 32463 (x, y) @@ -110,21 +126,22 @@ time : 2022-01-01 to 2022-01-05 UTC ## Calculate Covariates -`calc_covariates` stems from the `beethoven` package's need for various types of data extracted at precise locations. `calc_covariates`, therefore, extracts data from the "cleaned" `SpatRaster` or `SpatVector` object at user defined locations. Users can choose to buffer the locations. The function returns a `data.frame` with data extracted at all locations for each layer or row in the `SpatRaster` or `SpatVector` object, respectively. +`calc_covariates` stems from the [`beethoven`](https://github.com/NIEHS/beethoven) project's need for various types of data extracted at precise locations. `calc_covariates`, therefore, extracts data from the "cleaned" `SpatRaster` or `SpatVector` object at user defined locations. Users can choose to buffer the locations. The function returns a `data.frame` or `SpatVector` with data extracted at all locations for each layer or row in the `SpatRaster` or `SpatVector` object, respectively. Example of `calc_covariates` using processed "weasd" data. +```r +locs <- data.frame(id = "001", lon = -78.8277, lat = 35.95013) +weasd_covar <- calc_covariates( + covariate = "narr", + from = weasd_process, + locs = locs, + locs_id = "id", + radius = 0, + geom = FALSE +) +``` ``` -> locs <- data.frame(lon = -78.8277, lat = 35.95013) -> locs$id <- "0001" -> weasd_covar <- calc_covariates( -+ covariate = "narr", -+ from = weasd_process, -+ locs = locs, -+ locs_id = "id", -+ radius = 0, -+ geom = FALSE -+ ) Detected `data.frame` extraction locations... Calculating weasd covariates for 2022-01-01... Calculating weasd covariates for 2022-01-02... @@ -132,7 +149,11 @@ Calculating weasd covariates for 2022-01-03... Calculating weasd covariates for 2022-01-04... Calculating weasd covariates for 2022-01-05... Returning extracted covariates. -> weasd_covar +``` +```r +weasd_covar +``` +``` id time weasd_0 1 0001 2022-01-01 0.000000000 2 0001 2022-01-02 0.000000000 @@ -150,9 +171,15 @@ The following R packages can also be used to access climate and weather data in | [`dataRetrieval`](https://cran.r-project.org/web/packages/dataRetrieval/index.html) | [USGS Hydrological Data](https://www.usgs.gov/mission-areas/water-resources/data) and [EPA Water Quality Data](https://www.epa.gov/waterdata/water-quality-data) | | [`daymetr`](https://cran.r-project.org/web/packages/daymetr/index.html) | [Daymet](https://daac.ornl.gov/cgi-bin/dataset_lister.pl?p=32) | | [`ecmwfr`](https://cran.r-project.org/web/packages/ecmwfr/index.html) | [ECMWF Reanalysis v5 (ERA5)](https://www.ecmwf.int/en/forecasts/dataset/ecmwf-reanalysis-v5) | -| [`RClimChange`[^1]](https://github.com/hllauca/RClimChange/) | [NASA Earth Exchange Global Daily Downscaled Projections (NEX-GDDP-CMIP6)](https://www.nccs.nasa.gov/services/data-collections/land-based-products/nex-gddp-cmip6) | +| [`RClimChange`[^7]](https://github.com/hllauca/RClimChange/) | [NASA Earth Exchange Global Daily Downscaled Projections (NEX-GDDP-CMIP6)](https://www.nccs.nasa.gov/services/data-collections/land-based-products/nex-gddp-cmip6) | | [`rNOMADS`](https://cran.r-project.org/web/packages/rNOMADS/) | [NOAA Operational Model Archive and Distribution System](https://nomads.ncep.noaa.gov/) | -| [`sen2r`[^2]](https://github.com/ranghetti/sen2r) | [Sentinel-2](https://sentinels.copernicus.eu/web/sentinel/missions/sentinel-2) | - -[^1]: Last updated more than two years ago. -[^2]: Archived; no longer maintained. +| [`sen2r`[^8]](https://github.com/ranghetti/sen2r) | [Sentinel-2](https://sentinels.copernicus.eu/web/sentinel/missions/sentinel-2) | + +[^1]: Multi-Resolution Land Characteristics +[^2]: National Aeronautics and Space Administration +[^3]: Socioeconomic Data and Applications Center +[^4]: National Centers for Environmental Prediction +[^5]: United States Environmental Protection Agency +[^6]: United States Geological Survey +[^7]: Last updated more than two years ago. +[^8]: Archived; no longer maintained. diff --git a/inst/REFERENCES.bib b/inst/REFERENCES.bib new file mode 100644 index 00000000..476ddfe5 --- /dev/null +++ b/inst/REFERENCES.bib @@ -0,0 +1,2131 @@ +#################################################################################################### +## software +# R +@manual{software_R, + title = {R: A Language and Environment for Statistical Computing}, + author = {{R Core Team}}, + year = 2023, + address = {Vienna, Austria}, + url = {https://www.R-project.org/}, + note = {R version 4.3.2 (2023-10-31)}, + organization = {R Foundation for Statistical Computing} +} +# CRAN +@manual{software_CRAN, + title = {The Comprehensive {R} Archive Network}, + author = {Benjamin Altmann and Kurt Hornik and Tomas Kalibera and Konstanze Lauseker and Uwe Ligges and Brian D. Ripley and Simon Urbanek}, + address = {Vienna, Austria}, + url = {https://cran.r-project.org/} +} + +@manual{software_exactextract, + author = {Baston, Daniel}, + title = {exactextract}, + month = may, + year = 2024, + publisher = {Zenodo}, + version = {0.1.0}, + doi = {10.5281/zenodo.11396420}, + url = {https://doi.org/10.5281/zenodo.11396420} +} + +@manual{software_tigerline, + author = {U.S. Census Bureau}, + title = {2020 {TIGER/Line} Shapefiles (machine-readable data files)}, + year = {2020}, + url = {https://www.census.gov/programs-surveys/geography/technical-documentation/complete-technical-documentation/tiger-geo-line.2020.html} +} + +# R packages +@manual{package_RAQSAPI, + title = {A {R} Interface to the {US} {EPA} Air Quality System Data Mart {API}}, + author = {Clinton Mccrowey and Timothy Sharac and Nick Mangus and Doug Jager and Ryan Brown and Daniel Garver and Benjamin Wells and Hayley Brittingham}, + year = 2021, + url = {https://cran.r-project.org/package=RAQSAPI} +} +@manual{package_Reanalysis, + title = {Reanalysis}, + author = {Kevin Shook}, + year = 2022, + url = {https://github.com/CentreForHydrology/Reanalysis}, + note = {R package version 1.4.1} +} +@article{package_rNOMADS, + title = {Near real time weather and ocean model data access with {rNOMADS}}, + author = {Daniel C. Bowman and Jonathan M. Lees}, + year = 2015, + journal = {{Computers \& Geosciences}}, + volume = 78, + pages = {88--95}, + doi = {10.1016/j.cageo.2015.02.013} +} +@article{package_Kusch2021KrigRaTF, + title = {{KrigR}—a tool for downloading and statistically downscaling climate reanalysis data}, + author = {Erik Kusch and Richard Davy}, + year = 2021, + journal = {Environmental Research Letters}, + booktitle = {Environmental Research Letters}, + volume = 17 +} +@article{package_daymetr, + title = {An integrated phenology modelling framework in {R}: modelling vegetation phenology with {phenor}}, + author = {Koen Hufkens and David Basler and Tom Milliman and Eli K. Melaas and Andrew D. Richardson}, + year = 2018, + journal = {{Methods in Ecology \& Evolution}}, + volume = 9, + pages = {1--10}, + doi = {10.1111/2041-210X.12970} +} +@manual{package_climateR, + title = {{climateR}: climateR}, + author = {Mike Johnson}, + year = 2023, + url = {https://github.com/mikejohnson51/climateR}, + note = {R package version 0.3.2} +} +@manual{package_RClimChange, + title = {{RClimChange}: A package to manipulate Global Climate Models from {NCCS} {THREDDS} {NEX-GDDP-CMIP6}}, + author = {Harold Llauca}, + year = 2024, + note = {R package version 3.2.2} +} +@manual{package_ecmwfr, + title = {The ecwmfr package: an interface to {ECMWF} {API} endpoints}, + author = {Koen Hufkens and Reto Stauffer and Elio Campitelli}, + year = 2019, + doi = {10.5281/zenodo.2647531}, + url = {https://bluegreen-labs.github.io/ecmwfr/}, + note = {R package version 1.5.0} +} +@manual{package_dataRetrieval, + title = {{dataRetrieval}: {R} packages for discovering and retrieving water data available from U.S. federal hydrologic web services}, + author = {Laura DeCicco and Robert Hirsch and David Lorenz and David Watkins and Mike Johnson}, + year = 2024, + publisher = {U.S. Geological Survey}, + address = {Reston, VA}, + doi = {10.5066/P9X4L3GE}, + url = {https://code.usgs.gov/water/dataRetrieval}, + version = {2.7.15}, + institution = {U.S. Geological Survey} +} +@manual{package_luna, + title = {{luna}: Tools for Satellite Remote Sensing (Earth Observation) Data Processing}, + author = {Robert J. Hijmans and Aniruddha Ghosh}, + year = 2023, + note = {R package version 0.3-6} +} +@manual{package_FedData, + title = {{FedData}: Functions to Automate Downloading Geospatial Data Available from Several Federated Data Sources}, + author = {R. Kyle Bocinsky}, + year = 2023, + url = {https://CRAN.R-project.org/package=FedData}, + note = {R package version 4.0.0} +} +@manual{package_raqs, + title = {{raqs}: Interface to the {US EPA} Air Quality System ({AQS}) {API}}, + author = {Jaehyun Joo and Blanca Himes}, + year = 2023, + url = {https://CRAN.R-project.org/package=raqs}, + note = {R package version 1.0.2} +} +@manual{package_geodata, + title = {{geodata}: Download Geographic Data}, + author = {Robert J. Hijmans and Márcia Barbosa and Aniruddha Ghosh and Alex Mandel}, + year = 2023, + url = {https://CRAN.R-project.org/package=geodata}, + note = {R package version 0.5-9} +} +@manual{package_terra, + title = {{terra}: Spatial Data Analysis}, + author = {Robert J. Hijmans}, + year = 2023, + url = {https://CRAN.R-project.org/package=terra}, + note = {R package version 1.7-65} +} +@article{package_sf, + title = {{Simple Features for {R}: Standardized Support for Spatial Vector Data}}, + author = {Edzer Pebesma}, + year = 2018, + journal = {{The R Journal}}, + volume = 10, + number = 1, + pages = {439--446}, + doi = {10.32614/RJ-2018-009}, + url = {https://doi.org/10.32614/RJ-2018-009} +} +@book{package_stars, + title = {{Spatial Data Science: With applications in {R}}}, + author = {Edzer Pebesma and Roger Bivand}, + year = 2023, + publisher = {Chapman and Hall/CRC}, + address = {London}, + pages = 352, + doi = {10.1201/9780429459016}, + url = {https://r-spatial.org/book/} +} +@manual{package_MODISTools, + title = {The {MODISTools} package: an interface to the {MODIS} Land Products Subsets Web Services}, + author = {Koen Hufkens}, + year = 2023, + month = {Jan}, + publisher = {Zenodo}, + doi = {10.5281/zenodo.7551165}, + url = {https://doi.org/10.5281/zenodo.7551165}, + version = {R package version 1.1.4} +} +@article{package_MODIStsp, + title = {{MODIStsp}: an {R} package for preprocessing of {MODIS} Land Products time series}, + author = {Lorenzo Busetto and Luigi Ranghetti}, + year = 2016, + journal = {{Computers \& Geosciences}}, + volume = 97, + pages = {40--48}, + doi = {10.1016/j.cageo.2016.08.020}, + issn = {0098-3004}, + url = {https://github.com/ropensci/MODIStsp} +} +@manual{package_merra2ools, + title = {{merra2ools}: {R}-tools to process {MERRA-2} data ({NASA}) with focus on renewable energy}, + author = {Oleg Lugovoy and Shuo Gao}, + year = 2023, + url = {https://energyRt.github.io/merra2ools/}, + note = {R package version 0.1.03} +} +@article{package_testthat, + title = {testthat: Get Started with Testing}, + author = {Hadley Wickham}, + year = 2011, + journal = {The R Journal}, + volume = 3, + pages = {5--10}, + url = {https://journal.r-project.org/archive/2011-1/RJournal_2011-1_Wickham.pdf} +} +@manual{package_pkgdown, + title = {{pkgdown}: Make Static {HTML} Documentation for a Package}, + author = {Hadley Wickham and Jay Hesselberth and Maëlle Salmon}, + year = 2022, + url = {https://CRAN.R-project.org/package=pkgdown}, + note = {R package version 2.0.7} +} +@manual{package_roxygen2, + title = {{roxygen2}: In-Line Documentation for {R}}, + author = {Hadley Wickham and Peter Danenberg and Gábor Csárdi and Manuel Eugster}, + year = 2024, + url = {https://CRAN.R-project.org/package=roxygen2}, + note = {R package version 7.3.1} +} +@manual{package_httr, + title = {{httr}: Tools for Working with {URLs} and {HTTP}}, + author = {Hadley Wickham}, + year = 2023, + url = {https://CRAN.R-project.org/package=httr}, + note = {R package version 1.4.7} +} +@manual{package_qbms, + title = {{QBMS}: Query the Breeding Management System(s)}, + author = {Khaled Al-Shamaa}, + year = 2024, + url = {https://CRAN.R-project.org/package=QBMS}, + note = {R package version 1.0.0} +} +@manual{package_exactextractr, + title = {exactextractr: Fast Extraction from Raster Datasets using Polygons}, + author = {{Daniel Baston}}, + year = 2023, + url = {https://CRAN.R-project.org/package=exactextractr}, + note = {R package version 0.10.0} +} +@manual{package_tigris, + title = {{tigris}: Load {Census} {TIGER/Line} {Shapefiles}}, + author = {Kyle Walker}, + year = 2024, + url = {https://CRAN.R-project.org/package=tigris}, + note = {R package version 2.1} +} +@manual{package_covr, + title = {{covr}: Test Coverage for Packages}, + author = {Jim Hester}, + year = 2023, + url = {https://CRAN.R-project.org/package=covr}, + note = {R package version 3.6.4} +} +@manual{package_tidycensus, + title = {tidycensus: Load US Census Boundary and Attribute Data as 'tidyverse' and 'sf'-Ready Data Frames}, + author = {Kyle Walker and Matt Herman}, + year = 2024, + url = {https://CRAN.R-project.org/package=tidycensus}, + note = {R package version 1.6.3} +} + +# R functions +@manual{function_NARRdownloadNetCDF, + title = {{NARRdownloadNetCDF}: Downloads {NARR} {NetCDF} files}, + author = {Kevin Shook and Bastien Ferland-Raymond}, + year = 2022, + url = {https://rdrr.io/github/CentreForHydrology/Reanalysis/man/NARRdownloadNetCDF.html} +} +@manual{function_downloadDEM, + title = {download\_{DEM}: Downloading {DEM} data from {USGS} servers}, + author = {Erik Kusch}, + year = 2021, + url = {https://rdrr.io/github/ErikKusch/KrigR/man/download_DEM.html} +} +@manual{function_mt_subset, + title = {mt\_subset: Download {MODIS} Land Product subsets}, + author = {Koen Hufkens}, + year = 2023, + url = {https://bluegreen-labs.github.io/MODISTools/reference/mt_subset.html} +} +# R vignettes +@manual{vignette_RAQSAPI, + title = {Introduction to the {RAQSAPI} package}, + author = {Clinton Mccrowey}, + publisher = {US Environmental Protection Agency}, + url = {https://cran.r-project.org/web/packages/RAQSAPI/vignettes/RAQSAPIvignette.html#RAQSAPI%20functional%20families} +} + +#################################################################################################### +## datasets +@manual{data_SEDAC_population, + title = {Gridded Population of the World, Version 4 (GPWv4): Population Density Adjusted to Match 2015 Revision UN WPP Country Totals, Revision 11}, + author = {Center for International Earth Science Information Network - CIESIN - Columbia University}, + year = 2018, + month = jun, + journal = {{AGU} Advances}, + publisher = {NASA Socioeconomic Data and Applications Center (SEDAC)}, + doi = {10.7927/H4F47M65}, + url = {https://doi.org/10.7927/H4F47M65}, + howpublished = {\url{https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-density-adjusted-to-2015-unwpp-country-totals-rev11}} +} +@manual{data_koppen_geiger, + title = {Present and future K{\"o}ppen-Geiger climate classification maps at 1-km resolution}, + author = {Beck, Hylke E and Zimmermann, Niklaus E and McVicar, Tim R and Vergopolan, Noemi and Berg, Alexis and Wood, Eric F}, + year = 2018, + journal = {Scientific data}, + publisher = {Nature Publishing Group}, + volume = 5, + number = 1, + pages = {1--12}, + doi = {10.6084/m9.figshare.6396959}, + url = {https://doi.org/10.6084/m9.figshare.6396959}, + howpublished = {\url{https://figshare.com/articles/dataset/Present_and_future_K_ppen-Geiger_climate_classification_maps_at_1-km_resolution/6396959/2}} +} +@manual{data_acsdp05, + title = {ACS Demographic and Housing Estimates (DP05)}, + author = {U.S. Census Bureau}, + year = 2019, + howpublished = {\url{https://data.census.gov/cedsci/table?q=DP05}} +} + +#################################################################################################### +## web pages +@misc{web_SEDAC_GPWv4, + title = {{Gridded Population of the World (GPW)}, v4}, + author = {Center for International Earth Science Information Network - CIESIN - Columbia University}, + publisher = {NASA Socioeconomic Data and Applications Center (SEDAC)}, + url = {https://sedac.ciesin.columbia.edu/data/collection/gpw-v4/documentation}, + howpublished = {\url{https://sedac.ciesin.columbia.edu/data/collection/gpw-v4/documentation}} +} +@misc{web_Sruthi2024, + title = {Top 20 Best Programming Languages To Learn in 2024}, + author = {Sruthi Veeraraghavan}, + year = 2024, + url = {https://www.simplilearn.com/best-programming-languages-start-learning-today-article}, + howpublished = {\url{https://www.simplilearn.com/best-programming-languages-start-learning-today-article}} +} +@misc{web_NARRcrs, + title = {Lambert Conformal Format}, + publisher = {NOAA Physical Sciences Laboratory}, + url = {https://psl.noaa.gov/data/narr/format.html}, + howpublished = {\url{https://psl.noaa.gov/data/narr/format.html}} +} +@misc{web_NARRabout, + title = {NCEP North American Regional Reanalysis (NARR)}, + publisher = {NOAA Physical Sciences Laboratory}, + url = {https://psl.noaa.gov/data/gridded/data.narr.html}, + howpublished = {\url{https://psl.noaa.gov/data/gridded/data.narr.html}} +} +@misc{web_HMSabout, + title = {Hazard Mapping System Fire and Smoke Product: Hazard Mapping System}, + publisher = {NOAA Office of Satellite And Product Operations}, + url = {https://www.ospo.noaa.gov/Products/land/hms.html#about}, + howpublished = {\url{https://www.ospo.noaa.gov/Products/land/hms.html#about}} +} +@misc{web_ESRIshapefile, + title = {Shapefile file extensions}, + publisher = {Esri}, + year = {2021}, + url = {https://desktop.arcgis.com/en/arcmap/latest/manage-data/shapefiles/shapefile-file-extensions.htm}, + howpublished = {\url{https://desktop.arcgis.com/en/arcmap/latest/manage-data/shapefiles/shapefile-file-extensions.htm}} +} +@misc{web_HTTPresponse, + title = {{HTTP} response status codes}, + year = 2023, + publisher = {MDN Web Docs}, + url = {https://developer.mozilla.org/en-US/docs/Web/HTTP/Status}, + howpublished = {\url{https://developer.mozilla.org/en-US/docs/Web/HTTP/Status}} +} +@misc{web_NIEHSplan, + title = {Theme One: Advancing Environmental Health Sciences}, + year = 2018, + publisher = {National Institute of Environmental Health Sciences}, + url = {https://www.niehs.nih.gov/about/strategicplan/2018-2023_theme1} +} +@misc{web_sedctutorial, + title = {Euclidean Sum of Exponentially Decaying Contributions Tutorial}, + author = {Corinne Wiesner}, + url = {https://mserre.sph.unc.edu/BMElab_web/SEDCtutorial/index.html} +} +@misc{web_ropensci, + title = {Packages}, + publisher = {rOpenSci}, + url = {https://ropensci.org/packages/}, + howpublished = {\url{https://ropensci.org/packages/}} +} +@misc{web_wktformat, + title = {Well-known text ({WKT}) format}, + publisher = {IBM}, + url = {https://www.ibm.com/docs/en/i/7.5?topic=formats-well-known-text-wkt-format}, + howpublished = {\url{https://www.ibm.com/docs/en/i/7.5?topic=formats-well-known-text-wkt-format}} +} +@misc{web_exactextractr, + title = {exactextractr}, + author = {{Daniel Baston}}, + publisher = {isciences}, + url = {https://isciences.gitlab.io/exactextractr/}, + howpublished = {\url{https://isciences.gitlab.io/exactextractr/}} +} +@misc{web_exactextractr_background, + title = {exactextractr - Background}, + author = {{Daniel Baston}}, + url = {https://github.com/isciences/exactextract#background}, + howpublished = {\url{https://github.com/isciences/exactextract#background}} +} +@misc{web_FedData, + title = {{FedData}}, + author = {R. Kyle Bocinsky}, + year = 2024, + url = {https://github.com/ropensci/FedData}, + howpublished = {\url{https://github.com/ropensci/FedData}} +} +@misc{web_geoids, + title = {Geographic Identifiers}, + author = {U.S. Census Bureau}, + year = {n.d.}, + note = {Accessed: 2024-07-01}, + howpublished = {\url{https://www.census.gov/programs-surveys/geography/guidance/geo-identifiers.html}} +} + +#################################################################################################### +## books +@book{book_mayer2013big, + title = {Big data: {A} revolution that will transform how we live, work, and think}, + author = {Mayer-Sch{\"o}nberger, Viktor and Cukier, Kenneth}, + year = 2013, + publisher = {Houghton Mifflin Harcourt} +} +@incollection{book_RPackages_13, + title = {Testing basics}, + author = {Hadley Wickham and Jennifer Bryan}, + year = 2023, + booktitle = {R Packages, 2nd Edition}, + publisher = {O'Reilly Media, Inc.}, + isbn = 9781098134945, + url = {https://r-pkgs.org/}, + chapter = 13 +} +@book{book_RMarkdown, + title = {{R Markdown}: The Definitive Guide}, + author = {Yihui Xie and J.J. Allaire and Garrett Grolemund}, + year = 2019, + publisher = {{Chapman \& Hall/CRC}}, + isbn = {978-1-138-35933-0}, + url = {https://bookdown.org/yihui/rmarkdown/} +} + +#################################################################################################### +## journal articles +@article{article_beck2018present, + title = {Present and future K{\"o}ppen-Geiger climate classification maps at 1-km resolution}, + author = {Beck, Hylke E and Zimmermann, Niklaus E and McVicar, Tim R and Vergopolan, Noemi and Berg, Alexis and Wood, Eric F}, + year = 2018, + journal = {Scientific data}, + publisher = {Nature Publishing Group}, + volume = 5, + number = 1, + pages = {1--12}, + doi = {10.1038/sdata.2018.214}, + url = {https://doi.org/10.1038/sdata.2018.214} +} +@article{article_Giorgi2022TheRL, + title = {The {R} Language: An Engine for Bioinformatics and Data Science}, + author = {F. Giorgi and Carmine Ceraolo and D. Mercatelli}, + year = 2022, + journal = {Life}, + volume = 12, + doi = {10.3390/life12050648}, + url = {https://www.mdpi.com/2075-1729/12/5/648} +} +@article{article_Lai2019Eval, + title = {Evaluating the popularity of {R} in ecology}, + author = {Lai, Jiangshan and Lortie, Christopher J. and Muenchen, Robert A. and Yang, Jian and Ma, Keping}, + year = 2019, + journal = {Ecosphere}, + volume = 10, + number = 1, + pages = {e02567}, + doi = {https://doi.org/10.1002/ecs2.2567}, + url = {https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1002/ecs2.2567}, + keywords = {code, ecology journal, open science, packages, R, reproducibility, statistical programming, Web of Science}, + eprint = {https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1002/ecs2.2567}, + abstract = {Abstract The programming language R is widely used in many fields. We explored the extent of reported R use in the field of ecology using the Web of Science and text mining. We analyzed the frequencies of R packages reported in more than 60,000 peer-reviewed articles published in 30 ecology journals during a 10-yr period ending in 2017. The number of studies reported using R as their primary tool in data analysis increased linearly from 11.4\% in 2008 to 58.0\% in 2017. The top 10 packages reported were lme4, vegan, nlme, ape, MuMIn, MASS, mgcv, ade4, multcomp, and car. The increasing popularity of R has most likely furthered open science in ecological research because it can improve reproducibility of analyses and captures workflows when scripts and codes are included and shared. These findings may not be entirely unique to R because there are other programming languages used by ecologists, but they do strongly suggest that given the relatively high frequency of reported use of R, it is a significant component of contemporary analytics in the field of ecology.} +} +@article{article_Stieb2017PromiseAP, + title = {Promise and pitfalls in the application of big data to occupational and environmental health}, + author = {D. Stieb and C. Boot and M. Turner}, + year = 2017, + journal = {BMC Public Health}, + volume = 17, + doi = {10.1186/s12889-017-4286-8}, + url = {https://doi.org/10.1186/s12889-017-4286-8} +} +@article{article_Comess2020BringingBD, + title = {Bringing Big Data to Bear in Environmental Public Health: Challenges and Recommendations}, + author = {S. Comess and Alexia Akbay and Melpomene Vasiliou and R. Hines and L. Joppa and V. Vasiliou and N. Kleinstreuer}, + year = 2020, + journal = {Frontiers in Artificial Intelligence}, + volume = 3, + doi = {10.3389/frai.2020.00031}, + url = {https://doi.org/10.3389/frai.2020.00031} +} +@article{artcile_Tange053447, + title = {{Big Data Reality Check (BDRC)} for public health: to what extent the environmental health and health services research did meet the {\textquoteleft}V{\textquoteright} criteria for big data? A study protocol}, + author = {Pui Pui Tang and I Lam Tam and Yongliang Jia and Siu-wai Leung}, + year = 2022, + journal = {BMJ Open}, + publisher = {British Medical Journal Publishing Group}, + volume = 12, + number = 3, + doi = {10.1136/bmjopen-2021-053447}, + issn = {2044-6055}, + url = {https://bmjopen.bmj.com/content/12/3/e053447}, + elocation-id = {e053447}, + abstract = {Introduction Big data technologies have been talked up in the fields of science and medicine. The V-criteria (volume, variety, velocity and veracity, etc) for defining big data have been well-known and even quoted in most research articles; however, big data research into public health is often misrepresented due to certain common misconceptions. Such misrepresentations and misconceptions would mislead study designs, research findings and healthcare decision-making. This study aims to identify the V-eligibility of big data studies and their technologies applied to environmental health and health services research that explicitly claim to be big data studies.Methods and analysis Our protocol follows Preferred Reporting Items for Systematic Review and Meta-Analysis Protocols (PRISMA-P). Scoping review and/or systematic review will be conducted. The results will be reported using PRISMA for Scoping Reviews (PRISMA-ScR), or PRISMA 2020 and Synthesis Without Meta-analysis guideline. Web of Science, PubMed, Medline and ProQuest Central will be searched for the articles from the database inception to 2021. Two reviewers will independently select eligible studies and extract specified data. The numeric data will be analysed with R statistical software. The text data will be analysed with NVivo wherever applicable.Ethics and dissemination This study will review the literature of big data research related to both environmental health and health services. Ethics approval is not required as all data are publicly available and involves confidential personal data. We will disseminate our findings in a peer-reviewed journal.PROSPERO registration number CRD42021202306.}, + eprint = {https://bmjopen.bmj.com/content/12/3/e053447.full.pdf} +} +@article{article_BigDatainEnvironmentandHumanHealth, + title = {Big Data in Environment and Human Health}, + author = {Lora Fleming and Niccolò Tempini and Harriet Gordon-Brown and Gordon L. Nichols and Christophe Sarran and Paolo Vineis and Giovanni Leonardi and Brian Golding and Andy Haines and Anthony Kessel and Virginia Murray and Michael Depledge and Sabina Leonelli}, + year = 2017, + month = {07}, + journal = {Oxford Research Encyclopedia of Environmental Science}, + publisher = {Oxford University Press}, + doi = {10.1093/acrefore/9780199389414.013.541}, + url = {https://oxfordre.com/environmentalscience/view/10.1093/acrefore/9780199389414.001.0001/acrefore-9780199389414-e-541} +} +@article{article_Piel2020Using, + title = {{Using large and complex datasets for small-area environment-health studies: from theory to practice}}, + author = {Piel, Frédéric B and Cockings, Samantha}, + year = 2020, + month = {04}, + journal = {International Journal of Epidemiology}, + volume = 49, + number = {Supplement_1}, + pages = {i1-i3}, + doi = {10.1093/ije/dyaa018}, + issn = {0300-5771}, + url = {https://doi.org/10.1093/ije/dyaa018}, + abstract = {{Humans are exposed to a wide range of pollutants throughout their lifetime, many of which pose a potential risk to their health. Such hazards include features of the natural, human-modified, social and economic environments. In this supplement, we are primarily concerned with risks to human health resulting from hazards of the human-modified environment, although many of the concepts, methods and tools are equally applicable to investigations of the health impacts of other types of environmental hazards. Amongst human-modified environmental hazards, air pollution has been identified as the world’s largest killer, being responsible for an estimated 6.4 million deaths per year (1 in 9 deaths).1 According to the World Health Organization, two billion children live in areas where outdoor air pollution exceeds recommended international limits and 300 million children live in areas where outdoor air pollution exceeds six times those international limits. Other hazards of the human-modified environment include water pollutants, such as chemicals and microplastics; radiation from mobile phones, powerlines or nearby nuclear installations; and soil contaminants such as heavy metals.}}, + eprint = {https://academic.oup.com/ije/article-pdf/49/Supplement\_1/i1/33050268/dyaa018.pdf} +} +@article{article_Fleming2014Data, + title = {Data Mashups: Potential Contribution to Decision Support on Climate Change and Health}, + author = {Fleming, Lora E. and Haines, Andy and Golding, Brian and Kessel, Anthony and Cichowska, Anna and Sabel, Clive E. and Depledge, Michael H. and Sarran, Christophe and Osborne, Nicholas J. and Whitmore, Ceri and Cocksedge, Nicola and Bloomfield, Daniel}, + year = 2014, + journal = {International Journal of Environmental Research and Public Health}, + volume = 11, + number = 2, + pages = {1725--1746}, + doi = {10.3390/ijerph110201725}, + issn = {1660-4601}, + url = {https://www.mdpi.com/1660-4601/11/2/1725}, + pubmedid = 24499879, + abstract = {Linking environmental, socioeconomic and health datasets provides new insights into the potential associations between climate change and human health and wellbeing, and underpins the development of decision support tools that will promote resilience to climate change, and thus enable more effective adaptation. This paper outlines the challenges and opportunities presented by advances in data collection, storage, analysis, and access, particularly focusing on “data mashups”. These data mashups are integrations of different types and sources of data, frequently using open application programming interfaces and data sources, to produce enriched results that were not necessarily the original reason for assembling the raw source data. As an illustration of this potential, this paper describes a recently funded initiative to create such a facility in the UK for use in decision support around climate change and health, and provides examples of suitable sources of data and the purposes to which they can be directed, particularly for policy makers and public health decision makers.} +} +@article{article_Fleming2017BigDI, + title = {{Big Data in Environment and Human Health}}, + author = {Lora Fleming and Niccoló Tempini and Harriet Gordon-Brown and Gordon L. Nichols and Christophe Sarran and Paolo Vineis and Giovanni Leonardi and Brian Golding and Andy Haines and Anthony Kessel and Virginia Murray and Michael Depledge and Sabina Leonelli}, + year = 2017, + journal = {Oxford Research Encyclopedia of Environmental Science}, + doi = {10.1093/acrefore/9780199389414.013.541}, + url = {https://doi.org/10.1093/acrefore/9780199389414.013.541} +} +@article{article_wilkinson2016fair, + title = {The {FAIR} Guiding Principles for scientific data management and stewardship}, + author = {Wilkinson, Mark D and Dumontier, Michel and Aalbersberg, IJsbrand Jan and Appleton, Gabrielle and Axton, Myles and Baak, Arie and Blomberg, Niklas and Boiten, Jan-Willem and da Silva Santos, Luiz Bonino and Bourne, Philip E and others}, + year = 2016, + journal = {Scientific data}, + publisher = {Nature Publishing Group}, + volume = 3, + number = 1, + pages = {1--9} +} +@article{article_cui2022integrating, + title = {Integrating multiscale geospatial environmental data into large population health studies: challenges and opportunities}, + author = {Cui, Yuxia and Eccles, Kristin M and Kwok, Richard K and Joubert, Bonnie R and Messier, Kyle P and Balshaw, David M}, + year = 2022, + journal = {Toxics}, + publisher = {MDPI}, + volume = 10, + number = 7, + pages = 403 +} +@techreport{report_USGS2002, + title = {Methods to achieve accurate projection of regional and global raster databases}, + author = {Usery, E Lynn and Seong, Jeong Chang and Steinwand, Dan}, + year = 2002, + doi = {10.3133/ofr01181}, + url = {https://pubs.usgs.gov/publication/ofr01181}, + institution = {US Geological Survey} +} +@article{article_messier2012integrating, + title = {Integrating address geocoding, land use regression, and spatiotemporal geostatistical estimation for groundwater tetrachloroethylene}, + author = {Messier, Kyle P and Akita, Yasuyuki and Serre, Marc L}, + year = 2012, + journal = {Environmental science \& technology}, + publisher = {ACS Publications}, + volume = 46, + number = 5, + pages = {2772--2780} +} +@article{article_abatzoglou2013development, + title = {Development of gridded surface meteorological data for ecological applications and modelling}, + author = {Abatzoglou, John T}, + year = 2013, + journal = {International journal of climatology}, + publisher = {Wiley Online Library}, + volume = 33, + number = 1, + pages = {121--131} +} +@article{article_abatzoglou2018terraclimate, + title = {{TerraClimate}, a high-resolution global dataset of monthly climate and climatic water balance from 1958--2015}, + author = {Abatzoglou, John T and Dobrowski, Solomon Z and Parks, Sean A and Hegewisch, Katherine C}, + year = 2018, + journal = {Scientific data}, + publisher = {Nature Publishing Group}, + volume = 5, + number = 1, + pages = {1--12} +} +@article{article_christman2012error, + title = {Error propagation in raster data integration}, + author = {Christman, Zachary J and Rogan, John}, + year = 2012, + journal = {Photogrammetric Engineering \& Remote Sensing}, + publisher = {American Society for Photogrammetry and Remote Sensing}, + volume = 78, + number = 6, + pages = {617--624} +} +@article{article_steinwand1995reprojection, + title = {Map Projections for Global and Gontinental Data Sets and an Analysis of Pixel Distortion Caused by Reproiection}, + author = {Steinwand, Daniel R and Hutchinson, John A and Snyder, John P}, + year = 1995, + journal = {Photogrammetric Engineering \& Remote Sensing}, + volume = 61, + number = 12, + pages = {1487--1497} +} + +@article{article_cruzalonso2023easyclimate, +title = {The easyclimate {R} package: Easy access to high-resolution daily climate data for Europe}, +journal = {Environmental Modelling \& Software}, +volume = {161}, +pages = {105627}, +year = {2023}, +issn = {1364-8152}, +doi = {https://doi.org/10.1016/j.envsoft.2023.105627}, +url = {https://www.sciencedirect.com/science/article/pii/S1364815223000130}, +author = {Verónica Cruz-Alonso and Christoph Pucher and Sophia Ratcliffe and Paloma Ruiz-Benito and Julen Astigarraga and Mathias Neumann and Hubert Hasenauer and Francisco Rodríguez-Sánchez}, +keywords = {R package, Climate, Europe, Cloud-optimized geoTIFF, Daily data, Reproducibility}, +abstract = {In recent decades there has been an increasing demand in environmental sciences for harmonized climatic data at large spatial scales and long periods. Here we present easyclimate, a software package to obtain daily climatic data at high resolution (0.0083°, ∼1 km) with R. The package facilitates the downloading and processing of precipitation, minimum and maximum temperatures for Europe from 1950 to 2020. Using easyclimate and given a set of coordinates (points or polygons) and dates (days or years), the user can download the climatic information as a tidy table or a raster object. In this package we implemented Cloud-Optimized GeoTIFFs which provide access to daily climate data for thousands of sites/days, without having to download huge rasters. Daily climate data are not available in many of the current climate databases and are essential for many research questions and applications in environmental modelling, forestry, and ecological and vegetation studies across Europe.} +} + +@article{article_nandi2024imdlib, +title = {{IMDLIB}: {A}n open-source library for retrieval, processing and spatiotemporal exploratory assessments of gridded meteorological observation datasets over India}, +journal = {Environmental Modelling \& Software}, +volume = {171}, +pages = {105869}, +year = {2024}, +issn = {1364-8152}, +doi = {https://doi.org/10.1016/j.envsoft.2023.105869}, +url = {https://www.sciencedirect.com/science/article/pii/S1364815223002554}, +author = {Saswata Nandi and Pratiman Patel and Sabyasachi Swain}, +keywords = {IMD gridded datasets, Hydrometeorology, Python, Trend, Extreme indices, SDGs}, +abstract = {Addressing a pressing need for streamlined access to observed meteorological data in India, we present IMDLIB, an open-source Python library that operates on gridded datasets from the India Meteorological Department (IMD). IMDLIB simplifies the retrieval, management, and processing of IMD's rainfall, maximum and minimum temperature data at varying scales (point, regional, catchment, and country scales). IMDLIB stands out by directly interfacing with IMD's database through robust APIs, streamlining data acquisition. It offers transformation of IMD's binary data into common formats (e.g., NetCDF/GeoTIFF/CSV) and advanced analytics, including trend analysis, spatiotemporal data interpolation, calculation of meteorological indices and extreme characteristics, showcasing superior capabilities compared to traditional meteorological data processing tool available for the region. To underline its robustness, IMDLIB's application was illustrated in two distinct regions: Rajasthan State and the Godavari River Basin. Through IMDLIB, we envision enhanced data accessibility, leading to more insightful hydro-climatic research and analysis.} +} + +@article{article_vargasgodoy2023precipe, +title = {pRecipe: A global precipitation climatology toolbox and database}, +journal = {Environmental Modelling \& Software}, +volume = {165}, +pages = {105711}, +year = {2023}, +issn = {1364-8152}, +doi = {https://doi.org/10.1016/j.envsoft.2023.105711}, +url = {https://www.sciencedirect.com/science/article/pii/S136481522300097X}, +author = {Mijael Rodrigo {Vargas Godoy} and Yannis Markonis}, +keywords = {Multi-source data, Data set validation, Global precipitation, Satellite remote sensing, Reanalyses, Hydroclimatology}, +abstract = {Remote sensing data and model simulations of precipitation complemented the traditional surface measurements and offer unprecedented coverage on a global scale. However, the substantial heterogeneity among data products has hindered this unique opportunity to obtain a robust quantification of the climatologic properties of precipitation globally. Herein we present pRecipe, a package developed in R with reproducible science as our standard. pRecipe provides functions to download, explore, process, and visualize a database of 24 precipitation data sets at monthly time step and 0.25∘ resolution (20CR v3, CHIRPS v2.0, CMAP, CMORPH, CPC-Global, CRU TS v4.06, EM-EARTH, ERA-20C, ERA5, GHCN v2, GLDAS-CLSM, GLDAS-NOAH, GLDAS-VIC, GPCC v2020, GPCP v2.3, GPM IMERGM v06, MSWEP v2.8, NCEP/DOE R2, NCEP/NCAR R1, PERSIANN-CDR, PREC/L, TerraClimate, TRMM 3B43 v7, UDel v5.01).} +} + + +@article{article_sayyed2024satellite, + title = {Satellite data for environmental justice: a scoping review of the literature in the {United} {States}}, + volume = {19}, + issn = {1748-9326}, + shorttitle = {Satellite data for environmental justice}, + url = {https://iopscience.iop.org/article/10.1088/1748-9326/ad1fa4}, + doi = {10.1088/1748-9326/ad1fa4}, + abstract = {Abstract + In support of the environmental justice (EJ) movement, researchers, activists, and policymakers often use environmental data to document evidence of the unequal distribution of environmental burdens and benefits along lines of race, class, and other socioeconomic characteristics. Numerous limitations, such as spatial or temporal discontinuities, exist with commonly used data measurement techniques, which include ground monitoring and federal screening tools. Satellite data is well poised to address these gaps in EJ measurement and monitoring; however, little is known about how satellite data has advanced findings in EJ or can help to promote EJ through interventions. Thus, this scoping review aims to (1) explore trends in study design, topics, geographic scope, and satellite datasets used to research EJ, (2) synthesize findings from studies that use satellite data to characterize disparities and inequities across socio-demographic groups for various environmental categories, and (3) capture how satellite data are relevant to policy and real-world impact. Following PRISMA extension guidelines for scoping reviews, we retrieved 81 articles that applied satellite data for EJ research in the United States from 2000 to 2022. The majority of the studies leveraged the technical advantages of satellite data to identify socio-demographic disparities in exposure to environmental risk factors, such as air pollution, and access to environmental benefits, such as green space, at wider coverage and with greater precision than previously possible. These disparities in exposure and access are associated with health outcomes such as increased cardiovascular and respiratory diseases, mental illness, and mortality. Research using satellite data to illuminate EJ concerns can contribute to efforts to mitigate environmental inequalities and reduce health disparities. Satellite data for EJ research can therefore support targeted interventions or influence planning and policy changes, but significant work remains to facilitate the application of satellite data for policy and community impact.}, + number = {3}, + urldate = {2024-06-06}, + journal = {Environmental Research Letters}, + author = {Sayyed, Tanya Kreutzer and Ovienmhada, Ufuoma and Kashani, Mitra and Vohra, Karn and Kerr, Gaige Hunter and O’Donnell, Catherine and Harris, Maria H and Gladson, Laura and Titus, Andrea R and Adamo, Susana B and Fong, Kelvin C and Gargulinski, Emily M and Soja, Amber J and Anenberg, Susan and Kuwayama, Yusuke}, + month = mar, + year = {2024}, + pages = {033001} +} + +@article{article_thomas2022burning, + title = {A burning issue: {Reviewing} the socio-demographic and environmental justice aspects of the wildfire literature}, + volume = {17}, + issn = {1932-6203}, + shorttitle = {A burning issue}, + url = {https://dx.plos.org/10.1371/journal.pone.0271019}, + doi = {10.1371/journal.pone.0271019}, + abstract = {Larger and more severe wildfires are becoming more frequent and impacting different communities and human settlements. Much of the scientific literature and media on wildfires has focused on area of ecosystems burned and numbers of structures destroyed. Equally unprecedented, but often less reported, are the increasing socioeconomic impacts different people and communities face from wildfires. Such information seems to indicate an emerging need to account for wildfire effects on peri-urban or wildland urban interface (WUI) areas, newer socio-demographic groups, and disadvantaged communities. To address this, we reviewed the socio-demographic dimensions of the wildfire literature using an environmental justice (EJ) lens. Specifically using a literature review of wildfires, human communities, social vulnerability, and homeowner mitigation, we conducted bibliometric and statistical analyses of 299 publications. The majority of publications were from the United States, followed by Canada and Australia, and most dealt with homeowner mitigation of risk, defensible space, and fuel treatments in WUI areas. Most publications studied the direct effects of wildfire related damage. Secondary impacts such as smoke, rural and urban communities, and the role of poverty and language were less studied. Based on a proposed wildfire-relevant EJ definition, the first EJ publication was in 2004, but the term was first used as a keyword in 2018. Studies in WUI communities statistically decreased the likelihood that a publication was EJ relevant. There was a significant relationship between EJ designation and inclusion of race/ethnicity and poverty variables in the study. Complexity across the various definitions of EJ suggest that it should not be used as a quantitative or binary metric; but as a lens to better understand socio-ecological impacts to diverse communities. We present a wildfire-relevant definition to potentially guide policy formulation and account for social and environmental justice issues.}, + language = {en}, + number = {7}, + urldate = {2024-06-06}, + journal = {PLOS ONE}, + author = {Thomas, Alyssa S. and Escobedo, Francisco J. and Sloggy, Matthew R. and Sánchez, José J.}, + editor = {Jones, Julia A.}, + month = jul, + year = {2022}, + pages = {e0271019} +} + + + +@misc{data_mod09ga2021, + title = {{MODIS}/{Terra} {Surface} {Reflectance} {Daily} {L2G} {Global} 1km and 500m {SIN} {Grid} {V061}}, + url = {https://lpdaac.usgs.gov/products/mod09gav061/}, + doi = {10.5067/MODIS/MOD09GA.061}, + urldate = {2024-06-24}, + publisher = {NASA EOSDIS Land Processes Distributed Active Archive Center}, + author = {Vermote, Eric and Wolfe, Robert}, + year = {2021}, +} + +@misc{data_mod13a22021, + title = {{MODIS}/{Terra} {Vegetation} {Indices} 16-{Day} {L3} {Global} 1km {SIN} {Grid} {V061}}, + url = {https://lpdaac.usgs.gov/products/mod13a2v061/}, + doi = {10.5067/MODIS/MOD13A2.061}, + urldate = {2024-06-24}, + publisher = {NASA EOSDIS Land Processes Distributed Active Archive Center}, + author = {Didan, Kamel}, + year = {2021}, +} + +@misc{data_mod11a12021, + title = {{MODIS}/{Terra} {Land} {Surface} {Temperature}/{Emissivity} {Daily} {L3} {Global} 1km {SIN} {Grid} {V061}}, + url = {https://lpdaac.usgs.gov/products/mod11a1v061/}, + doi = {10.5067/MODIS/MOD11A1.061}, + urldate = {2024-06-24}, + publisher = {NASA EOSDIS Land Processes Distributed Active Archive Center}, + author = {Wan, Zhengming and Hook, Simon and Hulley, Glynn}, + year = {2021}, +} + +@misc{data_mcd19a22021, + title = {{MODIS}/{Terra}+{Aqua} {Land} {Aerosol} {Optical} {Depth} {Daily} {L2G} {Global} 1km {SIN} {Grid} {V061}}, + url = {https://lpdaac.usgs.gov/products/mcd19a2v061/}, + doi = {10.5067/MODIS/MCD19A2.061}, + urldate = {2024-06-24}, + publisher = {NASA EOSDIS Land Processes Distributed Active Archive Center}, + author = {Lyapustin, Alexei and Wang, Yujie}, + year = {2022}, +} + +@misc{data_mod06l2_2017, + title = {{MODIS}/{Terra} {Clouds} 5-{Min} {L2} {Swath} 1km and 5km}, + url = {https://ladsweb.modaps.eosdis.nasa.gov/missions-and-measurements/products/MOD06_L2}, + doi = {10.5067/MODIS/MOD06_L2.061}, + urldate = {2024-06-24}, + publisher = {NASA Level 1 and Atmosphere Archive and Distribution System Distributed Active Archive Center}, + author = {{MODIS Atmosphere Science Team}}, + year = {2017}, +} + +@article{article_roman2018vnp46, + title = {{NASA}'s {Black} {Marble} nighttime lights product suite}, + volume = {210}, + issn = {00344257}, + url = {https://linkinghub.elsevier.com/retrieve/pii/S003442571830110X}, + doi = {10.1016/j.rse.2018.03.017}, + language = {en}, + urldate = {2024-06-24}, + journal = {Remote Sensing of Environment}, + author = {Román, Miguel O. and Wang, Zhuosen and Sun, Qingsong and Kalb, Virginia and Miller, Steven D. and Molthan, Andrew and Schultz, Lori and Bell, Jordan and Stokes, Eleanor C. and Pandey, Bhartendu and Seto, Karen C. and Hall, Dorothy and Oda, Tomohiro and Wolfe, Robert E. and Lin, Gary and Golpayegani, Navid and Devadiga, Sadashiva and Davidson, Carol and Sarkar, Sudipta and Praderas, Cid and Schmaltz, Jeffrey and Boller, Ryan and Stevens, Joshua and Ramos González, Olga M. and Padilla, Elizabeth and Alonso, José and Detrés, Yasmín and Armstrong, Roy and Miranda, Ismael and Conte, Yasmín and Marrero, Nitza and MacManus, Kytt and Esch, Thomas and Masuoka, Edward J.}, + month = jun, + year = {2018}, + pages = {113--143}, +} + +@misc{web_usepa2024nei, + title = {Air {Emissions} {Inventories}}, + url = {https://www.epa.gov/air-emissions-inventories}, + urldate = {2024-06-24}, + author = {{United States Environmental Protection Agency}}, + year = {2024}, +} + +@misc{data_ciesin2013groads, + title = {Global {Roads} {Open} {Access} {Data} {Set}, {Version} 1 ({gROADSv1})}, + copyright = {Users may use and redistribute these data without explicit written permission from CIESIN or Information Technology Outreach Services (ITOS)/University of Georgia, with the exception of roads data associated with countries that are listed in the data documentation as requiring additional credits or holding special restrictions. Users are advised to consult the data documentation for further information and to obtain necessary permissions or adhere to relevant restrictions that apply to each of those data sets.}, + url = {https://sedac.ciesin.columbia.edu/data/set/groads-global-roads-open-access-v1}, + doi = {10.7927/H4VD6WCT}, + abstract = {The Global Roads Open Access Data Set, Version 1 (gROADSv1) was developed under the auspices of the CODATA Global Roads Data Development Task Group. The data set combines the best available roads data by country into a global roads coverage, using the UN Spatial Data Infrastructure Transport (UNSDI-T) version 2 as a common data model. All country road networks have been joined topologically at the borders, and many countries have been edited for internal topology. Source data for each country are provided in the documentation, and users are encouraged to refer to the readme file for use constraints that apply to a small number of countries. Because the data are compiled from multiple sources, the date range for road network representations ranges from the 1980s to 2010 depending on the country (most countries have no confirmed date), and spatial accuracy varies. The baseline global data set was compiled by the Information Technology Outreach Services (ITOS) of the University of Georgia. Updated data for 27 countries and 6 smaller geographic entities were assembled by Columbia University's Center for International Earth Science Information Network (CIESIN), with a focus largely on developing countries with the poorest data coverage.}, + urldate = {2024-06-24}, + publisher = {Palisades, NY: NASA Socioeconomic Data and Applications Center (SEDAC)}, + author = {{Center For International Earth Science Information Network-CIESIN-Columbia University} and {Information Technology Outreach Services-ITOS-University Of Georgia}}, + year = {2013}, + keywords = {poverty, agriculture, conservation, health, infrastructure, urban}, +} + +@article{article_omernik2014ecoregions, + title = {Ecoregions of the {Conterminous} {United} {States}: {Evolution} of a {Hierarchical} {Spatial} {Framework}}, + volume = {54}, + issn = {0364-152X, 1432-1009}, + shorttitle = {Ecoregions of the {Conterminous} {United} {States}}, + url = {http://link.springer.com/10.1007/s00267-014-0364-1}, + doi = {10.1007/s00267-014-0364-1}, + language = {en}, + number = {6}, + urldate = {2024-06-24}, + journal = {Environmental Management}, + author = {Omernik, James M. and Griffith, Glenn E.}, + month = dec, + year = {2014}, + pages = {1249--1266}, +} + +@article{article_beck2023koppen, + title = {High-resolution (1 km) {Köppen}-{Geiger} maps for 1901–2099 based on constrained {CMIP6} projections}, + volume = {10}, + issn = {2052-4463}, + url = {https://www.nature.com/articles/s41597-023-02549-6}, + doi = {10.1038/s41597-023-02549-6}, + abstract = {Abstract + + We introduce Version 2 of our widely used 1-km Köppen-Geiger climate classification maps for historical and future climate conditions. The historical maps (encompassing 1901–1930, 1931–1960, 1961–1990, and 1991–2020) are based on high-resolution, observation-based climatologies, while the future maps (encompassing 2041–2070 and 2071–2099) are based on downscaled and bias-corrected climate projections for seven shared socio-economic pathways (SSPs). We evaluated 67 climate models from the Coupled Model Intercomparison Project phase 6 (CMIP6) and kept a subset of 42 with the most plausible CO + 2 + -induced warming rates. We estimate that from 1901–1930 to 1991–2020, approximately 5\% of the global land surface (excluding Antarctica) transitioned to a different major Köppen-Geiger class. Furthermore, we project that from 1991–2020 to 2071–2099, 5\% of the land surface will transition to a different major class under the low-emissions SSP1-2.6 scenario, 8\% under the middle-of-the-road SSP2-4.5 scenario, and 13\% under the high-emissions SSP5-8.5 scenario. The Köppen-Geiger maps, along with associated confidence estimates, underlying monthly air temperature and precipitation data, and sensitivity metrics for the CMIP6 models, can be accessed at + www.gloh2o.org/koppen + .}, + language = {en}, + number = {1}, + urldate = {2024-06-24}, + journal = {Scientific Data}, + author = {Beck, Hylke E. and McVicar, Tim R. and Vergopolan, Noemi and Berg, Alexis and Lutsko, Nicholas J. and Dufour, Ambroise and Zeng, Zhenzhong and Jiang, Xin and Van Dijk, Albert I. J. M. and Miralles, Diego G.}, + month = oct, + year = {2023}, + pages = {724} +} + + +@article{article_daly2000prism, + title = {HIGH-QUALITY SPATIAL CLIMATE DATA SETS FOR THE {U}NITED {S}TATES AND BEYOND}, + volume = {43}, + issn = {2151-0059}, + url = {http://elibrary.asabe.org/abstract.asp??JID=3&AID=3101&CID=t2000&v=43&i=6&T=1}, + doi = {10.13031/2013.3101}, + language = {en}, + number = {6}, + urldate = {2024-06-24}, + journal = {Transactions of the ASAE}, + author = {Daly, C. and Taylor, G. H. and Gibson, W. P. and Parzybok, T. W. and Johnson, G. L. and Pasteris, P. A.}, + year = {2000}, + pages = {1957--1962}, +} + +@misc{web_usepa2024tri, + title = {{TRI} {Basic} {Data} {Files}: {Calendar} {Years} {1987 -- Present}}, + url = {https://www.epa.gov/toxics-release-inventory-tri-program/tri-basic-data-files-calendar-years-1987-present}, + urldate = {2024-06-24}, + author = {{United States Environmental Protection Agency}}, + year = {2024}, +} + +@book{data_hengl2023openlandmap, + author = {Hengl, T. and Parente, L. and Ho, Y.-F. and Simoes, R. and contributors}, + title = {{OpenLandMap Open Land Data services}}, + year = {2023}, + publisher = {OpenGeoHub foundation}, + address = {Wageningen}, + version = {v0.2}, + doi = {10.5281/zenodo.10522799}, + url = {https://openlandmap.github.io/book/} +} + +@misc{web_stacspec2024, + title = {{STAC}: {SpatioTemporal} {Asset} {Catalogs}}, + url = {https://www.stacspec.org/en}, + urldate = {2024-06-24}, + year = {2024} +} + +@inproceedings{abstract_simoes2021rstac, + address = {Brussels, Belgium}, + title = {Rstac: {An} {R} {Package} to {Access} {Spatiotemporal} {Asset} {Catalog} {Satellite} {Imagery}}, + copyright = {https://ieeexplore.ieee.org/Xplorehelp/downloads/license-information/IEEE.html}, + isbn = {978-1-66540-369-6}, + shorttitle = {Rstac}, + url = {https://ieeexplore.ieee.org/document/9553518/}, + doi = {10.1109/IGARSS47720.2021.9553518}, + urldate = {2024-06-24}, + booktitle = {2021 {IEEE} {International} {Geoscience} and {Remote} {Sensing} {Symposium} {IGARSS}}, + publisher = {IEEE}, + author = {Simoes, Rolf and De Souza, Felipe Carvalho and Zaglia, Matheus and De Queiroz, Gilberto Ribeiro and Dos Santos, Rafael D. C. and Ferreira, Karine Reis}, + month = jul, + year = {2021}, + pages = {7674--7677}, +} + +@misc{data_usgs2023nhd, + author = {{U.S. Geological Survey}}, + title = {{National Hydrography Dataset (NHD) -- USGS National Map Downloadable Data Collection}}, + url = {https://www.sciencebase.gov/catalog/item/4f5545cce4b018de15819ca9}, + urldate = {2024-06-24}, + year = {2023} +} + +@misc{data_usepa2023airdata, + author = {{U.S. Environmental Protection Agency}}, + title = {{Air Quality System Data Mart [internet database]}}, + url = {https://www.epa.gov/outdoor-air-quality-data}, + urldate = {2024-06-24}, + year = {2023} +} + + +@misc{data_ciesin2017gpwv4, + title = {Gridded {Population} of the {World}, {Version} 4 ({GPWv4}): {Population} {Density}, {Revision} 11}, + copyright = {This work is licensed under the Creative Commons Attribution 4.0 International License (https://creativecommons.org/licenses/by/4.0). Users are free to use, copy, distribute, transmit, and adapt the work for commercial and non-commercial purposes, without restriction, as long as clear attribution of the source is provided.}, + shorttitle = {Gridded {Population} of the {World}, {Version} 4 ({GPWv4})}, + url = {https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-density-rev11}, + doi = {10.7927/H49C6VHW}, + abstract = {The Gridded Population of the World, Version 4 (GPWv4): Population Density, Revision 11 consists of estimates of human population density (number of persons per square kilometer) based on counts consistent with national censuses and population registers, for the years 2000, 2005, 2010, 2015, and 2020. A proportional allocation gridding algorithm, utilizing approximately 13.5 million national and sub-national administrative units, was used to assign population counts to 30 arc-second grid cells. The population density rasters were created by dividing the population count raster for a given target year by the land area raster. The data files were produced as global rasters at 30 arc-second ({\textasciitilde}1 km at the equator) resolution. To enable faster global processing, and in support of research communities, the 30 arc-second count data were aggregated to 2.5 arc-minute, 15 arc-minute, 30 arc-minute and 1 degree resolutions to produce density rasters at these resolutions.}, + urldate = {2024-06-24}, + publisher = {Palisades, NY: Socioeconomic Data and Applications Center (SEDAC)}, + author = {{Center For International Earth Science Information Network-CIESIN-Columbia University}}, + year = {2017}, + keywords = {population}, +} + + + +@misc{data_gmao_merra-inst1_2d_asm_Nx, + title = {{MERRA}-2 inst1\_2d\_asm\_Nx: 2d,3-{Hourly},{Instantaneous},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst1\_2d\_asm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I1NXASM_5.12.4.html}, + doi = {10.5067/3Z173KIE2TPD}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst1_2d_int_Nx, + title = {{MERRA}-2 inst1\_2d\_int\_Nx: 2d,1-{Hourly},{Instantaneous},{Single}-{Level},{Assimilation},{Vertically} {Integrated} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst1\_2d\_int\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I1NXINT_5.12.4.html}, + doi = {10.5067/G0U6NGQ3BLE0}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst1_2d_lfo_Nx, + title = {{MERRA}-2 inst1\_2d\_lfo\_Nx: 2d,1-{Hourly},{Instantaneous},{Single}-{Level},{Assimilation},{Land} {Surface} {Forcings} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst1\_2d\_lfo\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I1NXLFO_5.12.4.html}, + doi = {10.5067/RCMZA6TL70BG}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst3_3d_asm_Np, + title = {{MERRA}-2 inst3\_3d\_asm\_Np: 3d,3-{Hourly},{Instantaneous},{Pressure}-{Level},{Assimilation},{Assimilated} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst3\_3d\_asm\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I3NPASM_5.12.4.html}, + doi = {10.5067/QBZ6MG944HW0}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst3_3d_aer_Nv, + title = {{MERRA}-2 inst3\_3d\_aer\_Nv: 3d,3-{Hourly},{Instantaneous},{Model}-{Level},{Assimilation},{Aerosol} {Mixing} {Ratio} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst3\_3d\_aer\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I3NVAER_5.12.4.html}, + doi = {10.5067/LTVB4GPCOTK2}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst3_3d_asm_Nv, + title = {{MERRA}-2 inst3\_3d\_asm\_Nv: 3d,3-{Hourly},{Instantaneous},{Model}-{Level},{Assimilation},{Assimilated} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst3\_3d\_asm\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I3NVASM_5.12.4.html}, + doi = {10.5067/WWQSXQ8IVFW8}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst3_3d_chm_Nv, + title = {{MERRA}-2 inst3\_3d\_chm\_Nv: 3d,3-{Hourly},{Instantaneous},{Model}-{Level},{Assimilation},{Carbon} {Monoxide} and {Ozone} {Mixing} {Ratio} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst3\_3d\_chm\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I3NVCHM_5.12.4.html}, + doi = {10.5067/HO9OVZWF3KW2}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst3_3d_gas_Nv, + title = {{MERRA}-2 inst3\_3d\_gas\_Nv: 3d,3-{Hourly},{Instantaneous},{Model}-{Level},{Assimilation},{Aerosol} {Mixing} {Ratio} {Analysis} {Increments} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst3\_3d\_gas\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I3NVGAS_5.12.4.html}, + doi = {10.5067/96BUID8HGGX5}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst3_2d_gas_Nx, + title = {{MERRA}-2 inst3\_2d\_gas\_Nx: 2d,3-{Hourly},{Instantaneous},{Single}-{Level},{Assimilation},{Aerosol} {Optical} {Depth} {Analysis} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst3\_2d\_gas\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I3NXGAS_5.12.4.html}, + doi = {10.5067/HNGA0EWW0R09}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst6_3d_ana_Np, + title = {{MERRA}-2 inst6\_3d\_ana\_Np: 3d,6-{Hourly},{Instantaneous},{Pressure}-{Level},{Analysis},{Analyzed} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst6\_3d\_ana\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I6NPANA_5.12.4.html}, + doi = {10.5067/A7S6XP56VZWS}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-inst6_3d_ana_Nv, + title = {{MERRA}-2 inst6\_3d\_ana\_Nv: 3d,6-{Hourly},{Instantaneous},{Model}-{Level},{Analysis},{Analyzed} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 inst6\_3d\_ana\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2I6NVANA_5.12.4.html}, + doi = {10.5067/IUUF4WB9FT4W}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-statD_2d_slv_Nx_d, + title = {{MERRA}-2 {statD}\_2d\_slv\_Nx: 2d,{Daily},{Aggregated} {Statistics},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {statD}\_2d\_slv\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2SDNXSLV_5.12.4.html}, + doi = {10.5067/9SC1VNTWGWV3}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_adg_Nx, + title = {{MERRA}-2 tavg1\_2d\_adg\_Nx: 2d,3-{Hourly},{Time}-averaged,{Single}-{Level},{Assimilation},{Aerosol} {Diagnostics} (extended) {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_adg\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXADG_5.12.4.html}, + doi = {10.5067/HM00OHQBHKTP}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_aer_Nx, + title = {{MERRA}-2 tavg1\_2d\_aer\_Nx: 2d,1-{Hourly},{Time}-averaged,{Single}-{Level},{Assimilation},{Aerosol} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_aer\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXAER_5.12.4.html}, + doi = {10.5067/KLICLTZ8EM9D}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_chm_Nx, + title = {{MERRA}-2 tavg1\_2d\_chm\_Nx: 2d,3-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Carbon} {Monoxide} and {Ozone} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_chm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXCHM_5.12.4.html}, + doi = {10.5067/3RQ5YS674DGQ}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_csp_Nx, + title = {{MERRA}-2 tavg1\_2d\_csp\_Nx: 2d,1-{Hourly},{Time}-averaged,{Single}-{Level},{Assimilation},{COSP} {Satellite} {Simulator} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_csp\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXCSP_5.12.4.html}, + doi = {10.5067/H0VVAD8F6MX5}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_flx_Nx, + title = {{MERRA}-2 tavg1\_2d\_flx\_Nx: 2d,1-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Surface} {Flux} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_flx\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXFLX_5.12.4.html}, + doi = {10.5067/7MCPBJ41Y0K6}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_int_Nx, + title = {{MERRA}-2 tavg1\_2d\_int\_Nx: 2d,1-{Hourly},{Time}-averaged,{Single}-{Level},{Assimilation},{Vertically} {Integrated} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_int\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXINT_5.12.4.html}, + doi = {10.5067/Q5GVUVUIVGO7}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{pawson_merra-2_2020, + title = {{MERRA}-2 tavg1\_2d\_lfo\_Nx: 2d,1-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Surface} {Forcings} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_lfo\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXLFO_5.12.4.html}, + doi = {10.5067/L0T5GEG1NYFA}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {Pawson, Steven}, + year = {2020}, +} + +@misc{data_gmao_merra-tavg1_2d_lnd_Nx, + title = {{MERRA}-2 tavg1\_2d\_lnd\_Nx: 2d,1-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Surface} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_lnd\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXLND_5.12.4.html}, + doi = {10.5067/RKPHT8KC1Y1T}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_ocn_Nx, + title = {{MERRA}-2 tavg1\_2d\_ocn\_Nx: 2d,1-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Ocean} {Surface} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_ocn\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXOCN_5.12.4.html}, + doi = {10.5067/Y67YQ1L3ZZ4R}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_rad_Nx, + title = {{MERRA}-2 tavg1\_2d\_rad\_Nx: 2d,1-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_rad\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXRAD_5.12.4.html}, + doi = {10.5067/Q9QMY5PBNV1T}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg1_2d_slv_Nx, + title = {{MERRA}-2 tavg1\_2d\_slv\_Nx: 2d,1-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg1\_2d\_slv\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T1NXSLV_5.12.4.html}, + doi = {10.5067/VJAFPLI1CSIV}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_mst_Ne, + title = {{MERRA}-2 tavg3\_3d\_mst\_Ne: 3d,3-{Hourly},{Time}-{Averaged},{Model}-{Level} {Edge},{Assimilation},{Moist} {Processes} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_mst\_Ne}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NEMST_5.12.4.html}, + doi = {10.5067/JRUZ3SJ3ZJ72}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_trb_Ne, + title = {{MERRA}-2 tavg3\_3d\_trb\_Ne: 3d,3-{Hourly},{Time}-{Averaged},{Model}-{Level} {Edge},{Assimilation},{Turbulence} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_trb\_Ne}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NETRB_5.12.4.html}, + doi = {10.5067/4I7ZI35QRH8K}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_nav_Ne, + title = {{MERRA}-2 tavg3\_3d\_nav\_Ne: 3d,3-{Hourly},{Time}-{Averaged}, {Vertical} {Coordinates} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_nav\_Ne}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NENAV_5.12.4.html}, + doi = {10.5067/N5WAKNS1UYQN}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_cld_Np, + title = {{MERRA}-2 tavg3\_3d\_cld\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Cloud} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_cld\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPCLD_5.12.4.html}, + doi = {10.5067/TX10URJSKT53}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_mst_Np, + title = {{MERRA}-2 tavg3\_3d\_mst\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Moist} {Processes} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_mst\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPMST_5.12.4.html}, + doi = {10.5067/0TUFO90Q2PMS}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_rad_Np, + title = {{MERRA}-2 tavg3\_3d\_rad\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_rad\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPRAD_5.12.4.html}, + doi = {10.5067/3UGE8WQXZAOK}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_tdt_Np, + title = {{MERRA}-2 tavg3\_3d\_tdt\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Temperature} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_tdt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPTDT_5.12.4.html}, + doi = {10.5067/9NCR9DDDOPFI}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_trb_Np, + title = {{MERRA}-2 tavg3\_3d\_trb\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Turbulence} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_trb\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPTRB_5.12.4.html}, + doi = {10.5067/ZRRJPGWL8AVL}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_udt_Np, + title = {{MERRA}-2 tavg3\_3d\_udt\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Wind} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_udt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPUDT_5.12.4.html}, + doi = {10.5067/CWV0G3PPPWFW}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_odt_Np, + title = {{MERRA}-2 tavg3\_3d\_odt\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Ozone} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_odt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPODT_5.12.4.html}, + doi = {10.5067/S0LYTK57786Z}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_qdt_Np, + title = {{MERRA}-2 tavg3\_3d\_qdt\_Np: 3d,3-{Hourly},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Moist} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_qdt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NPQDT_5.12.4.html}, + doi = {10.5067/A9KWADY78YHQ}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_asm_Nv, + title = {{MERRA}-2 tavg3\_3d\_asm\_Nv: 3d,3-{Hourly},{Time}-{Averaged},{Model}-{Level},{Assimilation},{Assimilated} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_asm\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NVASM_5.12.4.html}, + doi = {10.5067/SUOQESM06LPK}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_cld_Nv, + title = {{MERRA}-2 tavg3\_3d\_cld\_Nv: 3d,3-{Hourly},{Time}-{Averaged},{Model}-{Level},{Assimilation},{Cloud} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_cld\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NVCLD_5.12.4.html}, + doi = {10.5067/F9353J0FAHIH}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_mst_Nv, + title = {{MERRA}-2 tavg3\_3d\_mst\_Nv: 3d,3-{Hourly},{Time}-{Averaged},{Model}-{Level},{Assimilation},{Moist} {Processes} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_mst\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NVMST_5.12.4.html}, + doi = {10.5067/ZXTJ28TQR1TR}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_3d_rad_Nv, + title = {{MERRA}-2 tavg3\_3d\_rad\_Nv: 3d,3-{Hourly},{Time}-{Averaged},{Model}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_3d\_rad\_Nv}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NVRAD_5.12.4.html}, + doi = {10.5067/7GFQKO1T43RW}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavg3_2d_glc_Nx, + title = {{MERRA}-2 tavg3\_2d\_glc\_Nx: 2d,3-{Hourly},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Ice} {Surface} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 tavg3\_2d\_glc\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2T3NXGLC_5.12.4.html}, + doi = {10.5067/9ETB4TT5J6US}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instM_2d_asm_Nx, + title = {{MERRA}-2 {instM}\_2d\_asm\_Nx: 2d,{Monthly} mean,{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instM}\_2d\_asm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IMNXASM_5.12.4.html}, + doi = {10.5067/5ESKGQTZG7FO}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instM_2d_int_Nx, + title = {{MERRA}-2 {instM}\_2d\_int\_Nx: 2d,{Monthly} mean,{Instantaneous},{Single}-{Level},{Assimilation},{Vertically} {Integrated} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instM}\_2d\_int\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IMNXINT_5.12.4.html}, + doi = {10.5067/KVTU1A8BWFSJ}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instM_2d_lfo_Nx, + title = {{MERRA}-2 {instM}\_2d\_lfo\_Nx: 2d,{Monthly} mean,{Instantaneous},{Single}-{Level},{Assimilation},{Land} {Surface} {Forcings} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instM}\_2d\_lfo\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IMNXLFO_5.12.4.html}, + doi = {10.5067/11F99Y6TXN99}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instM_2d_gas_Nx, + title = {{MERRA}-2 {instM}\_2d\_gas\_Nx: 2d,{Monthly} mean,{Instantaneous},{Single}-{Level},{Assimilation},{Aerosol} {Optical} {Depth} {Analysis} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instM}\_2d\_gas\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IMNXGAS_5.12.4.html}, + doi = {10.5067/XOGNBQEPLUC5}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instM_3d_asm_Np, + title = {{MERRA}-2 {instM}\_3d\_asm\_Np: 3d,{Monthly} mean,{Instantaneous},{Pressure}-{Level},{Assimilation},{Assimilated} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instM}\_3d\_asm\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IMNPASM_5.12.4.html}, + doi = {10.5067/2E096JV59PK7}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instM_3d_ana_Np, + title = {{MERRA}-2 {instM}\_3d\_ana\_Np: 3d,{Monthly} mean,{Instantaneous},{Pressure}-{Level},{Analysis},{Analyzed} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instM}\_3d\_ana\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IMNPANA_5.12.4.html}, + doi = {10.5067/V92O8XZ30XBI}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_adg_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_adg\_Nx: 2d,{Monthly} mean,{Time}-averaged,{Single}-{Level},{Assimilation},{Aerosol} {Diagnostics} (extended) {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_adg\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXADG_5.12.4.html}, + doi = {10.5067/RZIK2TV7PP38}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_aer_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_aer\_Nx: 2d,{Monthly} mean,{Time}-averaged,{Single}-{Level},{Assimilation},{Aerosol} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_aer\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXAER_5.12.4.html}, + doi = {10.5067/FH9A0MLJPC7N}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_chm_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_chm\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Carbon} {Monoxide} and {Ozone} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_chm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXCHM_5.12.4.html}, + doi = {10.5067/WMT31RKEXK8I}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_csp_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_csp\_Nx: 2d,{Monthly} mean,{Time}-averaged,{Single}-{Level},{Assimilation},{COSP} {Satellite} {Simulator} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_csp\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXCSP_5.12.4.html}, + doi = {10.5067/BZPOTGJOQKLU}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_flx_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_flx\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Surface} {Flux} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_flx\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXFLX_5.12.4.html}, + doi = {10.5067/0JRLVL8YV2Y4}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_int_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_int\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Vertically} {Integrated} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_int\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXINT_5.12.4.html}, + doi = {10.5067/FQPTQ4OJ22TL}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_lfo_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_lfo\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Surface} {Forcings} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_2d\_lfo\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXLFO_5.12.4.html}, + doi = {10.5067/5V7K6LJD44SY}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_lnd_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_lnd\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Surface} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXLND_5.12.4.html}, + doi = {10.5067/8S35XF81C28F}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_ocn_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_ocn\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Ocean} {Surface} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXOCN_5.12.4.html}, + doi = {10.5067/4IASLIDL8EEC}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_rad_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_rad\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXRAD_5.12.4.html}, + doi = {10.5067/OU3HJDS973O0}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_slv_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_slv\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXSLV_5.12.4.html}, + doi = {10.5067/AP1B0BA5PD2K}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_2d_glc_Nx, + title = {{MERRA}-2 {tavgM}\_2d\_glc\_Nx: 2d,{Monthly} mean,{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Ice} {Surface} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNXGLC_5.12.4.html}, + doi = {10.5067/5W8Q3I9WUFGX}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_cld_Np, + title = {{MERRA}-2 {tavgM}\_3d\_cld\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Cloud} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPCLD_5.12.4.html}, + doi = {10.5067/J9R0LXGH48JR}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_mst_Np, + title = {{MERRA}-2 {tavgM}\_3d\_mst\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Moist} {Processes} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPMST_5.12.4.html}, + doi = {10.5067/ZRZGD0DCK1CG}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_rad_Np, + title = {{MERRA}-2 {tavgM}\_3d\_rad\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPRAD_5.12.4.html}, + doi = {10.5067/H3YGROBVBGFJ}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_tdt_Np, + title = {{MERRA}-2 {tavgM}\_3d\_tdt\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Temperature} {Tendencies} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPTDT_5.12.4.html}, + doi = {10.5067/VILT59HI2MOY}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_trb_Np, + title = {{MERRA}-2 {tavgM}\_3d\_trb\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Turbulence} {Diagnostics} {V5}.12.4}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPTRB_5.12.4.html}, + doi = {10.5067/2YOIQB5C3ACN}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_udt_Np, + title = {{MERRA}-2 {tavgM}\_3d\_udt\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Wind} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_3d\_udt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPUDT_5.12.4.html}, + doi = {10.5067/YSR6IA5057XX}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_odt_Np, + title = {{MERRA}-2 {tavgM}\_3d\_odt\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Ozone} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_3d\_odt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPODT_5.12.4.html}, + doi = {10.5067/Z2KCWAV4GPD2}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgM_3d_qdt_Np, + title = {{MERRA}-2 {tavgM}\_3d\_qdt\_Np: 3d,{Monthly} mean,{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Moist} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgM}\_3d\_qdt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TMNPQDT_5.12.4.html}, + doi = {10.5067/2ZTU87V69ATP}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-statD_2d_slv_Nx_m, + title = {{MERRA}-2 {statD}\_2d\_slv\_Nx: 2d,{Monthly},{Aggregated} {Statistics},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {statD}\_2d\_slv\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2SMNXSLV_5.12.4.html}, + doi = {10.5067/KVIMOMCUO83U}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-const_2d_asm_Nx, + title = {{MERRA}-2 const\_2d\_asm\_Nx: 2d, constants}, + shorttitle = {{MERRA}-2 const\_2d\_asm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2C0NXASM_5.12.4.html}, + doi = {10.5067/ME5QX6Q5IGGU}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instU_2d_asm_Nx, + title = {{MERRA}-2 {instU}\_2d\_asm\_Nx: 2d,{Diurnal},{Instantaneous},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instU}\_2d\_asm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IUNXASM_5.12.4.html}, + doi = {10.5067/BOJSTZAO2L8R}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instU_2d_int_Nx, + title = {{MERRA}-2 {instU}\_2d\_int\_Nx: 2d,{Diurnal},{Instantaneous},{Single}-{Level},{Assimilation},{Vertically} {Integrated} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instU}\_2d\_int\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IUNXINT_5.12.4.html}, + doi = {10.5067/DGAB3HFEYMLY}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instU_2d_lfo_Nx, + title = {{MERRA}-2 {instU}\_2d\_lfo\_Nx: 2d,{Diurnal},{Instantaneous},{Single}-{Level},{Assimilation},{Land} {Surface} {Forcings} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instU}\_2d\_lfo\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IUNXLFO_5.12.4.html}, + doi = {10.5067/FC3BVJ88Y8A2}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instU_2d_gas_Nx, + title = {{MERRA}-2 {instU}\_2d\_gas\_Nx: 2d,{Diurnal},{Instantaneous},{Single}-{Level},{Assimilation},{Aerosol} {Optical} {Depth} {Analysis} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instU}\_2d\_gas\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IUNXGAS_5.12.4.html}, + doi = {10.5067/TVJ4MHBED39L}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instU_3d_asm_Np, + title = {{MERRA}-2 {instU}\_3d\_asm\_Np: 3d,{Diurnal},{Instantaneous},{Pressure}-{Level},{Assimilation},{Assimilated} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instU}\_3d\_asm\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IUNPASM_5.12.4.html}, + doi = {10.5067/6EGRBNEBMIYS}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-instU_3d_ana_Np, + title = {{MERRA}-2 {instU}\_3d\_ana\_Np: 3d,{Diurnal},{Instantaneous},{Pressure}-{Level},{Analysis},{Analyzed} {Meteorological} {Fields} {V5}.12.4}, + shorttitle = {{MERRA}-2 {instU}\_3d\_ana\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2IUNPANA_5.12.4.html}, + doi = {10.5067/TRD91YO9S6E7}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_adg_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_adg\_Nx: 2d,{Diurnal},{Time}-averaged,{Single}-{Level},{Assimilation},{Aerosol} {Diagnostics} (extended) {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_adg\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXADG_5.12.4.html}, + doi = {10.5067/YZJJXZTFCX6B}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_aer_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_aer\_Nx: 2d,{Diurnal},{Time}-averaged,{Single}-{Level},{Assimilation},{Aerosol} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_aer\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXAER_5.12.4.html}, + doi = {10.5067/KPUMVXFEQLA1}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_chm_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_chm\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Carbon} {Monoxide} and {Ozone} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_chm\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXCHM_5.12.4.html}, + doi = {10.5067/5KFZ6GXRHZKN}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_csp_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_csp\_Nx: 2d,{Diurnal},{Time}-averaged,{Single}-{Level},{Assimilation},{COSP} {Satellite} {Simulator} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_csp\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXCSP_5.12.4.html}, + doi = {10.5067/9PH5QU4CL9E8}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_flx_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_flx\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Surface} {Flux} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_flx\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXFLX_5.12.4.html}, + doi = {10.5067/LUHPNWAKYIO3}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_int_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_int\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Vertically} {Integrated} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_int\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXINT_5.12.4.html}, + doi = {10.5067/R2MPVU4EOSWT}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_lfo_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_lfo\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Surface} {Forcings} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_lfo\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXLFO_5.12.4.html}, + doi = {10.5067/BTSNKAJND3ME}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_lnd_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_lnd\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Surface} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_lnd\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXLND_5.12.4.html}, + doi = {10.5067/W0J15047CF6N}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_ocn_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_ocn\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Ocean} {Surface} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_ocn\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXOCN_5.12.4.html}, + doi = {10.5067/KLNAVGAX7J66}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_rad_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_rad\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_rad\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXRAD_5.12.4.html}, + doi = {10.5067/4SDCJYK8P9QU}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_slv_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_slv\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Single}-{Level} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_slv\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXSLV_5.12.4.html}, + doi = {10.5067/AFOK0TPEVQEK}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_2d_glc_Nx, + title = {{MERRA}-2 {tavgU}\_2d\_glc\_Nx: 2d,{Diurnal},{Time}-{Averaged},{Single}-{Level},{Assimilation},{Land} {Ice} {Surface} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_2d\_glc\_Nx}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNXGLC_5.12.4.html}, + doi = {10.5067/7VUPQC736SWX}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_cld_Np, + title = {{MERRA}-2 {tavgU}\_3d\_cld\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Cloud} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_cld\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPCLD_5.12.4.html}, + doi = {10.5067/EPW7T5UO0C0N}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_mst_Np, + title = {{MERRA}-2 {tavgU}\_3d\_mst\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Moist} {Processes} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_mst\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPMST_5.12.4.html}, + doi = {10.5067/ZRSN0JU27DK2}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_rad_Np, + title = {{MERRA}-2 {tavgU}\_3d\_rad\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Radiation} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_rad\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPRAD_5.12.4.html}, + doi = {10.5067/H140JMDOWB0Y}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_tdt_Np, + title = {{MERRA}-2 {tavgU}\_3d\_tdt\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Temperature} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_tdt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPTDT_5.12.4.html}, + doi = {10.5067/QPO9E5TPZ8OF}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_trb_Np, + title = {{MERRA}-2 {tavgU}\_3d\_trb\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Turbulence} {Diagnostics} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_trb\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPTRB_5.12.4.html}, + doi = {10.5067/2A99C60CG7WC}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_udt_Np, + title = {{MERRA}-2 {tavgU}\_3d\_udt\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Wind} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_udt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPUDT_5.12.4.html}, + doi = {10.5067/DO715T7T5PG8}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_odt_Np, + title = {{MERRA}-2 {tavgU}\_3d\_odt\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Ozone} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_odt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPODT_5.12.4.html}, + doi = {10.5067/M8OJ09GZP23E}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{data_gmao_merra-tavgU_3d_qdt_Np, + title = {{MERRA}-2 {tavgU}\_3d\_qdt\_Np: 3d,{Diurnal},{Time}-{Averaged},{Pressure}-{Level},{Assimilation},{Moist} {Tendencies} {V5}.12.4}, + shorttitle = {{MERRA}-2 {tavgU}\_3d\_qdt\_Np}, + url = {https://disc.gsfc.nasa.gov/datacollection/M2TUNPQDT_5.12.4.html}, + doi = {10.5067/S8HJXIR0BFTS}, + urldate = {2024-06-24}, + publisher = {NASA Goddard Earth Sciences Data and Information Services Center}, + author = {{Global Modeling And Assimilation Office} and Pawson, Steven}, + year = {2015}, +} + +@misc{dewitz_national_2024, + title = {National {Land} {Cover} {Database} ({NLCD}) 2019 {Products} (ver. 3.0, {February} 2024)}, + url = {https://www.sciencebase.gov/catalog/item/5f21cef582cef313ed940043}, + doi = {10.5066/P9KZCM54}, + abstract = {The U.S. Geological Survey (USGS), in partnership with several federal agencies, has developed and released five National Land Cover Database (NLCD) products over the past two decades: NLCD 1992, 2001, 2006, 2011, and 2016. The 2016 release saw landcover created for additional years of 2003, 2008, and 2013. These products provide spatially explicit and reliable information on the Nation’s land cover and land cover change. To continue the legacy of NLCD and further establish a long-term monitoring capability for the Nation’s land resources, the USGS has designed a new generation of NLCD products named NLCD 2019. The NLCD 2019 design aims to provide innovative, consistent, and robust methodologies for production of a multi-temporal land cover and land cover change database from 2001 to 2019 at 2–3-year intervals. Comprehensive research was conducted and resulted in developed strategies for NLCD 2019: continued integration between impervious surface and all landcover products with impervious surface being directly mapped as developed classes in the landcover, a streamlined compositing process for assembling and preprocessing based on Landsat imagery and geospatial ancillary datasets; a multi-source integrated training data development and decision-tree based land cover classifications; a temporally, spectrally, and spatially integrated land cover change analysis strategy; a hierarchical theme-based post-classification and integration protocol for generating land cover and change products; a continuous fields biophysical parameters modeling method; and an automated scripted operational system for the NLCD 2019 production. The performance of the developed strategies and methods were tested in twenty composite referenced areas throughout the conterminous U.S. An overall accuracy assessment from the 2016 publication give a 91\% overall landcover accuracy, with the developed classes also showing a 91\% accuracy in overall developed. Results from this study confirm the robustness of this comprehensive and highly automated procedure for NLCD 2019 operational mapping. Questions about the NLCD 2019 land cover product can be directed to the NLCD 2019 land cover mapping team at USGS EROS, Sioux Falls, SD (605) 594-6151 or mrlc@usgs.gov. See included spatial metadata for more details.}, + urldate = {2024-06-24}, + publisher = {U.S. Geological Survey}, + author = {Dewitz, J.}, + month = feb, + year = {2024}, + keywords = {land use change}, +} + +@misc{dewitz_national_2023, + title = {National {Land} {Cover} {Database} ({NLCD}) 2021 {Products}}, + url = {https://www.sciencebase.gov/catalog/item/647626cbd34e4e58932d9d4e}, + doi = {10.5066/P9JZ7AO3}, + abstract = {The U.S. Geological Survey (USGS), in partnership with several federal agencies, has now developed and released seven National Land Cover Database (NLCD) products: NLCD 1992, 2001, 2006, 2011, 2016, 2019, and 2021. Beginning with the 2016 release, land cover products were created for two-to-three-year intervals between 2001 and the most recent year. These products provide spatially explicit and reliable information on the Nation?s land cover and land cover change. NLCD continues to provide innovative, consistent, and robust methodologies for production of a multi-temporal land cover and land cover change database. The NLCD 2021 release is update based, so the Land Cover and Impervious Surface products�released in�2019 are unchanged and used directly with NLCD 2021 for change analysis though the NLCD timespan.�Science products and the change index are updated and will need to be reacquired to contain the additional 2021 change. These new products use a streamlined compositing process for assembling and preprocessing Landsat imagery and geospatial ancillary datasets; a temporally, spectrally, and spatially integrated land cover change analysis strategy; a theme-based post-classification protocol for generating land cover and change products; a continuous fields biophysical parameters modeling method; and a scripted operational system. The overall accuracy of the 2019 Level I land cover was 91\%. Results from this study confirm the robustness of this comprehensive and highly automated procedure for NLCD 2021 operational mapping (see https://doi.org/10.1080/15481603.2023.2181143 for the latest accuracy assessment publication). Questions about the NLCD 2021 land cover product can be directed to the NLCD 2021 land cover mapping team at USGS EROS, Sioux Falls, SD (605) 594-6151 or mrlc@usgs.gov. See included spatial metadata for more details. Please see�National Land Cover Database (NLCD) 2019 Products (ver. 2.0, June 2021) - ScienceBase-Catalog�for the 2019 release of NLCD which is used with the 2021 release for comparisons through the years.� Also refer to the larger NLCD Community page for all things NLCD related�National Land Cover Database (NLCD) - ScienceBase-Catalog.�}, + urldate = {2024-06-24}, + publisher = {U.S. Geological Survey}, + author = {Dewitz, Jon}, + year = {2023}, + keywords = {Land Use Change}, +} + +@article{mesinger_north_2006, + title = {North {American} {Regional} {Reanalysis}}, + volume = {87}, + issn = {0003-0007, 1520-0477}, + url = {https://journals.ametsoc.org/doi/10.1175/BAMS-87-3-343}, + doi = {10.1175/BAMS-87-3-343}, + language = {en}, + number = {3}, + urldate = {2024-06-24}, + journal = {Bulletin of the American Meteorological Society}, + author = {Mesinger, Fedor and DiMego, Geoff and Kalnay, Eugenia and Mitchell, Kenneth and Shafran, Perry C. and Ebisuzaki, Wesley and Jović, Dušan and Woollen, Jack and Rogers, Eric and Berbery, Ernesto H. and Ek, Michael B. and Fan, Yun and Grumbine, Robert and Higgins, Wayne and Li, Hong and Lin, Ying and Manikin, Geoff and Parrish, David and Shi, Wei}, + month = mar, + year = {2006}, + pages = {343--360} +} + +@techreport{danielson_global_2011, + type = {Open-{File} {Report}}, + title = {Global multi-resolution terrain elevation data 2010 ({GMTED2010})}, + url = {https://doi.org/10.3133/ofr20111073}, + language = {en}, + number = {2011-1073}, + institution = {U.S. Geological Survey}, + author = {Danielson, Jeffrey J. and Gesch, Dean B.}, + year = {2011}, + note = {Series: Open-File Report}, + pages = {iv, 23 p.; Appendix}, +} + + +@article{keller_description_2021, + title = {Description of the {NASA} {GEOS} {Composition} {Forecast} {Modeling} {System} {GEOS}‐{CF} v1.0}, + volume = {13}, + issn = {1942-2466, 1942-2466}, + url = {https://agupubs.onlinelibrary.wiley.com/doi/10.1029/2020MS002413}, + doi = {10.1029/2020MS002413}, + abstract = {Abstract + + The Goddard Earth Observing System composition forecast (GEOS‐CF) system is a high‐resolution (0.25°) global constituent prediction system from NASA's Global Modeling and Assimilation Office (GMAO). GEOS‐CF offers a new tool for atmospheric chemistry research, with the goal to supplement NASA's broad range of space‐based and in‐situ observations. GEOS‐CF expands on the GEOS weather and aerosol modeling system by introducing the GEOS‐Chem chemistry module to provide hindcasts and 5‐days forecasts of atmospheric constituents including ozone (O + 3 + ), carbon monoxide (CO), nitrogen dioxide (NO + 2 + ), sulfur dioxide (SO + 2 + ), and fine particulate matter (PM + 2.5 + ). The chemistry module integrated in GEOS‐CF is identical to the offline GEOS‐Chem model and readily benefits from the innovations provided by the GEOS‐Chem community. Evaluation of GEOS‐CF against satellite, ozonesonde and surface observations for years 2018–2019 show realistic simulated concentrations of O + 3 + , NO + 2 + , and CO, with normalized mean biases of −0.1 to 0.3, normalized root mean square errors between 0.1–0.4, and correlations between 0.3–0.8. Comparisons against surface observations highlight the successful representation of air pollutants in many regions of the world and during all seasons, yet also highlight current limitations, such as a global high bias in SO + 2 + and an overprediction of summertime O + 3 + over the Southeast United States. GEOS‐CF v1.0 generally overestimates aerosols by 20\%–50\% due to known issues in GEOS‐Chem v12.0.1 that have been addressed in later versions. The 5‐days forecasts have skill scores comparable to the 1‐day hindcast. Model skills can be improved significantly by applying a bias‐correction to the surface model output using a machine‐learning approach. + + , + Plain Language Summary + + Accurate forecasting of the compostion of the atmosphere is important for a variety of applications, including air pollution mitigation, support of satellite and other remote‐sensing observations, and research applications. Producing such forecasts is computationally expensive due to the complexity of atmospheric chemistry, which interacts with weather on all scales. Here we present the NASA Goddard Earth Observing System composition forecast (GEOS‐CF) system, which produces global forecasts of major atmospheric constituents such as ozone (O + 3 + ), nitrogen dioxide (NO + 2 + ), and fine particulate matter (PM + 2.5 + ). On a daily basis, the model tracks the atmospheric concentrations of more than 250 chemical species in more than 55 million model grid cells, computing the interactions between those species using the state‐of‐the‐science GEOS‐Chem chemistry model. We present an in‐depth evaluation of the GEOS‐CF model through comparison against independent observations. We show how the model captures many observed features of atmospheric composition, such as spatio‐temporal variations in air pollution due to changes in pollutant emissions, weather, and chemistry. We also highlight some of the model deficiencies, for example, with respect to the simulation of aerosol particles. Finally, we demonstrate how surface observations and model data can be combined using machine learning to provide improved local air quality forecasts. + + , + Key Points + + + + + GEOS‐CF is a new modeling system that produces global forecasts of atmospheric composition at 25 km + 2 + horizontal resolution + + + + GEOS‐CF model output is freely available and offers a new tool for academic researchers, air quality managers, and the public}, + language = {en}, + number = {4}, + urldate = {2024-06-24}, + journal = {Journal of Advances in Modeling Earth Systems}, + author = {Keller, Christoph A. and Knowland, K. Emma and Duncan, Bryan N. and Liu, Junhua and Anderson, Daniel C. and Das, Sampa and Lucchesi, Robert A. and Lundgren, Elizabeth W. and Nicely, Julie M. and Nielsen, Eric and Ott, Lesley E. and Saunders, Emily and Strode, Sarah A. and Wales, Pamela A. and Jacob, Daniel J. and Pawson, Steven}, + month = apr, + year = {2021}, + pages = {e2020MS002413}, +} + +# Figure 1 icons +@misc{Freepik_Cloud, + author = {Freepik}, + title = {Cloud icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/cloud}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_Heat, + author = {Freepik}, + title = {Heat icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/heat}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_Snowstorm, + author = {Freepik}, + title = {Snowstorm icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/snowstorm}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_Forest, + author = {Freepik}, + title = {Forest icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/forest}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_CO2, + author = {Freepik}, + title = {Co2 icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/co2}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_Download, + author = {Freepik}, + title = {Download icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/download}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_Database, + author = {Freepik}, + title = {Database icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/database}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_GIS, + author = {Freepik}, + title = {Gis icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/gis}}, + note = {Accessed: 2024-07-10} +} + +@misc{Freepik_Excel, + author = {Freepik}, + title = {Excel icons}, + howpublished = {\url{https://www.flaticon.com/free-icons/excel}}, + note = {Accessed: 2024-07-10} +} \ No newline at end of file diff --git a/man/apply_extent.Rd b/man/apply_extent.Rd new file mode 100644 index 00000000..68a99b96 --- /dev/null +++ b/man/apply_extent.Rd @@ -0,0 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/process_auxiliary.R +\name{apply_extent} +\alias{apply_extent} +\title{Apply extent to the processed data} +\usage{ +apply_extent(data, extent, geom) +} +\arguments{ +\item{data}{sf/terra object.} + +\item{extent}{numeric(4). Extent to filter the data. +Should be ordered as c(xmin, xmax, ymin, ymax).} + +\item{geom}{character(1 or 2). Geometry type for if \code{data} is \code{data.frame}. +One of "geometry" or c("lon", "lat").} +} +\value{ +sf/terra object with the extent applied. +} +\description{ +User-defined extent is used to filter the data. +} +\keyword{internal} diff --git a/man/calc_covariates.Rd b/man/calc_covariates.Rd index 189b8251..d71cc83e 100644 --- a/man/calc_covariates.Rd +++ b/man/calc_covariates.Rd @@ -7,8 +7,8 @@ calc_covariates( covariate = c("modis", "koppen-geiger", "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "sedac_groads", "groads", "roads", "ecoregions", "ecoregion", - "hms", "noaa", "smoke", "gmted", "narr", "geos", "sedac_population", "population", - "nlcd", "merra", "merra2", "gridmet", "terraclimate", "tri", "nei"), + "hms", "smoke", "gmted", "narr", "geos", "sedac_population", "population", "nlcd", + "merra", "merra2", "gridmet", "terraclimate", "tri", "nei"), from, locs, locs_id = "site_id", @@ -30,7 +30,7 @@ Default is \code{"site_id"}.} function.} } \value{ -Calculated covariates. Mainly data.frame object. +Calculated covariates as a data.frame or SpatVector object } \description{ The \code{calculate_covariates()} function extracts values at point @@ -44,13 +44,25 @@ SpatRaster or SpatVector objects before passing to \note{ \code{covariate} argument value is converted to lowercase. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_covariates( + covariate = "narr", + from = narr, # derived from process_covariates() example + locs = loc, + locs_id = "id", + geom = FALSE +) +} +} \seealso{ \itemize{ \item \code{\link{calc_modis_par}}: \code{"modis"}, \code{"MODIS"} \item \code{\link{calc_koppen_geiger}}: \code{"koppen-geiger"}, \code{"koeppen-geiger"}, \code{"koppen"} \item \code{\link{calc_ecoregion}}: \code{"ecoregion"}, \code{"ecoregions"} \item -\item \code{\link{calc_hms}}: \code{"hms"}, \code{"noaa"}, \code{"smoke"} +\item \code{\link{calc_hms}}: \code{"hms"}, \code{"smoke"} \item \item \item \code{\link{calc_geos}}: \code{"geos"}, \code{"geos_cf"} diff --git a/man/calc_ecoregion.Rd b/man/calc_ecoregion.Rd index 21d14855..65930eff 100644 --- a/man/calc_ecoregion.Rd +++ b/man/calc_ecoregion.Rd @@ -14,17 +14,15 @@ a unique identifier field named \code{locs_id}} \item{locs_id}{character(1). Name of unique identifier.} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object with dummy variables and attributes of: +a data.frame or SpatVector object object with dummy variables and +attributes of: \itemize{ \item \code{attr(., "ecoregion2_code")}: Ecoregion lv.2 code and key \item \code{attr(., "ecoregion3_code")}: Ecoregion lv.3 code and key @@ -36,6 +34,17 @@ locations. Returns a \code{data.frame} object containing \code{locs_id} and binary (0 = point not in ecoregion; 1 = point in ecoregion) variables for each ecoregion. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_ecoregion( + from = ecoregion, # derived from process_ecoregion() example + locs = loc, + locs_id = "id", + geom = FALSE +) +} +} \seealso{ \code{\link{process_ecoregion}} } diff --git a/man/calc_geos.Rd b/man/calc_geos.Rd index 804fc856..cf2c6844 100644 --- a/man/calc_geos.Rd +++ b/man/calc_geos.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract atmospheric composition values at point locations. Returns a @@ -47,6 +44,19 @@ pressure level, and atmospheric composition variable. Atmospheric composition variable column name reflects variable and circular buffer radius. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_geos( + from = geos, # derived from process_geos() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link[=process_geos]{process_geos()}} } diff --git a/man/calc_gmted.Rd b/man/calc_gmted.Rd index 58c19e32..b9ae2523 100644 --- a/man/calc_gmted.Rd +++ b/man/calc_gmted.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract elevation values at point locations. Returns a \code{data.frame} @@ -47,6 +44,19 @@ Elevation variable column name reflects the elevation statistic, spatial resolution of \code{from}, and circular buffer radius (ie. Breakline Emphasis at 7.5 arc-second resolution with 0 meter buffer: breakline_emphasis_r75_0). } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_gmted( + from = gmted, # derived from process_gmted() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link[=process_gmted]{process_gmted()}} } diff --git a/man/calc_gridmet.Rd b/man/calc_gridmet.Rd index 2a28b10a..9dcfa1d2 100644 --- a/man/calc_gridmet.Rd +++ b/man/calc_gridmet.Rd @@ -28,23 +28,33 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract gridMET values at point locations. Returns a \code{data.frame} object containing \code{locs_id} and gridMET variable. gridMET variable column name reflects the gridMET variable and circular buffer radius. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_gridmet( + from = gridmet, # derived from process_gridmet() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link[=process_gridmet]{process_gridmet()}} } diff --git a/man/calc_hms.Rd b/man/calc_hms.Rd index f1fc2588..b82d116e 100644 --- a/man/calc_hms.Rd +++ b/man/calc_hms.Rd @@ -4,7 +4,7 @@ \alias{calc_hms} \title{Calculate wildfire smoke covariates} \usage{ -calc_hms(from, locs, locs_id = NULL, radius = 0, ...) +calc_hms(from, locs, locs_id = NULL, radius = 0, geom = FALSE, ...) } \arguments{ \item{from}{SpatVector(1). Output of \code{process_hms()}.} @@ -17,10 +17,14 @@ containing identifier for each unique coordinate location.} \item{radius}{integer(1). Circular buffer distance around site locations. (Default = 0).} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} + \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract wildfire smoke plume values at point locations. Returns a @@ -28,6 +32,18 @@ Extract wildfire smoke plume values at point locations. Returns a for wildfire smoke plume density inherited from \code{from} (0 = point not covered by wildfire smoke plume; 1 = point covered by wildfire smoke plume). } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_hms( + from = hms, # derived from process_hms() example + locs = loc, + locs_id = "id", + radius = 0, + geom = FALSE +) +} +} \seealso{ \code{\link[=process_hms]{process_hms()}} } diff --git a/man/calc_koppen_geiger.Rd b/man/calc_koppen_geiger.Rd index 23b08083..101ced2d 100644 --- a/man/calc_koppen_geiger.Rd +++ b/man/calc_koppen_geiger.Rd @@ -20,17 +20,14 @@ a unique identifier field named \code{locs_id}} \item{locs_id}{character(1). Name of unique identifier.} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract climate classification values at point locations. Returns a @@ -39,11 +36,22 @@ binary (0 = point not in climate region; 1 = point in climate region) variables for each climate classification region. } \note{ -The returned \code{data.frame} object contains a +The returned object contains a \verb{$description} column to represent the temporal range covered by the dataset. For more information, see \url{https://www.nature.com/articles/sdata2018214}. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_koppen_geiger( + from = kg, # derived from process_koppen_geiger() example + locs = loc, + locs_id = "id", + geom = FALSE +) +} +} \seealso{ \code{\link{process_koppen_geiger}} } diff --git a/man/calc_lagged.Rd b/man/calc_lagged.Rd index b067859b..546bf974 100644 --- a/man/calc_lagged.Rd +++ b/man/calc_lagged.Rd @@ -4,7 +4,7 @@ \alias{calc_lagged} \title{Calculate temporally lagged covariates} \usage{ -calc_lagged(from, date, lag, locs_id, time_id = "time") +calc_lagged(from, date, lag, locs_id, time_id = "time", geom = FALSE) } \arguments{ \item{from}{data.frame(1). A \code{data.frame} containing calculated covariates @@ -18,6 +18,10 @@ Length of 10 each, format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01").} \item{locs_id}{character(1). Name of unique identifier.} \item{time_id}{character(1). Column containing time values.} + +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.} To return as a \code{SpatVector}, \code{from} must also be a \code{SpatVector}} } \value{ a \code{data.frame} object @@ -37,6 +41,26 @@ with geometry features of the same name. \code{locs_id}, and fixed columns of "lat" and "lon", follow the genre, variable, lag, buffer radius format adopted in \code{calc_setcolumns()}. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +terracliamte_covar <- calc_terraclimate( + from = terraclimate, # derived from process_terraclimate() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +calc_lagged( + from = terracliamte_covar, + locs_id = "id", + date = c("2023-01-02", "2023-01-10"), + lag = 1, + time_id = "time" +) +} +} \seealso{ \code{\link[=calc_covariates]{calc_covariates()}} } diff --git a/man/calc_merra2.Rd b/man/calc_merra2.Rd index 9a8e86ff..87a09842 100644 --- a/man/calc_merra2.Rd +++ b/man/calc_merra2.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract meteorological and atmospheric values at point locations. Returns a @@ -46,6 +43,19 @@ Extract meteorological and atmospheric values at point locations. Returns a pressure level, and meteorological or atmospheric variable. Variable column name reflects variable and circular buffer radius. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_merra2( + from = merra2, # derived from process_merra2() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link[=calc_geos]{calc_geos()}}, \code{\link[=process_merra2]{process_merra2()}} } diff --git a/man/calc_modis_daily.Rd b/man/calc_modis_daily.Rd index d92e1532..6c62dcf7 100644 --- a/man/calc_modis_daily.Rd +++ b/man/calc_modis_daily.Rd @@ -13,6 +13,7 @@ calc_modis_daily( name_extracted = NULL, fun_summary = "mean", max_cells = 3e+07, + geom = FALSE, ... ) } @@ -37,13 +38,17 @@ for details.} \item{max_cells}{integer(1). Maximum number of cells to be read at once. Higher values will expedite processing, but will increase memory usage. -Maximum possible value is \code{2^31 - 1}. +Maximum possible value is \code{2^31 - 1}.} + +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.} See \code{\link[exactextractr:exact_extract]{exactextractr::exact_extract}} for details.} \item{...}{Placeholders.} } \value{ -A data.frame object. +a data.frame or SpatVector object. } \description{ The function operates at MODIS/VIIRS products @@ -55,10 +60,25 @@ Please note that this function does not provide a function to filter swaths or tiles, so it is strongly recommended to check and pre-filter the file names at users' discretion. } +\examples{ +\dontrun{ +locs <- data.frame(lon = -78.8277, lat = 35.95013, id = "001") +calc_modis_daily( + from = mod06l2_warp, + locs = locs, + locs_id = "id", + radius = 0, + date = "2024-01-01", + name_extracted = "cloud_fraction_0", + fun_summary = "mean", + max_cells = 3e7 +) +} +} \seealso{ \itemize{ \item Preprocessing: \code{\link[=process_modis_merge]{process_modis_merge()}}, \code{\link[=process_modis_swath]{process_modis_swath()}}, -\code{\link[=process_bluemarble]{process_bluemarble()}} +\code{\link[=process_blackmarble]{process_blackmarble()}} \item Parallelization: \code{\link[=calc_modis_par]{calc_modis_par()}} } } diff --git a/man/calc_modis_par.Rd b/man/calc_modis_par.Rd index 1cf02d19..6531420b 100644 --- a/man/calc_modis_par.Rd +++ b/man/calc_modis_par.Rd @@ -17,6 +17,7 @@ calc_modis_par( package_list_add = NULL, export_list_add = NULL, max_cells = 3e+07, + geom = FALSE, ... ) } @@ -36,7 +37,7 @@ Default is \code{c(0, 1000, 10000, 50000)}.} \item{name_covariates}{character. Name header of covariates. e.g., \code{"MOD_NDVIF_0_"}. The calculated covariate names will have a form of -'{name_covariates}{zero-padded buffer radius in meters}', +"\code{\{name_covariates\}\{zero-padded buffer radius in meters\}}", e.g., 'MOD_NDVIF_0_50000' where 50 km radius circular buffer was used to calculate mean NDVI value.} @@ -62,10 +63,14 @@ Higher values will expedite processing, but will increase memory usage. Maximum possible value is \code{2^31 - 1}. See \code{\link[exactextractr:exact_extract]{exactextractr::exact_extract}} for details.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} + \item{...}{Arguments passed to \code{preprocess}.} } \value{ -A data.frame with an attribute: +A data.frame or SpatVector with an attribute: \itemize{ \item \code{attr(., "dates_dropped")}: Dates with insufficient tiles. Note that the dates mean the dates with insufficient tiles, @@ -100,7 +105,7 @@ depending on \code{preprocess} function: e.g., \code{"^LST_"} \item \code{process_modis_swath()}: Subdataset names. e.g., \code{c("Cloud_Fraction_Day", "Cloud_Fraction_Night")} -\item \code{process_bluemarble()}: Subdataset number. +\item \code{process_blackmarble()}: Subdataset number. e.g., for VNP46A2 product, 3L. Dates with less than 80 percent of the expected number of tiles, which are determined by the mode of the number of tiles, are removed. @@ -109,6 +114,24 @@ The result data.frame will have an attribute with the dates with insufficient tiles. } } +\examples{ +\dontrun{ +locs <- data.frame(lon = -78.8277, lat = 35.95013, id = "001") +locs <- terra::vect(locs, geom = c("lon", "lat"), crs = "EPSG:4326") +calc_modis_par( + from = + list.files("./data", pattern = "VNP46A2.", full.names = TRUE), + locs = locs, + locs_id = "site_id", + radius = c(0L, 1000L), + preprocess = process_modis_merge, + name_covariates = "cloud_fraction_0", + subdataset = "Cloud_Fraction", + fun_summary = "mean", + nthreads = 1 +) +} +} \seealso{ See details for setting parallelization: \itemize{ @@ -128,6 +151,6 @@ Also, for preprocessing, please refer to: \itemize{ \item \code{\link[=process_modis_merge]{process_modis_merge()}} \item \code{\link[=process_modis_swath]{process_modis_swath()}} -\item \code{\link[=process_bluemarble]{process_bluemarble()}} +\item \code{\link[=process_blackmarble]{process_blackmarble()}} } } diff --git a/man/calc_narr.Rd b/man/calc_narr.Rd index ae6701b6..67c6d665 100644 --- a/man/calc_narr.Rd +++ b/man/calc_narr.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract meteorological values at point locations. Returns a \code{data.frame} @@ -46,6 +43,19 @@ object containing \code{locs_id}, date, vertical pressure level, and meteorological variable. Meteorological variable column name reflects variable and circular buffer radius. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_narr( + from = narr, # derived from process_narr() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link{process_narr}} } diff --git a/man/calc_nei.Rd b/man/calc_nei.Rd index f66e6113..8a749c86 100644 --- a/man/calc_nei.Rd +++ b/man/calc_nei.Rd @@ -4,7 +4,7 @@ \alias{calc_nei} \title{Calculate road emissions covariates} \usage{ -calc_nei(from = NULL, locs = NULL, locs_id = "site_id", ...) +calc_nei(from = NULL, locs = NULL, locs_id = "site_id", geom = FALSE, ...) } \arguments{ \item{from}{SpatVector(1). Output of \code{process_nei()}.} @@ -14,14 +14,28 @@ calc_nei(from = NULL, locs = NULL, locs_id = "site_id", ...) \item{locs_id}{character(1). Unique site identifier column name. Unused but kept for compatibility.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} + \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Calculate road emissions covariates } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_nei( + from = nei, # derived from process_nei example, + locs = loc, + locs_id = "id" +) +} +} \seealso{ \code{\link{process_nei}} } diff --git a/man/calc_nlcd.Rd b/man/calc_nlcd.Rd index 237a6bc3..321ab858 100644 --- a/man/calc_nlcd.Rd +++ b/man/calc_nlcd.Rd @@ -36,19 +36,16 @@ Maximum possible value is \code{2^31 - 1}. Only valid when \code{mode = "exact"}. See \code{\link[exactextractr:exact_extract]{exactextractr::exact_extract}} for details.} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{nthreads}{integer(1). Number of threads to be used} \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Compute ratio of land cover class in circle buffers around points. Returns @@ -64,6 +61,18 @@ intersecting with the buffer. The \code{"exact"} may be more accurate but uses more memory as it will account for the partial overlap with the buffer. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_nlcd( + from = nlcd, # derived from process_nlcd() example + locs = loc, + locs_id = "id", + mode = "exact", + geom = FALSE +) +} +} \seealso{ \code{\link{process_nlcd}} } diff --git a/man/calc_return_locs.Rd b/man/calc_return_locs.Rd new file mode 100644 index 00000000..5a01955b --- /dev/null +++ b/man/calc_return_locs.Rd @@ -0,0 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/calculate_covariates_auxiliary.R +\name{calc_return_locs} +\alias{calc_return_locs} +\title{Prepare covariates for return} +\usage{ +calc_return_locs(covar, POSIXt = TRUE, geom, crs) +} +\arguments{ +\item{covar}{data.frame(1). Calculated covariates \code{data.frame}.} + +\item{POSIXt}{logical(1). Should the time values in \code{covar} be of class +\code{POSIXt}? If \code{FALSE}, the time values will be checked for integer class +(year and year-month).} + +\item{geom}{logical(1). Should \code{covar} be returned as a +\code{data.frame}? Default is \code{FALSE}.} + +\item{crs}{terra::crs(1). Coordinate reference system (inherited from +\code{from}).} +} +\description{ +Check the time column for proper class and, if \code{geom = TRUE}, +transform \code{data.frame} into a \code{SpatVector} object. +} +\author{ +Mitchell Manware +} +\keyword{auxiliary} diff --git a/man/calc_sedac_groads.Rd b/man/calc_sedac_groads.Rd index 2d23b4f2..e2332317 100644 --- a/man/calc_sedac_groads.Rd +++ b/man/calc_sedac_groads.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{function(1). Function used to summarize the length of roads within sites location buffer (Default is \code{sum}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object with three columns. +a data.frame or SpatVector object } \description{ Prepared groads data is clipped with the buffer polygons @@ -52,6 +49,19 @@ Unit is km / sq km. The returned \code{data.frame} object contains a \verb{$time} column to represent the temporal range covered by the dataset. For more information, see \url{https://sedac.ciesin.columbia.edu/data/set/groads-global-roads-open-access-v1/metadata}. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_sedac_groads( + from = groads, # derived from process_sedac_groads() example + locs = loc, + locs_id = "id", + radius = 1000, + fun = "sum", + geom = FALSE +) +} +} \seealso{ \code{\link{process_sedac_groads}} } diff --git a/man/calc_sedac_population.Rd b/man/calc_sedac_population.Rd index 764b42a3..193792e4 100644 --- a/man/calc_sedac_population.Rd +++ b/man/calc_sedac_population.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract population density values at point locations. Returns a @@ -46,6 +43,19 @@ Extract population density values at point locations. Returns a density variable. Population density variable column name reflects spatial resolution of \code{from} and circular buffer radius. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_sedac_population( + from = pop, # derived from process_sedac_population() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link[=process_sedac_population]{process_sedac_population()}} } diff --git a/man/calc_sedc.Rd b/man/calc_sedc.Rd index 638172ba..b34855d7 100644 --- a/man/calc_sedc.Rd +++ b/man/calc_sedc.Rd @@ -9,7 +9,8 @@ calc_sedc( locs = NULL, locs_id = NULL, sedc_bandwidth = NULL, - target_fields = NULL + target_fields = NULL, + geom = FALSE ) } \arguments{ @@ -25,9 +26,13 @@ Distance at which the source concentration is reduced to \code{exp(-3)} (approximately -95 \%)} \item{target_fields}{character(varying). Field names in characters.} + +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} } \value{ -a data.frame (tibble) object with input field names with +a data.frame (tibble) or SpatVector object with input field names with a suffix \code{"_sedc"} where the sums of EDC are stored. Additional attributes are attached for the EDC information. \itemize{ diff --git a/man/calc_setcolumns.Rd b/man/calc_setcolumns.Rd index 449abd50..a86a9cc6 100644 --- a/man/calc_setcolumns.Rd +++ b/man/calc_setcolumns.Rd @@ -7,8 +7,9 @@ calc_setcolumns(from, lag, dataset, locs_id) } \arguments{ -\item{from}{data.frame(1). Calculated covariates as returned from -\code{calc_covariates()} or a source specific covariate function.} +\item{from}{data.frame(1) or SpatVector(1). Calculated covariates as +returned from \code{calc_covariates()} or a source specific covariate +function.} \item{lag}{integer(1). Temporal lag.} diff --git a/man/calc_temporal_dummies.Rd b/man/calc_temporal_dummies.Rd index f786829d..93a3a8e2 100644 --- a/man/calc_temporal_dummies.Rd +++ b/man/calc_temporal_dummies.Rd @@ -4,7 +4,13 @@ \alias{calc_temporal_dummies} \title{Calculate temporal dummy covariates} \usage{ -calc_temporal_dummies(locs, locs_id = "site_id", year = seq(2018L, 2022L), ...) +calc_temporal_dummies( + locs, + locs_id = "site_id", + year = seq(2018L, 2022L), + geom = FALSE, + ... +) } \arguments{ \item{locs}{data.frame with a temporal field named \code{"time"}} @@ -13,18 +19,32 @@ calc_temporal_dummies(locs, locs_id = "site_id", year = seq(2018L, 2022L), ...) Default is \code{"site_id"}.} \item{year}{integer. Year domain to dummify. -Default is \code{seq(2018L, 2022L)}} +Default is \code{seq(2018L, 2022L)}.} + +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Calculate temporal dummy covariates at point locations. Returns a \code{data.frame} object with \code{locs_id}, year binary variable for each value in \code{year}, and month and day of week binary variables. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_temporal_dummies( + locs = loc, + locs_id = "id", + year = seq(2018L, 2022L) +) +} +} \author{ Insang Song } diff --git a/man/calc_terraclimate.Rd b/man/calc_terraclimate.Rd index 4f97714d..c038ae7f 100644 --- a/man/calc_terraclimate.Rd +++ b/man/calc_terraclimate.Rd @@ -28,17 +28,14 @@ containing identifier for each unique coordinate location.} \item{fun}{character(1). Function used to summarize multiple raster cells within sites location buffer (Default = \code{mean}).} -\item{geom}{logical(1). Should the geometry of \code{locs} be returned in the -\code{data.frame}? Default is \code{FALSE}. If \code{geom = TRUE} and \code{locs} contain -polygon geometries, the \verb{$geometry} column in the returned data frame may -make the \code{data.frame} difficult to read due to long geometry strings. The -coordinate reference system of the \verb{$geometry} is the coordinate -reference system of \code{from}.} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract TerraClimate values at point locations. Returns a \code{data.frame} @@ -51,6 +48,19 @@ TerraClimate data has monthly temporal resolution, so the \verb{$time} column will contain the year and month in YYYYMM format (ie. January, 2018 = 201801). } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_terraclimate( + from = terraclimate, # derived from process_terraclimate() example + locs = loc, + locs_id = "id", + radius = 0, + fun = "mean", + geom = FALSE +) +} +} \seealso{ \code{\link[=process_terraclimate]{process_terraclimate()}} } diff --git a/man/calc_tri.Rd b/man/calc_tri.Rd index 9395eadd..977c99fe 100644 --- a/man/calc_tri.Rd +++ b/man/calc_tri.Rd @@ -9,6 +9,7 @@ calc_tri( locs, locs_id = "site_id", radius = c(1000L, 10000L, 50000L), + geom = FALSE, ... ) } @@ -23,10 +24,14 @@ Default is \code{"site_id"}.} \item{radius}{Circular buffer radius. Default is \code{c(1000, 10000, 50000)} (meters)} +\item{geom}{logical(1). Should the function return a \code{SpatVector}? +Default is \code{FALSE}. The coordinate reference system of the \code{SpatVector} is +that of \code{from.}} + \item{...}{Placeholders.} } \value{ -a data.frame object +a data.frame or SpatVector object } \description{ Extract toxic release values at point locations. Returns a \code{data.frame} @@ -36,6 +41,17 @@ object containing \code{locs_id} and variables for each chemical in \note{ U.S. context. } +\examples{ +\dontrun{ +loc <- data.frame(id = "001", lon = -78.90, lat = 35.97) +calc_tri( + from = tri, # derived from process_tri() example + locs = loc, + locs_id = "id", + radius = c(1e3L, 1e4L, 5e4L) +) +} +} \seealso{ \code{\link{calc_sedc}}, \code{\link{process_tri}} } diff --git a/man/download_aqs.Rd b/man/download_aqs.Rd index 22500b67..6fda80ed 100644 --- a/man/download_aqs.Rd +++ b/man/download_aqs.Rd @@ -7,8 +7,7 @@ download_aqs( parameter_code = 88101, resolution_temporal = "daily", - year_start = 2018, - year_end = 2022, + year = c(2018, 2022), url_aqs_download = "https://aqs.epa.gov/aqsweb/airdata/", directory_to_save = NULL, acknowledgement = FALSE, @@ -27,11 +26,7 @@ EPA pollutant parameter code. For details, please refer to Name of column containing POC values. Currently, no value other than \code{"daily"} works.} -\item{year_start}{integer(1). length of 4. -Start year for downloading data.} - -\item{year_end}{integer(1). length of 4. -End year for downloading data.} +\item{year}{character(2). length of 4 each. Start/end years for downloading data.} \item{url_aqs_download}{character(1). URL to the AQS pre-generated datasets.} @@ -64,6 +59,22 @@ NULL; Zip and/or data files will be downloaded and stored in \description{ The \code{download_aqs()} function accesses and downloads Air Quality System (AQS) data from the \href{https://aqs.epa.gov/aqsweb/airdata/download_files.html}{U.S. Environmental Protection Agency's (EPA) Pre-Generated Data Files}. } +\examples{ +\dontrun{ +download_aqs( + parameter_code = 88101, + resolution_temporal = "daily", + year = c(2022, 2023), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{data_usepa2023airdata}{amadeus} +} \author{ Mariana Kassien, Insang Song, Mitchell Manware } diff --git a/man/download_cropscape.Rd b/man/download_cropscape.Rd index 82b6e0fa..88f56aac 100644 --- a/man/download_cropscape.Rd +++ b/man/download_cropscape.Rd @@ -56,10 +56,12 @@ JSON files should be found at STAC catalog of OpenLandMap \examples{ \dontrun{ download_cropscape( - 2020, "~/data", + year = 2020, + source = "USDA", + directory_to_save = "./data", acknowledgement = TRUE, download = TRUE, - unzip = TRUE + remove_command = TRUE ) } } diff --git a/man/download_data.Rd b/man/download_data.Rd index d7da4c3e..59285b77 100644 --- a/man/download_data.Rd +++ b/man/download_data.Rd @@ -6,9 +6,8 @@ \usage{ download_data( dataset_name = c("aqs", "ecoregion", "ecoregions", "geos", "gmted", "koppen", - "koppengeiger", "merra2", "merra", "narr_monolevel", "modis", "narr_p_levels", - "nlcd", "noaa", "sedac_groads", "sedac_population", "groads", "population", - "plevels", "p_levels", "monolevel", "hms", "smoke", "tri", "nei", "gridmet", + "koppengeiger", "merra2", "merra", "modis", "narr", "nlcd", "noaa", "sedac_groads", + "sedac_population", "groads", "population", "hms", "smoke", "tri", "nei", "gridmet", "terraclimate", "huc", "cropscape", "cdl", "prism", "olm", "openlandmap"), directory_to_save = NULL, acknowledgement = FALSE, @@ -35,6 +34,19 @@ The \code{download_data()} function accesses and downloads atmospheric, meteorol \item All download function names are in \code{download_*} formats } } +\examples{ +\dontrun{ +download_data( + dataset_name = "narr", + variables = "weasd", + year = c(2023, 2023), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_commands = TRUE +) +} +} \seealso{ For details of each download function per dataset, Please refer to: @@ -45,9 +57,7 @@ Please refer to: \item \code{\link{download_gmted}}: \code{"gmted"}, \code{"GMTED"} \item \code{\link{download_koppen_geiger}}: \code{"koppen"}, \code{"koppengeiger"} \item \code{\link{download_merra2}}: "merra2", \code{"merra"}, \code{"MERRA"}, \code{"MERRA2"} -\item \code{\link{download_narr_monolevel}}: \code{"narr_monolevel"}, \code{"monolevel"} -\item \code{\link{download_narr_p_levels}}: \code{"narr_p_levels"}, \code{"p_levels"}, -\code{"plevels"} +\item \code{\link{download_narr}}: \code{"narr"} \item \code{\link{download_nlcd}}: \code{"nlcd"}, \code{"NLCD"} \item \code{\link{download_hms}}: \code{"noaa"}, \code{"smoke"}, \code{"hms"} \item \code{\link{download_sedac_groads}}: \code{"sedac_groads"}, \code{"groads"} diff --git a/man/download_ecoregion.Rd b/man/download_ecoregion.Rd index bd7d71d0..e73adbe1 100644 --- a/man/download_ecoregion.Rd +++ b/man/download_ecoregion.Rd @@ -64,6 +64,19 @@ in wget command) file in ./inst/extdata. The instruction above is for certificate updates in the future. } } +\examples{ +\dontrun{ +download_ecoregion( + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{article_omernik2014ecoregions}{amadeus} +} \author{ Insang Song } diff --git a/man/download_geos.Rd b/man/download_geos.Rd index 766cfc67..7c4f06bc 100644 --- a/man/download_geos.Rd +++ b/man/download_geos.Rd @@ -8,8 +8,7 @@ download_geos( collection = c("aqc_tavg_1hr_g1440x721_v1", "chm_tavg_1hr_g1440x721_v1", "met_tavg_1hr_g1440x721_x1", "xgc_tavg_1hr_g1440x721_x1", "chm_inst_1hr_g1440x721_p23", "met_inst_1hr_g1440x721_p23"), - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2018-01-01", "2018-01-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -19,11 +18,8 @@ download_geos( \arguments{ \item{collection}{character(1). GEOS-CF data collection file name.} -\item{date_start}{character(1). length of 10. Start date for downloading -data. Format YYYY-MM-DD (ex. September 1, 2023 = \code{"2023-09-01"}).} - -\item{date_end}{character(1). length of 10. End date for downloading data. -Format YYYY-MM-DD (ex. September 1, 2023 = \code{"2023-09-01"}).} +\item{date}{character(2). length of 10 each. Start/end date for downloading data. +Format "YYYY-MM-DD" (ex. January 1, 2018 = \code{"2018-01-01"}).} \item{directory_to_save}{character(1). Directory to save data. Sub-directories will be created within \code{directory_to_save} for each @@ -49,6 +45,21 @@ collection-specific folder within \code{directory_to_save}. The \code{download_geos()} function accesses and downloads various atmospheric composition collections from \href{https://gmao.gsfc.nasa.gov/GEOS_systems/}{NASA's Global Earth Observing System (GEOS) model}. } +\examples{ +\dontrun{ +download_geos( + collection = "aqc_tavg_1hr_g1440x721_v1", + date = c("2024-01-01", "2024-01-05"), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{keller_description_2021}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_gmted.Rd b/man/download_gmted.Rd index ce6440e6..3b07e148 100644 --- a/man/download_gmted.Rd +++ b/man/download_gmted.Rd @@ -54,6 +54,21 @@ The \code{download_gmted()} function accesses and downloads Global Multi-resolution Terrain Elevation Data (GMTED2010) from \href{https://www.usgs.gov/coastal-changes-and-impacts/gmted2010}{U.S. Geological Survey and National Geospatial-Intelligence Agency}. } +\examples{ +\dontrun{ +download_gmted( + statistic = "Breakline Emphasis", + resolution = "7.5 arc-seconds", + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{danielson_global_2011}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_gridmet.Rd b/man/download_gridmet.Rd index 4ef5c8cc..e3201172 100644 --- a/man/download_gridmet.Rd +++ b/man/download_gridmet.Rd @@ -6,8 +6,7 @@ \usage{ download_gridmet( variables = NULL, - year_start = 2022, - year_end = 2022, + year = c(2018, 2022), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -19,11 +18,7 @@ download_gridmet( for variable names and acronym codes. (Note: variable "Burning Index" has code "bi" and variable "Energy Release Component" has code "erc").} -\item{year_start}{integer(1). length of 4. Start of year range for -downloading data.} - -\item{year_end}{integer(1). length of 4. End of year range for downloading -data.} +\item{year}{character(2). length of 4 each. Start/end years for downloading data.} \item{directory_to_save}{character(1). Directory(s) to save downloaded data files.} @@ -47,6 +42,21 @@ folder within \code{directory_to_save}. \description{ The \code{download_gridmet} function accesses and downloads gridded surface meteorological data from the \href{https://www.climatologylab.org/gridmet.html}{University of California Merced Climatology Lab's gridMET dataset}. } +\examples{ +\dontrun{ +download_gridmet( + variables = "Precipitation", + year = c(2023, 2024), + directory_to_save = "./data" + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{article_abatzoglou2013development}{amadeus} +} \author{ Mitchell Manware } diff --git a/man/download_hms.Rd b/man/download_hms.Rd index 91c8930c..b9ee5a61 100644 --- a/man/download_hms.Rd +++ b/man/download_hms.Rd @@ -6,8 +6,7 @@ \usage{ download_hms( data_format = "Shapefile", - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2018-01-01", "2018-01-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -19,11 +18,7 @@ download_hms( \arguments{ \item{data_format}{character(1). "Shapefile" or "KML".} -\item{date_start}{character(1). length of 10. Start date for downloading -data. Format YYYY-MM-DD (ex. September 1, 2023 is \code{"2023-09-01"}).} - -\item{date_end}{character(1). length of 10. End date for downloading data. -Format YYYY-MM-DD (ex. September 10, 2023 is \code{"2023-09-10"}).} +\item{date}{character(2). length of 10 each. Start/end date for downloading data.} \item{directory_to_save}{character(1). Directory to save data. If \code{data_format = "Shapefile"}, two sub-directories will be created for the @@ -59,6 +54,21 @@ respective sub-directories within \code{directory_to_save}. The \code{download_hms()} function accesses and downloads wildfire smoke plume coverage data from \href{https://www.ospo.noaa.gov/Products/land/hms.html#0}{NOAA's Hazard Mapping System Fire and Smoke Product}. } +\examples{ +\dontrun{ +download_hms( + data_format = "Shapefile", + date = c("2024-01-01", "2024-01-05"), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{web_HMSabout}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_huc.Rd b/man/download_huc.Rd index ec3c2e7e..3b882826 100644 --- a/man/download_huc.Rd +++ b/man/download_huc.Rd @@ -53,11 +53,18 @@ please visit \href{https://www.epa.gov/waterdata/get-nhdplus-national-hydrograph } \examples{ \dontrun{ -download_huc("Lower48", "Seamless", "/data" - acknowledgement = TRUE, - download = TRUE, - unzip = TRUE) +download_huc( + region = "Lower48", + type = "Seamless", + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} } +\references{ +\insertRef{data_usgs2023nhd}{amadeus} } \author{ Insang Song diff --git a/man/download_koppen_geiger.Rd b/man/download_koppen_geiger.Rd index 926cd4f5..a0043815 100644 --- a/man/download_koppen_geiger.Rd +++ b/man/download_koppen_geiger.Rd @@ -55,6 +55,22 @@ climate classification data from the \emph{Present and future Köppen-Geiger climate classification maps at 1-km resolution}(\href{https://www.nature.com/articles/sdata2018214}{link for article}; \href{https://figshare.com/articles/dataset/Present_and_future_K_ppen-Geiger_climate_classification_maps_at_1-km_resolution/6396959/2}{link for data}). } +\examples{ +\dontrun{ +download_koppen_geiger( + data_resolution = "0.0083", + time_period = "Present", + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{article_beck2023koppen}{amadeus} +\insertRef{article_beck2018present}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_merra2.Rd b/man/download_merra2.Rd index 070dc701..921bc93e 100644 --- a/man/download_merra2.Rd +++ b/man/download_merra2.Rd @@ -16,8 +16,7 @@ download_merra2( "tavg3_3d_mst_Np", "tavg3_3d_rad_Np", "tavg3_3d_tdt_Np", "tavg3_3d_trb_Np", "tavg3_3d_udt_Np", "tavg3_3d_odt_Np", "tavg3_3d_qdt_Np", "tavg3_3d_asm_Nv", "tavg3_3d_cld_Nv", "tavg3_3d_mst_Nv", "tavg3_3d_rad_Nv", "tavg3_2d_glc_Nx"), - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2018-01-01", "2018-01-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -27,11 +26,8 @@ download_merra2( \arguments{ \item{collection}{character(1). MERRA-2 data collection file name.} -\item{date_start}{character(1). length of 10. Start date for downloading -data. Format YYYY-MM-DD (ex. September 1, 2023 is \code{"2023-09-01"}).} - -\item{date_end}{character(1). length of 10. End date for downloading data. -Format YYYY-MM-DD (ex. September 1, 2023 is \code{"2023-09-01"}).} +\item{date}{character(2). length of 10 each. Start/end date for downloading data. +Format "YYYY-MM-DD" (ex. January 1, 2018 = \code{"2018-01-01"}).} \item{directory_to_save}{character(1). Directory to save data.} @@ -55,6 +51,113 @@ collection-specific folder within \code{directory_to_save}. The \code{download_merra2()} function accesses and downloads various meteorological and atmospheric collections from \href{https://gmao.gsfc.nasa.gov/reanalysis/MERRA-2/}{NASA's Modern-Era Retrospective analysis for Research and Applications, Version 2 (MERRA-2) model}. } +\examples{ +\dontrun{ +download_merra2( + collection = "inst1_2d_int_Nx", + date = c("2024-01-01", "2024-01-05"), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{data_gmao_merra-inst1_2d_asm_Nx}{amadeus} +\insertRef{data_gmao_merra-inst1_2d_int_Nx}{amadeus} +\insertRef{data_gmao_merra-inst1_2d_lfo_Nx}{amadeus} +\insertRef{data_gmao_merra-inst3_3d_asm_Np}{amadeus} +\insertRef{data_gmao_merra-inst3_3d_aer_Nv}{amadeus} +\insertRef{data_gmao_merra-inst3_3d_asm_Nv}{amadeus} +\insertRef{data_gmao_merra-inst3_3d_chm_Nv}{amadeus} +\insertRef{data_gmao_merra-inst3_3d_gas_Nv}{amadeus} +\insertRef{data_gmao_merra-inst3_2d_gas_Nx}{amadeus} +\insertRef{data_gmao_merra-inst6_3d_ana_Np}{amadeus} +\insertRef{data_gmao_merra-inst6_3d_ana_Nv}{amadeus} +\insertRef{data_gmao_merra-statD_2d_slv_Nx_m}{amadeus} +\insertRef{data_gmao_merra-statD_2d_slv_Nx_d}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_adg_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_aer_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_chm_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_csp_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_flx_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_int_Nx}{amadeus} +\insertRef{pawson_merra-2_2020}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_lnd_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_ocn_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_rad_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg1_2d_slv_Nx}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_mst_Ne}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_trb_Ne}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_nav_Ne}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_cld_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_mst_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_rad_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_tdt_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_trb_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_udt_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_odt_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_qdt_Np}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_asm_Nv}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_cld_Nv}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_mst_Nv}{amadeus} +\insertRef{data_gmao_merra-tavg3_3d_rad_Nv}{amadeus} +\insertRef{data_gmao_merra-tavg3_2d_glc_Nx}{amadeus} +\insertRef{data_gmao_merra-instM_2d_asm_Nx}{amadeus} +\insertRef{data_gmao_merra-instM_2d_int_Nx}{amadeus} +\insertRef{data_gmao_merra-instM_2d_lfo_Nx}{amadeus} +\insertRef{data_gmao_merra-instM_2d_gas_Nx}{amadeus} +\insertRef{data_gmao_merra-instM_3d_asm_Np}{amadeus} +\insertRef{data_gmao_merra-instM_3d_ana_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_adg_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_aer_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_chm_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_csp_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_flx_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_int_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_lfo_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_lnd_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_ocn_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_rad_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_slv_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_2d_glc_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_cld_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_mst_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_rad_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_tdt_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_trb_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_udt_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_odt_Np}{amadeus} +\insertRef{data_gmao_merra-tavgM_3d_qdt_Np}{amadeus} +\insertRef{data_gmao_merra-const_2d_asm_Nx}{amadeus} +\insertRef{data_gmao_merra-instU_2d_asm_Nx}{amadeus} +\insertRef{data_gmao_merra-instU_2d_int_Nx}{amadeus} +\insertRef{data_gmao_merra-instU_2d_lfo_Nx}{amadeus} +\insertRef{data_gmao_merra-instU_2d_gas_Nx}{amadeus} +\insertRef{data_gmao_merra-instU_3d_asm_Np}{amadeus} +\insertRef{data_gmao_merra-instU_3d_ana_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_adg_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_aer_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_chm_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_csp_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_flx_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_int_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_lfo_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_lnd_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_ocn_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_rad_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_slv_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_2d_glc_Nx}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_cld_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_mst_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_rad_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_tdt_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_trb_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_udt_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_odt_Np}{amadeus} +\insertRef{data_gmao_merra-tavgU_3d_qdt_Np}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_modis.Rd b/man/download_modis.Rd index 85e56764..c32a306a 100644 --- a/man/download_modis.Rd +++ b/man/download_modis.Rd @@ -11,8 +11,7 @@ download_modis( vertical_tiles = c(3, 6), mod06_links = NULL, nasa_earth_data_token = NULL, - date_start = "2023-09-01", - date_end = "2023-09-01", + date = c("2023-09-01", "2023-09-01"), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -38,11 +37,9 @@ from NASA LPDAAC. Default is \code{NULL}.} Token for downloading data from NASA. Should be set before trying running the function.} -\item{date_start}{character(1). length of 10. Start date for downloading -data. Format YYYY-MM-DD (ex. September 1, 2023 is \code{"2023-09-01"}).} - -\item{date_end}{character(1). length of 10. End date for downloading data. -Format YYYY-MM-DD (ex. September 1, 2023 is \code{"2023-09-01"}).} +\item{date}{character(2). length of 10 each. Start/end date for downloading data. +Format "YYYY-MM-DD" (ex. January 1, 2018 = \code{"2018-01-01"}). Note: ignored if +\code{product == "MOD06_L2"}.} \item{directory_to_save}{character(1). Directory to save data.} @@ -68,11 +65,61 @@ combinations. An exception is MOD06_L2 product, which is produced every five minutes every day. } \note{ -\code{date_start} and \code{date_end} should be in the same year. +Both dates in \code{date} should be in the same year. Directory structure looks like -input/modis/raw/\{version\}/\{product\}/\{year\}/\{day_of_year\} -Please note that \code{date_start} and \code{date_end} are -ignored if \code{product == 'MOD06_L2'}. +input/modis/raw/\{version\}/\{product\}/\{year\}/\{day_of_year\}. +} +\examples{ +\dontrun{ +# example with MOD0GA product +download_modis( + product = "MOD09GA", + version = "61", + horizontal_tiles = c(8, 10), + vertical_tiles = c(4, 5), + date = c("2024-01-01", "2024-01-10"), + nasa_earth_data_token = readLines("~/pre_generated_token.txt"), + directory_to_save = "./data/mod09ga", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +# example with MOD06_L2 product +download_modis( + product = "MOD06_L2", + version = "61", + horizontal_tiles = c(8, 10), + vertical_tiles = c(4, 5), + mod06_links = "~/LAADS_query.2024-07-15T12_17.csv", + date = c("2024-01-01", "2024-01-10"), + nasa_earth_data_token = readLines("~/pre_generated_token.txt"), + directory_to_save = "./data/mod06l2", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +# example with VNP46A2 product +download_modis( + product = "VNP46A2", + version = "61", + horizontal_tiles = c(8, 10), + vertical_tiles = c(4, 5), + date = c("2024-01-01", "2024-01-10"), + nasa_earth_data_token = readLines("~/pre_generated_token.txt"), + directory_to_save = "./data/vnp46a2", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{data_mcd19a22021}{amadeus} +\insertRef{data_mod06l2_2017}{amadeus} +\insertRef{data_mod09ga2021}{amadeus} +\insertRef{data_mod11a12021}{amadeus} +\insertRef{data_mod13a22021}{amadeus} +\insertRef{article_roman2018vnp46}{amadeus} } \author{ Mitchell Manware, Insang Song diff --git a/man/download_narr_p_levels.Rd b/man/download_narr.Rd similarity index 58% rename from man/download_narr_p_levels.Rd rename to man/download_narr.Rd index ecb28eda..7f8c4754 100644 --- a/man/download_narr_p_levels.Rd +++ b/man/download_narr.Rd @@ -1,13 +1,12 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/download.R -\name{download_narr_p_levels} -\alias{download_narr_p_levels} -\title{Download meteorological data (pressure levels)} +\name{download_narr} +\alias{download_narr} +\title{Download meteorological data} \usage{ -download_narr_p_levels( +download_narr( variables = NULL, - year_start = 2022, - year_end = 2022, + year = c(2018, 2022), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -18,11 +17,7 @@ download_narr_p_levels( \item{variables}{character. Variable(s) name acronym. See \href{https://ftp.cpc.ncep.noaa.gov/NARR/fixed/merged_land_AWIP32corrected.pdf}{List of Variables in NARR Files} for variable names and acronym codes.} -\item{year_start}{integer(1). length of 4. Start of year range for -downloading data.} - -\item{year_end}{integer(1). length of 4. End of year range for downloading -data.} +\item{year}{character(2). length of 4 each. Start/end years for downloading data.} \item{directory_to_save}{character(1). Directory(s) to save downloaded data files.} @@ -44,7 +39,25 @@ NULL; netCDF (.nc) files will be stored in \code{directory_to_save}. } \description{ -The \code{download_narr_p_levels} function accesses and downloads pressure levels meteorological data from \href{https://psl.noaa.gov/data/gridded/data.narr.html}{NOAA's North American Regional Reanalysis (NARR) model}. "Pressure levels" variables contain variable values at 29 atmospheric levels, ranging from 1000 hPa to 100 hPa. All pressure levels data will be downloaded for each variable. +The \code{download_narr} function accesses and downloads daily meteorological data from \href{https://psl.noaa.gov/data/gridded/data.narr.html}{NOAA's North American Regional Reanalysis (NARR) model}. +} +\note{ +"Pressure levels" variables contain variable values at 29 atmospheric levels, ranging from 1000 hPa to 100 hPa. All pressure levels data will be downloaded for each variable. +} +\examples{ +\dontrun{ +download_narr( + variables = c("weasd", "omega"), + year = c(2022, 2023), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{mesinger_north_2006}{amadeus} } \author{ Mitchell Manware, Insang Song diff --git a/man/download_narr_monolevel.Rd b/man/download_narr_monolevel.Rd deleted file mode 100644 index 7d4814f8..00000000 --- a/man/download_narr_monolevel.Rd +++ /dev/null @@ -1,51 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/download.R -\name{download_narr_monolevel} -\alias{download_narr_monolevel} -\title{Download meteorological data (monolevel)} -\usage{ -download_narr_monolevel( - variables = NULL, - year_start = 2022, - year_end = 2022, - directory_to_save = NULL, - acknowledgement = FALSE, - download = FALSE, - remove_command = FALSE -) -} -\arguments{ -\item{variables}{character. Variable(s) name acronym. See \href{https://ftp.cpc.ncep.noaa.gov/NARR/fixed/merged_land_AWIP32corrected.pdf}{List of Variables in NARR Files} -for variable names and acronym codes.} - -\item{year_start}{integer(1). length of 4. Start of year range for -downloading data.} - -\item{year_end}{integer(1). length of 4. End of year range for downloading -data.} - -\item{directory_to_save}{character(1). Directory(s) to save downloaded data -files.} - -\item{acknowledgement}{logical(1). By setting \code{TRUE} the -user acknowledges that the data downloaded using this function may be very -large and use lots of machine storage and memory.} - -\item{download}{logical(1). \code{FALSE} will generate a *.txt file -containing all download commands. By setting \code{TRUE} the function -will download all of the requested data files.} - -\item{remove_command}{logical(1). -Remove (\code{TRUE}) or keep (\code{FALSE}) -the text file containing download commands.} -} -\value{ -NULL; netCDF (.nc) files will be stored in a variable-specific -folder within \code{directory_to_save}. -} -\description{ -The \code{download_narr_monolevel} function accesses and downloads monolevel meteorological data from \href{https://psl.noaa.gov/data/gridded/data.narr.html}{NOAA's North American Regional Reanalysis (NARR) model}. "Monolevel" variables contain a single value for the entire atmospheric column (ie. Variable: Convective cloud cover; Level: Entire atmosphere considered as a single layer), or represent a specific altitude associated with the variable (ie. Variable: Air temperature; Level: 2 m). -} -\author{ -Mitchell Manware, Insang Song -} diff --git a/man/download_nei.Rd b/man/download_nei.Rd index 5b842b01..358c3589 100644 --- a/man/download_nei.Rd +++ b/man/download_nei.Rd @@ -8,7 +8,7 @@ download_nei( epa_certificate_path = system.file("extdata/cacert_gaftp_epa.pem", package = "amadeus"), certificate_url = "http://cacerts.digicert.com/DigiCertGlobalG2TLSRSASHA2562020CA1-1.crt", - year_target = c(2017L, 2020L), + year = c(2017L, 2020L), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -24,7 +24,7 @@ for EPA DataCommons. Default is \item{certificate_url}{character(1). URL to certificate file. See notes for details.} -\item{year_target}{Available years of NEI data. +\item{year}{Available years of NEI data. Default is \code{c(2017L, 2020L)}.} \item{directory_to_save}{character(1). Directory to save data. Two @@ -65,6 +65,20 @@ in wget command) file in ./inst/extdata. The instruction above is for certificate updates in the future. } } +\examples{ +\dontrun{ +download_nei( + year = c(2017L, 2020L), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{web_usepa2024nei}{amadeus} +} \author{ Ranadeep Daw, Insang Song } diff --git a/man/download_nlcd.Rd b/man/download_nlcd.Rd index 521b1ad0..db33662f 100644 --- a/man/download_nlcd.Rd +++ b/man/download_nlcd.Rd @@ -53,6 +53,22 @@ The \code{download_nlcd()} function accesses and downloads land cover data from the \href{https://www.mrlc.gov/data}{Multi-Resolution Land Characteristics (MRLC) Consortium's National Land Cover Database (NLCD) products data base}. } +\examples{ +\dontrun{ +download_nlcd( + collection = "Coterminous United States", + year = 2021, + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{dewitz_national_2023}{amadeus} +\insertRef{dewitz_national_2024}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_olm.Rd b/man/download_olm.Rd index e02d965d..c7808dc2 100644 --- a/man/download_olm.Rd +++ b/man/download_olm.Rd @@ -120,6 +120,21 @@ Accesses and downloads OpenLandMap data from the \href{https://www.openlandmap.o Users may want to check the available assets to download data directly. For developers: JSON files should be found at STAC catalog of OpenLandMap when updated. } +\examples{ +\dontrun{ +download_olm( + product = "no2_s5p.l3.trop.tmwm", + format = "tif", + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{data_hengl2023openlandmap}{amadeus} +} \seealso{ \link{list_stac_files} } diff --git a/man/download_prism.Rd b/man/download_prism.Rd index 3dadecf5..954b2f40 100644 --- a/man/download_prism.Rd +++ b/man/download_prism.Rd @@ -77,7 +77,7 @@ download_prism( element = "ppt", data_type = "ts", format = "nc", - directory_to_save = "~/data", + directory_to_save = "./data", acknowledgement = TRUE, download = TRUE, remove_command = TRUE @@ -85,6 +85,8 @@ download_prism( } } \references{ +\insertRef{article_daly2000prism}{amadeus} + \itemize{ \item \href{http://www.prism.oregonstate.edu/}{PRISM Climate Group} \item \href{https://prism.oregonstate.edu/documents/PRISM_downloads_web_service.pdf}{PRISM Web Service Guide} diff --git a/man/download_sedac_groads.Rd b/man/download_sedac_groads.Rd index cda88773..385800c0 100644 --- a/man/download_sedac_groads.Rd +++ b/man/download_sedac_groads.Rd @@ -52,6 +52,21 @@ respective sub-directories within \code{directory_to_save}. The \code{download_sedac_groads()} function accesses and downloads roads data from \href{https://sedac.ciesin.columbia.edu/data/set/groads-global-roads-open-access-v1/data-download}{NASA's Global Roads Open Access Data Set (gROADS), v1 (1980-2010)}. } +\examples{ +\dontrun{ +download_sedac_groads( + data_region = "Americas", + data_format = "Shapefile", + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{data_ciesin2013groads}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_sedac_population.Rd b/man/download_sedac_population.Rd index 73840a15..4d0533b9 100644 --- a/man/download_sedac_population.Rd +++ b/man/download_sedac_population.Rd @@ -56,6 +56,22 @@ respective sub-directories within \code{directory_to_save}. The \code{download_sedac_population()} function accesses and downloads population density data from \href{https://sedac.ciesin.columbia.edu/data/set/gpw-v4-population-density-adjusted-to-2015-unwpp-country-totals-rev11}{NASA's UN WPP-Adjusted Population Density, v4.11}. } +\examples{ +\dontrun{ +download_sedac_population( + data_resolution = "30 second", + data_format = "GeoTIFF", + year = "2020", + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{data_ciesin2017gpwv4}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_terraclimate.Rd b/man/download_terraclimate.Rd index 1f1f35de..bd56d516 100644 --- a/man/download_terraclimate.Rd +++ b/man/download_terraclimate.Rd @@ -6,8 +6,7 @@ \usage{ download_terraclimate( variables = NULL, - year_start = 2022, - year_end = 2022, + year = c(2018, 2022), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -18,11 +17,7 @@ download_terraclimate( \item{variables}{character(1). Variable(s) name(s). See \href{https://climate.northwestknowledge.net/TERRACLIMATE/index_directDownloads.php}{TerraClimate Direct Downloads} for variable names and acronym codes.} -\item{year_start}{integer(1). length of 4. Start of year range for -downloading data.} - -\item{year_end}{integer(1). length of 4. End of year range for downloading -data.} +\item{year}{character(2). length of 4 each. Start/end years for downloading data.} \item{directory_to_save}{character(1). Directory(s) to save downloaded data files.} @@ -46,6 +41,21 @@ folder within \code{directory_to_save}. \description{ The \code{download_terraclimate} function accesses and downloads climate and water balance data from the \href{https://www.climatologylab.org/terraclimate.html}{University of California Merced Climatology Lab's TerraClimate dataset}. } +\examples{ +\dontrun{ +download_terraclimate( + variables = "Precipitation", + year = c(2023, 2024), + directory_to_save = "./data" + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{article_abatzoglou2018terraclimate}{amadeus} +} \author{ Mitchell Manware, Insang Song } diff --git a/man/download_tri.Rd b/man/download_tri.Rd index 56ea0435..01422906 100644 --- a/man/download_tri.Rd +++ b/man/download_tri.Rd @@ -5,8 +5,7 @@ \title{Download toxic release data} \usage{ download_tri( - year_start = 2018L, - year_end = 2022L, + year = c(2018L, 2022L), directory_to_save = NULL, acknowledgement = FALSE, download = FALSE, @@ -14,9 +13,7 @@ download_tri( ) } \arguments{ -\item{year_start}{integer(1). length of 4. Start year for downloading data.} - -\item{year_end}{integer(1). length of 4. End year for downloading data.} +\item{year}{character(2). length of 4 each. Start/end years for downloading data.} \item{directory_to_save}{character(1). Directory to download files.} @@ -38,6 +35,20 @@ NULL; Comma-separated value (CSV) files will be stored in \description{ The \code{download_tri()} function accesses and downloads toxic release data from the \href{https://www.epa.gov/toxics-release-inventory-tri-program/find-understand-and-use-tri}{U.S. Environmental Protection Agency's (EPA) Toxic Release Inventory (TRI) Program}. } +\examples{ +\dontrun{ +download_tri( + year = c(2020L, 2021L), + directory_to_save = "./data", + acknowledgement = TRUE, + download = TRUE, + remove_command = TRUE +) +} +} +\references{ +\insertRef{web_usepa2024tri}{amadeus} +} \author{ Mariana Kassien, Insang Song } diff --git a/man/figures/amadeus-combined.svg b/man/figures/amadeus-combined.svg new file mode 100644 index 00000000..53d73f51 --- /dev/null +++ b/man/figures/amadeus-combined.svg @@ -0,0 +1,236 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + www. + + + + + + + + + + + + + + \ No newline at end of file diff --git a/man/figures/amadeus_hex.svg b/man/figures/amadeus_hex.svg new file mode 100644 index 00000000..2daec0d8 --- /dev/null +++ b/man/figures/amadeus_hex.svg @@ -0,0 +1,131 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + www. + + + + + + + + + + + \ No newline at end of file diff --git a/man/figures/chords_hex.svg b/man/figures/chords_hex.svg new file mode 100644 index 00000000..338aae5b --- /dev/null +++ b/man/figures/chords_hex.svg @@ -0,0 +1,124 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/vignettes/images/readme_issues.png b/man/figures/readme_issues.png similarity index 100% rename from vignettes/images/readme_issues.png rename to man/figures/readme_issues.png diff --git a/man/narr_variable.Rd b/man/narr_variable.Rd new file mode 100644 index 00000000..7ef23596 --- /dev/null +++ b/man/narr_variable.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/download_auxiliary.R +\name{narr_variable} +\alias{narr_variable} +\title{Sort NOAA NARR variables} +\usage{ +narr_variable(variable) +} +\arguments{ +\item{variable}{character(1). User-selected NARR variable} +} +\value{ +list with URL base and vector of months (blank for monolevel) +} +\description{ +Determine whether a NOAA NARR variable selected for download is a +monolevel or pressure level variable. Monolevel variables are derived +from https://downloads.psl.noaa.gov/Datasets/NARR/Dailies/monolevel/, +and pressure level variables are derived from +https://downloads.psl.noaa.gov//Datasets/NARR/Dailies/pressure/. +} +\keyword{auxiliary} diff --git a/man/process_aqs.Rd b/man/process_aqs.Rd index f8c7fa29..b5ff58d4 100644 --- a/man/process_aqs.Rd +++ b/man/process_aqs.Rd @@ -2,14 +2,15 @@ % Please edit documentation in R/process.R \name{process_aqs} \alias{process_aqs} -\title{Process unique U.S. EPA AQS sites} +\title{Process U.S. EPA AQS daily CSV data} \usage{ process_aqs( path = NULL, date = c("2018-01-01", "2022-12-31"), - mode = c("full", "sparse", "location"), + mode = c("date-location", "available-data", "location"), data_field = "Arithmetic.Mean", return_format = c("terra", "sf", "data.table"), + extent = NULL, ... ) } @@ -19,14 +20,21 @@ process_aqs( \item{date}{character(2). Start and end date. Should be in \code{"YYYY-MM-DD"} format and sorted.} -\item{mode}{character(1). One of "full" (all dates * all locations) -or "sparse" (date-location pairs with available data) or -"location" (unique locations).} +\item{mode}{character(1). One of +\itemize{ +\item "date-location" (all dates * all locations) +\item "available-data" (date-location pairs with available data) +\item "location" (unique locations). +}} \item{data_field}{character(1). Data field to extract.} \item{return_format}{character(1). \code{"terra"} or \code{"sf"} or \code{"data.table"}.} +\item{extent}{numeric(4). Spatial extent of the resulting object. +The order should be \code{c(xmin, xmax, ymin, ymax)}. +The coordinate system should be WGS84 (EPSG:4326).} + \item{...}{Placeholders.} } \value{ @@ -34,7 +42,8 @@ a SpatVector, sf, or data.table object depending on the \code{return_format} } \description{ The \code{process_aqs()} function cleans and imports raw air quality -monitoring sites, returning a single \code{SpatVector} or sf object. +monitoring sites from pre-generated daily CSV files, returning a single +\code{SpatVector} or \code{sf} object. \code{date} is used to filter the raw data read from csv files. Filtered rows are then processed according to \code{mode} argument. Some sites report multiple measurements per day with and without @@ -44,8 +53,19 @@ are multiple event types per site-time. } \note{ Choose \code{date} and \code{mode} values with caution. -The function may return a massive data.table, resulting in -a long processing time or even a crash. +The function may return a massive data.table depending on the time range, +resulting in a long processing time or even a crash if data is too large +for your computing environment to process. +} +\examples{ +\dontrun{ +aqs <- process_aqs( + path = "./data/aqs_daily_example.csv", + date = c("2022-12-01", "2023-01-31"), + mode = "full", + return_format = "terra" +) +} } \seealso{ \itemize{ diff --git a/man/process_bluemarble.Rd b/man/process_blackmarble.Rd similarity index 60% rename from man/process_bluemarble.Rd rename to man/process_blackmarble.Rd index 9c8c7a30..5cb58b9f 100644 --- a/man/process_bluemarble.Rd +++ b/man/process_blackmarble.Rd @@ -1,13 +1,13 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/process.R -\name{process_bluemarble} -\alias{process_bluemarble} -\title{Assign VIIRS Blue Marble products corner coordinates to retrieve a merged raster} +\name{process_blackmarble} +\alias{process_blackmarble} +\title{Assign VIIRS Black Marble products corner coordinates to retrieve a merged raster} \usage{ -process_bluemarble( +process_blackmarble( path = NULL, date = NULL, - tile_df = process_bluemarble_corners(), + tile_df = process_blackmarble_corners(), subdataset = 3L, crs = "EPSG:4326", ... @@ -20,7 +20,7 @@ process_bluemarble( \item{tile_df}{data.frame. Contains four corner coordinates in fields named \code{c("xmin", "xmax", "ymin", "ymax")}. -See \code{\link{process_bluemarble_corners}} to generate a valid object for this argument.} +See \code{\link{process_blackmarble_corners}} to generate a valid object for this argument.} \item{subdataset}{integer(1). Subdataset number to process. Default is 3L.} @@ -35,19 +35,32 @@ a \code{SpatRaster} object } \description{ This function will return a \code{SpatRaster} object with -georeferenced h5 files of Blue Marble product. Referencing corner coordinates +georeferenced h5 files of Black Marble product. Referencing corner coordinates are necessary as the original h5 data do not include such information. } +\examples{ +\dontrun{ +vnp46a2 <- process_blackmarble( + path = + list.files("./data", pattern = "VNP46A2.", full.names = TRUE), + date = "2024-01-01", + tile_df = + process_blackmarble_corners(hrange = c(8, 10), vrange = c(4, 5)) + subdataset = 3L, + crs = "EPSG:4326" +) +} +} \references{ \itemize{ -\item \href{https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document\%20Archive/Science\%20Data\%20Product\%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf}{Wang, Z. (2022). Blue Marble User Guide (Version 1.3). NASA.} +\item \href{https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document\%20Archive/Science\%20Data\%20Product\%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf}{Wang, Z. (2022). Black Marble User Guide (Version 1.3). NASA.} } } \seealso{ \itemize{ \item \code{\link[terra:describe]{terra::describe}} \item \code{\link[terra:merge]{terra::merge}} -\item \code{\link{process_bluemarble_corners}} +\item \code{\link{process_blackmarble_corners}} } } \author{ diff --git a/man/process_bluemarble_corners.Rd b/man/process_blackmarble_corners.Rd similarity index 61% rename from man/process_bluemarble_corners.Rd rename to man/process_blackmarble_corners.Rd index f44892a2..e3ccca3b 100644 --- a/man/process_bluemarble_corners.Rd +++ b/man/process_blackmarble_corners.Rd @@ -1,10 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/process.R -\name{process_bluemarble_corners} -\alias{process_bluemarble_corners} -\title{Process Blue Marble corners} +\name{process_blackmarble_corners} +\alias{process_blackmarble_corners} +\title{Process Black Marble corners} \usage{ -process_bluemarble_corners(hrange = c(5, 11), vrange = c(3, 6)) +process_blackmarble_corners(hrange = c(5, 11), vrange = c(3, 6)) } \arguments{ \item{hrange}{integer(2). Both should be in 0-35.} @@ -15,15 +15,18 @@ process_bluemarble_corners(hrange = c(5, 11), vrange = c(3, 6)) \code{data.frame} with xmin, xmax, ymin, and ymax fields } \description{ -Tile corner generator for Blue Marble products. +Tile corner generator for Black Marble products. -Blue Marble products are in HDF5 format and are read without +Black Marble products are in HDF5 format and are read without georeference with typical R geospatial packages. This function generates a \code{data.frame} of corner coordinates for assignment. } +\examples{ +process_blackmarble_corners(hrange = c(1, 2), vrange = c(1, 2)) +} \references{ \itemize{ -\item \href{https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document\%20Archive/Science\%20Data\%20Product\%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf}{Wang, Z. (2022). Blue Marble User Guide (Version 1.3). NASA.} +\item \href{https://ladsweb.modaps.eosdis.nasa.gov/api/v2/content/archives/Document\%20Archive/Science\%20Data\%20Product\%20Documentation/VIIRS_Black_Marble_UG_v1.3_Sep_2022.pdf}{Wang, Z. (2022). Black Marble User Guide (Version 1.3). NASA.} } } \author{ diff --git a/man/process_collection.Rd b/man/process_collection.Rd index dc9f206e..d94e6685 100644 --- a/man/process_collection.Rd +++ b/man/process_collection.Rd @@ -1,17 +1,9 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/process.R, R/process_auxiliary.R +% Please edit documentation in R/process_auxiliary.R \name{process_collection} \alias{process_collection} \title{Process GEOS-CF and MERRA2 collection codes} \usage{ -process_collection( - path, - source, - collection = FALSE, - date = FALSE, - datetime = FALSE -) - process_collection( path, source, @@ -35,14 +27,9 @@ on provided file path(s).} (YYYYMoMoDDHHMiMi) based on provided file path(s).} } \value{ -character - character } \description{ -Identify the GEOS-CF or MERRA2 collection based on the file path. - Identify the GEOS-CF or MERRA2 collection based on the file path. } \keyword{auxiliary} -\keyword{auxillary} diff --git a/man/process_covariates.Rd b/man/process_covariates.Rd index 20e34bb1..d2a02cd2 100644 --- a/man/process_covariates.Rd +++ b/man/process_covariates.Rd @@ -5,7 +5,7 @@ \title{Process raw data wrapper function} \usage{ process_covariates( - covariate = c("modis_swath", "modis_merge", "koppen-geiger", "bluemarble", + covariate = c("modis_swath", "modis_merge", "koppen-geiger", "blackmarble", "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "hms", "smoke", "sedac_population", "population", "sedac_groads", "groads", "roads", "nlcd", "tri", "narr", "nei", "ecoregions", "ecoregion", "merra", "merra2", "gridmet", @@ -33,6 +33,16 @@ the underlying source-specific processing functions have been designed to operate on the raw data files. To avoid errors, \strong{do not edit the raw data files before passing to \code{process_covariates}}. } +\examples{ +\dontrun{ +narr <- process_covariates( + covariate = "narr", + date = c("2023-01-01", "2023-01-10"), + variable = "weasd", + path = "./data/weasd" +) +} +} \seealso{ \itemize{ \item diff --git a/man/process_cropscape.Rd b/man/process_cropscape.Rd index 040faaef..cb11ef73 100644 --- a/man/process_cropscape.Rd +++ b/man/process_cropscape.Rd @@ -4,13 +4,16 @@ \alias{process_cropscape} \title{Process CropScape data} \usage{ -process_cropscape(path = NULL, year = 2021, ...) +process_cropscape(path = NULL, year = 2021, extent = NULL, ...) } \arguments{ \item{path}{character giving CropScape data path} \item{year}{numeric giving the year of CropScape data used} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -22,6 +25,14 @@ returning a single \code{SpatRaster} object. Reads CropScape file of selected \code{year}. } +\examples{ +\dontrun{ +cropscape <- process_cropscape( + path = "./data/cropscape_example.tif", + year = 2020 +) +} +} \author{ Insang Song } diff --git a/man/process_ecoregion.Rd b/man/process_ecoregion.Rd index dc74c786..e69f5bd7 100644 --- a/man/process_ecoregion.Rd +++ b/man/process_ecoregion.Rd @@ -4,11 +4,14 @@ \alias{process_ecoregion} \title{Process ecoregion data} \usage{ -process_ecoregion(path = NULL, ...) +process_ecoregion(path = NULL, extent = NULL, ...) } \arguments{ \item{path}{character(1). Path to Ecoregion Shapefiles} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -23,6 +26,13 @@ The function will fix Tukey's bridge in Portland, ME. This fix will ensure that the EPA air quality monitoring sites will be located within the ecoregion. } +\examples{ +\dontrun{ +ecoregion <- process_ecoregion( + path = "./data/epa_ecoregion.gpkg" +) +} +} \author{ Insang Song } diff --git a/man/process_flatten_sds.Rd b/man/process_flatten_sds.Rd index 9dcef5a1..41619482 100644 --- a/man/process_flatten_sds.Rd +++ b/man/process_flatten_sds.Rd @@ -38,6 +38,16 @@ information about MODIS sub-datasets, consider running list of sub-datasets in the input file then consult the documentation of MODIS product. } +\examples{ +\dontrun{ +mod09ga_flatten <- process_flatten_sds( + path = + list.files("./data", pattern = "MOD09GA.", full.names = TRUE)[1], + subdataset = process_modis_sds("MOD09GA"), + fun_agg = "mean" +) +} +} \seealso{ \link[terra:tapp]{terra::tapp}, \link[terra:rast]{terra::rast}, \link[terra:describe]{terra::describe} } diff --git a/man/process_geos.Rd b/man/process_geos.Rd index fdf9b5dc..d4ad60a3 100644 --- a/man/process_geos.Rd +++ b/man/process_geos.Rd @@ -8,6 +8,7 @@ process_geos( date = c("2018-01-01", "2018-01-01"), variable = NULL, path = NULL, + extent = NULL, ... ) } @@ -18,6 +19,9 @@ process_geos( \item{path}{character(1). Directory with downloaded netCDF (.nc4) files.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -31,6 +35,15 @@ composition data, returning a single \code{SpatRaster} object. Layer names of the returned \code{SpatRaster} object contain the variable, pressure level, date, and hour. } +\examples{ +\dontrun{ +geos <- process_geos( + date = c("2024-01-01", "2024-01-10"), + variable = "O3", + path = "./data/aqc_tavg_1hr_g1440x721_v1" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_gmted.Rd b/man/process_gmted.Rd index c26eeab0..0a03a98e 100644 --- a/man/process_gmted.Rd +++ b/man/process_gmted.Rd @@ -4,7 +4,7 @@ \alias{process_gmted} \title{Process elevation data} \usage{ -process_gmted(variable = NULL, path = NULL, ...) +process_gmted(variable = NULL, path = NULL, extent = NULL, ...) } \arguments{ \item{variable}{vector(1). Vector containing the GMTED statistic first and @@ -20,6 +20,9 @@ the resolution second. (Example: variable = c("Breakline Emphasis", \item{path}{character(1). Directory with downloaded GMTED "*_grd" folder containing .adf files.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -33,6 +36,14 @@ returning a single \code{SpatRaster} object. \code{SpatRaster} layer name indicates selected variable and resolution, and year of release (2010). } +\examples{ +\dontrun{ +gmted <- process_gmted( + variable = c("Breakline Emphasis", "7.5 arc-seconds"), + path = "./data/be75_grd" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_gridmet.Rd b/man/process_gridmet.Rd index 11b23d3c..0b17d39b 100644 --- a/man/process_gridmet.Rd +++ b/man/process_gridmet.Rd @@ -7,7 +7,9 @@ process_gridmet( date = c("2023-09-01", "2023-09-01"), variable = NULL, - path = NULL + path = NULL, + extent = NULL, + ... ) } \arguments{ @@ -20,6 +22,11 @@ for variable names and acronym codes. (Note: variable "Burning Index" has code " "Energy Release Component" has code "erc").} \item{path}{character(1). Directory with downloaded netCDF (.nc) files.} + +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + +\item{...}{Placeholders.} } \value{ a \code{SpatRaster} object @@ -32,6 +39,15 @@ data, returning a single \code{SpatRaster} object. Layer names of the returned \code{SpatRaster} object contain the variable acronym, and date. } +\examples{ +\dontrun{ +gridmet <- process_gridmet( + date = c("2023-01-01", "2023-01-10"), + variable = "Precipitation", + path = "./data/pr" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_hms.Rd b/man/process_hms.Rd index 3f110427..b00283d5 100644 --- a/man/process_hms.Rd +++ b/man/process_hms.Rd @@ -6,8 +6,8 @@ \usage{ process_hms( date = c("2018-01-01", "2018-01-01"), - variable = c("Light", "Medium", "Heavy"), path = NULL, + extent = NULL, ... ) } @@ -16,10 +16,11 @@ process_hms( Start/end date of downloaded data. Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01").} -\item{variable}{character(1). "Light", "Medium", or "Heavy".} - \item{path}{character(1). Directory with downloaded NOAA HMS data files.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the output +if \code{NULL} (default), the entire data is returned} + \item{...}{Placeholders.} } \value{ @@ -32,13 +33,14 @@ plume coverage data, returning a single \code{SpatVector} object. \note{ \code{process_hms()} will return a character object if there are no wildfire smoke plumes present for the selected dates and density. The returned -character will contain the selected density value and the sequence of dates +character will contain the density value and the sequence of dates for which no wildfire smoke plumes were detected (see "Examples"). +If multiple density polygons overlap, the function will return the +highest density value. } \examples{ -process_hms( +hms <- process_hms( date = c("2018-12-30", "2019-01-01"), - variable = "Light", path = "../tests/testdata/hms/" ) } diff --git a/man/process_huc.Rd b/man/process_huc.Rd index ca1b2700..19b7d637 100644 --- a/man/process_huc.Rd +++ b/man/process_huc.Rd @@ -4,7 +4,14 @@ \alias{process_huc} \title{Retrieve Hydrologic Unit Code (HUC) data} \usage{ -process_huc(path, layer_name = NULL, huc_level = NULL, huc_header = NULL, ...) +process_huc( + path, + layer_name = NULL, + huc_level = NULL, + huc_header = NULL, + extent = NULL, + ... +) } \arguments{ \item{path}{character. Path to the file or the directory containing HUC data.} @@ -16,6 +23,9 @@ process_huc(path, layer_name = NULL, huc_level = NULL, huc_header = NULL, ...) \item{huc_header}{character(1). The upper level HUC code header to extract lower level HUCs.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Arguments passed to \code{nhdplusTools::get_huc()}} } \value{ diff --git a/man/process_koppen_geiger.Rd b/man/process_koppen_geiger.Rd index 8e25a3d2..222924fd 100644 --- a/man/process_koppen_geiger.Rd +++ b/man/process_koppen_geiger.Rd @@ -4,13 +4,14 @@ \alias{process_koppen_geiger} \title{Process climate classification data} \usage{ -process_koppen_geiger(path = NULL, year = NULL, ...) +process_koppen_geiger(path = NULL, extent = NULL, ...) } \arguments{ \item{path}{character(1). Path to Koppen-Geiger climate zone raster file} -\item{year}{data year. Not applicable for this function.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} \item{...}{Placeholders.} } @@ -21,6 +22,13 @@ a \code{SpatRaster} object The \code{process_koppen_geiger()} function imports and cleans raw climate classification data, returning a single \code{SpatRaster} object. } +\examples{ +\dontrun{ +kg <- process_koppen_geiger( + path = "./data/koppen_geiger_data.tif" +) +} +} \author{ Insang Song } diff --git a/man/process_merra2.Rd b/man/process_merra2.Rd index c4f173a9..42cb08f7 100644 --- a/man/process_merra2.Rd +++ b/man/process_merra2.Rd @@ -8,6 +8,7 @@ process_merra2( date = c("2018-01-01", "2018-01-01"), variable = NULL, path = NULL, + extent = NULL, ... ) } @@ -18,6 +19,9 @@ process_merra2( \item{path}{character(1). Directory with downloaded netCDF (.nc4) files.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -33,6 +37,15 @@ pressure level, date, and hour. Pressure level values utilized for layer names are taken directly from raw data and are not edited to retain pressure level information. } +\examples{ +\dontrun{ +merra2 <- process_merra2( + date = c("2024-01-01", "2024-01-10"), + variable = "CPT", + path = "./data/inst1_2d_int_Nx" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_modis_merge.Rd b/man/process_modis_merge.Rd index 4b16875c..8c6f91b1 100644 --- a/man/process_modis_merge.Rd +++ b/man/process_modis_merge.Rd @@ -41,6 +41,17 @@ MODIS products downloaded by functions in \code{amadeus}, \href{https://cran.r-project.org/web/packages/MODISTools/index.html}{MODISTools}, and \href{https://github.com/rspatial/luna}{luna} are accepted. } +\examples{ +\dontrun{ +mod09ga_merge <- process_modis_merge( + path = + list.files("./data", pattern = "MOD09GA.", full.names = TRUE), + date = "2024-01-01", + subdataset = "sur_refl_b01_1", + fun_agg = "mean" +) +} +} \seealso{ \code{\link{download_data}} } diff --git a/man/process_modis_sds.Rd b/man/process_modis_sds.Rd index 71153dd1..a2b21c0e 100644 --- a/man/process_modis_sds.Rd +++ b/man/process_modis_sds.Rd @@ -44,6 +44,9 @@ When utilizing a product code from this "Short Name" column, \strong{do not include} the version number following the period. For example, if "Short Name" = MCD12C1.006, then \code{product = "MCD12C1"}. } +\examples{ +process_modis_sds(product = "MOD09GA") +} \seealso{ \link{calc_modis_par} } diff --git a/man/process_modis_swath.Rd b/man/process_modis_swath.Rd index a04244c6..9b4a372c 100644 --- a/man/process_modis_swath.Rd +++ b/man/process_modis_swath.Rd @@ -49,6 +49,21 @@ Users need to select a subdataset to process. The full path looks like \code{"HDF4_EOS:EOS_SWATH:{file_path}:mod06:subdataset"}, where file_path is the full path to the hdf file. } +\examples{ +\dontrun{ +mod06l2_swath <- process_modis_swath( + path = list.files( + "./data/mod06l2", + full.names = TRUE, + pattern = ".hdf" + ), + date = "2024-01-01", + subdataset = "Cloud_Fraction", + suffix = ":mod06:", + resolution = 0.05 +) +} +} \seealso{ \itemize{ \item \code{\link[=process_modis_warp]{process_modis_warp()}}, \code{\link[stars:read_stars]{stars::read_stars()}}, \code{\link[stars:st_warp]{stars::st_warp()}} diff --git a/man/process_modis_warp.Rd b/man/process_modis_warp.Rd index abf290d5..36566b0f 100644 --- a/man/process_modis_warp.Rd +++ b/man/process_modis_warp.Rd @@ -43,6 +43,24 @@ grid points. \note{ This function handles one file at a time. } +\examples{ +\dontrun{ +mod06l2_warp <- process_modis_warp( + path = paste0( + "HDF4_EOS:EOS_SWATH:", + list.files( + "./data/mod06l2", + full.names = TRUE, + pattern = ".hdf" + )[1], + ":mod06:Cloud_Fraction" + ), + cellsize = 0.1, + threshold = 0.4, + crs = 4326 +) +} +} \seealso{ \code{\link[terra:rectify]{terra::rectify}} } diff --git a/man/process_narr.Rd b/man/process_narr.Rd index 9764b1c3..fd674088 100644 --- a/man/process_narr.Rd +++ b/man/process_narr.Rd @@ -8,6 +8,7 @@ process_narr( date = c("2023-09-01", "2023-09-01"), variable = NULL, path = NULL, + extent = NULL, ... ) } @@ -21,6 +22,9 @@ for variable names and acronym codes.} \item{path}{character(1). Directory with downloaded netCDF (.nc) files.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -34,6 +38,15 @@ data, returning a single \code{SpatRaster} object. Layer names of the returned \code{SpatRaster} object contain the variable acronym, pressure level, and date. } +\examples{ +\dontrun{ +narr <- process_narr( + date = c("2022-01-01", "2022-01-10"), + variable = "weasd", + path = "./data/weasd" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_nei.Rd b/man/process_nei.Rd index cfc6a522..fe8a46bd 100644 --- a/man/process_nei.Rd +++ b/man/process_nei.Rd @@ -35,6 +35,15 @@ or by using \code{tigris} package. This function does not reproject census bound Users should be aware of the coordinate system of census boundary data for other analyses. } +\examples{ +\dontrun{ +nei <- process_nei( + path = "./data", + county = system.file("gpkg/nc.gpkg", package = "sf"), + year = 2017 +) +} +} \author{ Insang Song } diff --git a/man/process_nlcd.Rd b/man/process_nlcd.Rd index 472012f4..c9d5cb7d 100644 --- a/man/process_nlcd.Rd +++ b/man/process_nlcd.Rd @@ -25,6 +25,14 @@ returning a single \code{SpatRaster} object. Reads NLCD file of selected \code{year}. } +\examples{ +\dontrun{ +nlcd <- process_nlcd( + path = "./data/", + year = 2021 +) +} +} \author{ Eva Marques, Insang Song } diff --git a/man/process_olm.Rd b/man/process_olm.Rd index 73980c52..422ae211 100644 --- a/man/process_olm.Rd +++ b/man/process_olm.Rd @@ -4,11 +4,14 @@ \alias{process_olm} \title{Process OpenLandMap data} \usage{ -process_olm(path = NULL, ...) +process_olm(path = NULL, extent = NULL, ...) } \arguments{ \item{path}{character giving OpenLandMap data path} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -17,6 +20,16 @@ a \code{SpatRaster} object \description{ Process OpenLandMap data } +\examples{ +\dontrun{ +olm <- process_olm( + path = paste0( + "./data/no2_s5p.l3.trop.tmwm.p50_p90_2km_a_", + "20180501_20221130_go_epsg.4326_v20221219.tif" + ) +) +} +} \author{ Insang Song } diff --git a/man/process_prism.Rd b/man/process_prism.Rd index 3be6500c..a329fa9f 100644 --- a/man/process_prism.Rd +++ b/man/process_prism.Rd @@ -4,7 +4,7 @@ \alias{process_prism} \title{Process PRISM data} \usage{ -process_prism(path = NULL, element = NULL, time = NULL, ...) +process_prism(path = NULL, element = NULL, time = NULL, extent = NULL, ...) } \arguments{ \item{path}{character giving PRISM data path @@ -16,6 +16,9 @@ Both file and directory path are acceptable.} Should be character in length of 2, 4, 6, or 8. "annual" is acceptable.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -27,6 +30,15 @@ returning a single \code{SpatRaster} object. Reads time series or 30-year normal PRISM data. } +\examples{ +\dontrun{ +prism <- process_prism( + path = "./data/PRISM_ppt_stable_4kmM3_202104_nc.nc", + element = "ppt", + time = "202104" +) +} +} \seealso{ \code{\link[terra:rast]{terra::rast}}, \code{\link[terra:metags]{terra::metags}} } diff --git a/man/process_sedac_groads.Rd b/man/process_sedac_groads.Rd index 38c03e8d..21418032 100644 --- a/man/process_sedac_groads.Rd +++ b/man/process_sedac_groads.Rd @@ -4,11 +4,14 @@ \alias{process_sedac_groads} \title{Process roads data} \usage{ -process_sedac_groads(path = NULL, ...) +process_sedac_groads(path = NULL, extent = NULL, ...) } \arguments{ \item{path}{character(1). Path to geodatabase or shapefiles.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -23,6 +26,13 @@ U.S. context. The returned \code{SpatVector} object contains a \verb{$description} column to represent the temporal range covered by the dataset. For more information, see \url{https://sedac.ciesin.columbia.edu/data/set/groads-global-roads-open-access-v1/metadata}. } +\examples{ +\dontrun{ +groads <- process_sedac_groads( + path = "./data/groads_example.shp" +) +} +} \author{ Insang Song } diff --git a/man/process_sedac_population.Rd b/man/process_sedac_population.Rd index 4664e97f..1eeb3d0e 100644 --- a/man/process_sedac_population.Rd +++ b/man/process_sedac_population.Rd @@ -4,11 +4,14 @@ \alias{process_sedac_population} \title{Process population density data} \usage{ -process_sedac_population(path = NULL, ...) +process_sedac_population(path = NULL, extent = NULL, ...) } \arguments{ \item{path}{character(1). Path to GeoTIFF (.tif) or netCDF (.nc) file.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -18,6 +21,13 @@ a \code{SpatRaster} object The \code{process_secac_population()} function imports and cleans raw population density data, returning a single \code{SpatRaster} object. } +\examples{ +\dontrun{ +pop <- process_sedac_population( + path = "./data/sedac_population_example.tif" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_terraclimate.Rd b/man/process_terraclimate.Rd index f752a022..bda3d6ca 100644 --- a/man/process_terraclimate.Rd +++ b/man/process_terraclimate.Rd @@ -7,7 +7,9 @@ process_terraclimate( date = c("2023-09-01", "2023-09-01"), variable = NULL, - path = NULL + path = NULL, + extent = NULL, + ... ) } \arguments{ @@ -19,6 +21,11 @@ Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01").} for variable names and acronym codes.} \item{path}{character(1). Directory with downloaded netCDF (.nc) files.} + +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + +\item{...}{Placeholders.} } \value{ a \code{SpatRaster} object @@ -34,6 +41,15 @@ and month. TerraClimate data has monthly temporal resolution, so the first day of each month is used as a placeholder temporal value. } +\examples{ +\dontrun{ +terraclimate <- process_terraclimate( + date = c("2023-01-01", "2023-01-10"), + variable = "Precipitation", + path = "./data/ppt" +) +} +} \author{ Mitchell Manware } diff --git a/man/process_tri.Rd b/man/process_tri.Rd index f6cc34b1..59f7651f 100644 --- a/man/process_tri.Rd +++ b/man/process_tri.Rd @@ -8,6 +8,7 @@ process_tri( path = NULL, year = 2018, variables = c(1, 13, 12, 14, 20, 34, 36, 47, 48, 49), + extent = NULL, ... ) } @@ -18,6 +19,9 @@ process_tri( \item{variables}{integer. Column index of TRI data.} +\item{extent}{numeric(4) or SpatExtent giving the extent of the raster +if \code{NULL} (default), the entire raster is loaded} + \item{...}{Placeholders.} } \value{ @@ -32,6 +36,15 @@ returning a single \code{SpatVector} (points) object for the selected \code{year Visit \href{https://www.epa.gov/toxics-release-inventory-tri-program/tri-data-and-tools}{TRI Data and Tools} to view the available years and variables. } +\examples{ +\dontrun{ +tri <- process_tri( + path = "./data", + year = 2020, + variables = c(1, 13, 12, 14, 20, 34, 36, 47, 48, 49) +) +} +} \references{ https://www.epa.gov/toxics-release-inventory-tri-program/tri-data-and-tools } diff --git a/man/test_download_functions.Rd b/man/test_download_functions.Rd index f5d43ab0..1431f1ba 100644 --- a/man/test_download_functions.Rd +++ b/man/test_download_functions.Rd @@ -5,15 +5,12 @@ \title{Download unit tests} \usage{ test_download_functions( - directory_to_download = NULL, directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status ) } \arguments{ -\item{directory_to_download}{directory to test download} - \item{directory_to_save}{directory to test saving} \item{commands_path}{file path with download commands} diff --git a/tests/testdata/hms/hms_smoke20181230.dbf b/tests/testdata/hms/hms_smoke20181230.dbf new file mode 100644 index 00000000..4e04b11b Binary files /dev/null and b/tests/testdata/hms/hms_smoke20181230.dbf differ diff --git a/tests/testdata/hms/hms_smoke20181230.prj b/tests/testdata/hms/hms_smoke20181230.prj new file mode 100644 index 00000000..f45cbadf --- /dev/null +++ b/tests/testdata/hms/hms_smoke20181230.prj @@ -0,0 +1 @@ +GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]] \ No newline at end of file diff --git a/tests/testdata/hms/hms_smoke20181230.shp b/tests/testdata/hms/hms_smoke20181230.shp new file mode 100644 index 00000000..ee1d58c8 Binary files /dev/null and b/tests/testdata/hms/hms_smoke20181230.shp differ diff --git a/tests/testdata/hms/hms_smoke20181230.shx b/tests/testdata/hms/hms_smoke20181230.shx new file mode 100644 index 00000000..04e5dccd Binary files /dev/null and b/tests/testdata/hms/hms_smoke20181230.shx differ diff --git a/tests/testdata/hms/hms_smoke20181231.dbf b/tests/testdata/hms/hms_smoke20181231.dbf new file mode 100644 index 00000000..b81b820d Binary files /dev/null and b/tests/testdata/hms/hms_smoke20181231.dbf differ diff --git a/tests/testdata/hms/hms_smoke20181231.prj b/tests/testdata/hms/hms_smoke20181231.prj new file mode 100644 index 00000000..f45cbadf --- /dev/null +++ b/tests/testdata/hms/hms_smoke20181231.prj @@ -0,0 +1 @@ +GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]] \ No newline at end of file diff --git a/tests/testdata/hms/hms_smoke20181231.shp b/tests/testdata/hms/hms_smoke20181231.shp new file mode 100644 index 00000000..3d95e38a Binary files /dev/null and b/tests/testdata/hms/hms_smoke20181231.shp differ diff --git a/tests/testdata/hms/hms_smoke20181231.shx b/tests/testdata/hms/hms_smoke20181231.shx new file mode 100644 index 00000000..3d95e38a Binary files /dev/null and b/tests/testdata/hms/hms_smoke20181231.shx differ diff --git a/tests/testdata/hms/hms_smoke20190101.dbf b/tests/testdata/hms/hms_smoke20190101.dbf new file mode 100644 index 00000000..9ce22a26 Binary files /dev/null and b/tests/testdata/hms/hms_smoke20190101.dbf differ diff --git a/tests/testdata/hms/hms_smoke20190101.prj b/tests/testdata/hms/hms_smoke20190101.prj new file mode 100644 index 00000000..f45cbadf --- /dev/null +++ b/tests/testdata/hms/hms_smoke20190101.prj @@ -0,0 +1 @@ +GEOGCS["GCS_WGS_1984",DATUM["D_WGS_1984",SPHEROID["WGS_1984",6378137.0,298.257223563]],PRIMEM["Greenwich",0.0],UNIT["Degree",0.0174532925199433]] \ No newline at end of file diff --git a/tests/testdata/hms/hms_smoke20190101.shp b/tests/testdata/hms/hms_smoke20190101.shp new file mode 100644 index 00000000..3bcf6b17 Binary files /dev/null and b/tests/testdata/hms/hms_smoke20190101.shp differ diff --git a/tests/testdata/hms/hms_smoke20190101.shx b/tests/testdata/hms/hms_smoke20190101.shx new file mode 100644 index 00000000..9f5dc762 Binary files /dev/null and b/tests/testdata/hms/hms_smoke20190101.shx differ diff --git a/tests/testdata/kop/Beck_KG_V1_future_0p5.tif b/tests/testdata/kop/Beck_KG_V1_future_0p5.tif new file mode 100644 index 00000000..ef66d9d1 Binary files /dev/null and b/tests/testdata/kop/Beck_KG_V1_future_0p5.tif differ diff --git a/tests/testthat/test-calculate_covariates.R b/tests/testthat/test-calculate_covariates.R index e4050a0e..d8601067 100644 --- a/tests/testthat/test-calculate_covariates.R +++ b/tests/testthat/test-calculate_covariates.R @@ -46,8 +46,8 @@ testthat::test_that("calc_koppen_geiger works well", { geom = TRUE ) ) - testthat::expect_equal(ncol(kg_geom), 8) - testthat::expect_true("geometry" %in% names(kg_geom)) + testthat::expect_equal(ncol(kg_geom), 7) + testthat::expect_true("SpatVector" %in% class(kg_geom)) }) ## 2. Temporal Dummies #### @@ -75,6 +75,16 @@ testthat::test_that("calc_dummies works well", { # should have each of the indicator groups testthat::expect_equal(sum(unlist(dum_res[, -1:-4])), 3L) + # with geometry + testthat::expect_no_error( + dum_res_geom <- calc_temporal_dummies( + locs = site_faux, + year = seq(2018L, 2022L), + geom = TRUE + ) + ) + testthat::expect_s4_class(dum_res_geom, "SpatVector") + # error cases site_faux_err <- site_faux colnames(site_faux_err)[4] <- "date" @@ -169,10 +179,10 @@ testthat::test_that("calc_ecoregion works well", { ) ) testthat::expect_equal( - ncol(ecor_geom), 5 + ncol(ecor_geom), 4 ) testthat::expect_true( - "geometry" %in% names(ecor_geom) + "SpatVector" %in% class(ecor_geom) ) }) @@ -253,6 +263,25 @@ testthat::test_that("calc_modis works well.", { ) ) + # with geometry + testthat::expect_no_error( + suppressWarnings( + calc_mod11_geom <- + calc_modis_par( + from = path_mod11, + locs = sf::st_as_sf(site_faux), + preprocess = process_modis_merge, + package_list_add = c("MASS"), + export_list_add = c("aux"), + name_covariates = c("MOD_LSTNT_0_", "MOD_LSTDY_0_"), + subdataset = "(LST_)", + nthreads = 1L, + geom = TRUE + ) + ) + ) + testthat::expect_s4_class(calc_mod11_geom, "SpatVector") + # case 2: swath mod06l2 path_mod06 <- list.files( @@ -285,6 +314,23 @@ testthat::test_that("calc_modis works well.", { ) testthat::expect_s3_class(calc_mod06, "data.frame") + # with geometry + testthat::expect_no_error( + suppressWarnings( + calc_mod06_geom <- + calc_modis_par( + from = path_mod06, + locs = site_faux, + subdataset = c("Cloud_Fraction_Day", "Cloud_Fraction_Night"), + preprocess = process_modis_swath, + name_covariates = c("MOD_CLFRN_0_", "MOD_CLFRD_0_"), + nthreads = 1, + geom = TRUE + ) + ) + ) + testthat::expect_s4_class(calc_mod06_geom, "SpatVector") + # case 3: VIIRS path_vnp46 <- list.files( @@ -293,10 +339,10 @@ testthat::test_that("calc_modis works well.", { full.names = TRUE ) testthat::expect_warning( - base_vnp <- process_bluemarble( + base_vnp <- process_blackmarble( path = path_vnp46, date = "2018-08-13", - tile_df = process_bluemarble_corners(c(9, 10), c(5, 5)) + tile_df = process_blackmarble_corners(c(9, 10), c(5, 5)) ) ) @@ -306,16 +352,53 @@ testthat::test_that("calc_modis works well.", { calc_modis_par( from = path_vnp46, locs = site_faux, - preprocess = process_bluemarble, + preprocess = process_blackmarble, name_covariates = c("MOD_NITLT_0_"), subdataset = 3L, nthreads = 1, - tile_df = process_bluemarble_corners(c(9, 10), c(5, 5)) + tile_df = process_blackmarble_corners(c(9, 10), c(5, 5)) ) ) ) testthat::expect_s3_class(calc_vnp46, "data.frame") + # with geometry (as SpatVector) + testthat::expect_no_error( + suppressWarnings( + calc_vnp46_geom_v <- + calc_modis_par( + from = path_vnp46, + locs = site_faux, + preprocess = process_blackmarble, + name_covariates = c("MOD_NITLT_0_"), + subdataset = 3L, + nthreads = 1, + tile_df = process_blackmarble_corners(c(9, 10), c(5, 5)), + geom = TRUE + ) + ) + ) + testthat::expect_s4_class(calc_vnp46_geom_v, "SpatVector") + + + # with geometry (as sf) + testthat::expect_no_error( + suppressWarnings( + calc_vnp46_geom_sf <- + calc_modis_par( + from = path_vnp46, + locs = sf::st_as_sf(site_faux), + preprocess = process_blackmarble, + name_covariates = c("MOD_NITLT_0_"), + subdataset = 3L, + nthreads = 1, + tile_df = process_blackmarble_corners(c(9, 10), c(5, 5)), + geom = TRUE + ) + ) + ) + testthat::expect_s4_class(calc_vnp46_geom_sf, "SpatVector") + # error cases testthat::expect_error( process_modis_merge(path = site_faux) @@ -399,6 +482,19 @@ testthat::test_that("calc_modis works well.", { ) ) + # test calc_modis_daily directly with geometry + testthat::expect_no_error( + calc_mod_geom <- calc_modis_daily( + from = mcd_merge, + date = "2021-08-15", + locs = sf::st_as_sf(site_faux2), + radius = 1000, + name_extracted = "MCD_EXTR_1K_", + geom = TRUE + ) + ) + testthat::expect_s4_class(calc_mod_geom, "SpatVector") + testthat::expect_error( calc_modis_par(from = site_faux) ) @@ -419,11 +515,11 @@ testthat::test_that("calc_modis works well.", { calc_modis_par( from = path_vnp46, locs = site_faux, - preprocess = process_bluemarble, + preprocess = process_blackmarble, name_covariates = c("MOD_NITLT_0_", "MOD_K1_"), subdataset = 3L, nthreads = 2, - tile_df = process_bluemarble_corners(c(9, 10), c(5, 5)) + tile_df = process_blackmarble_corners(c(9, 10), c(5, 5)) ) ) testthat::expect_warning( @@ -431,7 +527,7 @@ testthat::test_that("calc_modis works well.", { from = path_vnp46, locs = site_faux, name_covariates = c("MOD_NITLT_0_"), - preprocess = process_bluemarble, + preprocess = process_blackmarble, subdataset = 3L, nthreads = 1, radius = c(-1000, 0L) @@ -612,10 +708,10 @@ testthat::test_that("Check calc_nlcd works", { ) # with geometry will have 12 columns testthat::expect_equal( - ncol(output_geom), 16 + ncol(output_geom), 15 ) testthat::expect_true( - "geometry" %in% names(output_geom) + "SpatVector" %in% class(output_geom) ) }) @@ -691,6 +787,16 @@ testthat::test_that("NEI calculation", { testthat::expect_true(any(grepl("NEI", names(neicalced)))) testthat::expect_equal(neicalced$TRF_NEINP_0_00000, 1579079, tolerance = 1) + # with geometry + testthat::expect_no_error( + neicalced_geom <- calc_nei( + locs = ncp, + from = neiras, + geom = TRUE + ) + ) + testthat::expect_s4_class(neicalced_geom, "SpatVector") + # more error cases testthat::expect_condition( calc_nei( @@ -710,8 +816,8 @@ testthat::test_that("TRI calculation", { withr::local_package("data.table") withr::local_options(sf_use_s2 = FALSE) - ncp <- data.frame(lon = -78.8277, lat = 35.95013) - ncp$site_id <- "3799900018810101" + ncp <- data.frame(lon = c(-78.8277, -78.0000), lat = c(35.95013, 80.000)) + ncp$site_id <- c("3799900018810101", "3799900018819999") ncp$time <- 2018L ncpt <- terra::vect(ncp, geom = c("lon", "lat"), @@ -728,11 +834,22 @@ testthat::test_that("TRI calculation", { tri_c <- calc_tri( from = tri_r, locs = ncpt, - radius = 50000L + radius = c(1500L, 50000L) ) ) testthat::expect_true(is.data.frame(tri_c)) + # with geometry + testthat::expect_no_error( + tri_c_geom <- calc_tri( + from = tri_r, + locs = ncpt, + radius = c(1500L, 50000L), + geom = TRUE + ) + ) + testthat::expect_s4_class(tri_c_geom, "SpatVector") + testthat::expect_no_error( calc_tri( from = tri_r, @@ -808,6 +925,19 @@ testthat::test_that("calc_sedc tests", { ) ) + # with geometry + testthat::expect_no_error( + tri_sedc_geom <- calc_sedc( + locs = ncpt, + from = tri_r, + locs_id = "site_id", + sedc_bandwidth = 30000, + target_fields = targcols, + geom = TRUE + ) + ) + testthat::expect_s4_class(tri_sedc_geom, "SpatVector") + # warning case: duplicate field names between locs and from ncpta <- ncpt ncpta$YEAR <- 2018 @@ -826,11 +956,6 @@ testthat::test_that("calc_sedc tests", { ## 9. HMS #### testthat::test_that("calc_hms returns expected.", { withr::local_package("terra") - densities <- c( - "Light", - "Medium", - "Heavy" - ) radii <- c(0, 1000) ncp <- data.frame(lon = -78.8277, lat = 35.95013) ncp$site_id <- "3799900018810101" @@ -838,64 +963,82 @@ testthat::test_that("calc_hms returns expected.", { expect_true( is.function(calc_hms) ) - for (d in seq_along(densities)) { - density <- densities[d] - for (r in seq_along(radii)) { - hms <- - process_hms( - date = c("2022-06-10", "2022-06-11"), - variable = density, - path = testthat::test_path( - "..", - "testdata", - "hms" - ) - ) - hms_covariate <- - calc_hms( - from = hms, - locs = ncp, - locs_id = "site_id", - radius = radii[r] + for (r in seq_along(radii)) { + hms <- + process_hms( + date = c("2022-06-10", "2022-06-11"), + path = testthat::test_path( + "..", + "testdata", + "hms" ) - # set column names - hms_covariate <- calc_setcolumns( - from = hms_covariate, - lag = 0, - dataset = "hms", - locs_id = "site_id" - ) - # expect output is data.frame - expect_true( - class(hms_covariate) == "data.frame" - ) - # expect 3 columns - expect_true( - ncol(hms_covariate) == 3 ) - # expect 2 rows - expect_true( - nrow(hms_covariate) == 2 - ) - # expect integer for binary value - expect_true( - class(hms_covariate[, 3]) == "integer" - ) - # expect binary - expect_true( - all(unique(hms_covariate[, 3]) %in% c(0, 1)) + hms_covariate <- + calc_hms( + from = hms, + locs = ncp, + locs_id = "site_id", + radius = radii[r], + geom = FALSE ) - } + # set column names + hms_covariate <- calc_setcolumns( + from = hms_covariate, + lag = 0, + dataset = "hms", + locs_id = "site_id" + ) + # expect output is data.frame + expect_true( + class(hms_covariate) == "data.frame" + ) + # expect 3 columns + expect_true( + ncol(hms_covariate) == 5 + ) + # expect 2 rows + expect_true( + nrow(hms_covariate) == 2 + ) + # expect integer for binary value + expect_true( + is.integer(hms_covariate[, 3]) + ) + # expect binary + expect_true( + all(unique(hms_covariate[, 3]) %in% c(0, 1)) + ) } }) -testthat::test_that("calc_hms returns expected with missing polygons.", { - withr::local_package("terra") - densities <- c( - "Light", - "Medium", - "Heavy" +testthat::test_that("calc_hms with geom = TRUE", { + ncp <- data.frame(lon = -78.8277, lat = 35.95013) + ncp$site_id <- "3799900018810101" + hms_dir <- testthat::test_path( + "..", "testdata", "hms" + ) + hms <- process_hms( + date = c("2022-06-10", "2022-06-13"), + path = hms_dir + ) + hms_covariate_geom <- calc_hms( + from = hms, + locs = ncp, + locs_id = "site_id", + radius = 0, + geom = TRUE + ) + # with geometry will have 5 columns + testthat::expect_equal( + ncol(hms_covariate_geom), 5 ) + testthat::expect_s4_class( + hms_covariate_geom, "SpatVector" + ) +}) + +testthat::test_that("calc_hms with missing polygons (12/31/2018).", { + withr::local_package("terra") radii <- c(0, 1000) ncp <- data.frame(lon = -78.8277, lat = 35.95013) ncp$site_id <- "3799900018810101" @@ -903,53 +1046,44 @@ testthat::test_that("calc_hms returns expected with missing polygons.", { expect_true( is.function(calc_hms) ) - hms_dir <- testthat::test_path( - "..", "testdata", "hms" - ) - for (d in seq_along(densities)) { - density <- densities[d] - for (r in seq_along(radii)) { - hms <- - process_hms( - date = c("2022-06-10", "2022-06-13"), - variable = density, - path = hms_dir - ) - hms_covariate <- - calc_hms( - from = hms, - locs = ncp, - locs_id = "site_id", - radius = radii[r] - ) - # set column names - hms_covariate <- calc_setcolumns( - from = hms_covariate, - lag = 0, - dataset = "hms", - locs_id = "site_id" - ) - # expect output is data.frame - expect_true( - class(hms_covariate) == "data.frame" - ) - # expect 3 columns - expect_true( - ncol(hms_covariate) == 3 - ) - # expect 4 rows - expect_true( - nrow(hms_covariate) == 4 - ) - # expect integer for binary value - expect_true( - class(hms_covariate[, 3]) == "integer" - ) - # expect binary - expect_true( - all(unique(hms_covariate[, 3]) %in% c(0, 1)) + # expect function + testthat::expect_true( + is.function(process_hms) + ) + hms <- + process_hms( + date = c("2018-12-31", "2018-12-31"), + path = testthat::test_path( + "..", + "testdata", + "hms" ) - } + ) + for (r in seq_along(radii)) { + hms_covar <- calc_hms( + from = hms, + locs = ncp, + locs_id = "site_id", + radius = radii[r], + geom = FALSE + ) + # data frame + testthat::expect_true(methods::is(hms_covar, "data.frame")) + # 5 columns + testthat::expect_equal(ncol(hms_covar), 7) + } + for (r in seq_along(radii)) { + hms_covar <- calc_hms( + from = hms, + locs = ncp, + locs_id = "site_id", + radius = radii[r], + geom = TRUE + ) + # SpatVector + testthat::expect_true(methods::is(hms_covar, "SpatVector")) + # 5 columns + testthat::expect_equal(ncol(hms_covar), 5) } }) @@ -1031,10 +1165,10 @@ testthat::test_that("calc_gmted returns expected.", { ) ) testthat::expect_equal( - ncol(gmted_geom), 4 + ncol(gmted_geom), 3 ) testthat::expect_true( - "geometry" %in% names(gmted_geom) + "SpatVector" %in% class(gmted_geom) ) }) @@ -1111,6 +1245,23 @@ testthat::test_that("calc_narr returns expected.", { ) } } + # with geometry + testthat::expect_no_error( + narr_covariate_geom <- calc_narr( + from = narr, + locs = ncp, + locs_id = "site_id", + radius = 0, + fun = "mean", + geom = TRUE + ) + ) + testthat::expect_equal( + ncol(narr_covariate_geom), 4 # 4 columns because omega has pressure levels + ) + testthat::expect_true( + "SpatVector" %in% class(narr_covariate_geom) + ) }) ## 11. GEOS-CF #### @@ -1176,6 +1327,23 @@ testthat::test_that("calc_geos returns as expected.", { ) } } + # with included geometry + testthat::expect_no_error( + geos_covariate_geom <- calc_geos( + from = geos, + locs = ncp, + locs_id = "site_id", + radius = 0, + fun = "mean", + geom = TRUE + ) + ) + testthat::expect_equal( + ncol(geos_covariate_geom), 4 + ) + testthat::expect_true( + "SpatVector" %in% class(geos_covariate_geom) + ) }) ## 12. SEDAC: Population #### @@ -1232,6 +1400,23 @@ testthat::test_that("calc_sedac_population returns as expected.", { ) } } + # with included geometry + testthat::expect_no_error( + pop_covariate_geom <- calc_sedac_population( + from = pop, + locs = ncp, + locs_id = "site_id", + radius = 0, + fun = "mean", + geom = TRUE + ) + ) + testthat::expect_equal( + ncol(pop_covariate_geom), 3 + ) + testthat::expect_true( + "SpatVector" %in% class(pop_covariate_geom) + ) }) ## 13. SEDAC: Global Roads #### @@ -1283,10 +1468,10 @@ testthat::test_that("groads calculation works", { ) ) testthat::expect_equal( - ncol(groads_geom), 5 + ncol(groads_geom), 4 ) testthat::expect_true( - "geometry" %in% names(groads_geom) + "SpatVector" %in% class(groads_geom) ) }) @@ -1374,6 +1559,23 @@ testthat::test_that("calc_merra2 returns as expected.", { ) } } + # with included geometry + testthat::expect_no_error( + merra2_covariate_geom <- calc_merra2( + from = merra2, + locs = ncp, + locs_id = "site_id", + radius = 0, + fun = "mean", + geom = TRUE + ) + ) + testthat::expect_equal( + ncol(merra2_covariate_geom), 4 + ) + testthat::expect_true( + "SpatVector" %in% class(merra2_covariate_geom) + ) }) ## 15. GRIDMET #### @@ -1385,7 +1587,7 @@ testthat::test_that("calc_gridmet returns as expected.", { ncp$site_id <- "3799900018810101" # expect function expect_true( - is.function(calc_terraclimate) + is.function(calc_gridmet) ) for (r in seq_along(radii)) { gridmet <- @@ -1432,6 +1634,23 @@ testthat::test_that("calc_gridmet returns as expected.", { "POSIXt" %in% class(gridmet_covariate$time) ) } + # with included geometry + testthat::expect_no_error( + gridmet_covariate_geom <- calc_gridmet( + from = gridmet, + locs = ncp, + locs_id = "site_id", + radius = 0, + fun = "mean", + geom = TRUE + ) + ) + testthat::expect_equal( + ncol(gridmet_covariate_geom), 3 + ) + testthat::expect_true( + "SpatVector" %in% class(gridmet_covariate_geom) + ) }) ## 16. TerraClimate #### @@ -1490,6 +1709,23 @@ testthat::test_that("calc_terraclimate returns as expected.", { nchar(terraclimate_covariate$time)[1] == 6 ) } + # with included geometry + testthat::expect_no_error( + terraclimate_covariate_geom <- calc_terraclimate( + from = terraclimate, + locs = ncp, + locs_id = "site_id", + radius = 0, + fun = "mean", + geom = TRUE + ) + ) + testthat::expect_equal( + ncol(terraclimate_covariate_geom), 3 + ) + testthat::expect_true( + "SpatVector" %in% class(terraclimate_covariate_geom) + ) }) ## 17. Lagged variables #### @@ -1571,8 +1807,7 @@ testthat::test_that("calc_lagged returns as expected.", { } }) - -## 18. Wrapper #### +## 19. Wrapper #### testthat::test_that("calc_covariates wrapper works", { withr::local_package("rlang") @@ -1585,7 +1820,7 @@ testthat::test_that("calc_covariates wrapper works", { "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "sedac_groads", "groads", "roads", - "ecoregions", "ecoregion", "hms", "noaa", "smoke", + "ecoregions", "ecoregion", "hms", "smoke", "gmted", "narr", "geos", "sedac_population", "population", "nlcd", "merra", "MERRA", "merra2", "MERRA2", @@ -1633,7 +1868,7 @@ testthat::test_that("calc_covariates wrapper works", { "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "sedac_groads", "groads", "roads", - "ecoregions", "ecoregion", "hms", "noaa", "smoke", + "ecoregions", "ecoregion", "hms", "smoke", "gmted", "narr", "geos", "sedac_population", "population", "nlcd", "merra", "merra2", @@ -1646,6 +1881,7 @@ testthat::test_that("calc_covariates wrapper works", { } }) +# calc check time testthat::test_that("calc_check_time identifies missing `time` column.", { testthat::expect_error( # provide integer instead of data.frame to provoke error diff --git a/tests/testthat/test-download_functions.R b/tests/testthat/test-download_functions.R index a7c113ae..372b85b8 100644 --- a/tests/testthat/test-download_functions.R +++ b/tests/testthat/test-download_functions.R @@ -2,10 +2,10 @@ testthat::test_that("Error when acknowledgement = FALSE", { download_datasets <- c("aqs", "ecoregion", "geos", "gmted", "koppen", - "koppengeiger", "merra2", "merra", "narr_monolevel", - "narr_p_levels", "nlcd", "noaa", "sedac_groads", - "sedac_population", "groads", "population", "plevels", - "p_levels", "monolevel", "hms", "smoke", "gridmet", + "koppengeiger", "merra2", "merra", "narr", + "nlcd", "noaa", "sedac_groads", + "sedac_population", "groads", "population", + "hms", "smoke", "gridmet", "terraclimate", "huc", "cropscape", "cdl", "prism", "olm", "openlandmap") for (d in seq_along(download_datasets)) { @@ -20,10 +20,10 @@ testthat::test_that("Error when acknowledgement = FALSE", { testthat::test_that("Error when one parameter is NULL.", { download_datasets <- c("aqs", "ecoregion", "geos", "gmted", "koppen", - "koppengeiger", "merra2", "merra", "narr_monolevel", - "narr_p_levels", "nlcd", "noaa", "sedac_groads", - "sedac_population", "groads", "population", "plevels", - "p_levels", "monolevel", "hms", "smoke", "gridmet", + "koppengeiger", "merra2", "merra", "narr", + "nlcd", "noaa", "sedac_groads", + "sedac_population", "groads", "population", + "hms", "smoke", "gridmet", "terraclimate", "huc", "cropscape", "cdl", "prism", "olm", "openlandmap") for (d in seq_along(download_datasets)) { @@ -38,76 +38,70 @@ testthat::test_that("Error when one parameter is NULL.", { }) testthat::test_that("Errors when temporal ranges invalid.", { + error_directory <- testthat::test_path("..", "testdata", "error_temp/") expect_error( download_geos( - date_start = "1900-01-01", + date = c("1900-01-01", "2018-01-01"), collection = "aqc_tavg_1hr_g1440x721_v1", acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", "") + directory_to_save = error_directory ) ) expect_error( download_aqs( - year_start = 1900, - year_end = 1919, + year = c(1900, 2022), acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", ""), + directory_to_save = error_directory ) ) expect_error( - download_narr_monolevel( - year_start = 1900, + download_narr( + year = c(1900, 2022), variables = "air.sfc", acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", "") - ) - ) - expect_error( - download_narr_p_levels( - year_start = 1900, - variables = "omega", - acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", "") + directory_to_save = error_directory ) ) expect_error( download_merra2( - date_start = "1900-01-01", + date = c("1900-01-01", "2023-09-01"), collection = "inst1_2d_asm_Nx", - directory_to_save = testthat::test_path("..", "testdata/", ""), + directory_to_save = error_directory, acknowledgement = TRUE, remove_command = TRUE ) ) file.remove( testthat::test_path( - "../testdata", "merra2_1900-01-01_2023-09-01_wget_commands.txt" + "..", "testdata", "error_temp", + "merra2_1900-01-01_2023-09-01_wget_commands.txt" ) ) sink() expect_error( download_hms( - date_start = "1900-01-01", - directory_to_save = testthat::test_path("..", "testdata/", ""), + date = c("1900-01-01", "2018-01-01"), + directory_to_save = error_directory, acknowledgement = TRUE ) ) expect_error( download_gridmet( - year_start = 1900, + year = c(1900, 2022), variables = "Precipitation", acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", "") + directory_to_save = error_directory ) ) expect_error( download_terraclimate( - year_start = 1900, + year = c(1900, 2022), variables = "Wind Speed", acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", "") + directory_to_save = error_directory ) ) + unlink(error_directory, recursive = TRUE) }) testthat::test_that("EPA AQS download URLs have HTTP status 200.", { @@ -121,8 +115,7 @@ testthat::test_that("EPA AQS download URLs have HTTP status 200.", { directory_to_save <- testthat::test_path("..", "testdata", "aqs_temp") # run download function download_data(dataset_name = "aqs", - year_start = year_start, - year_end = year_end, + year = c(year_start, year_end), directory_to_save = directory_to_save, acknowledgement = TRUE, unzip = FALSE, @@ -160,6 +153,7 @@ testthat::test_that("EPA AQS download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) # Ecoregion tests #### @@ -224,7 +218,7 @@ testthat::test_that("Ecoregion download URLs have HTTP status 200.", { epa_certificate_path = certificate ) ) - + unlink(directory_to_save, recursive = TRUE) }) # GEOS-CF tests #### @@ -233,17 +227,15 @@ testthat::test_that("GEOS-CF download URLs have HTTP status 200.", { withr::local_package("stringr") # function parameters date_start <- "2019-09-09" - date_end <- "2019-09-21" + date_end <- "2019-09-09" collections <- c("aqc_tavg_1hr_g1440x721_v1", "chm_inst_1hr_g1440x721_p23") - directory_to_save <- testthat::test_path("..", "testdata/", "") - directory_to_save2 <- testthat::test_path("..", "testdata", "geos_temp") + directory_to_save <- testthat::test_path("..", "testdata", "geos_temp/") # run download function testthat::expect_no_error( download_data(dataset_name = "geos", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), collection = collections, directory_to_save = directory_to_save, acknowledgement = TRUE, @@ -266,19 +258,10 @@ testthat::test_that("GEOS-CF download URLs have HTTP status 200.", { test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) - testthat::expect_no_error( - download_data(dataset_name = "geos", - date_start = date_start, - date_end = date_end, - collection = collections, - directory_to_save = directory_to_save2, - acknowledgement = TRUE, - remove_command = TRUE, - download = FALSE) - ) # remove file with commands after test file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) # GMTED tests #### @@ -357,13 +340,11 @@ testthat::test_that("MERRA2 download URLs have HTTP status 200.", { date_start <- "2022-02-14" date_end <- "2022-03-08" collections <- c("inst1_2d_asm_Nx", "inst3_3d_asm_Np") - directory_to_save <- testthat::test_path("..", "testdata/", "") - directory_to_save2 <- testthat::test_path("..", "testdata", "hej") + directory_to_save <- testthat::test_path("..", "testdata", "merra2_temp/") # run download function testthat::expect_no_error( download_data(dataset_name = "merra2", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), collection = collections, directory_to_save = directory_to_save, acknowledgement = TRUE, @@ -386,18 +367,9 @@ testthat::test_that("MERRA2 download URLs have HTTP status 200.", { test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) - testthat::expect_no_error( - download_data(dataset_name = "merra2", - date_start = date_start, - date_end = date_end, - collection = collections, - directory_to_save = directory_to_save2, - acknowledgement = TRUE, - remove_command = TRUE, - download = FALSE) - ) # remove file with commands after test file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) # MERRA2 Collection error test #### @@ -415,26 +387,25 @@ testthat::test_that("MERRA2 returns message with unrecognized collection.", { ) }) -## NARR Monolevel #### -testthat::test_that("NARR monolevel download URLs have HTTP status 200.", { +## NARR (monolevel and pressure level) +testthat::test_that("NARR download URLs have HTTP status 200.", { withr::local_package("httr") withr::local_package("stringr") # function parameters year_start <- 2018 year_end <- 2018 - variables <- c("weasd", "air.2m") - directory_to_save <- testthat::test_path("..", "testdata/", "") + variables <- c("weasd", "omega", "soill") # includes monolevel, pressure level, subsurface + directory_to_save <- testthat::test_path("..", "testdata", "narr_temp/") # run download function - download_data(dataset_name = "narr_monolevel", - year_start = year_start, - year_end = year_end, + download_data(dataset_name = "narr", + year = c(year_start, year_end), variables = variables, directory_to_save = directory_to_save, acknowledgement = TRUE, download = FALSE) # define path with commands commands_path <- paste0(directory_to_save, - "narr_monolevel_", + "narr_", year_start, "_", year_end, "_curl_commands.txt") # import commands @@ -449,64 +420,26 @@ testthat::test_that("NARR monolevel download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) -testthat::test_that("NARR monolevel error with invalid years.", { +testthat::test_that("NARR error with invalid years.", { testthat::expect_error( download_data( - dataset_name = "narr_monolevel", + dataset_name = "narr", variables = "weasd", - year_start = 10, - year_end = 11, + year = c(10, 11), acknowledgement = TRUE, directory_to_save = testthat::test_path("..", "testdata/", "") ) ) }) -# NARR -- p-levels #### -testthat::test_that("NARR p-levels download URLs have HTTP status 200.", { - withr::local_package("httr") - withr::local_package("stringr") - # function parameters - year_start <- 2020 - year_end <- 2021 - variables <- c("shum", "omega") - directory_to_save <- testthat::test_path("..", "testdata/", "") - directory_to_save2 <- testthat::test_path("..", "testdata", "hej") - # run download function - download_data(dataset_name = "narr_p_levels", - year_start = year_start, - year_end = year_end, - variables = variables, - directory_to_save = directory_to_save, - acknowledgement = TRUE, - download = FALSE) - # define file path with commands - commands_path <- paste0(directory_to_save, - "narr_p_levels_", - year_start, "_", year_end, - "_curl_commands.txt") - # import commands - commands <- read_commands(commands_path = commands_path) - # extract urls - urls <- extract_urls(commands = commands, position = 6) - # check HTTP URL status - url_status <- check_urls(urls = urls, size = 10L, method = "HEAD") - # implement unit tests - test_download_functions(directory_to_save = directory_to_save, - commands_path = commands_path, - url_status = url_status) - download_data(dataset_name = "narr_p_levels", - year_start = year_start, - year_end = year_end, - variables = variables, - directory_to_save = directory_to_save2, - acknowledgement = TRUE, - remove_command = TRUE, - download = FALSE) - # remove file with commands after test - file.remove(commands_path) +#### NARR variable sorting function +testthat::test_that("narr_variable with unrecognized variable.", { + testthat::expect_error( + narr_variable("uNrEcOgNiZed") + ) }) testthat::test_that("NOAA HMS Smoke download URLs have HTTP status 200.", { @@ -520,8 +453,7 @@ testthat::test_that("NOAA HMS Smoke download URLs have HTTP status 200.", { for (d in seq_along(data_formats)) { # run download function download_data(dataset_name = "smoke", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), data_format = data_formats[d], directory_to_save = directory_to_save, acknowledgement = TRUE, @@ -567,15 +499,17 @@ testthat::test_that("NOAA HMS Smoke download URLs have HTTP status 200.", { }) testthat::test_that("download_hms error for unzip and directory.", { + error_directory <- testthat::test_path("..", "testdata", "error_temp/") testthat::expect_error( download_data( dataset_name = "hms", acknowledgement = TRUE, - directory_to_save = testthat::test_path("..", "testdata/", ""), + directory_to_save = error_directory, unzip = FALSE, remove_zip = TRUE ) ) + unlink(error_directory, recursive = TRUE) }) testthat::test_that("NLCD download URLs have HTTP status 200.", { @@ -626,8 +560,6 @@ testthat::test_that("NLCD download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) - # remove temporary nlcd - unlink(directory_to_save, recursive = TRUE) } testthat::expect_error( download_data(dataset_name = "nlcd", @@ -640,6 +572,8 @@ testthat::test_that("NLCD download URLs have HTTP status 200.", { unzip = FALSE, remove_zip = FALSE) ) + # remove temporary nlcd + unlink(directory_to_save, recursive = TRUE) }) testthat::test_that("SEDAC groads download URLs have HTTP status 200.", { @@ -689,8 +623,6 @@ testthat::test_that("SEDAC groads download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) - # remove temporary groads - unlink(directory_to_save, recursive = TRUE) } } @@ -705,14 +637,16 @@ testthat::test_that("SEDAC groads download URLs have HTTP status 200.", { remove_zip = FALSE, remove_command = TRUE) ) + # remove temporary groads + unlink(directory_to_save, recursive = TRUE) }) testthat::test_that("SEDAC population download URLs have HTTP status 200.", { withr::local_package("httr") withr::local_package("stringr") # function parameters - years <- c("2020") - data_formats <- c("GeoTIFF") + years <- c("2020", "all") + data_formats <- c("GeoTIFF", "ASCII") data_resolutions <- cbind(c("30 second"), c("30_sec")) directory_to_save <- testthat::test_path("..", "testdata", "pop_temp") @@ -771,7 +705,7 @@ testthat::test_that("SEDAC population download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) - # remove temporary groads + # remove temporary population unlink(directory_to_save, recursive = TRUE) } } @@ -782,11 +716,10 @@ testthat::test_that("SEDAC population data types are coerced.", { withr::local_package("httr") withr::local_package("stringr") # function parameters - year <- c("totpop") + year <- c("all") data_formats <- c("GeoTIFF", "ASCII", "netCDF") data_resolutions <- c("30 second", "2pt5_min") - directory_to_download <- testthat::test_path("..", "testdata/", "") - directory_to_save <- testthat::test_path("..", "testdata/", "") + directory_to_save <- testthat::test_path("..", "testdata", "pop_temp/") for (f in seq_along(data_formats)) { download_data(dataset_name = "sedac_population", year = year, @@ -798,9 +731,9 @@ testthat::test_that("SEDAC population data types are coerced.", { unzip = FALSE, remove_zip = FALSE, remove_command = FALSE) - commands_path <- paste0(directory_to_download, + commands_path <- paste0(directory_to_save, "sedac_population_", - year, + "totpop", "_", data_resolutions[2], "_", @@ -813,12 +746,12 @@ testthat::test_that("SEDAC population data types are coerced.", { # check HTTP URL status url_status <- check_urls(urls = urls, size = 1L, method = "GET") # implement unit tests - test_download_functions(directory_to_download = directory_to_download, - directory_to_save = directory_to_save, + test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) # remove file with commands after test file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) } }) @@ -875,6 +808,7 @@ testthat::test_that("Koppen Geiger download URLs have HTTP status 200.", { file.remove(commands_path) } } + unlink(directory_to_save, recursive = TRUE) }) testthat::test_that("MODIS-MOD09GA download URLs have HTTP status 200.", { @@ -893,8 +827,7 @@ testthat::test_that("MODIS-MOD09GA download URLs have HTTP status 200.", { date_end <- paste0(years[y], "-06-24") # run download function download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = version, horizontal_tiles = horizontal_tiles, @@ -945,8 +878,7 @@ testthat::test_that("MODIS-MOD06L2 download URLs have HTTP status 200.", { testthat::expect_error( kax <- download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = version, horizontal_tiles = horizontal_tiles, @@ -972,8 +904,7 @@ testthat::test_that("MODIS-MOD06L2 download URLs have HTTP status 200.", { write.csv(faux_urls, mod06_scenes, row.names = FALSE) download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = version, horizontal_tiles = horizontal_tiles, @@ -1028,8 +959,7 @@ testthat::test_that("MODIS download error cases.", { # no token testthat::expect_no_error( download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = version, horizontal_tiles = horizontal_tiles, @@ -1044,8 +974,7 @@ testthat::test_that("MODIS download error cases.", { # no token testthat::expect_error( download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = version, horizontal_tiles = horizontal_tiles, @@ -1060,8 +989,7 @@ testthat::test_that("MODIS download error cases.", { # year difference between date_start and date_end testthat::expect_error( download_data(dataset_name = "modis", - date_start = date_start, - date_end = "2024-03-28", + date = c(date_start, "2024-03-28"), product = "MOD11A1", version = version, horizontal_tiles = horizontal_tiles, @@ -1076,8 +1004,7 @@ testthat::test_that("MODIS download error cases.", { # null version testthat::expect_error( download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = NULL, horizontal_tiles = horizontal_tiles, @@ -1092,8 +1019,7 @@ testthat::test_that("MODIS download error cases.", { # invalid tile range (horizontal) testthat::expect_error( download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = "61", horizontal_tiles = c(-13, -3), @@ -1108,8 +1034,7 @@ testthat::test_that("MODIS download error cases.", { # invalid tile range (horizontal) testthat::expect_error( download_data(dataset_name = "modis", - date_start = date_start, - date_end = date_end, + date = c(date_start, date_end), product = product, version = "61", horizontal_tiles = horizontal_tiles, @@ -1150,7 +1075,7 @@ testthat::test_that("EPA TRI download URLs have HTTP status 200.", { withr::local_package("httr") withr::local_package("stringr") # function parameters - directory_to_save <- testthat::test_path("..", "testdata/", "") + directory_to_save <- testthat::test_path("..", "testdata", "tri_temp/") # run download function download_data(dataset_name = "tri", directory_to_save = directory_to_save, @@ -1182,6 +1107,7 @@ testthat::test_that("EPA TRI download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) @@ -1193,12 +1119,12 @@ testthat::test_that("EPA NEI (AADT) download URLs have HTTP status 200.", { certificate <- system.file("extdata/cacert_gaftp_epa.pem", package = "amadeus") # run download function - year_target <- c(2017L, 2020L) + year <- c(2017L, 2020L) download_data(dataset_name = "nei", directory_to_save = directory_to_save, acknowledgement = TRUE, download = FALSE, - year_target = year_target, + year = year, remove_command = FALSE, epa_certificate_path = certificate ) @@ -1214,7 +1140,7 @@ testthat::test_that("EPA NEI (AADT) download URLs have HTTP status 200.", { commands_path <- paste0( download_sanitize_path(directory_to_save), "NEI_AADT_", - paste(year_target, collapse = "-"), + paste(year, collapse = "-"), "_", Sys.Date(), "_wget_commands.txt" @@ -1238,12 +1164,45 @@ testthat::test_that("EPA NEI (AADT) download URLs have HTTP status 200.", { unlink(directory_to_save, recursive = TRUE) }) +testthat::test_that("EPA NEI (AADT) download LIVE.", { + withr::local_package("httr") + withr::local_package("stringr") + # function parameters + directory_to_save <- testthat::test_path("..", "testdata", "nei_live") + certificate <- system.file("extdata/cacert_gaftp_epa.pem", + package = "amadeus") + # run download function + year <- c(2017L, 2020L) + testthat::expect_no_error( + download_data(dataset_name = "nei", + directory_to_save = directory_to_save, + acknowledgement = TRUE, + download = TRUE, + year = year, + remove_command = FALSE, + epa_certificate_path = certificate, + unzip = TRUE + ) + ) + testthat::expect_equal( + length(list.files(paste0(directory_to_save, "/zip_files"))), 2 + ) + testthat::expect_equal( + length(list.files( + paste0(directory_to_save, "/data_files"), + recursive = TRUE) + ), 12 + ) + # remove temporary nei + unlink(directory_to_save, recursive = TRUE) +}) + testthat::test_that("Test error cases in EPA gaftp sources 1", { withr::local_package("httr") withr::local_package("stringr") # function parameters tdir <- tempdir() - directory_to_save <- testthat::test_path("..", "testdata/", "") + directory_to_save <- testthat::test_path("..", "testdata", "epa_temp/") certificate <- file.path(tdir, "cacert_gaftp_epa.pem") # remove if there is a preexisting file if (file.exists(certificate)) { @@ -1252,13 +1211,13 @@ testthat::test_that("Test error cases in EPA gaftp sources 1", { } # run download function - year_target <- c(2017L) + year <- c(2017L) testthat::expect_message( download_data(dataset_name = "nei", directory_to_save = directory_to_save, acknowledgement = TRUE, download = FALSE, - year_target = year_target, + year = year, remove_command = FALSE, epa_certificate_path = certificate ) @@ -1267,7 +1226,7 @@ testthat::test_that("Test error cases in EPA gaftp sources 1", { commands_path <- paste0( directory_to_save, "NEI_AADT_", - paste(year_target, collapse = "-"), + paste(year, collapse = "-"), "_", Sys.Date(), "_wget_commands.txt" @@ -1275,6 +1234,7 @@ testthat::test_that("Test error cases in EPA gaftp sources 1", { # remove file with commands after test testthat::expect_true(file.exists(commands_path)) file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) testthat::test_that("Test error cases in EPA gaftp sources 2", { @@ -1282,7 +1242,7 @@ testthat::test_that("Test error cases in EPA gaftp sources 2", { withr::local_package("stringr") # function parameters tdir <- tempdir(check = TRUE) - directory_to_save <- testthat::test_path("..", "testdata/", "") + directory_to_save <- testthat::test_path("..", "testdata", "epa_temp/") certificate <- file.path(tdir, "cacert_gaftp_epa.pem") # remove if there is a preexisting file if (file.exists(certificate)) { @@ -1317,6 +1277,7 @@ testthat::test_that("Test error cases in EPA gaftp sources 2", { # remove file with commands after test testthat::expect_true(file.exists(commands_path)) file.remove(commands_path) + unlink(directory_to_save, recursive = TRUE) }) @@ -1366,8 +1327,7 @@ testthat::test_that("download_hms LIVE run.", { # run download function download_data( dataset_name = "hms", - date_start = date, - date_end = date, + date = c(date, date), directory_to_save = directory, acknowledgement = TRUE, download = TRUE, @@ -1395,11 +1355,10 @@ testthat::test_that("gridmet download URLs have HTTP status 200.", { year_end <- 2023 variables <- "Precipitation" directory_to_save <- - testthat::test_path("..", "testdata", "gridmet", "tmp") + testthat::test_path("..", "testdata", "gridmet_temp/") # run download function download_data(dataset_name = "gridmet", - year_start = year_start, - year_end = year_end, + year = c(year_start, year_end), variables = variables, directory_to_save = directory_to_save, acknowledgement = TRUE, @@ -1421,8 +1380,7 @@ testthat::test_that("gridmet download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) - file.remove(list.files(directory_to_save, full.names = TRUE)) - file.remove(directory_to_save, recursive = TRUE) + unlink(directory_to_save, recursive = TRUE) }) testthat::test_that("gridmet error with invalid years.", { @@ -1430,8 +1388,7 @@ testthat::test_that("gridmet error with invalid years.", { download_data( dataset_name = "gridmet", variables = "Precipitation", - year_start = 10, - year_end = 11, + year = c(10, 11), acknowledgement = TRUE, directory_to_save = testthat::test_path("..", "testdata", "gridmet", "tmp") @@ -1444,8 +1401,7 @@ testthat::test_that("gridmet error with invalid variables", { download_data( dataset_name = "gridmet", variables = "temp", - year_start = 2018, - year_end = 2018, + year = c(2018, 2018), acknowledgement = TRUE, directory_to_save = testthat::test_path("..", "testdata", "gridmet", "tmp") @@ -1461,11 +1417,10 @@ testthat::test_that("terraclimate download URLs have HTTP status 200.", { year_end <- 2023 variables <- "Precipitation" directory_to_save <- - testthat::test_path("..", "testdata", "terraclimate", "tmp") + testthat::test_path("..", "testdata", "terraclimate_temp/") # run download function download_data(dataset_name = "terraclimate", - year_start = year_start, - year_end = year_end, + year = c(year_start, year_end), variables = variables, directory_to_save = directory_to_save, acknowledgement = TRUE, @@ -1487,8 +1442,7 @@ testthat::test_that("terraclimate download URLs have HTTP status 200.", { url_status = url_status) # remove file with commands after test file.remove(commands_path) - file.remove(list.files(directory_to_save, full.names = TRUE)) - file.remove(directory_to_save, recursive = TRUE) + unlink(directory_to_save, recursive = TRUE) }) testthat::test_that("terraclimate error with invalid years.", { @@ -1496,8 +1450,7 @@ testthat::test_that("terraclimate error with invalid years.", { download_data( dataset_name = "terraclimate", variables = "Precipitation", - year_start = 10, - year_end = 11, + year = c(10, 11), acknowledgement = TRUE, directory_to_save = testthat::test_path("..", "testdata", "terraclimate", "tmp") @@ -1510,8 +1463,7 @@ testthat::test_that("terraclimate error with invalid variables", { download_data( dataset_name = "gridmet", variables = "temp", - year_start = 2018, - year_end = 2018, + year = c(2018, 2018), acknowledgement = TRUE, directory_to_save = testthat::test_path("..", "testdata", "terraclimate", "tmp") @@ -1537,7 +1489,7 @@ testthat::test_that("download_cropscape generates correct download commands (GMU withr::local_package("stringr") # Set up test data year <- 2010 - directory_to_save <- testthat::test_path("../testdata/") + directory_to_save <- testthat::test_path("..", "testdata", "cps_temp/") # Call the function testthat::expect_no_error( @@ -1568,13 +1520,12 @@ testthat::test_that("download_cropscape generates correct download commands (GMU # check HTTP URL status url_status <- check_urls(urls = urls, size = 1L, method = "HEAD") # implement unit tests - test_download_functions(directory_to_download = directory_to_save, - directory_to_save = directory_to_save, + test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) # remove file with commands after test file.remove(commands_path) - + unlink(directory_to_save, recursive = TRUE) }) @@ -1583,7 +1534,7 @@ test_that("download_cropscape generates correct download commands (USDA)", { withr::local_package("stringr") # Set up test data year <- 2010 - directory_to_save <- testthat::test_path("../testdata/") + directory_to_save <- testthat::test_path("..", "testdata", "cps_temp/") # Call the function testthat::expect_no_error( @@ -1614,13 +1565,12 @@ test_that("download_cropscape generates correct download commands (USDA)", { # check HTTP URL status url_status <- check_urls(urls = urls, size = 1L, method = "HEAD") # implement unit tests - test_download_functions(directory_to_download = directory_to_save, - directory_to_save = directory_to_save, + test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) # remove file with commands after test file.remove(commands_path) - + unlink(directory_to_save, recursive = TRUE) }) @@ -1637,7 +1587,7 @@ testthat::test_that("download_prism downloads the correct data files", { element <- sample(element, 1) data_type <- "ts" format <- "nc" - directory_to_save <- testthat::test_path("..", "testdata/") + directory_to_save <- testthat::test_path("..", "testdata", "prism_temp/") acknowledgement <- TRUE download <- FALSE remove_command <- FALSE @@ -1686,8 +1636,7 @@ testthat::test_that("download_prism downloads the correct data files", { # check HTTP URL status url_status <- check_urls(urls = urls, size = 1L, method = "HEAD") # implement unit tests - test_download_functions(directory_to_download = directory_to_save, - directory_to_save = directory_to_save, + test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) # remove file with commands after test @@ -1698,7 +1647,7 @@ testthat::test_that("download_prism downloads the correct data files", { element <- "soltotal" data_type <- "ts" format <- "nc" - directory_to_save <- testthat::test_path("..", "testdata/") + directory_to_save <- testthat::test_path("..", "testdata", "prism_temp/") acknowledgement <- TRUE download <- FALSE remove_command <- FALSE @@ -1714,7 +1663,7 @@ testthat::test_that("download_prism downloads the correct data files", { download = download, remove_command = remove_command )) - + unlink(directory_to_save, recursive = TRUE) }) @@ -1754,7 +1703,7 @@ testthat::test_that("download_huc works", { withr::local_package("httr") - directory_to_save <- testthat::test_path("..", "testdata/") + directory_to_save <- testthat::test_path("..", "testdata", "huc_temp/") allregions <- c("Lower48", "Islands") alltypes <- c("Seamless", "OceanCatchment") @@ -1786,8 +1735,7 @@ testthat::test_that("download_huc works", # check HTTP URL status url_status <- check_urls(urls = urls, size = 1L, method = "HEAD") # implement unit tests - test_download_functions(directory_to_download = directory_to_save, - directory_to_save = directory_to_save, + test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) # remove file with commands after test @@ -1805,6 +1753,7 @@ testthat::test_that("download_huc works", unzip = TRUE ) ) + unlink(directory_to_save, recursive = TRUE) }) @@ -1818,7 +1767,7 @@ testthat::test_that( ) product <- "no2_s5p.l3.trop.tmwm" format <- "p50_p90_2km*.*tif" - directory_to_save <- testthat::test_path("..", "testdata/") + directory_to_save <- testthat::test_path("..", "testdata", "olm_temp/") acknowledgement <- TRUE download <- FALSE @@ -1848,13 +1797,12 @@ testthat::test_that( # check HTTP URL status url_status <- check_urls(urls = urls, size = 1L, method = "HEAD") # implement unit tests - test_download_functions(directory_to_download = directory_to_save, - directory_to_save = directory_to_save, + test_download_functions(directory_to_save = directory_to_save, commands_path = commands_path, url_status = url_status) # remove file with commands after test file.remove(commands_path) - + unlink(directory_to_save, recursive = TRUE) } ) diff --git a/tests/testthat/test-manipulate_spacetime_data.R b/tests/testthat/test-manipulate_spacetime_data.R index ee759f01..b22a2ee1 100644 --- a/tests/testthat/test-manipulate_spacetime_data.R +++ b/tests/testthat/test-manipulate_spacetime_data.R @@ -598,3 +598,15 @@ testthat::test_that("sftime_as_spatrds works as expected", { rename_time(mysft, "date") testthat::expect_no_error(sftime_as_spatrds(mysft)) }) + +testthat::test_that("as_mysftime with time-varying SpatRasterDataset.", { + m1 <- terra::rast(matrix(1:100, nrow = 10)) + terra::time(m1) <- as.Date("2024-01-01") + m2 <- terra::rast(matrix(1:100, nrow = 10)) + terra::time(m2) <- as.Date("2024-01-02") + m3 <- terra::sds(c(m1, m2)) + + testthat::expect_error( + as_mysftime(m3) + ) +}) diff --git a/tests/testthat/test-process.R b/tests/testthat/test-process.R index 02e655ca..0a77bf29 100644 --- a/tests/testthat/test-process.R +++ b/tests/testthat/test-process.R @@ -37,10 +37,10 @@ testthat::test_that("test generic process_covariates", { full.names = TRUE ) - corn <- process_bluemarble_corners() + corn <- process_blackmarble_corners() testthat::expect_warning( bm_proc <- process_covariates( - covariate = "bluemarble", + covariate = "blackmarble", path = path_vnp46[1], tile_df = corn, date = "2018-08-13" @@ -48,7 +48,7 @@ testthat::test_that("test generic process_covariates", { ) testthat::expect_warning( process_covariates( - covariate = "Bluemarble", + covariate = "Blackmarble", path = path_vnp46[1], tile_df = corn, date = "2018-08-13" @@ -56,7 +56,7 @@ testthat::test_that("test generic process_covariates", { ) testthat::expect_warning( process_covariates( - covariate = "BLUEMARBLE", + covariate = "BLACKMARBLE", path = path_vnp46[1], tile_df = corn, date = "2018-08-13" @@ -66,7 +66,7 @@ testthat::test_that("test generic process_covariates", { covar_types <- c("modis_swath", "modis_merge", "koppen-geiger", - "bluemarble", + "blackmarble", "koeppen-geiger", "koppen", "koeppen", "geos", "dummies", "gmted", "hms", "smoke", @@ -280,14 +280,14 @@ testthat::test_that("VNP46 preprocess tests", { ) testthat::expect_no_error( - corn <- process_bluemarble_corners() + corn <- process_blackmarble_corners() ) testthat::expect_error( - process_bluemarble_corners(hrange = c(99, 104)) + process_blackmarble_corners(hrange = c(99, 104)) ) testthat::expect_warning( - vnp46_proc <- process_bluemarble( + vnp46_proc <- process_blackmarble( path = path_vnp46[1], tile_df = corn, date = "2018-08-13" @@ -297,7 +297,7 @@ testthat::test_that("VNP46 preprocess tests", { testthat::expect_equal(terra::nlyr(vnp46_proc), 1L) testthat::expect_warning( - vnp46_proc2 <- process_bluemarble( + vnp46_proc2 <- process_blackmarble( path = path_vnp46[1], tile_df = corn, subdataset = c(3L, 5L), @@ -309,7 +309,7 @@ testthat::test_that("VNP46 preprocess tests", { testthat::expect_equal(terra::nlyr(vnp46_proc2), 2L) testthat::expect_error( - process_bluemarble( + process_blackmarble( path = path_vnp46[1], tile_df = corn, date = "2018~08~13" @@ -415,9 +415,13 @@ testthat::test_that("read ecoregion", { path_eco <- testthat::test_path("..", "testdata", "eco_l3_clip.gpkg") testthat::expect_no_error( - process_ecoregion(path_eco) + eco <- process_ecoregion(path_eco) ) + # test with cropping extent + testthat::expect_no_error( + process_ecoregion(path_eco, extent = terra::ext(eco)) + ) ecotemp <- sf::st_read(path_eco) # nolint start addpoly <- @@ -447,6 +451,14 @@ testthat::test_that("process_nlcd tests", { testthat::expect_no_error( nlcd19 <- process_nlcd(path = path_nlcd19, year = 2019) ) + # test with extent cropping + testthat::expect_no_error( + nlcd19_ext <- process_nlcd( + path = path_nlcd19, + year = 2019, + extent = terra::ext(-1580000, -1520000, 1920000, 1980000) + ) + ) testthat::expect_s4_class(nlcd19, "SpatRaster") testthat::expect_equal(unname(terra::metags(nlcd19, name = "year")), "2019") @@ -463,6 +475,14 @@ testthat::test_that("process_nlcd tests", { testthat::expect_error( process_nlcd(path_nlcd19, year = 2020) ) + # make duplicate with tif and img + tdir <- tempdir() + dir.create(paste0(tdir, "/nlcd_all")) + file.create(paste0(tdir, "/nlcd_all/nlcd_2019_land_cover_20240624.tif")) + file.create(paste0(tdir, "/nlcd_all/nlcd_2019_land_cover_20240624.img")) + testthat::expect_error( + process_nlcd(path = paste0(tdir, "/nlcd_all"), year = 2019) + ) }) @@ -477,7 +497,20 @@ testthat::test_that("process_koppen_geiger tests", { kgeiger <- process_koppen_geiger(path_kgeiger) ) + # test with cropping extent + testthat::expect_no_error( + kgeiger_ext <- process_koppen_geiger( + path_kgeiger, + extent = terra::ext(kgeiger) + ) + ) testthat::expect_s4_class(kgeiger, "SpatRaster") + + path_kgeiger_f <- + testthat::test_path("../testdata", "kop", "Beck_KG_V1_future_0p5.tif") + testthat::expect_no_error( + kgeiger_f <- process_koppen_geiger(path_kgeiger_f) + ) }) # test TRI #### @@ -489,6 +522,15 @@ testthat::test_that("process_tri tests", { tri_r <- process_tri(path = path_tri) ) testthat::expect_s4_class(tri_r, "SpatVector") + + # test with cropping extent + testthat::expect_no_error( + tri_r_ext <- process_tri( + path = path_tri, + extent = terra::ext(tri_r) + ) + ) + testthat::expect_s4_class(tri_r, "SpatVector") }) # test NEI #### @@ -522,7 +564,9 @@ testthat::test_that("process_nei tests", { testthat::expect_error( process_nei(path_nei, year = 2020, county = path_cnty) ) - + testthat::expect_error( + process_nei("./EmPtY/pAtH", year = 2020, county = path_cnty) + ) }) @@ -602,6 +646,13 @@ testthat::test_that("process_sedac_population returns expected.", { any(c(0, 1) %in% dim(pop)[1:2]) ) } + # test with cropping extent + testthat::expect_no_error( + pop_ext <- process_sedac_population( + paths[1], + extent = terra::ext(pop) + ) + ) }) testthat::test_that("process_sedac_population returns null for netCDF.", { @@ -629,56 +680,68 @@ testthat::test_that("sedac_codes", { # test HMS #### -testthat::test_that("process_hms returns expected.", { +testthat::test_that("process_hms with present polygons", { withr::local_package("terra") - densities <- c( - "Light", - "Medium", - "Heavy" - ) # expect function testthat::expect_true( is.function(process_hms) ) - for (d in seq_along(densities)) { - hms <- - process_hms( - date = c("2022-06-10", "2022-06-11"), - variable = densities[d], - path = testthat::test_path( - "..", - "testdata", - "hms" - ) + hms <- + process_hms( + date = c("2022-06-10", "2022-06-13"), + path = testthat::test_path( + "..", + "testdata", + "hms" ) - # expect output is a SpatVector or character - testthat::expect_true( - class(hms)[1] %in% c("SpatVector", "character") ) - if (class(hms)[1] == "SpatVector") { - # expect non-null coordinate reference system - testthat::expect_false( - is.null(terra::crs(hms)) - ) - # expect two columns - testthat::expect_true( - ncol(hms) == 2 - ) - # expect density and date column - testthat::expect_true( - all(c("Density", "Date") %in% names(hms)) - ) - } else if (class(hms)[1] == "character") { - # expect first is density type - testthat::expect_true( - hms[1] %in% c("Light", "Medium", "Heavy") - ) - # expect other elements are 10 character dates - testthat::expect_true( - all(nchar(hms[2:length(hms)]) == 10) + # expect output is a SpatVector or character + testthat::expect_true( + methods::is(hms, "SpatVector") + ) + # expect non-null coordinate reference system + testthat::expect_false( + is.null(terra::crs(hms)) + ) + # expect two columns + testthat::expect_true( + ncol(hms) == 2 + ) + # expect density and date column + testthat::expect_true( + all(c("Density", "Date") %in% names(hms)) + ) + # test with cropping extent + testthat::expect_no_error( + hms_ext <- process_hms( + date = c("2022-06-10", "2022-06-11"), + path = testthat::test_path( + "..", + "testdata", + "hms" + ), + extent = terra::ext(hms) + ) + ) +}) + +testthat::test_that("process_hms with missing polygons (12/31/2018).", { + withr::local_package("terra") + # expect function + testthat::expect_true( + is.function(process_hms) + ) + hms <- + process_hms( + date = c("2018-12-31", "2018-12-31"), + path = testthat::test_path( + "..", + "testdata", + "hms" ) - } - } + ) + # expect character + testthat::expect_true(is.character(hms)) }) # test GMTED #### @@ -739,6 +802,21 @@ testthat::test_that("process_gmted returns expected.", { ) } } + # test with cropping extent + testthat::expect_no_error( + gmted_ext <- + process_gmted( + variable = c("Breakline Emphasis", "7.5 arc-seconds"), + path = + testthat::test_path( + "..", + "testdata", + "gmted", + "be75_grd" + ), + ext = terra::ext(gmted) + ) + ) }) testthat::test_that("import_gmted returns error with non-vector variable.", { @@ -835,6 +913,22 @@ testthat::test_that("process_narr returns expected.", { ) } } + # test with cropping extent + testthat::expect_no_error( + narr_ext <- + process_narr( + date = c("2018-01-01", "2018-01-01"), + variable = "omega", + path = + testthat::test_path( + "..", + "testdata", + "narr", + "omega" + ), + extent = terra::ext(narr) + ) + ) }) # test GEOS-CF #### @@ -901,6 +995,21 @@ testthat::test_that("process_geos returns expected.", { ) } } + # test with cropping extent + testthat::expect_no_error( + geos_ext <- process_geos( + date = c("2018-01-01", "2018-01-01"), + variable = "O3", + path = + testthat::test_path( + "..", + "testdata", + "geos", + "c" + ), + extent = terra::ext(geos) + ) + ) }) testthat::test_that("process_geos expected errors.", { @@ -1040,6 +1149,9 @@ testthat::test_that("process_locs_vector vector data and missing columns.", { testthat::test_that("process_aqs", { withr::local_package("terra") withr::local_package("data.table") + withr::local_package("sf") + withr::local_package("dplyr") + withr::local_options(list(sf_use_s2 = FALSE)) aqssub <- testthat::test_path( "..", @@ -1055,7 +1167,7 @@ testthat::test_that("process_aqs", { aqsft <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "full", + mode = "date-location", return_format = "terra" ) ) @@ -1063,7 +1175,7 @@ testthat::test_that("process_aqs", { aqsst <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "sparse", + mode = "available-data", return_format = "terra" ) ) @@ -1085,7 +1197,7 @@ testthat::test_that("process_aqs", { aqsfs <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "full", + mode = "date-location", return_format = "sf" ) ) @@ -1093,7 +1205,7 @@ testthat::test_that("process_aqs", { aqsss <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "sparse", + mode = "available-data", return_format = "sf" ) ) @@ -1113,7 +1225,7 @@ testthat::test_that("process_aqs", { aqsfd <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "full", + mode = "date-location", return_format = "data.table" ) ) @@ -1121,7 +1233,7 @@ testthat::test_that("process_aqs", { aqssd <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "sparse", + mode = "available-data", return_format = "data.table" ) ) @@ -1129,7 +1241,7 @@ testthat::test_that("process_aqs", { aqssdd <- process_aqs( path = aqssub, date = c("2022-02-04", "2022-02-28"), - mode = "sparse", + mode = "available-data", data_field = "Arithmetic.Mean", return_format = "data.table" ) @@ -1191,6 +1303,31 @@ testthat::test_that("process_aqs", { testthat::expect_error( process_aqs(path = aqssub, date = c("2021-08-15")) ) + testthat::expect_error( + process_aqs(path = aqssub, date = NULL) + ) + testthat::expect_no_error( + process_aqs( + path = aqssub, date = c("2022-02-04", "2022-02-28"), + mode = "available-data", return_format = "sf", + extent = c(-79, 33, -78, 36) + ) + ) + testthat::expect_no_error( + process_aqs( + path = aqssub, date = c("2022-02-04", "2022-02-28"), + mode = "available-data", return_format = "sf", + extent = c(-79, 33, -78, 36) + ) + ) + testthat::expect_warning( + process_aqs( + path = aqssub, date = c("2022-02-04", "2022-02-28"), + mode = "available-data", return_format = "data.table", + extent = c(-79, -78, 33, 36) + ), + "Extent is not applicable for data.table. Returning data.table..." + ) }) # test SEDAC GRoads #### @@ -1209,6 +1346,13 @@ testthat::test_that("test process_sedac_groads", { testthat::expect_error( process_sedac_groads(path = 1L) ) + # test with cropping extent + testthat::expect_no_error( + groads_ext <- process_sedac_groads( + path = testthat::test_path("../testdata/groads_test.shp"), + extent = terra::ext(groads) + ) + ) }) # test MERRA2 #### @@ -1244,12 +1388,6 @@ testthat::test_that("process_merra2 returns as expected.", { merra2_df$collection[c] ) ) - cat( - paste0( - names(merra2), - "\n" - ) - ) # expect output is SpatRaster expect_true( class(merra2)[1] == "SpatRaster" @@ -1283,6 +1421,22 @@ testthat::test_that("process_merra2 returns as expected.", { all(dim(merra2) == c(2, 3, 1)) ) } + class(merra2) + # test with cropping extent + testthat::expect_no_error( + merra2_ext <- process_merra2( + date = c("2018-01-01", "2018-01-01"), + variable = "CPT", + path = + testthat::test_path( + "..", + "testdata", + "merra2", + "inst1_2d_int_Nx" + ), + extent = terra::ext(merra2) + ) + ) }) # test GridMET #### @@ -1329,6 +1483,21 @@ testthat::test_that("process_gridmet returns expected.", { expect_true( dim(gridmet)[3] == 1 ) + # test with cropping extent + testthat::expect_no_error( + gridmet_ext <- process_gridmet( + date = c("2018-01-03", "2018-01-03"), + variable = "Precipitation", + path = + testthat::test_path( + "..", + "testdata", + "gridmet", + "pr" + ), + extent = terra::ext(gridmet) + ) + ) }) # test TerraClimate #### @@ -1375,131 +1544,20 @@ testthat::test_that("process_terraclimate returns expected.", { expect_true( dim(terraclimate)[3] == 1 ) -}) - -testthat::test_that("gridmet and terraclimate auxiliary functions.", { - # gridmet - gc1 <- process_gridmet_codes("all") - expect_true(ncol(gc1) == 2) - gc2 <- process_gridmet_codes("sph", invert = TRUE) - expect_true(class(gc2) == "character") - expect_true(nchar(gc2) > 7) - gc3 <- process_gridmet_codes("Near-Surface Specific Humidity") - expect_true(class(gc3) == "character") - expect_true(nchar(gc3) < 7) - # terraclimate - tc1 <- process_terraclimate_codes("all") - expect_true(ncol(gc1) == 2) - tc2 <- process_terraclimate_codes("aet", invert = TRUE) - expect_true(class(gc2) == "character") - expect_true(nchar(gc2) > 7) - tc3 <- process_terraclimate_codes("Actual Evapotranspiration") - expect_true(class(gc3) == "character") - expect_true(nchar(gc3) < 7) - # process_variable_codes - expect_no_error(process_variable_codes("sph", "gridmet")) - expect_no_error( - process_variable_codes("Near-Surface Specific Humidity", "gridmet") - ) - expect_error( - process_variable_codes("error", "gridmet") - ) - expect_no_error(process_variable_codes("aet", "terraclimate")) - expect_no_error( - process_variable_codes("Actual Evapotranspiration", "terraclimate") - ) - expect_error( - process_variable_codes("error", "terraclimate") - ) -}) - -testthat::test_that("process_gridmet returns expected.", { - withr::local_package("terra") - variable <- "Precipitation" - # expect function - expect_true( - is.function(process_gridmet) - ) - gridmet <- - process_gridmet( - date = c("2018-01-03", "2018-01-03"), - variable = variable, - path = - testthat::test_path( - "..", - "testdata", - "gridmet", - "pr" - ) - ) - # expect output is SpatRaster - expect_true( - class(gridmet)[1] == "SpatRaster" - ) - # expect values - expect_true( - terra::hasValues(gridmet) - ) - # expect non-null coordinate reference system - expect_false( - is.null(terra::crs(gridmet)) - ) - # expect lon and lat dimensions to be > 1 - expect_false( - any(c(0, 1) %in% dim(gridmet)[1:2]) - ) - # expect non-numeric and non-empty time - expect_false( - any(c("", 0) %in% terra::time(gridmet)) - ) - # expect dimensions according to levels - expect_true( - dim(gridmet)[3] == 1 - ) -}) - -testthat::test_that("process_terraclimate returns expected.", { - withr::local_package("terra") - variable <- "ppt" - # expect function - expect_true( - is.function(process_terraclimate) - ) - terraclimate <- - process_terraclimate( + # test with cropping extent + testthat::expect_no_error( + terraclimate_ext <- process_terraclimate( date = c("2018-01-01", "2018-01-01"), - variable = variable, + variable = "ppt", path = - testthat::test_path( - "..", - "testdata", - "terraclimate", - "ppt" - ) + testthat::test_path( + "..", + "testdata", + "terraclimate", + "ppt" + ), + extent = terra::ext(terraclimate) ) - # expect output is SpatRaster - expect_true( - class(terraclimate)[1] == "SpatRaster" - ) - # expect values - expect_true( - terra::hasValues(terraclimate) - ) - # expect non-null coordinate reference system - expect_false( - is.null(terra::crs(terraclimate)) - ) - # expect lon and lat dimensions to be > 1 - expect_false( - any(c(0, 1) %in% dim(terraclimate)[1:2]) - ) - # expect non-numeric and non-empty time - expect_false( - any(c("", 0) %in% terra::time(terraclimate)) - ) - # expect dimensions according to levels - expect_true( - dim(terraclimate)[3] == 1 ) }) @@ -1539,7 +1597,6 @@ testthat::test_that("gridmet and terraclimate auxiliary functions.", { ) }) - # test PRISM #### testthat::test_that( "process_prism returns a SpatRaster object with correct metadata", @@ -1581,6 +1638,16 @@ testthat::test_that( ) testthat::expect_error(process_prism(path_dir, element_bad, time)) testthat::expect_error(process_prism(path_dir, element, time_bad)) + + # test with cropping extent + testthat::expect_no_error( + result_ext <- process_prism( + path, + element, + time, + extent = terra::ext(result) + ) + ) } ) @@ -1599,6 +1666,13 @@ testthat::test_that( testthat::expect_no_error(result <- process_cropscape(filepath, year)) testthat::expect_no_error(process_cropscape(dirpath, year)) + # test with cropping extent + testthat::expect_no_error( + result_ext <- process_cropscape( + filepath, year, extent = terra::ext(result) + ) + ) + # Check the return type testthat::expect_true(inherits(result, "SpatRaster")) @@ -1669,6 +1743,17 @@ testthat::test_that("process_huc", # Call the function and expect an error testthat::expect_error(process_huc(path2)) + + # test with cropping extent + testthat::expect_no_error( + huc_ext <- process_huc( + path, + layer_name = "NHDPlus_test", + huc_level = "HUC_12", + huc_header = "030202", + extent = terra::ext(result) + ) + ) } ) @@ -1685,10 +1770,15 @@ testthat::test_that("process_olm", { testthat::expect_error( process_olm(path = 1L) ) + + # test with cropping extent + testthat::expect_no_error( + olm_ext <- process_olm(path = tmwm, extent = terra::ext(olm)) + ) }) # nolint end -## AUX tests #### +# AUX tests #### testthat::test_that("loc_radius tests", { withr::local_package("terra") withr::local_package("sf") @@ -1756,3 +1846,35 @@ testthat::test_that("process_locs_vector tests", { testthat::expect_true(terra::geomtype(dfdftr) == "points") testthat::expect_true(terra::geomtype(dfdftrb) == "polygons") }) + +# apply_extent +testthat::test_that("apply_extent tests", { + withr::local_package("terra") + withr::local_package("sf") + withr::local_options(list(sf_use_s2 = FALSE)) + + lon <- seq(-112, -101, length.out = 5) # create lon sequence + lat <- seq(33.5, 40.9, length.out = 5) # create lat sequence + df <- expand.grid("lon" = lon, "lat" = lat) # expand to regular grid + dfsf <- sf::st_as_sf( + df, + coords = c("lon", "lat"), + crs = "EPSG:4326", + remove = FALSE + ) + dftr <- terra::vect(dfsf) + + testthat::expect_no_error( + dftr1 <- apply_extent(dftr, c(-112, -101, 33.5, 40.9)) + ) + testthat::expect_no_error( + dfsftr <- apply_extent(dfsf, c(-112, -101, 33.5, 40.9)) + ) + testthat::expect_no_error( + dfdftr <- + apply_extent(df, c(-112, -101, 33.5, 40.9), geom = c("lon", "lat")) + ) + testthat::expect_s4_class(dftr1, "SpatVector") + testthat::expect_s3_class(dfsftr, "sf") + testthat::expect_s4_class(dfdftr, "SpatVector") +}) diff --git a/vignettes/download_functions.Rmd b/vignettes/download_functions.Rmd index f180a70a..5101f5fb 100644 --- a/vignettes/download_functions.Rmd +++ b/vignettes/download_functions.Rmd @@ -1,11 +1,11 @@ --- -title: "download_data and NASA EarthData Account" +title: "download_data" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{download_data and NASA EarthData Account} + %\VignetteIndexEntry{download_data} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} -date: "2024-05-02" +date: "2024-07-09" author: "Mitchell Manware" --- @@ -20,23 +20,37 @@ devtools::load_all("../") ## Motivation -The `data_download` function was developed to improve researchers' access to publicly available geospatial datasets. Although the data are already available online, using a web browser to manually download hundreds or thousands of data files is slow, arduous, and not efficiently repeatable. A function which downloads raw data files onto the user's machine allows for re +The `download_data` function was developed to improve researchers' access to publicly available environmental data. +Although the data are already available online, using a web browser to manually download hundreds or thousands of data files is slow, arduous, and not efficiently repeatable. +Additionally, as users may not be familiar with creating download recipes in Bash (Unix shell), `download_data` allows researchers to download data directly with `R`, a common coding language in the field of environmental health research. +Finally, function-izing data downloads is useful for repeated code or automated analysis pipelines. -Additionally, as users may not be familiar with creating download recipes in Bash (Unix shell), `data_download` allows researchers to download data directly with R, a common coding language in the field of environmental health research. Finally, function-izing data downloads is useful for repeated code or automated analysis pipelines. +## download_data -## data_download - -`data_download` is capable of accessing and downloading geospatial datasets, collections, and variables from a variety of sources. This wrapper function calls on source-specific data download functions, each utilizing a unique combination of input parameters, host URL, naming convention, and data formats. +`download_data` is acccesses and downloads environmental datasets, collections, and variables from a variety of sources. +This wrapper function calls source-specific data download functions, each utilizing a unique combination of input parameters, host URL, naming convention, and data formats. ```{r, echo = FALSE} functions <- c( - "download_aqs", "download_ecoregion", - "download_geos_cf_data", "download_gmted", - "download_koppen_geiger", "download_merra2", - "download_narr_monolevel", "download_narr_p_levels", - "download_nlcd", "download_hms", - "download_sedac_groads", "download_sedac_population", - "download_modis" + "download_aqs", + "download_ecoregion", + "download_geos_data", + "download_gmted", + "download_koppen_geiger", + "download_merra2", + "download_narr", + "download_nlcd", + "download_hms", + "download_sedac_groads", + "download_sedac_population", + "download_modis", + "download_terraclimate", + "download_gridmet", + "download_osm", + "download_prism", + "download_nei", + "download_tri", + "download_huc" ) source <- c( "US EPA Air Data Pre-Generated Data Files", @@ -48,16 +62,19 @@ source <- c( "NASA Modern-Era Retrospective analysis for Research and ", "Applications, Version 2 (MERRA-2)" ), - "NOAA NCEP North American Regional Reanalysis (NARR) (monolevel variables)", - paste0( - "NOAA NCEP North American Regional Reanalysis (NARR) (pressure ", - "levels variables)" - ), + "NOAA NCEP North American Regional Reanalysis (NARR)", "MRLC Consortium National Land Cover Database (NLCD)", "NOAA Hazard Mapping System Fire and Smoke Product", "NASA SEDAC Global Roads Open Access Data Set", "NASA SEDAC UN WPP-Adjusted Population Density", - "NASA Moderate Resolution Imaging Spectroradiometer (MODIS)" + "NASA Moderate Resolution Imaging Spectroradiometer (MODIS)", + "Climatology Lab TerraClimate", + "Climatology Lab GridMet", + "OpenGeoHub Foundation OpenLandMap", + "Parameter Elevation Regression on Independent Slopes Model (PRISM)", + "US EPA National Emissions Inventory (NEI)", + "US EPA Toxic Release Inventory (TRI) Program", + "USGS National Hydrography Dataset (NHD)" ) link <- c( @@ -68,7 +85,6 @@ link <- c( "https://www.nature.com/articles/sdata2018214", "https://gmao.gsfc.nasa.gov/reanalysis/MERRA-2/", "https://psl.noaa.gov/data/gridded/data.narr.html", - "https://psl.noaa.gov/data/gridded/data.narr.html", "https://www.mrlc.gov/data", "https://www.ospo.noaa.gov/Products/land/hms.html#0", paste0( @@ -80,8 +96,22 @@ link <- c( "population-density-adjusted-to-2015-unwpp-country-", "totals-rev11" ), - "https://modis.gsfc.nasa.gov/data/" + "https://modis.gsfc.nasa.gov/data/", + "https://www.climatologylab.org/terraclimate.html", + "https://www.climatologylab.org/gridmet.html", + "https://opengeohub.org/about-openlandmap/", + paste0( + "https://elibrary.asabe.org/abstract.asp??JID=3&", + "AID=3101&CID=t2000&v=43&i=6&T=1" + ), + "https://www.epa.gov/air-emissions-inventories", + paste0( + "https://www.epa.gov/toxics-release-inventory-tri-program/", + "tri-basic-data-files-calendar-years-1987-present" + ), + "https://www.sciencebase.gov/catalog/item/4f5545cce4b018de15819ca9" ) + source <- paste0( "[", source, @@ -91,14 +121,15 @@ source <- paste0( ) functions_sources <- data.frame(functions, source) -colnames(functions_sources) <- c("Function", "Source") -kable(functions_sources, +functions_sources_sorted <- functions_sources[order(functions_sources$source), ] +colnames(functions_sources_sorted) <- c("Download Function", "Data Source") +kable(functions_sources_sorted, caption = - "Source-Specific Download Functions and Sources" + "Source-specific download functions and data sources" ) ``` -It is important to note that `data_download` calls a source-specific function based on the `dataset_name` parameter. Using the source-specific function directly will return the exact same data (**if the parameters are the same**), but the error messages produced by each differ slightly/ +It is important to note that `download_data` calls a source-specific function based on the `dataset_name` parameter. Using the source-specific function directly will return the same data **if the parameters are the same**, but the error messages produced by each differ slightly. ### Parameters @@ -106,10 +137,10 @@ User-defined parameters differ based on the data source. Required parameters for ```{r} names(formals(download_hms)) -names(formals(download_narr_monolevel)) +names(formals(download_narr)) ``` -The two functions have different required parameters because `download_hms` uses a daily temporal resolution while `download_narr_monolevel` uses yearly, but they share some common, standard parameters. +The two functions have different required parameters because `download_hms` uses a daily temporal resolution while `download_narr` uses yearly, but they share some common, standard parameters. #### Standard parameters @@ -119,7 +150,8 @@ Four parameters are included in all of the data download functions. parameter <- c( "directory_to_save", "acknowledgement", - "download", "remove_command" + "download", + "remove_command" ) type <- c("Character", "Logical", "Logical", "Logical") description <- c( @@ -148,7 +180,7 @@ colnames(parameter_descriptions) <- c("Parameter", "Type", "Description") kable(parameter_descriptions) ``` -Additionally, the `dataset_name` parameter must be specified when using `data_download`, but is assumed when using a source-specific download function. +Additionally, the `dataset_name` parameter must be specified when using `download_data`, but is assumed when using a source-specific download function. ### Function Structure @@ -176,14 +208,13 @@ Cleaning the user-defined parameters is highly dependent on the parameters thems ```{r} # user defined parameters -date_start <- "2023-12-28" -date_end <- "2024-01-02" +dates <- c("2023-12-28", "2024-01-02") ``` ```{r} date_sequence <- seq( - as.Date(date_start, format = "%Y-%m-%d"), - as.Date(date_end, format = "%Y-%m-%d"), + as.Date(dates[1], format = "%Y-%m-%d"), + as.Date(dates[2], format = "%Y-%m-%d"), "day" ) date_sequence <- gsub("-", "", as.character(date_sequence)) @@ -326,7 +357,7 @@ system_command <- paste0( system_command ``` -Running the `system_command` deploys a "helper function", `download_run`, a function created to reduce repeated code across the source-specific download functions. The function takes two parameters, `system_command`, which indicates the command to be run, and `download`, a user-defined logical parameter. +Running the `system_command` deploys an "auxiliary" function, `download_run`, a function created to reduce repeated code across the source-specific download functions. The function takes two parameters, `system_command`, which indicates the command to be run, and `download`, a user-defined logical parameter. ```{r} download_run <- function( @@ -365,7 +396,7 @@ paste0("hms_smoke_Shapefile_", date_sequence, ".zip") #### 8. Zip files (if applicable) {#zip-files-if-applicable} -All of the source-specific data download functions follow this general pattern, but those functions which download zip files require additional steps to inflate and remove the downloaded zip files, if desired. Each of these two steps are run by helper functions, and they are run by the user-defined `unzip` and `remove_zip` parameters in `data_download`. +All of the source-specific data download functions follow this general pattern, but those functions which download zip files require additional steps to inflate and remove the downloaded zip files, if desired. Each of these two steps are run by helper functions, and they are run by the user-defined `unzip` and `remove_zip` parameters in `download_data`. `download_unzip` inflates zip files if `unzip = TRUE`, and skips inflation if `unzip = FALSE`. @@ -548,9 +579,8 @@ testthat::test_that( test_directory <- "./data/" # download download_data( - dataset_name = "noaa", - date_start = test_start, - date_end = test_end, + dataset_name = "hms", + date = c(test_start, test_end), data_format = "Shapefile", directory_to_save = test_directory, acknowledgement = TRUE, @@ -588,9 +618,8 @@ testthat::test_that( test_directory <- "../inst/extdata/" # download download_data( - dataset_name = "noaa", - date_start = test_start, - date_end = test_end, + dataset_name = "hms", + date = c(test_start, test_end), data_format = "Shapefile", directory_to_save = test_directory, acknowledgement = TRUE, @@ -619,10 +648,9 @@ testthat::test_that( ) ``` - Although the `testthat::test_that(...)` chunk contains 32 lines of code, the unit test is performed by `expect_true(all(url_status))`. In words, this line is expecting (`expect_true`) that all (`all`) of the sampled URLs return HTTP response status 200 (`url_status`). Since this expectation was met, the test passed! -For an alternate example, we can use a start and end date that are known to not have data. As the URLs associated with these dates do not exist, we expect the function will fail. This test utilizes `expect_error()` because the `data_download` wrapper function returns an error message if the underlying source-specific download function returns an error. +For an alternate example, we can use a start and end date that are known to not have data. As the URLs associated with these dates do not exist, we expect the function will fail. This test utilizes `expect_error()` because the `download_data` wrapper function returns an error message if the underlying source-specific download function returns an error. ```{r} testthat::test_that( @@ -635,9 +663,8 @@ testthat::test_that( # test for error testthat::expect_error( download_data( - dataset_name = "noaa", - date_start = test_start, - date_end = test_end, + dataset_name = "hms", + date = c(test_start, test_end), data_format = "Shapefile", directory_to_download = test_directory, directory_to_save = test_directory, @@ -653,7 +680,7 @@ testthat::test_that( ``` -This test utilizes `testthat::expect_error` because the `data_download` wrapper function returns an error message if the underlying source-specific download function returns an error. If we directly used the `download_hms` function, we would expect and receive an error. +This test utilizes `testthat::expect_error` because the `download_data` wrapper function returns an error message if the underlying source-specific download function returns an error. If we directly used the `download_hms` function, we would expect and receive an error. ```{r} testthat::test_that( @@ -666,8 +693,7 @@ testthat::test_that( # test for error testthat::expect_error( download_hms( - date_start = test_start, - date_end = test_end, + date = c(test_start, test_end), data_format = "Shapefile", directory_to_download = test_directory, directory_to_save = test_directory, @@ -701,8 +727,7 @@ names(formals(download_hms)) Define the parameters. ```{r} -date_start <- "2023-12-28" -date_end <- "2024-01-02" +dates <- c("2023-12-28", "2024-01-02") data_format <- "Shapefile" data_directory <- "./download_example/" acknowledgement <- TRUE @@ -717,9 +742,7 @@ Download the data. ```{r, eval = FALSE} download_data( dataset_name = "hms", - date_start = date_start, - date_end = date_end, - directory_to_download = data_directory, + date = dates, directory_to_save = data_directory, acknowledgement = acknowledgement, download = download, @@ -766,290 +789,7 @@ for (s in seq_along(date_sequence)) { zips ``` -## NASA EarthData Account - -As mentioned in [Motivation], `data_download` provides access to publicly available geospatial data. Although publicly available, some of the NASA data sources require a NASA EarthData Account. - -For example, the UN WPP-Adjusted population density data from NASA Socioeconomic Data and Applications Center (SEDAC) requires an EarthData account. Without an EarthData Account and the prerequisite files prepared, the data download functions will return an error. - -```{r, eval = FALSE} -download_data( - dataset_name = "sedac_population", - year = "2020", - data_format = "GeoTIFF", - data_resolution = "60 minute", - directory_to_download = "./sedac_population/", - directory_to_save = "./sedac_population", - acknowledgement = TRUE, - download = TRUE, - unzip = TRUE, - remove_zip = FALSE, - remove_command = TRUE -) -``` - -```{r, echo = FALSE} -to_cat <- - paste0( - "Downloading requested files...\n", - "Requested files have been downloaded.\n", - "Unzipping files...\n\n", - "Warning in unzip(file_name, exdir = directory_to_unzip): ", - "error 1 in extracting from zip file\n\n", - "Files unzipped and saved in ./sedac_population/.\n\n" - ) -cat(to_cat) -``` - -The downloaded file cannot be unzipped because the data was not downloaded properly. - -### Register or log in - -Visit [https://urs.earthdata.nasa.gov/](http://urs.earthdata.nasa.gov) to register for or log into a NASA EarthData account. - -![NASA EarthData Account Landing Page](images/NASA_EarthData_login.png) - -Account registration provides access to NASA's Earth Observing System Data and Information System (EOSDIS) and its twelve Distributed Active Archive Centers (DAAC), including: - -- Alaska Satellite Facility (ASF) DAAC -- Atmospheric Science Data Center (ASDC) -- Crustal Dynamics Data Information System (CDDIS) -- Global Hydrometeorology Resource Center (GHRC) -- Goddard Earth Sciences Data and Information Services Center (GES DISC) -- Land Processes DAAC (LP DAAC) -- Level 1 and Atmosphere Archive and Distribution System (LAADS) DAAC -- National Snow and Ice Data Center (NSIDC) DAAC -- Oak Ridge National Laboratory (ORNL) DAAC -- Ocean Biology DAAC (OB.DAAC) -- Physical Oceanography DAAC (PO.DAAC) -- Socioeconomic Data and Applications Center (SEDAC) - -See for more information. - -### Approved applications - -After creating an account, navigate to "My Profile"(https://urs.earthdata.nasa.gov/profile), and then to "Applications \> Authorized Apps". This "Authorized Apps" page specifies which NASA EarthData applications can use your login credentials. For this example, ensure that authorization is enabled for "SEDAC Website", "SEDAC Website (Alpha)", and "SEDAC Website (Beta)". - -![NASA EarthData Approved Applications](images/NASA_EarthData_applications.png) - -### Prerequisite files - -With a NASA EarthData Account and the required applications authorized to use the credentials, it is time to create the prerequisite files. - -**Note** As the steps to produce the prerequisite files is very specific, much of the code used is adopted from [How to Generate Earthdata Prerequisite Files](https://disc.gsfc.nasa.gov/information/howto?title=How%20to%20Generate%20Earthdata%20Prerequisite%20Files) on NASA GES DISC's "How-To's" webpage ([link](https://disc.gsfc.nasa.gov/information/howto)). - -#### `.netrc` - -The following commands create the `.netrc` file, which contains your NASA EarthData Account credentials. - -First, set your working directory to the home directory. Setting a working directory differs between Mac/Linux and Windows machines. - -```{r, eval = FALSE} -if (.Platform$OS.type == "unix") { - setwd("~/") -} else if (.Platform$OS.type == "windows") { - setwd("C:/") -} -``` - -Create a file named `.netrc` with `file.create`. - -```{r, eval = FALSE} -file.create(".netrc") -``` - -Open a connection to `.netrc` with `sink`. Write the line `machine urs...` replacing `YOUR_USERNAME` and `YOUR_PASSWORD` with your NASA EarthData username and password, respectively. After writing the line, close the connection with `sink` again. - -```{r, eval = FALSE} -sink(".netrc") -writeLines( - "machine urs.earthdata.nasa.gov login YOUR_USERNAME password YOUR_PASSWORD" -) -sink() -``` - -Edit the settings so only you, the owner of the file, can read and write `.netrc`. - -```{r, eval = FALSE} -system("chmod 0600 .netrc") -``` - -After, check to ensure the file was created properly. - -```{r, eval = FALSE} -file.exists(".netrc") -``` - -```{r, echo = FALSE} -TRUE -``` - -```{r, eval = FALSE} -readLines(".netrc") -``` - -```{r, echo = FALSE} -paste0( - "machine urs.earthdata.nasa.gov login YOUR_USERNAME password YOUR_PASSWORD" -) -``` - - -#### `.urs_cookies` - -The following commands create the `.urs_cookies` file. - -First, set your working directory to the home directory. - -```{r, eval = FALSE} -if (.Platform$OS.type == "unix") { - setwd("~/") -} else if (.Platform$OS.type == "windows") { - setwd("C:/") -} -``` - -Create a file named `.netrc` with `file.create`. - -```{r, eval = FALSE} -file.create(".urs_cookies") -``` - -After, check to ensure the file was created properly. - -```{r, eval = FALSE} -file.exists(".urs_cookies") -``` - -```{r, echo = FALSE} -TRUE -``` - -#### `.dodsrc` - -The following commands create the `.urs_cookies` file. - -First, set your working directory to the home directory. - -```{r, eval = FALSE} -if (.Platform$OS.type == "unix") { - setwd("~/") -} else if (.Platform$OS.type == "windows") { - setwd("C:/") -} -``` - -Create a file named ".dodsrc" with `file.create`. - -```{r, eval = FALSE} -file.create(".dodsrc") -``` - -Open a connection to `.dodsrc` with `sink`. Write the lines beginning with `HTTP.`, replacing `YOUR_USERNAME` and `YOUR_PASSWORD` with your NASA EarthData username and password, respectively. After writing the line, close the connection with `sink` again. - -```{r, eval = FALSE} -sink(".dodsrc") -writeLines( - paste0( - "HTTP.NETRC=YOUR_HOME_DIRECTORY/.netrc\n", - "HTTP.COOKIE.JAR=YOUR_HOME_DIRECTORY/.urs_cookies" - ) -) -sink() -``` - -After, check to ensure the file was created properly. - -```{r, eval = FALSE} -file.exists(".dodsrc") -``` - -```{r, echo = FALSE} -TRUE -``` - -```{r, eval = FALSE} -readLines(".dodsrc") -``` - -```{r, echo = FALSE} -paste0( - c( - "HTTP.NETRC=YOUR_HOME_DIRECTORY/.netrc", - "HTTP.COOKIE.JAR=YOUR_HOME_DIRECTORY/.urs_cookies" - ) -) -``` - -If working on a Windows machine, copy the `.dodsrc` file to the project working directory. Replace `YOUR_WORKING_DIRECTORY` with the absolute path to the project working directory. - -```{r} -if (.Platform$OS.type == "windows") { - file.copy( - "C:/.dodsrc", - "YOUR_WORKING_DIRECTORY/.dodsrc" - ) -} -``` - -It is important to ensure that these commands, as well as your username, password, and home directory, are typed without error, as a single problem with any of these files will result in a failed download. - -If the files have been created correctly, the UN WPP-Adjusted population density data from NASA Socioeconomic Data and Applications Center (SEDAC) will be downloaded and unzipped without returning an error. - -```{r, eval = FALSE} -download_data( - dataset_name = "sedac_population", - year = "2020", - data_format = "GeoTIFF", - data_resolution = "60 minute", - directory_to_save = "./sedac_population", - acknowledgement = TRUE, - download = TRUE, - unzip = TRUE, - remove_zip = FALSE, - remove_command = TRUE -) -``` - -```{r, echo = FALSE} -to_cat <- - paste0( - "Downloading requested files...\n", - "Requested files have been downloaded.\n", - "Unzipping files...\n", - "Files unzipped and saved in ./sedac_population/.\n" - ) -cat(to_cat) -``` - -```{r, eval = FALSE} -list.files("./sedac_population") -``` - -```{r, echo = FALSE} -sedac_files <- c( - paste0( - "gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_", - "rev11_2020_1_deg_tif_readme.txt" - ), - paste0( - "gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_", - "rev11_2020_1_deg_tif.zip" - ), - paste0( - "gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_", - "rev11_2020_1_deg.tif" - ) -) -sedac_files -``` - -## References - -- EOSDIS Distributed Active Archive Centers (DAAC). *National Aeronautics and Space Administration (NASA)*. Date accessed: January 3, 2024. [https://www.earthdata.nasa.gov/eosdis/daacs](). -- How to Generate Earthdata Prerequisite Files. *National Aeronautics and Space Administration (NASA)*. Date accessed: January 3, 2024. [https://disc.gsfc.nasa.gov/information/howto?title=How%20to%20Generate%20Earthdata%20Prerequisite%20Files](). - -## Code Example +## `download_hms` function code The following is the entire R code used to create `download_hms`. diff --git a/vignettes/protected_datasets.Rmd b/vignettes/protected_datasets.Rmd new file mode 100644 index 00000000..41d3d226 --- /dev/null +++ b/vignettes/protected_datasets.Rmd @@ -0,0 +1,280 @@ +--- +title: "Protected Data Sources" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Protected Data Sources} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +date: "2024-07-09" +author: "Mitchell Manware" +--- + +The `download_data` function from `amadeus` provides access to a variety of publicly available environmental data sources. +Although publicly available, certain data sources are protected and require users to provide login credentials before accessing and downloading the data. +Datasets from the National Aeronautics and Space Administration (NASA), for example, require users to have and provide credentials for a NASA EarthData account. +Manually downloading data from the web while logged into a NASA EarthData Account will automatically reference the user's credentials, but accessing data via the `download_data` function requires "prerequiste files" which store user credentials. + +## Motivation + +This vignette will demonstrate how to create and log into a NASA EarthData Account, and how to generate the prerequisite files with R code. + +## NASA EarthData Account + +Visit [https://urs.earthdata.nasa.gov/](http://urs.earthdata.nasa.gov) to register for or log into a NASA EarthData account. + +![NASA EarthData Account Landing Page](images/NASA_EarthData_login.png) + +Account registration provides access to NASA's Earth Observing System Data and Information System (EOSDIS) and its twelve Distributed Active Archive Centers (DAAC), including: + +- Alaska Satellite Facility (ASF) DAAC +- Atmospheric Science Data Center (ASDC) +- Crustal Dynamics Data Information System (CDDIS) +- Global Hydrometeorology Resource Center (GHRC) +- Goddard Earth Sciences Data and Information Services Center (GES DISC) +- Land Processes DAAC (LP DAAC) +- Level 1 and Atmosphere Archive and Distribution System (LAADS) DAAC +- National Snow and Ice Data Center (NSIDC) DAAC +- Oak Ridge National Laboratory (ORNL) DAAC +- Ocean Biology DAAC (OB.DAAC) +- Physical Oceanography DAAC (PO.DAAC) +- Socioeconomic Data and Applications Center (SEDAC) + +See for more information. + +### Approved applications + +After creating an account, navigate to "My Profile"(https://urs.earthdata.nasa.gov/profile), and then to "Applications \> Authorized Apps". This "Authorized Apps" page specifies which NASA EarthData applications can use your login credentials. For this example, ensure that authorization is enabled for "SEDAC Website", "SEDAC Website (Alpha)", and "SEDAC Website (Beta)". + +![NASA EarthData Approved Applications](images/NASA_EarthData_applications.png) + +## Prerequisite files + +With a NASA EarthData Account and the required applications authorized to use the credentials, it is time to create the prerequisite files. +The following examples will utilize the [UN WPP-Adjusted population density data from NASA Socioeconomic Data and Applications Center (SEDAC)](https://sedac.ciesin.columbia.edu/data/collection/gpw-v4/united-nations-adjusted). + +Before generating the prerequisite, try to download the population data with `download_data`. + +```{r, eval = FALSE} +download_data( + dataset_name = "sedac_population", + year = "2020", + data_format = "GeoTIFF", + data_resolution = "60 minute", + directory_to_save = "./sedac_population", + acknowledgement = TRUE, + download = TRUE, + unzip = TRUE, + remove_zip = FALSE, + remove_command = TRUE +) +``` + +```{r, echo = FALSE} +to_cat <- + paste0( + "Downloading requested files...\n", + "Requested files have been downloaded.\n", + "Unzipping files...\n\n", + "Warning in unzip(file_name, exdir = directory_to_unzip): ", + "error 1 in extracting from zip file\n\n", + "Files unzipped and saved in ./sedac_population/.\n\n" + ) +cat(to_cat) +``` + +As the error message indicates, the downloaded file cannot be unzipped because the data file was not accessed properly. +To be able to download protected NASA data with `download_data`, the `.netrc`, `.urs_cookies`, and `.dodsrc` must be generated. + +**Note** The following code has been adopted from [How to Generate Earthdata Prerequisite Files](https://disc.gsfc.nasa.gov/information/howto?title=How%20to%20Generate%20Earthdata%20Prerequisite%20Files) on NASA GES DISC's ["How-To's" webpage](https://disc.gsfc.nasa.gov/information/howto). + +**The folowing steps assume a Mac or Linux operating system. Instructions for generating prerequisite files on Windows operating system in R is being developed.** + +### `.netrc` + +The following commands create the `.netrc` file, which contains your NASA EarthData Account credentials. + +First, set your working directory to the home directory. + +```{r, eval = FALSE} +setwd("~/") +``` + +Create a file named `.netrc` with `file.create`. + +```{r, eval = FALSE} +file.create(".netrc") +``` + +Open a connection to `.netrc` with `sink`. Write the line `machine urs...` replacing `YOUR_USERNAME` and `YOUR_PASSWORD` with your NASA EarthData username and password, respectively. After writing the line, close the connection with `sink` again. + +```{r, eval = FALSE} +sink(".netrc") +writeLines( + "machine urs.earthdata.nasa.gov login YOUR_USERNAME password YOUR_PASSWORD" +) +sink() +``` + +Edit the settings so only you, the owner of the file, can read and write `.netrc`. + +```{r, eval = FALSE} +system("chmod 0600 .netrc") +``` + +After, check to ensure the file was created properly. + +```{r, eval = FALSE} +file.exists(".netrc") +``` + +```{r, echo = FALSE} +TRUE +``` + +```{r, eval = FALSE} +readLines(".netrc") +``` + +```{r, echo = FALSE} +paste0( + "machine urs.earthdata.nasa.gov login YOUR_USERNAME password YOUR_PASSWORD" +) +``` + +### `.urs_cookies` + +The following commands create the `.urs_cookies` file. + +First, set your working directory to the home directory. + +```{r, eval = FALSE} +setwd("~/") +``` + +Create a file named `.netrc` with `file.create`. + +```{r, eval = FALSE} +file.create(".urs_cookies") +``` + +After, check to ensure the file was created properly. + +```{r, eval = FALSE} +file.exists(".urs_cookies") +``` + +```{r, echo = FALSE} +TRUE +``` + +### `.dodsrc` + +The following commands create the `.urs_cookies` file. + +First, set your working directory to the home directory. + +```{r, eval = FALSE} +setwd("~/") +``` + +Create a file named ".dodsrc" with `file.create`. + +```{r, eval = FALSE} +file.create(".dodsrc") +``` + +Open a connection to `.dodsrc` with `sink`. Write the lines beginning with `HTTP.`, replacing `YOUR_USERNAME` and `YOUR_PASSWORD` with your NASA EarthData username and password, respectively. After writing the line, close the connection with `sink` again. + +```{r, eval = FALSE} +sink(".dodsrc") +writeLines( + paste0( + "HTTP.NETRC=YOUR_HOME_DIRECTORY/.netrc\n", + "HTTP.COOKIE.JAR=YOUR_HOME_DIRECTORY/.urs_cookies" + ) +) +sink() +``` + +After, check to ensure the file was created properly. + +```{r, eval = FALSE} +file.exists(".dodsrc") +``` + +```{r, echo = FALSE} +TRUE +``` + +```{r, eval = FALSE} +readLines(".dodsrc") +``` + +```{r, echo = FALSE} +paste0( + c( + "HTTP.NETRC=YOUR_HOME_DIRECTORY/.netrc", + "HTTP.COOKIE.JAR=YOUR_HOME_DIRECTORY/.urs_cookies" + ) +) +``` + +It is important to ensure that these commands, as well as your username, password, and home directory, are typed without error, as a single problem with any of these files will result in a failed download. +If the files have been created correctly, the UN WPP-Adjusted population density data from NASA Socioeconomic Data and Applications Center (SEDAC) will be downloaded and unzipped without returning an error. + +```{r, eval = FALSE} +download_data( + dataset_name = "sedac_population", + year = "2020", + data_format = "GeoTIFF", + data_resolution = "60 minute", + directory_to_save = "./sedac_population", + acknowledgement = TRUE, + download = TRUE, + unzip = TRUE, + remove_zip = FALSE, + remove_command = TRUE +) +``` + +```{r, echo = FALSE} +to_cat <- + paste0( + "Downloading requested files...\n", + "Requested files have been downloaded.\n", + "Unzipping files...\n", + "Files unzipped and saved in ./sedac_population/.\n" + ) +cat(to_cat) +``` + +Check the downloaded data files. + +```{r, eval = FALSE} +list.files("./sedac_population") +``` + +```{r, echo = FALSE} +sedac_files <- c( + paste0( + "gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_", + "rev11_2020_1_deg_tif_readme.txt" + ), + paste0( + "gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_", + "rev11_2020_1_deg_tif.zip" + ), + paste0( + "gpw_v4_population_density_adjusted_to_2015_unwpp_country_totals_", + "rev11_2020_1_deg.tif" + ) +) +sedac_files +``` + +As indicated by the files in `./sedac_population`, the data files have been downloaded properly. + +## References + +- EOSDIS Distributed Active Archive Centers (DAAC). *National Aeronautics and Space Administration (NASA)*. Date accessed: January 3, 2024. [https://www.earthdata.nasa.gov/eosdis/daacs](). +- How to Generate Earthdata Prerequisite Files. *National Aeronautics and Space Administration (NASA)*. Date accessed: January 3, 2024. [https://disc.gsfc.nasa.gov/information/howto?title=How%20to%20Generate%20Earthdata%20Prerequisite%20Files]().