Package {amadeus}

Title:	Accessing and Analyzing Large-Scale Environmental Data
Version:	2.0.0
Maintainer:	Kyle Messier <kyle.messier@nih.gov>
Description:	Functions are designed to facilitate access to and utility with large scale, publicly available environmental data in R. The package contains functions for downloading raw data files from web URLs (download_data()), processing the raw data files into clean spatial objects (process_covariates()), and extracting values from the spatial data objects at point and polygon locations (calculate_covariates()). These functions call a series of source-specific functions which are tailored to each data sources/datasets particular URL structure, data format, and spatial/temporal resolution. The functions are tested, versioned, and open source and open access. For sum_edc() method details, see Messier, Akita, and Serre (2012) <doi:10.1021/es203152a>.
Depends:	R (≥ 4.2.0)
Imports:	dplyr, sf, sftime, stats, terra (≥ 1.8-50), methods, data.table, httr2, exactextractr, utils, stringi, stars, tidyr, rlang, archive, collapse, Rdpack
Suggests:	covr, devtools, doRNG, FNN, furrr, ggplot2, knitr, lwgeom, maps, mirai, nhdplusTools, rmarkdown, spelling, stringr, targets, testthat (≥ 3.0.0), tigris, withr
RdMacros:	Rdpack
Encoding:	UTF-8
VignetteBuilder:	knitr, rmarkdown
RoxygenNote:	7.3.3
Config/Needs/website:	tidyverse/tidytemplate
Config/testhat/edition:	3
License:	MIT + file LICENSE
URL:	https://niehs.github.io/amadeus/
BugReports:	https://github.com/NIEHS/amadeus/issues
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-05-21 19:17:53 UTC; messierkp
Author:	Mitchell Manware [aut, ctb], Insang Song [aut, ctb], Eva Marques [aut, ctb], Mariana Alifa Kassien [aut, ctb], Elizabeth Scholl [ctb], Kyle Messier [aut, cre], Spatiotemporal Exposures and Toxicology Group [cph]
Repository:	CRAN
Date/Publication:	2026-05-21 21:00:08 UTC

Apply extent to the processed data

Description

User-defined extent is used to filter the data.

Usage

apply_extent(data, extent, geom)

Arguments

Value

sf/terra object with the extent applied.

Create an sftime object

Description

Create a sftime object from one of data.frame, data.table, sf, sftime, SpatRaster, SpatRasterDataset, SpatVector

Usage

as_mysftime(x, ...)

Arguments

Value

an sftime object with constrained time column name

Author(s)

Eva Marques

See Also

check_mysftime, sf_as_mysftime, data.frame, data.table::data.table, terra::rast, terra::sds, terra::vect

Bucket a time column to a .by_time unit

Description

Buckets time values to one of the supported .by_time units.

Usage

bucket_time_by_unit(time_vals, unit)

Arguments

Value

vector. Bucketed values as POSIXct (minute/hour) or Date.

Author(s)

Insang Song

Apply default/native or explicit temporal summarization

Description

Apply default/native or explicit temporal summarization

Usage

calc_apply_time_summary(
  covar,
  .by_time = NULL,
  fun_summary = "mean",
  locs_id = "site_id",
  time_col = "time",
  group_cols_extra = NULL
)

Arguments

Value

data.frame

Check time values

Description

Check the time values within calculated covariates data.frame

Usage

calc_check_time(covar, POSIXt = TRUE)

Arguments

Value

NULL; returns a stop error if time is wrong class

Validate extents overlap

Description

Validate extents overlap

Usage

calc_extents_overlap(x, y)

Arguments

Value

logical(1)

Send progress messages

Description

Send messages updating covariate extraction progress.

Usage

calc_message(dataset, variable, time, time_type, level, layer_time = NULL)

Arguments

Value

NULL; provides progress messages to R console.

Convert point extractions to tiny polygons for exact extraction

Description

Convert point extractions to tiny polygons for exact extraction

Usage

calc_prepare_exact_geoms(locs_vector, radius)

Arguments

Value

sf object for exactextractr

Prepare extraction locations

Description

Prepare the point locations for extracting data by transforming locs to a SpatVector, projecting to the coordinate reference system of from, and creating a data.frame containing locs_id for retaining extracted values.

Usage

calc_prepare_locs(from, locs, locs_id, radius, geom = FALSE)

Arguments

Value

A list containing SpatVector and data.frame objects

See Also

process_locs_vector(), check_for_null_parameters()

Prepare optional weighting raster

Description

Prepare optional weighting raster

Usage

calc_prepare_weights(from, weights = NULL)

Arguments

Value

NULL or single-layer SpatRaster aligned to from.

Prepare covariates for return

Description

Check the time column for proper class and, if geom = TRUE, transform data.frame into a SpatVector object.

Usage

calc_return_locs(covar, POSIXt = TRUE, geom, crs)

Arguments

Value

a data.frame or SpatVector object (depending on geom paramter)

Author(s)

Mitchell Manware

Set column names

Description

Apply standard column names to calculated covariates consistent with the requirements of the beethoven package. Column names follow fixed format of 3 character data genre, 2 - 15 character variable code, 1 digit temporal lag, and 5 digit buffer radius (in meters). Variable code character range is required to retain interpretable column names across datasets.

Usage

calc_setcolumns(from, lag, dataset, locs_id)

Arguments

Value

a data.frame or SpatVector object (depending on from)

Note

beethoven utilizes point, 1km, and 10km radius buffer distance for covariate calculation, and therefore the buffer radius column is padded to 5 digits. If provided a buffer radius greater than 5 digits, calc_setcolumns() will expand to the number of digits. (ie. buffer radius of 100km = CCC_CCCCC_I_100000).

Summarize extracted covariates by .by_time temporal unit

Description

Generic temporal summarizer for covariate tables. When .by_time is NULL, the input is returned unchanged. Otherwise, numeric covariates are summarized by locs_id + bucketed time + group_cols_extra.

Usage

calc_summarize_by(
  covar,
  fun_summary = "mean",
  locs_id = "site_id",
  time_col = "time",
  .by_time = NULL,
  group_cols_extra = NULL,
  ...
)

Arguments

Value

a data.frame.

Author(s)

Insang Song

Summarize extracted covariates at native temporal grain

Description

Internal helper that summarizes numeric covariates by locs_id + time + group_cols_extra while preserving the original time representation.

Usage

calc_summarize_native_time(
  covar,
  fun_summary = "mean",
  locs_id = "site_id",
  time_col = "time",
  group_cols_extra = NULL
)

Arguments

Value

a data.frame.

Summarize extracted covariates by temporal bucket

Description

Applies a named summary function across covariate columns after bucketing the time column to a coarser temporal resolution (daily by default). When fun_temporal is NULL, the input is returned unchanged (backward-compatible default). A WKT "geometry" column produced by calc_prepare_locs() is preserved by carrying forward the first observed geometry per group.

Usage

calc_summarize_temporal(
  covar,
  fun_temporal,
  locs_id = "site_id",
  time_col = "time",
  time_bucket = "day",
  group_cols_extra = NULL
)

Arguments

Value

a data.frame. When fun_temporal is NULL, covar is returned as-is. Otherwise each row represents one unique group / time-bucket combination with covariate columns aggregated by fun_temporal.

Author(s)

Insang Song

Prepare time values

Description

Prepare the time values for covariate calculation based on type of time value.

Usage

calc_time(time, format, dataset = NULL, layer_name = NULL, layer_time = NULL)

Arguments

Value

a Date, POSIXt, or integer object based on ⁠format =⁠

Resolve weighted summary function names for exactextractr

Description

Resolve weighted summary function names for exactextractr

Usage

calc_weighted_fun(fun, weighted = FALSE)

Arguments

Value

character(1)

Perform covariate extraction

Description

Extract covariate values from SpatRaster object passed from process_*().

Usage

calc_worker(
  dataset,
  from,
  locs_vector,
  locs_df,
  fun = "mean",
  variable = 1,
  time,
  time_type = c("date", "hour", "year", "yearmonth", "timeless"),
  radius,
  level = NULL,
  max_cells = 1e+08,
  weights = NULL,
  ...
)

Arguments

Value

a data.frame object

Calculate covariates wrapper function

Description

The calculate_covariates() function extracts values at point locations from a SpatRaster or SpatVector object returned from process_covariates(). calculate_covariates() and the underlying source-specific covariate functions have been designed to operate on the processed objects. To avoid errors, do not edit the processed SpatRaster or SpatVector objects before passing to calculate_covariates().

Usage

calculate_covariates(
  covariate = c("modis", "koppen-geiger", "koeppen-geiger", "koppen", "koeppen", "geos",
    "dummies", "gmted", "sedac_groads", "groads", "roads", "ecoregions", "ecoregion",
    "hms", "smoke", "gmted", "narr", "geos", "sedac_population", "population", "nlcd",
    "merra", "merra2", "gridmet", "terraclimate", "tri", "nei", "mcd14ml", "prism",
    "cropscape", "cdl", "huc", "edgar", "goes", "goes_adp", "GOES", "drought", "spei",
    "eddi", "usdm"),
  from,
  locs,
  locs_id = "site_id",
  .by_time = NULL,
  weights = NULL,
  ...
)

Arguments

Value

Calculated covariates as a data.frame or SpatVector object

Note

covariate argument value is converted to lowercase.

Author(s)

Insang Song

See Also

• calculate_modis: "modis", "MODIS"

• calculate_koppen_geiger: "koppen-geiger", "koeppen-geiger", "koppen"

• calculate_ecoregion: "ecoregion", "ecoregions"

• calculate_temporal_dummies: "dummies", "Dummies"

• calculate_hms: "hms", "smoke", "HMS"

• calculate_gmted: "gmted", "GMTED"

• calculate_narr: "narr", "NARR"

• calculate_geos: "geos", "geos_cf", "GEOS"

• calculate_goes: "goes", "goes_adp", "GOES"

• calculate_population: "population", "sedac_population"

• calculate_groads: "roads", "groads", "sedac_groads"

• calculate_nlcd: "nlcd", "NLCD"

• calculate_tri: "tri", "TRI"

• calculate_nei: "nei", "NEI"

• calculate_merra2: "merra", "MERRA", "merra2", "MERRA2"

• calculate_gridmet: "gridMET", "gridmet"

• calculate_terraclimate: "terraclimate", "TerraClimate"

• calculate_prism: "prism", "PRISM"

• calculate_cropscape: "cropscape", "cdl"

• calculate_huc: "huc", "HUC"

• calculate_edgar: "edgar"

• calculate_drought: "drought", "spei", "eddi", "usdm"

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_covariates(
  covariate = "narr",
  from = narr, # derived from process_covariates() example
  locs = loc,
  locs_id = "id",
  geom = FALSE
)

## End(Not run)

Calculate Cropscape covariates

Description

Extract Cropscape (CDL) values at point locations. Returns a data.frame object containing locs_id and crop specific cell fractions.

Usage

calculate_cropscape(
  from,
  locs,
  locs_id = "site_id",
  radius = 0,
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Insang Song

See Also

process_cropscape()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_cropscape(
  from = cropscape, # derived from process_cropscape() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  geom = FALSE
)

## End(Not run)

Calculate drought index covariates

Description

The calculate_drought() function extracts drought index values at point locations from an object returned by process_drought(). Three source datasets are supported:

• SPEI / EDDI (SpatRaster): cell values are extracted at each location using the standard raster-extraction pipeline (calc_prepare_locs() -> calc_worker() -> calc_return_locs()). Time column format is "YYYY-MM-DD".

• USDM (SpatVector polygons): the drought monitor class (DM, integer 0-4) at each location is determined via spatial overlay. A time column of class Date is populated from the date attribute of from.

When .by_time is supplied the extracted result is passed through calc_summarize_by() using the same semantics as all other calculate_*() functions in this package.

Usage

calculate_drought(
  from,
  locs,
  locs_id = "site_id",
  radius = 0L,
  fun = "mean",
  weights = NULL,
  geom = FALSE,
  .by_time = NULL,
  ...
)

Arguments

Value

A data.frame (default) or SpatVector/sf object (when geom is set) with columns:

<locs_id>

Location identifier.

time

Date of the observation (Date or "YYYY-MM-DD" character).

<value_column>

Extracted drought index or class value.

When .by_time is non-NULL, rows are aggregated to the specified resolution via calc_summarize_by().

Note

• The column name for extracted drought values follows the pattern "<source>_<timescale>_<radius>" (e.g. "spei_01_0") for SPEI/EDDI, and "usdm_dm_0" for USDM.

• For USDM with radius > 0, proportion columns are added as "usdm_dm_<class>_<radius>" for classes 0–4.

Author(s)

Insang Song

See Also

process_drought, download_drought, calc_summarize_by

Examples

## Not run: 
locs <- data.frame(site_id = "001", lon = -97.5, lat = 35.5)
## SPEI example
spei <- process_drought(
  source = "spei",
  path = "./data/drought",
  date = c("2020-01-01", "2020-12-31"),
  timescale = 1L
)
calculate_drought(
  from = spei,
  locs = locs,
  locs_id = "site_id",
  radius = 0L,
  fun = "mean"
)
## USDM example
usdm <- process_drought(
  source = "usdm",
  path = "./data/drought",
  date = c("2020-01-07", "2020-03-31")
)
calculate_drought(
  from = usdm,
  locs = locs,
  locs_id = "site_id"
)

## End(Not run)

Calculate ecoregions covariates

Description

Extract ecoregions covariates (U.S. EPA Ecoregions Level 2/3) at point or polygon locations. Returns a data.frame object containing locs_id and either dummy indicators (frac = FALSE) or area fractions (frac = TRUE) for each ecoregion.

Usage

calculate_ecoregion(
  from = NULL,
  locs,
  locs_id = "site_id",
  colnames = c("coded", "full_ecoregion"),
  frac = FALSE,
  drop = FALSE,
  weights = NULL,
  geom = FALSE,
  radius = 0,
  ...
)

Arguments

Value

a data.frame or SpatVector object with ecoregion indicator/fraction variables and attributes of:

• Indicator names are controlled by colnames: "coded" (default) creates key-based names such as DUM_E2083_00000 and DUM_E3064_00000 when frac = FALSE, or FRC_E2083_00000 and FRC_E3064_00000 when frac = TRUE; "full_ecoregion" creates sanitized name-based columns such as DUM_E2_SOUTHEASTERN_USA_PLAINS_00000 / FRC_E2_SOUTHEASTERN_USA_PLAINS_00000 and DUM_E3_NORTHERN_PIEDMONT_00000 / FRC_E3_NORTHERN_PIEDMONT_00000 (duplicates are suffixed, e.g. ⁠_1⁠).

• attr(., "ecoregion2_code"): Ecoregion lv.2 code and key

• attr(., "ecoregion3_code"): Ecoregion lv.3 code and key

Author(s)

Insang Song

See Also

process_ecoregion

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_ecoregion(
  from = ecoregion, # derived from process_ecoregion() example
  locs = loc,
  locs_id = "id",
  colnames = "coded",
  geom = FALSE
)

## End(Not run)

Calculate EDGAR covariates

Description

Extract EDGAR gridded emissions values at point locations. For radius = 0, cell values are extracted directly. For radius > 0, means are calculated over a circular buffer around each location.

Usage

calculate_edgar(
  from,
  locs,
  locs_id = "site_id",
  radius = 0,
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Mariana Alifa Kassien, Insang Song

See Also

process_edgar()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires data that is
##       not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_edgar(
  from = edgar, # derived from process_edgar() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  geom = FALSE
)

## End(Not run)

Calculate atmospheric composition covariates

Description

Extract atmospheric composition values at point locations. Returns a data.frame object containing locs_id, date and hour, vertical pressure level, and atmospheric composition variable. Atmospheric composition variable column name reflects variable and circular buffer radius.

Usage

calculate_geos(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object. When .by_time is provided, rows are aggregated using calc_summarize_by().

Author(s)

Mitchell Manware

See Also

process_geos()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_geos(
  from = geos, # derived from process_geos() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate elevation covariates

Description

Extract elevation values at point locations. Returns a data.frame object containing locs_id, year of release, and elevation variable. Elevation variable column name follows the pattern gmted_<radius> (for example, gmted_0 or gmted_100).

Usage

calculate_gmted(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Mitchell Manware

See Also

process_gmted()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_gmted(
  from = gmted, # derived from process_gmted() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate NOAA GOES ADP covariates

Description

Extract NOAA GOES Aerosol Detection Product (ADP) values at point locations from a SpatRaster returned by process_goes(). Returns a data.frame (or SpatVector / sf) containing locs_id, time, and the extracted variable column ({variable}_{radius}).

Usage

calculate_goes(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object.

Author(s)

Mitchell Manware

See Also

process_goes

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires downloaded
##       and processed data.
## Not run: 
loc <- data.frame(id = "001", lon = -95.0, lat = 34.5)
calculate_goes(
  from = goes,  # derived from process_goes() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean"
)

## End(Not run)

Calculate gridMET covariates

Description

Extract gridMET values at point locations. Returns a data.frame object containing locs_id and gridMET variable. gridMET variable column name reflects the gridMET variable and circular buffer radius.

Usage

calculate_gridmet(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Mitchell Manware

See Also

process_gridmet()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_gridmet(
  from = gridmet, # derived from process_gridmet() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate roads covariates

Description

Prepared groads data is clipped with the buffer polygons of radius. The total length of the roads are calculated. Then the density of the roads is calculated by dividing the total length from the area of the buffer. terra::linearUnits() is used to convert the unit of length to meters.

Usage

calculate_groads(
  from = NULL,
  locs = NULL,
  locs_id = NULL,
  radius = 1000,
  fun = "sum",
  drop = FALSE,
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Note

Unit is km / sq km. The returned data.frame object contains a ⁠$time⁠ column to represent the temporal range covered by the dataset. For more information, see https://data.nasa.gov/dataset/global-roads-open-access-data-set-version-1-groadsv1.

Author(s)

Insang Song

See Also

process_groads

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_groads(
  from = groads, # derived from process_groads() example
  locs = loc,
  locs_id = "id",
  radius = 1000,
  fun = "sum",
  geom = FALSE
)

## End(Not run)

Calculate wildfire smoke covariates

Description

Extract wildfire smoke plume values at point or buffered locations. Returns a data.frame object containing locs_id, date, and either binary indicators (frac = FALSE) or fractional overlap values (frac = TRUE) for wildfire smoke plume density inherited from from.

Usage

calculate_hms(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  weights = NULL,
  .by_time = NULL,
  frac = FALSE,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object. When .by_time is provided, rows are aggregated using calc_summarize_by().

Author(s)

Mitchell Manware

See Also

process_hms()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_hms(
  from = hms, # derived from process_hms() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  geom = FALSE
)

## End(Not run)

Calculate HUC covariates

Description

Extract HUC IDs at point locations. Returns a data.frame object containing locs_id and HUC IDs.

Usage

calculate_huc(
  from,
  locs,
  locs_id = "site_id",
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Insang Song

See Also

process_huc()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_huc(
  from = huc, # derived from process_huc() example
  locs = loc,
  locs_id = "id",
  geom = FALSE
)

## End(Not run)

Calculate climate classification covariates

Description

Extract Koppen-Geiger climate classes at point or buffered locations. Returns a data.frame with locs_id, a description column, and either binary indicators (frac = FALSE) or fractional overlap values (frac = TRUE) for climate groups A-E.

Usage

calculate_koppen_geiger(
  from = NULL,
  locs = NULL,
  locs_id = "site_id",
  weights = NULL,
  geom = FALSE,
  frac = FALSE,
  radius = 0,
  ...
)

Arguments

Value

a data.frame or SpatVector object with climate columns named like DUM_CLRGA_00000 (frac = FALSE) or FRC_CLRGA_100000 (frac = TRUE) where the suffix reflects the extraction radius.

Note

The returned object contains a ⁠$description⁠ column to represent the temporal range covered by the dataset. For more information, see https://www.nature.com/articles/sdata2018214.

Author(s)

Insang Song

See Also

process_koppen_geiger

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_koppen_geiger(
  from = kg, # derived from process_koppen_geiger() example
  locs = loc,
  locs_id = "id",
  geom = FALSE
)

## End(Not run)

Calculate temporally lagged covariates

Description

The calculate_lagged() function calculates daily temporal lagged covariates from the output of calculate_covariates() or calc_*().

Usage

calculate_lagged(from, date, lag, locs_id, time_id = "time", geom = FALSE)

Arguments

Value

a data.frame object

Note

In order to calculate temporally lagged covariates, from must contain at least the number of lag days before the desired start date. For example, if ⁠date = c("2024-01-01", "2024-01-31)⁠ and lag = 1, from must contain data starting at 2023-12-31. If from contains geometry features, calculate_lagged will return a column with geometry features of the same name. calculate_lagged() assumes that all columns other than time_id, locs_id, and fixed columns of "lat" and "lon", follow the genre, variable, lag, buffer radius format adopted in calc_setcolumns().

See Also

calculate_covariates()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
terracliamte_covar <- calculate_terraclimate(
  from = terraclimate, # derived from process_terraclimate() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)
calculate_lagged(
  from = terracliamte_covar,
  locs_id = "id",
  date = c("2023-01-02", "2023-01-10"),
  lag = 1,
  time_id = "time"
)

## End(Not run)

Calculate meteorological and atmospheric covariates

Description

Extract meteorological and atmospheric values at point locations. Returns a data.frame object containing locs_id, date and hour, vertical pressure level, and meteorological or atmospheric variable. Variable column name reflects variable and circular buffer radius.

Usage

calculate_merra2(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object. When .by_time is provided, rows are aggregated using calc_summarize_by().

Author(s)

Mitchell Manware

See Also

calculate_geos(), process_merra2()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_merra2(
  from = merra2, # derived from process_merra2() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate MODIS product covariates

Description

calculate_modis orchestrates daily extraction using calculate_modis_daily(). In raw-path mode, files are grouped by inferred date, preprocessed for each day, and then extracted over requested radii. With product-specific preprocessing, files are handled according to each product's structure and naming conventions.

Usage

calculate_modis(
  from = NULL,
  from_secondary = NULL,
  locs = NULL,
  locs_id = "site_id",
  radius = c(0L, 1000L, 10000L, 50000L),
  preprocess = amadeus::process_modis_merge,
  name_covariates = NULL,
  subdataset = NULL,
  fun_summary = "mean",
  .by_time = NULL,
  weights = NULL,
  package_list_add = NULL,
  export_list_add = NULL,
  max_cells = 3e+07,
  geom = FALSE,
  scale = NULL,
  fusion_method = c("mean", "primary_first", "secondary_first"),
  ...
)

Arguments

Value

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. When .by_time is provided, rows are summarized with calc_summarize_by() semantics.

Note

locs is expected to be convertible to sf object. sf, SpatVector, and other class objects that could be converted to sf can be used. In raw path mode, preprocess is called once per inferred day using a single-date value. Temporal aggregation across extracted rows should be done with .by_time. Common arguments in preprocess functions such as date and path are automatically detected and passed to the function. Please note that locs here and path in preprocess functions are assumed to have a standard naming convention of raw files from NASA. The argument subdataset should be in a proper format depending on preprocess function:

• process_modis_merge(): Regular expression pattern. e.g., "^LST_"

• process_modis_swath(): Subdataset names. e.g., c("Cloud_Fraction_Day", "Cloud_Fraction_Night")

• process_blackmarble(): Subdataset number. e.g., for VNP46A2 product, 3L.

For MOD13/MYD13 families, Terra and Aqua composites are 16-day phased products offset by 8 days; combining both can improve effective temporal coverage. This behavior aligns with NASA MOD13 product guidance: https://modis.gsfc.nasa.gov/data/dataprod/mod13.php

For MCD19A2 MAIAC, common sub-datasets include both optical depth and plume injection height layers. Typical selectors are "(Optical_Depth|Injection_Height)" for both families or "(Injection_Height)" when targeting plume height only.

For MOD14A1/MYD14A1 fire grids, the FireMask raw values are commonly interpreted as:

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.

See Also

This function leverages the calculation of single-day MODIS covariates:

• calculate_modis_daily()

Also, for preprocessing, please refer to:

• process_modis_merge()

• process_modis_swath()

• process_blackmarble()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
locs <- data.frame(lon = -78.8277, lat = 35.95013, id = "001")
locs <- terra::vect(locs, geom = c("lon", "lat"), crs = "EPSG:4326")
calculate_modis(
  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"
)

## End(Not run)

A single-date MODIS worker

Description

The function operates at MODIS/VIIRS products on a daily basis. Given that the raw hdf files are downloaded from NASA, standard file names include a data retrieval date flag starting with letter "A". Leveraging that piece of information, the function will select files of scope on the date of interest. 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.

Usage

calculate_modis_daily(
  from = NULL,
  locs = NULL,
  locs_id = "site_id",
  radius = 0L,
  date = NULL,
  name_extracted = NULL,
  fun_summary = "mean",
  weights = NULL,
  max_cells = 3e+07,
  geom = FALSE,
  scale = NULL,
  ...
)

Arguments

Value

a data.frame or SpatVector object.

Author(s)

Insang Song

See Also

• Preprocessing: process_modis_merge(), process_modis_swath(), process_blackmarble()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
locs <- data.frame(lon = -78.8277, lat = 35.95013, id = "001")
calculate_modis_daily(
  from = mod06l2_warp, # dervied from process_modis() example
  locs = locs,
  locs_id = "id",
  radius = 0,
  date = "2024-01-01",
  name_extracted = "cloud_fraction_0",
  fun_summary = "mean",
  max_cells = 3e7
)

## End(Not run)

Calculate meteorological covariates

Description

Extract meteorological values at point locations. Returns a data.frame object containing locs_id, date, vertical pressure level, and meteorological variable. Meteorological variable column name reflects variable and circular buffer radius.

Usage

calculate_narr(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Mitchell Manware

See Also

process_narr

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_narr(
  from = narr, # derived from process_narr() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate road emissions covariates

Description

Calculate road emissions covariates

Usage

calculate_nei(
  from = NULL,
  locs = NULL,
  locs_id = "site_id",
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Insang Song, Ranadeep Daw

See Also

process_nei

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_nei(
  from = nei, # derived from process_nei example
  locs = loc,
  locs_id = "id"
)

## End(Not run)

Calculate land cover covariates

Description

Compute ratio of land cover class in circle buffers around points. Returns a data.frame object containing locs_id, longitude, latitude, time (year), and computed ratio for each land cover class.

Usage

calculate_nlcd(
  from,
  locs,
  locs_id = "site_id",
  mode = c("exact", "terra"),
  radius = 1000,
  drop = FALSE,
  weights = NULL,
  max_cells = 5e+07,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Note

NLCD is available in U.S. only. Users should be aware of the spatial extent of the data. The results are different depending on mode argument. The "terra" mode is less memory intensive but less accurate because it counts the number of cells intersecting with the buffer. The "exact" may be more accurate but uses more memory as it will account for the partial overlap with the buffer.

See Also

process_nlcd

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_nlcd(
  from = nlcd, # derived from process_nlcd() example
  locs = loc,
  locs_id = "id",
  mode = "exact",
  geom = FALSE
)

## End(Not run)

Calculate population density covariates

Description

Extract population density values at point locations. Returns a data.frame object containing locs_id, year, and population density variable. Population density variable column name reflects spatial resolution of from and circular buffer radius.

Usage

calculate_population(
  from,
  locs,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Mitchell Manware

See Also

process_population()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_population(
  from = pop, # derived from process_population() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate PRISM covariates

Description

Extract PRISM values at point locations. Returns a data.frame object containing locs_id and PRISM variable. PRISM variable column name reflects the PRISM variable and circular buffer radius.

Usage

calculate_prism(
  from,
  locs,
  locs_id = "site_id",
  radius = 0,
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Insang Song

See Also

process_prism()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_prism(
  from = prism, # derived from process_prism() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  geom = FALSE
)

## End(Not run)

Calculate temporal dummy covariates

Description

Calculate temporal dummy covariates at point locations. Returns a data.frame object with locs_id, year binary variable for each value in year, and month and day of week binary variables.

Usage

calculate_temporal_dummies(
  locs,
  locs_id = "site_id",
  year = seq(2018L, 2022L),
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Author(s)

Insang Song

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_temporal_dummies(
  locs = loc,
  locs_id = "id",
  year = seq(2018L, 2022L)
)

## End(Not run)

Calculate TerraClimate covariates

Description

Extract TerraClimate values at point locations. Returns a data.frame object containing locs_id and TerraClimate variable. TerraClimate variable column name reflects the TerraClimate variable and circular buffer radius. The ⁠$time⁠ column will contain the year and month ("YYYYMM") as TerraClimate products have monthly temporal resolution.

Usage

calculate_terraclimate(
  from = NULL,
  locs = NULL,
  locs_id = NULL,
  radius = 0,
  fun = "mean",
  weights = NULL,
  .by_time = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Note

TerraClimate data has monthly temporal resolution, so the ⁠$time⁠ column will contain the year and month in YYYYMM format (ie. January, 2018 = 201801).

Author(s)

Mitchell Manware

See Also

process_terraclimate()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_terraclimate(
  from = terraclimate, # derived from process_terraclimate() example
  locs = loc,
  locs_id = "id",
  radius = 0,
  fun = "mean",
  geom = FALSE
)

## End(Not run)

Calculate toxic release covariates

Description

Calculate toxic release values for polygons or isotropic buffer point locations. Returns a data.frame object containing locs_id and variables for each processed TRI field in from. Target fields are derived from metadata attached by process_tri(), with a fallback to non-coordinate columns in from.

Usage

calculate_tri(
  from = NULL,
  locs,
  locs_id = "site_id",
  decay_range = c(1000L, 10000L, 50000L),
  C0 = NULL,
  use_threshold = TRUE,
  weights = NULL,
  geom = FALSE,
  ...
)

Arguments

Value

a data.frame or SpatVector object

Note

U.S. context.

Author(s)

Insang Song, Mariana Kassien

See Also

sum_edc, process_tri

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
loc <- data.frame(id = "001", lon = -78.90, lat = 35.97)
calculate_tri(
  from = tri, # derived from process_tri() example
  locs = loc,
  locs_id = "id",
  decay_range = c(1e3L, 1e4L, 5e4L)
)

## End(Not run)

Validate the .by_time temporal summarization argument

Description

Validates the .by_time argument used by covariate extraction functions for temporal summarization. When non-NULL, .by_time must be a single character string naming a supported temporal unit token (singular or plural): "minute", "hour", "day", "week", "month", "quarter", or "year".

Usage

check_by_time(.by_time)

Arguments

Value

NULL invisibly; stops with an informative error if the value is invalid.

Author(s)

Insang Song

Check if destination file exists or is 0 bytes.

Description

Check if destination file exists or is 0 bytes. If either condition is met, the function returns TRUE to allow the download to proceed.

Usage

check_destfile(destfile)

Arguments

Value

logical(1)

Check parameters

Description

Check that all parameters have been assigned a value.

Usage

check_for_null_parameters(parameters)

Arguments

Value

NULL; returns a stop error if one or more function parameters other than 'extent' are NULL

Validate the fun_temporal parameter

Description

Validates the fun_temporal argument used by covariate extraction functions. When NULL (the default), no temporal aggregation is applied and existing per-layer extraction behavior is preserved. When non-NULL, the value must be one of "mean", "median", "sum", "max", or "min".

Usage

check_fun_temporal(fun_temporal)

Arguments

Value

NULL invisibly; stops with an informative error if the value is invalid.

Author(s)

Insang Song

Check that geom value is one of FALSE, "sf", or "terra"

Description

Check that geom value is one of FALSE, "sf", or "terra".

Usage

check_geom(geom)

Arguments

Value

NULL; will stop if geom is not one of the three options

Author(s)

Mitchell Manware

Check sf object

Description

Check an sf object for its class, $geometry column, and geometry class.

Usage

check_mysf(x)

Arguments

Value

NULL; returns stop error if x does not match class and/or column expectations

Author(s)

Eva Marques

Check sftime object

Description

Check an sftime object for its class, $time column, $geometry column, and geometry class.

Usage

check_mysftime(x)

Arguments

Value

NULL; returns stop error if x does not match class and column expectations

Author(s)

Eva Marques

Reject deprecated legacy grouping argument in dots

Description

Internal helper for calculate APIs that now support temporal summarization via .by_time only. Stops immediately when a deprecated legacy grouping argument is supplied through ....

Usage

check_unsupported_by(..., .call = NULL)

Arguments

Value

NULL invisibly; stops on deprecated legacy grouping input.

Author(s)

Insang Song

Check HTTP status

Description

Check if provided URL returns HTTP status 200 or 206.

Usage

check_url_status(url, max_tries = 3L)

Arguments

Value

logical object

Author(s)

Insang Song; Mitchell Manware; Kyle Messier

Implement check_url_status

Description

Apply check_url_status() function to a sample of download URLs.

Usage

check_urls(urls = urls, size = NULL, method = NULL)

Arguments

Value

logical vector for URL status = 200

Collapse listed NLCD values while filling in NA for sites outside data.

Description

Collapse listed NLCD values while filling in NA for sites outside data.

Usage

collapse_nlcd(
  data,
  mode = c("terra", "exact"),
  locs = NULL,
  locs_id = "site_id"
)

Arguments

Download air quality data

Description

The download_aqs() function accesses and downloads Air Quality System (AQS) data from the U.S. Environmental Protection Agency's (EPA) Pre-Generated Data Files.

Usage

download_aqs(
  parameter_code = 88101,
  resolution_temporal = "daily",
  year = c(2018, 2022),
  url_aqs_download = "https://aqs.epa.gov/aqsweb/airdata/",
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Details

Common AQS parameter codes include:

• 88101 — PM2.5 - Local Conditions

• 88502 — Acceptable PM2.5 AQI & Speciation Mass

• 81102 — PM10 Total 0-10um STP

• 44201 — Ozone

• 42602 — Nitrogen dioxide (NO2)

• 42401 — Sulfur dioxide (SO2)

• 42101 — Carbon monoxide

This list is not exhaustive; for the full official table, see the linked EPA AQS parameter code table.

Value

invisible list with download results; or hash character if hash=TRUE

Note

AQS data does not require authentication. AQS measurements are generally intended for use as dependent variables, so the package supports download and processing for AQS but does not expose AQS through calculate_covariates().

Author(s)

Mariana Kassien, Insang Song, Mitchell Manware

References

U.S. Environmental Protection Agency (2023). “Air Quality System Data Mart [internet database].” https://www.epa.gov/outdoor-air-quality-data.

See Also

EPA AQS Parameter Codes

Examples

## Not run: 
download_aqs(
  parameter_code = 88101,
  resolution_temporal = "daily",
  year = 2023,
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download CropScape data

Description

Accesses and downloads United States Department of Agriculture CropScape Cropland Data Layer data from the USDA National Agricultural Statistics Service or the George Mason University website.

Usage

download_cropscape(
  year = seq(1997, 2023),
  source = c("USDA", "GMU"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  hash = FALSE,
  show_progress = TRUE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

• For hash = FALSE, NULL

• For hash = TRUE, an rlang::hash_file character.

• Yearly comma-separated value (CSV) files will be stored in directory_to_save.

Note

JSON files should be found at STAC catalog of OpenLandMap

Author(s)

Insang Song

Examples

## Not run: 
download_cropscape(
  year = 2020,
  source = "USDA",
  directory_to_save = tempdir(),
  acknowledgement = TRUE,
  download = FALSE, # NOTE: download skipped for examples,
  remove_command = TRUE,
  unzip = FALSE
)

## End(Not run)

Download raw data wrapper function

Description

The download_data() function accesses and downloads atmospheric, meteorological, and environmental data from various open-access data sources.

Usage

download_data(
  dataset_name = c("aqs", "ecoregion", "ecoregions", "geos", "goes", "goes_adp", "GOES",
    "gmted", "koppen", "koppengeiger", "merra2", "merra", "modis", "narr", "nlcd",
    "noaa", "sedac_groads", "sedac_population", "groads", "population", "hms", "smoke",
    "tri", "nei", "gridmet", "terraclimate", "huc", "cropscape", "cdl", "prism", "edgar",
    "improve", "IMPROVE", "drought", "spei", "eddi", "usdm"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  hash = FALSE,
  nasa_earth_data_token = NULL,
  rate_limit = 2,
  ...
)

Arguments

Value

• For hash = FALSE, NULL

• For hash = TRUE, an rlang::hash_file character.

• Data files will be downloaded and stored in respective sub-directories within directory_to_save. File format and sub-directory names depend on data source and dataset of interest.

Note

• All download function names are in download_* formats

Author(s)

Insang Song

See Also

For details of each download function per dataset, Please refer to:

• download_aqs: "aqs", "AQS"

• download_ecoregion: "ecoregions", "ecoregion"

• download_geos: "geos"

• download_goes: "goes", "goes_adp", "GOES"

• download_gmted: "gmted", "GMTED"

• download_koppen_geiger: "koppen", "koppengeiger"

• download_merra2: "merra2", "merra", "MERRA", "MERRA2"

• download_narr: "narr"

• download_nlcd: "nlcd", "NLCD"

• download_hms: "noaa", "smoke", "hms"

• download_groads: "sedac_groads", "groads"

• download_population: "sedac_population", "population"

• download_modis: "modis", "MODIS"

• download_tri: "tri", "TRI"

• download_nei: "nei", "NEI"

• download_gridmet: "gridMET", "gridmet"

• download_terraclimate: "TerraClimate", "terraclimate"

• download_huc: "huc"

• download_cropscape: "cropscape", "cdl"

• download_prism: "prism"

• download_edgar: "edgar"

• download_improve: "improve", "IMPROVE"

• download_drought: "drought", "spei", "eddi", "usdm"

Examples

## Not run: 
download_data(
  dataset_name = "narr",
  variables = "weasd",
  year = 2023,
  directory_to_save = tempdir(),
  acknowledgement = TRUE,
  download = FALSE, # NOTE: download skipped for examples,
  remove_command = TRUE
)

## End(Not run)

Download drought index data

Description

The download_drought() function downloads drought index data from publicly available sources. Three source datasets are supported:

• SPEI (Standardized Precipitation-Evapotranspiration Index): Multi-year netCDF files by timescale from https://spei.csic.es.

• EDDI (Evaporative Demand Drought Index): Weekly raster files by timescale from https://www.drought.gov/data-maps-tools/evaporative-demand-drought-index-eddi.

• USDM (U.S. Drought Monitor): Weekly drought class shapefiles from https://droughtmonitor.unl.edu.

Usage

download_drought(
  source = c("spei", "eddi", "usdm"),
  date = c("2020-01-01", "2020-12-31"),
  timescale = 1L,
  directory_to_save = NULL,
  acknowledgement = FALSE,
  hash = FALSE,
  show_progress = TRUE,
  max_tries = 3L,
  rate_limit = 2,
  unzip = TRUE,
  remove_zip = FALSE,
  ...
)

Arguments

Value

invisible(NULL) when hash = FALSE; a character hash string when hash = TRUE.

Note

• SPEI and EDDI are raster products; USDM is a polygon product (shapefile). Their process_drought() and calculate_drought() handling differ accordingly.

• No authentication is required for any of these sources.

Author(s)

Insang Song

See Also

process_drought, calculate_drought

Examples

## Not run: 
download_drought(
  source = "spei",
  date = c("2020-01-01", "2020-12-31"),
  timescale = 1L,
  directory_to_save = "./data/drought",
  acknowledgement = TRUE
)
download_drought(
  source = "usdm",
  date = c("2020-01-07", "2020-03-31"),
  directory_to_save = "./data/drought",
  acknowledgement = TRUE
)

## End(Not run)

Download ecoregion data

Description

The download_ecoregion() function accesses and downloads United States Ecoregions data from the U.S. Environmental Protection Agency's (EPA) Ecoregions.

Usage

download_ecoregion(
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

Ecoregion data does not require authentication.

Author(s)

Insang Song

References

Omernik JM, Griffith GE (2014). “Ecoregions of the Conterminous United States: Evolution of a Hierarchical Spatial Framework.” Environmental Management, 54(6), 1249–1266. ISSN 0364-152X, 1432-1009, doi:10.1007/s00267-014-0364-1, https://link.springer.com/article/10.1007/s00267-014-0364-1.

Examples

## Not run: 
download_ecoregion(
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download EDGAR Emissions Data

Description

Constructs and optionally downloads EDGAR emissions data URLs based on user-specified inputs including species, temporal resolution, emission sectors, and file formats.

Usage

download_edgar(
  species = c("BC", "CO", "NH3", "NMVOC", "NOx", "OC", "PM10", "PM2.5", "SO2"),
  version = "8.1",
  temp_res = NULL,
  sector_yearly = NULL,
  sector_monthly = NULL,
  sector_voc = NULL,
  format = "nc",
  output = "emi",
  year_range = NULL,
  voc = NULL,
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  hash = FALSE,
  show_progress = TRUE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

A list of download URLs (character). Optionally downloads available files and warns about missing ones.

• For hash = FALSE, NULL

• For hash = TRUE, an rlang::hash_file character.

• Zip and/or data files will be downloaded and stored in directory_to_save.

Author(s)

Mariana Alifa Kassien

Examples

## Not run: 
download_edgar(
species = "CO",
acknowledgement = TRUE,
temp_res = "yearly",
sector_yearly = "ENE",
year_range = c(2021, 2022)
)

## End(Not run)
## Not run: 
download_edgar(
species = "PM2.5",
acknowledgement = TRUE,
temp_res = "monthly",
sector_monthly = c("TRANSPORT", "WASTE")
)

## End(Not run)
## Not run: 
download_edgar(
species = "SO2",
acknowledgement = TRUE,
temp_res = "timeseries"
)

## End(Not run)

Download atmospheric composition data

Description

The download_geos() function accesses and downloads various atmospheric composition collections from NASA's Global Earth Observing System (GEOS) compositional forecast model.

Usage

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"),
  nasa_earth_data_token = NULL,
  date = c("2018-01-01", "2018-01-01"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

Due to NASA data access policies, downloads require a valid NASA Earthdata token for authentication. Use setup_nasa_token() for setup.

Author(s)

Mitchell Manware, Insang Song

References

Keller CA, Knowland KE, Duncan BN, Liu J, Anderson DC, Das S, Lucchesi RA, Lundgren EW, Nicely JM, Nielsen E, Ott LE, Saunders E, Strode SA, Wales PA, Jacob DJ, Pawson S (2021). “Description of the NASA GEOS Composition Forecast Modeling System GEOS‐CF v1.0.” Journal of Advances in Modeling Earth Systems, 13(4), e2020MS002413. ISSN 1942-2466, 1942-2466, doi:10.1029/2020MS002413.

Examples

## Not run: 
download_geos(
  collection = "aqc_tavg_1hr_g1440x721_v1",
  date = "2024-01-01",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download elevation data

Description

The download_gmted() function accesses and downloads Global Multi-resolution Terrain Elevation Data (GMTED2010) from U.S. Geological Survey.

Usage

download_gmted(
  statistic = c("Breakline Emphasis", "Systematic Subsample", "Median Statistic",
    "Minimum Statistic", "Mean Statistic", "Maximum Statistic",
    "Standard Deviation Statistic"),
  resolution = c("7.5 arc-seconds", "15 arc-seconds", "30 arc-seconds"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

GMTED data does not require authentication.

Author(s)

Mitchell Manware, Insang Song

References

Danielson JJ, Gesch DB (2011). “Global multi-resolution terrain elevation data 2010 (GMTED2010).” Open-File Report 2011-1073, U.S. Geological Survey. Series: Open-File Report, https://doi.org/10.3133/ofr20111073.

Examples

## Not run: 
download_gmted(
  statistic = "Breakline Emphasis",
  resolution = "7.5 arc-seconds",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download NOAA GOES ADP data

Description

The download_goes() function accesses and downloads NOAA GOES-16 or GOES-18 Aerosol Detection Product (ADP) files from the NOAA Open Data Dissemination (NODD) AWS S3 bucket. Files are in NetCDF format and contain aerosol detection variables (e.g. "Smoke", "Dust") on the GOES fixed geostationary grid.

Usage

download_goes(
  date = c("2024-01-01", "2024-01-01"),
  satellite = "16",
  product = "ADP-C",
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash = TRUE

Note

• GOES data does not require authentication.

• GOES-16 (East) covers the Americas; GOES-18 (West) covers the western hemisphere and Pacific.

• ADP-C (CONUS) scans are produced approximately every 5 minutes. A single day may contain several hundred files.

• GOES ADP files use the GOES fixed geostationary projection. Use process_goes() to load and reproject to EPSG:4326.

Author(s)

Mitchell Manware

Examples

## Not run: 
download_goes(
  date = "2024-01-01",
  satellite = "16",
  product = "ADP-C",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download gridMET data

Description

The download_gridmet function accesses and downloads gridded surface meteorological data from the University of California Merced Climatology Lab's gridMET dataset.

Usage

download_gridmet(
  variables = NULL,
  year = c(2018, 2022),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

gridMET data does not require authentication.

Author(s)

Mitchell Manware

References

Abatzoglou JT (2013). “Development of gridded surface meteorological data for ecological applications and modelling.” International journal of climatology, 33(1), 121–131.

Examples

## Not run: 
download_gridmet(
  variables = "pr",
  year = 2023,
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download roads data

Description

The download_groads() function accesses and downloads roads data from NASA's Global Roads Open Access Data Set (gROADS).

Usage

download_groads(
  data_region = c("Americas", "Global", "Africa", "Asia", "Europe", "Oceania East",
    "Oceania West"),
  data_format = c("Shapefile", "Geodatabase"),
  nasa_earth_data_token = NULL,
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

gROADS data is hosted on NASA EarthData and requires a valid NASA EarthData token for authentication. Set the NASA_EARTHDATA_TOKEN environment variable or pass the token directly via nasa_earth_data_token. Use setup_nasa_token() for setup.

Author(s)

Mitchell Manware, Insang Song

References

Center For International Earth Science Information Network-CIESIN-Columbia University, Information Technology Outreach Services-ITOS-University Of Georgia (2013). “Global Roads Open Access Data Set, Version 1 (gROADSv1).” doi:10.7927/H4VD6WCT, https://data.nasa.gov/dataset/global-roads-open-access-data-set-version-1-groadsv1.

Examples

## Not run: 
download_groads(
  data_region = "Americas",
  data_format = "Shapefile",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Create hash of downloaded files.

Description

Create a combined md5sum hash based on the files in a specified directory.

Usage

download_hash(hash = TRUE, dir = NULL)

Arguments

Value

character(1) Combined 128-bit md5sum of download files.

Download wildfire smoke data

Description

The download_hms() function accesses and downloads wildfire smoke plume coverage data from NOAA's Hazard Mapping System Fire and Smoke Product.

Usage

download_hms(
  data_format = "Shapefile",
  date = c("2018-01-01", "2018-01-01"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

HMS data does not require authentication.

Author(s)

Mitchell Manware, Insang Song

References

(????). “Hazard Mapping System Fire and Smoke Product: Hazard Mapping System.” https://www.ospo.noaa.gov/products/land/hms.html#about. https://www.ospo.noaa.gov/products/land/hms.html#about.

Examples

## Not run: 
download_hms(
  data_format = "Shapefile",
  date = "2024-01-01",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download National Hydrography Dataset (NHD) data

Description

NHDPlus data provides the most comprehensive and high-resolution hydrography data. This function downloads national dataset from NHDPlus Version 2.1 on USGS Amazon S3 storage.

Usage

download_huc(
  region = c("Lower48", "Islands"),
  type = c("Seamless", "OceanCatchment"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = FALSE,
  hash = FALSE,
  show_progress = TRUE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

• For hash = FALSE, NULL

• For hash = TRUE, an rlang::hash_file character.

• Downloaded files will be stored in directory_to_save.

Note

For HUC, set type = "Seamless". HUC12 layer presents in the seamless geodatabase. Users can aggregate HUC12 layer to make HUC6, HUC8, HUC10, etc. For whom wants to download a specific region, please visit Get NHDPlus Data

Author(s)

Insang Song

References

U.S. Geological Survey (2023). “National Hydrography Dataset (NHD) – USGS National Map Downloadable Data Collection.” https://www.usgs.gov/national-hydrography.

Examples

## Not run: 
download_huc(
  region = "Lower48",
  type = "Seamless",
  directory_to_save = tempdir(),
  acknowledgement = TRUE,
  download = FALSE, # NOTE: download skipped for examples,
  remove_command = TRUE,
  unzip = FALSE
)

## End(Not run)

Download IMPROVE aerosol monitoring data

Description

The download_improve() function accesses and downloads IMPROVE (Interagency Monitoring of Protected Visual Environments) data files from the VIEWS/VIBE data export service hosted at CIRA/CSU. Annual files are downloaded as .txt.zip archives and extracted to pipe-delimited .txt files containing aerosol measurements at federal-land monitoring stations.

Usage

download_improve(
  year = c(2018, 2022),
  product = c("raw", "rhr2", "rhr3"),
  url_improve = "https://vibe.cira.colostate.edu/data/export/",
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash = TRUE.

Note

• IMPROVE data does not require authentication.

• Three product types are available: "raw" (IMPAER — speciated aerosol mass concentrations), "rhr2" (IMPRHR2 — Regional Haze Rule II light extinction), "rhr3" (IMPRHR3 — Regional Haze Rule III deciview index).

• Site metadata is handled by process_improve using an embedded table; annual downloads include measurement files only.

• IMPROVE monitors ~1 \mu g / m^3 precision instruments deployed at Class I and other federal land areas.

Author(s)

Insang Song, Mitchell Manware

See Also

process_improve

Examples

## Not run: 
download_improve(
  year = 2022,
  product = "raw",
  directory_to_save = "./data/improve/",
  acknowledgement = TRUE
)

## End(Not run)

Download climate classification data

Description

The download_koppen_geiger() function accesses and downloads climate classification data.

Usage

download_koppen_geiger(
  data_resolution = c("0.0083", "0.083", "0.5"),
  time_period = c("Present", "Future"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

Köppen-Geiger data does not require authentication.

Author(s)

Mitchell Manware, Insang Song

References

Beck HE, McVicar TR, Vergopolan N, Berg A, Lutsko NJ, Dufour A, Zeng Z, Jiang X, Van Dijk AIJM, Miralles DG (2023). “High-resolution (1 km) Köppen-Geiger maps for 1901–2099 based on constrained CMIP6 projections.” Scientific Data, 10(1), 724. ISSN 2052-4463, doi:10.1038/s41597-023-02549-6, https://www.nature.com/articles/s41597-023-02549-6. Beck HE, Zimmermann NE, McVicar TR, Vergopolan N, Berg A, Wood EF (2018). “Present and future Köppen-Geiger climate classification maps at 1-km resolution.” Scientific data, 5(1), 1–12. doi:10.1038/sdata.2018.214.

Examples

## Not run: 
download_koppen_geiger(
  data_resolution = "0.0083",
  time_period = "Present",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download meteorological and atmospheric data

Description

The 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, and the daily corrected Global Fire Weather Index (FWI) product derived from MERRA-2 weather inputs.

Usage

download_merra2(
  collection = c("inst1_2d_asm_Nx", "inst1_2d_int_Nx", "inst1_2d_lfo_Nx",
    "inst3_3d_asm_Np", "inst3_3d_aer_Nv", "inst3_3d_asm_Nv", "inst3_3d_chm_Nv",
    "inst3_3d_gas_Nv", "inst3_2d_gas_Nx", "inst6_3d_ana_Np", "inst6_3d_ana_Nv",
    "statD_2d_slv_Nx", "tavg1_2d_adg_Nx", "tavg1_2d_aer_Nx", "tavg1_2d_chm_Nx",
    "tavg1_2d_csp_Nx", "tavg1_2d_flx_Nx", "tavg1_2d_int_Nx", "tavg1_2d_lfo_Nx",
    "tavg1_2d_lnd_Nx", "tavg1_2d_ocn_Nx", "tavg1_2d_rad_Nx", "tavg1_2d_slv_Nx",
    "tavg3_3d_mst_Ne", "tavg3_3d_trb_Ne", "tavg3_3d_nav_Ne", "tavg3_3d_cld_Np", 
    
    "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", "fwi"),
  nasa_earth_data_token = NULL,
  date = c("2018-01-01", "2018-01-01"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  hash = FALSE,
  show_progress = TRUE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

Due to NASA data access policies, standard MERRA-2 GES DISC downloads require a valid NASA Earthdata token for authentication. Use setup_nasa_token() for setup. The "fwi" collection is hosted on the public GlobalFWI portal and does not require Earthdata authentication.

Author(s)

Mitchell Manware, Insang Song, Kyle Messier

Examples

## Not run: 
download_merra2(
  collection = "inst1_2d_int_Nx",
  date = "2024-01-01",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download MODIS product files

Description

Downloads MODIS data using httr2 with robust retry logic and rate limiting. This function queries NASA's CMR API for available granules and downloads relevant tiles based on the specified extent.

Usage

download_modis(
  product = c("MOD09GA", "MYD09GA", "MOD09GQ", "MYD09GQ", "MOD09A1", "MYD09A1",
    "MOD09Q1", "MYD09Q1", "MOD11A1", "MYD11A1", "MOD11A2", "MYD11A2", "MOD11B1",
    "MYD11B1", "MOD13A1", "MYD13A1", "MOD13A2", "MYD13A2", "MOD13Q1", "MYD13Q1",
    "MOD13A3", "MYD13A3", "MCD12Q1", "MOD14A1", "MYD14A1", "MOD14A2", "MYD14A2",
    "MOD14CM1", "MYD14CM1", "MOD16A2", "MYD16A2", "MCD64A1", "MCD64CMQ", "MOD06_L2",
    "MCD14ML", "MCD19A2", "VNP46A2", "VNP64A1"),
  version = "061",
  nasa_earth_data_token = NULL,
  date = c("2023-09-01", "2023-09-01"),
  extent = c(-125, 22, -64, 50),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

Due to NASA data access policies, downloads require a valid NASA Earthdata token for authentication. For security, it's recommended to store your token in an environment variable or file rather than in your code. Use setup_nasa_token() for easy, secure token setup.

Both dates in date should be in the same year. Directory structure: input/modis/raw/{version}/{product}/{year}/{day_of_year}.

Author(s)

Mitchell Manware, Insang Song

References

Lyapustin A, Wang Y (2022). “MODIS/Terra+Aqua Land Aerosol Optical Depth Daily L2G Global 1km SIN Grid V061.” doi:10.5067/MODIS/MCD19A2.061, https://www.earthdata.nasa.gov/data/catalog/lpcloud-mcd19a2-061. MODIS Atmosphere Science Team (2017). “MODIS/Terra Clouds 5-Min L2 Swath 1km and 5km.” doi:10.5067/MODIS/MOD06_L2.061, https://ladsweb.modaps.eosdis.nasa.gov/missions-and-measurements/products/MOD06_L2. Vermote E, Wolfe R (2021). “MODIS/Terra Surface Reflectance Daily L2G Global 1km and 500m SIN Grid V061.” doi:10.5067/MODIS/MOD09GA.061, https://www.earthdata.nasa.gov/data/catalog/lpcloud-mod09ga-061. Wan Z, Hook S, Hulley G (2021). “MODIS/Terra Land Surface Temperature/Emissivity Daily L3 Global 1km SIN Grid V061.” doi:10.5067/MODIS/MOD11A1.061, https://www.earthdata.nasa.gov/data/catalog/lpcloud-mod11a1-061. Didan K (2021). “MODIS/Terra Vegetation Indices 16-Day L3 Global 1km SIN Grid V061.” doi:10.5067/MODIS/MOD13A2.061, https://www.earthdata.nasa.gov/data/catalog/lpcloud-mod13a2-061. Román MO, Wang Z, Sun Q, Kalb V, Miller SD, Molthan A, Schultz L, Bell J, Stokes EC, Pandey B, Seto KC, Hall D, Oda T, Wolfe RE, Lin G, Golpayegani N, Devadiga S, Davidson C, Sarkar S, Praderas C, Schmaltz J, Boller R, Stevens J, Ramos González OM, Padilla E, Alonso J, Detrés Y, Armstrong R, Miranda I, Conte Y, Marrero N, MacManus K, Esch T, Masuoka EJ (2018). “NASA's Black Marble nighttime lights product suite.” Remote Sensing of Environment, 210, 113–143. ISSN 00344257, doi:10.1016/j.rse.2018.03.017, https://linkinghub.elsevier.com/retrieve/pii/S003442571830110X.

Examples

## Not run: 
# RECOMMENDED: Set up token once (persists across sessions)
setup_nasa_token()

# Then download without specifying token
download_modis(
  product = "MOD09GA",
  version = "061",
  date = "2024-01-01",
  extent = c(-80, 35, -75, 40),
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

# ALTERNATIVE: Token from file
download_modis(
  product = "MOD09GA",
  version = "061",
  date = "2024-01-01",
  extent = c(-80, 35, -75, 40),
  nasa_earth_data_token = "~/.nasa_earthdata_token",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

# ALTERNATIVE: Set token for current session
Sys.setenv(NASA_EARTHDATA_TOKEN = "your_token_here")
download_modis(
  product = "MOD09GA",
  date = "2024-01-01",
  acknowledgement = TRUE
)

# Date range
download_modis(
  product = "MOD09GA",
  version = "061",
  date = c("2024-01-01", "2024-01-07"),
  extent = c(-80, 35, -75, 40),
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download meteorological data

Description

The download_narr function accesses and downloads daily meteorological data from NOAA's North American Regional Reanalysis (NARR) model via the NOAA Physical Sciences Laboratory (PSL) NARR Dailies server (https://downloads.psl.noaa.gov/Datasets/NARR/Dailies/).

Usage

download_narr(
  variables = NULL,
  year = c(2018, 2022),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Available NARR Variables

The variables argument accepts one or more of the following abbreviations. Variables are grouped into three categories that determine the source URL path used for download.

Monolevel variables (single vertical level, surface / near-surface fields):

acpcp

Convective precipitation

air.2m

Air temperature at 2 m

air.sfc

Air temperature at surface

albedo

Surface albedo

apcp

Total accumulated precipitation

bgrun

Baseflow-groundwater runoff

bmixl.hl1

Blackadar mixing length scale at hybrid level 1

cape

Convective available potential energy

ccond

Canopy conductance

cdcon

Convective cloud cover

cdlyr

Non-convective cloud cover

cfrzr

Categorical freezing rain

cicep

Categorical ice pellets

cin

Convective inhibition

cnwat

Plant canopy surface water

crain

Categorical rain

csnow

Categorical snow

dlwrf

Downward longwave radiation flux

dpt.2m

Dew point temperature at 2 m

dswrf

Downward shortwave radiation flux

evap

Evaporation

gflux

Ground heat flux

hcdc

High cloud cover

hgt.tropo

Geopotential height at tropopause

hlcy

Storm relative helicity

hpbl

Planetary boundary layer height

lcdc

Low cloud cover

lftx4

Best (4-layer) lifted index

lhtfl

Latent heat net flux

mcdc

Mid-cloud cover

mconv.hl1

Horizontal moisture divergence at hybrid level 1

mslet

Mean sea level pressure (ETA model reduction)

mstav

Moisture availability

pevap

Potential evaporation

pottmp.hl1

Potential temperature at hybrid level 1

pottmp.sfc

Potential temperature at surface

prate

Precipitation rate

pres.sfc

Surface pressure

pres.tropo

Pressure at tropopause

prmsl

Pressure reduced to mean sea level

pr_wtr

Precipitable water

rcq

Specific humidity tendency from all physics

rcs

Snowfall water equivalent tendency

rcsol

Solar radiative heating rates

rct

Temperature tendency from all physics

rhum.2m

Relative humidity at 2 m

shtfl

Sensible heat net flux

shum.2m

Specific humidity at 2 m

snod

Snow depth

snohf

Snow phase-change heat flux

snom

Snow melt

snowc

Snow cover

soilm

Soil moisture content (0–200 cm layer)

ssrun

Storm surface runoff

tcdc

Total cloud cover

tke.hl1

Turbulent kinetic energy at hybrid level 1

ulwrf.ntat

Upward longwave radiation flux at nominal top of atmosphere

ulwrf.sfc

Upward longwave radiation flux at surface

ustm

U-component of storm motion

uswrf.ntat

Upward shortwave radiation flux at nominal top of atmosphere

uswrf.sfc

Upward shortwave radiation flux at surface

uwnd.10m

U-component of wind at 10 m

veg

Vegetation fraction

vis

Visibility

vstm

V-component of storm motion

vvel.hl1

Vertical velocity at hybrid level 1

vwnd.10m

V-component of wind at 10 m

vwsh.tropo

Vertical wind shear at tropopause

wcconv

Convective wetting of vegetation canopy

wcinc

Wetting of vegetation canopy

wcuflx

U-component of convective canopy moisture flux

wcvflx

V-component of convective canopy moisture flux

weasd

Water-equivalent accumulated snow depth

wvconv

Convective column moisture convergence

wvinc

Column moisture increase

wvuflx

U-component of vertically-integrated moisture flux

wvvflx

V-component of vertically-integrated moisture flux

Pressure level variables (29 atmospheric pressure levels from 1000 to 100 hPa; all levels are downloaded together):

air

Air temperature

hgt

Geopotential height

omega

Vertical velocity (pressure / omega)

shum

Specific humidity

tke

Turbulent kinetic energy

uwnd

U-component of wind

vwnd

V-component of wind

Subsurface (soil) variables (4 soil layers):

soill

Liquid volumetric soil moisture (non-frozen fraction)

soilw

Volumetric soil moisture content

tsoil

Soil temperature

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.

The 88 variables supported by this function represent the complete set of variables available as individual NetCDF files on the PSL NARR Dailies server. The NARR archive also contains additional variables (e.g., cloud water mixing ratio, ice mixing ratio, surface friction velocity, momentum fluxes, and static land/soil properties) that are only present in the raw merged GRIB files (merged_AWIP32.YYYYMMDDHH) available at https://ftp.cpc.ncep.noaa.gov/NARR/. Those variables cannot be downloaded with this function.

Author(s)

Mitchell Manware, Insang Song, Kyle Messier

References

Mesinger F, DiMego G, Kalnay E, Mitchell K, Shafran PC, Ebisuzaki W, Jović D, Woollen J, Rogers E, Berbery EH, Ek MB, Fan Y, Grumbine R, Higgins W, Li H, Lin Y, Manikin G, Parrish D, Shi W (2006). “North American Regional Reanalysis.” Bulletin of the American Meteorological Society, 87(3), 343–360. ISSN 0003-0007, 1520-0477, doi:10.1175/BAMS-87-3-343.

Examples

## Not run: 
download_narr(
  variables = c("weasd", "omega"),
  year = 2023,
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

# Multiple years
download_narr(
  variables = c("air.2m", "rhum.2m"),
  year = c(2020, 2022),
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download road emissions data

Description

The download_nei() function accesses and downloads road emissions data from the U.S Environmental Protection Agency's (EPA) National Emissions Inventory (NEI).

Usage

download_nei(
  epa_certificate_path = NULL,
  certificate_url = paste0("http://cacerts.digicert.com/",
    "DigiCertGlobalG2TLSRSASHA2562020CA1-1.crt"),
  year = c(2017L, 2020L),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

NEI data does not require authentication.

Author(s)

Kyle Messier, Insang Song

References

United States Environmental Protection Agency (2024). “Air Emissions Inventories.” https://www.epa.gov/air-emissions-inventories.

Examples

## Not run: 
download_nei(
  year = c(2017L, 2020L),
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download National Land Cover Database (NLCD) data

Description

Downloads NLCD data products from the Multi-Resolution Land Characteristics (MRLC) Consortium. NLCD provides nationwide land cover and land cover change information for the United States at a 30m resolution.

Usage

download_nlcd(
  product = "Land Cover",
  year = 2021,
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible NULL; or hash character if hash=TRUE

Author(s)

Mitchell Manware, Insang Song, Kyle Messier

References

Dewitz J (2023). “National Land Cover Database (NLCD) 2021 Products.” doi:10.5066/P9JZ7AO3.

Examples

## Not run: 
# Download 2021 Land Cover
download_nlcd(
  product = "Land Cover",
  year = 2021,
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

# Download Land Cover Change for 2019
download_nlcd(
  product = "Land Cover Change",
  year = 2019,
  directory_to_save = tempdir(),
  acknowledgement = TRUE,
  unzip = TRUE,
  remove_zip = TRUE
)

## End(Not run)

Check data download acknowledgement

Description

Return an error if the acknowledgement = FALSE.

Usage

download_permit(acknowledgement)

Arguments

Value

NULL; returns a stop error if the acknowledgement is FALSE

Note

The acknowledgement parameter is designed to help users avoid accidentally initiating a very large data download that may take a very long time to run or exceed machine capabilities.

Download population density data

Description

The download_population() function accesses and downloads population density data from NASA's UN WPP-Adjusted Population Density.

Usage

download_population(
  data_resolution = "60 minute",
  data_format = c("GeoTIFF", "ASCII", "netCDF"),
  year = "2020",
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2,
  nasa_earth_data_token = NULL
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

Population data may require NASA EarthData authentication depending on access method.

Author(s)

Mitchell Manware, Insang Song

References

Center For International Earth Science Information Network-CIESIN-Columbia University (2017). “Gridded Population of the World, Version 4 (GPWv4): Population Density, Revision 11.” doi:10.7927/H49C6VHW, https://earthdata.nasa.gov/data/catalog/sedac-ciesin-sedac-gpwv4-popdens-r11-4.11.

Examples

## Not run: 
# RECOMMENDED: Set up token once (persists across sessions)
setup_nasa_token()

download_population(
  data_resolution = "30 second",
  data_format = "GeoTIFF",
  year = "2020",
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download PRISM data

Description

Accesses and downloads Oregon State University's PRISM data from the PRISM Climate Group Web Service

Usage

download_prism(
  time,
  element = c("ppt", "tmin", "tmax", "tmean", "tdmean", "vpdmin", "vpdmax", "solslope",
    "soltotal", "solclear", "soltrans"),
  data_type = c("ts", "normals_800", "normals"),
  format = c("nc", "asc", "grib2"),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  unzip = TRUE,
  remove_zip = FALSE,
  hash = FALSE,
  show_progress = TRUE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

• For hash = FALSE, NULL

• For hash = TRUE, an rlang::hash_file character.

• .bil (normals) or single grid files depending on the format choice will be stored in directory_to_save.

Author(s)

Insang Song

References

Daly C, Taylor GH, Gibson WP, Parzybok TW, Johnson GL, Pasteris PA (2000). “HIGH-QUALITY SPATIAL CLIMATE DATA SETS FOR THE UNITED STATES AND BEYOND.” Transactions of the ASAE, 43(6), 1957–1962. ISSN 2151-0059, doi:10.13031/2013.3101, http://elibrary.asabe.org/abstract.asp??JID=3&AID=3101&CID=t2000&v=43&i=6&T=1.

• PRISM Climate Group

• PRISM Web Service Guide

Examples

## Not run: 
download_prism(
  time = "202104",
  element = "ppt",
  data_type = "ts",
  format = "nc",
  directory_to_save = tempdir(),
  acknowledgement = TRUE,
  download = FALSE, # NOTE: download skipped for examples,
  remove_command = TRUE
)

## End(Not run)

Remove download commands

Description

Remove or retain the .txt file storing all download commands.

Usage

download_remove_command(commands_txt = NULL, remove = FALSE)

Arguments

Value

NULL; removes .txt/.bat file storing all download commands.

Remove zip files

Description

Remove downloaded ".zip" files.

Usage

download_remove_zips(remove = FALSE, download_name)

Arguments

Value

NULL; removes downloaded zip files after they are unzipped

Note

!!! USE THE FUNCTION WITH CAUTION !!! If remove = TRUE, ensure that unzip = TRUE. Choosing to remove ".zip" files without unzipping will retain none of the downloaded data. then it will remove all files in the second higher level directory.

Legacy download_run function for backwards compatibility

Description

DEPRECATED: This function is maintained for backwards compatibility. New code should use download_run_method() directly.

Execute or skip the commands listed in the ...wget/curl_commands.txt file produced by one of the data download functions.

Usage

download_run(download = FALSE, commands_txt = NULL, remove = FALSE)

Arguments

Value

NULL; runs download commands with shell (Unix/Linux) or command prompt (Windows) and removes commands_txt file if remove = TRUE.

Download files using httr2

Description

Execute downloads using httr2 with robust retry logic and rate limiting. This function handles authentication, retries, progress tracking, and streams files directly to disk. HTTP-status retries use exponential backoff capped at 30 s to avoid long hangs from DNS timeouts (each attempt takes ~10 s). Transport-level failures (SSL drops, connection resets) are also retried up to max_tries times.

Usage

download_run_method(
  urls = NULL,
  destfiles = NULL,
  token = NULL,
  show_progress = TRUE,
  max_tries = 20,
  rate_limit = 2,
  timeout = 3600,
  http_version = NULL
)

Arguments

Value

invisible list with success and failure counts

Sanitize directory

Description

Append forward slash to end of directory if it does not already end with one.

Usage

download_sanitize_path(directory)

Arguments

Value

character ending with a forward slash.

Setup directory

Description

Create directory if it does not already exist.

If directory does not exist, the directory will be created.

Usage

download_setup_dir(directory, zip = FALSE)

Arguments

Value

NULL; if zip = TRUE a vector of directories for zip files and data files

Sink download commands

Description

Open connection to command_txt file to store download commands.

Usage

download_sink(command_txt)

Arguments

Value

NULL; creates and opens connection to text file to store download commands

Download TerraClimate data

Description

The download_terraclimate function accesses and downloads climate and water balance data from the University of California Merced Climatology Lab's TerraClimate dataset.

Usage

download_terraclimate(
  variables = NULL,
  year = c(2018, 2022),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

TerraClimate data does not require authentication.

Author(s)

Mitchell Manware, Insang Song

References

Abatzoglou JT, Dobrowski SZ, Parks SA, Hegewisch KC (2018). “TerraClimate, a high-resolution global dataset of monthly climate and climatic water balance from 1958–2015.” Scientific data, 5(1), 1–12.

Examples

## Not run: 
download_terraclimate(
  variables = "ppt",
  year = 2023,
  directory_to_save = tempdir(),
  acknowledgement = TRUE
)

## End(Not run)

Download toxic release data

Description

The download_tri() function accesses and downloads toxic release data from the U.S. Environmental Protection Agency's (EPA) Toxic Release Inventory (TRI) Program. The EPA TRI basic data files contain annual, facility-reported toxic chemical release and waste management information. EPA publishes TRI basic files in multiple annual variants under the same service endpoint: a nationwide file ("US"), state-specific files identified by two-letter postal abbreviations (for example "AZ" or "NC"), and a tribal file ("tbl").

Usage

download_tri(
  year = c(2018L, 2022L),
  directory_to_save = NULL,
  acknowledgement = FALSE,
  jurisdiction = "US",
  download = TRUE,
  remove_command = FALSE,
  show_progress = TRUE,
  hash = FALSE,
  max_tries = 20,
  rate_limit = 2
)

Arguments

Value

invisible list with download results; or hash character if hash=TRUE

Note

TRI data does not require authentication. State and tribal downloads are saved with jurisdiction-specific file names, while the U.S.-wide download keeps the historical tri_raw_<year>.csv naming pattern.

Author(s)

Mariana Kassien, Insang Song

References

United States Environmental Protection Agency (2024). “TRI Basic Data Files: Calendar Years 1987 – Present.” https://www.epa.gov/toxics-release-inventory-tri-program/tri-data-action-0.

Examples

## Not run: 
download_tri(
  year = 2021L,
  directory_to_save = tempdir(),
  jurisdiction = "NC",
  acknowledgement = TRUE
)

## End(Not run)

Extract downloaded archives

Description

Extract downloaded ".zip" or ".7z" files.

Usage

download_unzip(file_name, directory_to_unzip, unzip = TRUE)

Arguments

Value

NULL; extracts downloaded archive files

Generate weekly Tuesday dates for drought products

Description

Return a character vector of YYYYMMDD strings for each Tuesday falling within [date_start, date_end]. EDDI and USDM are both released on Tuesdays; this helper centralises the logic.

Usage

drought_weekly_dates(date_start, date_end)

Arguments

Value

character vector of "YYYYMMDD" strings (may be length 0).

Convert a data.table to an sftime

Description

Convert a data.table object to an sftime. x must be a data.table object with "lon", "lat", and "time" columns to describe the longitude, latitude, and time-orientation, respectively, of x.

Usage

dt_as_mysftime(x, lonname, latname, timename, crs)

Arguments

Value

an sftime object

Author(s)

Eva Marques

Convert spatial extent to MODIS sinusoidal tile codes

Description

Returns the set of MODIS sinusoidal grid tile codes (e.g. "h08v04") whose geographic footprint overlaps the supplied bounding box.

Usage

extent_to_modis_tiles(extent)

Arguments

Details

The MODIS sinusoidal grid divides the globe into 18 x 36 tiles, each nominally covering 10 degrees of latitude. Because the sinusoidal projection compresses longitude at high latitudes, the geographic lon/lat bounding boxes of tiles are not simple 10-degree squares — they can be significantly wider in geographic longitude near the poles.

This function uses the official NASA MODLAND sinusoidal tile bounding coordinates table (sn_bound_10deg.txt, https://modis-land.gsfc.nasa.gov/pdf/sn_bound_10deg.txt) bundled in inst/extdata/. It returns every non-fill tile whose geographic bounding box overlaps the requested extent.

Horizontal tile numbers (h) range from 0 to 35 (west to east); vertical tile numbers (v) range from 0 to 17 (north to south).

Value

character vector of tile codes in "hXXvYY" format, ordered by increasing v then h.

Author(s)

Kyle Messier

See Also

download_modis

Examples

extent_to_modis_tiles(c(-125, 22, -64, 50))

Extract download URLs

Description

Extract download URLs from multi-argument download commands.

Usage

extract_urls(commands = commands, position = NULL)

Arguments

Value

character vector containing download URLs

Generate date sequence

Description

Generate a sequence of dates from date_start to date_end.

Usage

generate_date_sequence(date_start, date_end, sub_hyphen = TRUE)

Arguments

Value

vector

Generate time sequence

Description

Generate a sequence of time values based on the GEOS-CF collection.

Usage

generate_time_sequence(collection)

Arguments

Value

vector

Note

GEOS-CF hourly values are observed on the hour (ie. 0000 = 12:00:00 AM, 0100 = 01:00:00 AM) or the half hour (ie. 0030 = 12:30:00 AM, 0130 = 01:30:00 AM). Typically, 2-dimensional collections (latitude and longitude only) utilize half hour, and 3-dimensional collections (latitude, longitude, and time) utilize hour.

Get GEOS variable lookup information

Description

Returns a lookup table of available GEOS collection and variable selectors from locally downloaded GEOS-CF netCDF files. This helper inspects layer metadata only and does not read raster values into memory.

Usage

get_geos_info(path = NULL, include_file = FALSE, ...)

Arguments

Value

a data.frame with GEOS collection and variable selectors.

Author(s)

Kyle Messier

Examples

## Not run: 
get_geos_info(path = "./data/geos")
get_geos_info(path = "./data/geos", include_file = TRUE)

## End(Not run)

Get MERRA2 variable lookup information

Description

Returns a lookup table of available MERRA2 collection and variable selectors from locally downloaded MERRA2 netCDF files. This helper inspects layer metadata only and does not read raster values into memory.

Usage

get_merra2_info(path = NULL, include_file = FALSE, ...)

Arguments

Value

a data.frame with MERRA2 collection and variable selectors.

Author(s)

Kyle Messier

Examples

## Not run: 
get_merra2_info(path = "./data/merra2")
get_merra2_info(path = "./data/merra2", include_file = TRUE)

## End(Not run)

Get MODIS product subdataset lookup information

Description

Returns a lookup table of available MODIS product and subdataset selectors from locally downloaded MODIS/VIIRS-style HDF/H5 files. This helper uses metadata inspection (terra::describe(..., sds = TRUE) and layer names) and does not read raster values into memory.

Usage

get_modis_info(path = NULL, include_file = FALSE, ...)

Arguments

Value

a data.frame with MODIS product and subdataset selectors.

Author(s)

Kyle Messier

Examples

## Not run: 
get_modis_info(path = "./data/modis")
get_modis_info(path = "./data/modis", include_file = TRUE)

## End(Not run)

Get authentication token from various sources

Description

Retrieves authentication token from environment variable, file, or direct input. Priority order: 1) Environment variable, 2) File path, 3) Direct token string. This function helps prevent accidental token exposure in code or logs.

Usage

get_token(token = NULL, env_var = "NASA_EARTHDATA_TOKEN")

Arguments

Value

character(1). The authentication token

Get TRI lookup information for chemicals or industries

Description

Returns a lookup table from local TRI files. By default it returns chemical information (TRI_CHEMICAL_COMPOUND_ID, CHEMICAL, CASN). Set type = "industries" to return industry sector information (INDUSTRY_SECTOR_CODE, INDUSTRY_SECTOR).

Usage

get_tri_info(
  path = NULL,
  type = c("chemicals", "industries"),
  year = NULL,
  include_na = FALSE,
  ...
)

Arguments

Value

a data.frame containing the requested TRI lookup table.

Author(s)

Kyle Messier

Examples

## Not run: 
get_tri_info(path = "./data")
get_tri_info(path = "./data", type = "industries")
get_tri_info(path = "./data", year = 2020)

## End(Not run)

Parse GOES start datetime from filename

Description

Extracts the scan start datetime from a GOES-R series ADP filename. The start timestamp field uses the format sYYYYDDDHHMMSSf where DDD is the day of year (1–366).

Usage

goes_parse_start_datetime(path)

Arguments

Value

POSIXct scalar (UTC).

Check date format

Description

Check date input strings conform to the required format.

Usage

is_date_proper(instr = NULL, format = "%Y-%m-%d")

Arguments

Value

No returning value. It stops the function if instr doesn't conform to the format.

Author(s)

Insang Song

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/.

Usage

narr_variable(variable)

Arguments

Value

list with URL base and vector of months (blank for monolevel)

Normalize .by_time time-unit aliases

Description

Internal helper that maps singular/plural .by_time tokens to canonical units.

Usage

normalize_by_time_unit(unit)

Arguments

Value

character(1). Canonical unit.

Author(s)

Insang Song

Process U.S. EPA AQS daily CSV data

Description

The process_aqs() function cleans and imports raw air quality 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 exceptional events the internal procedure of this function keeps "Included" if there are multiple event types per site-time.

Usage

process_aqs(
  path = NULL,
  date = c("2018-01-01", "2022-12-31"),
  mode = c("date-location", "available-data", "location"),
  data_field = "Arithmetic.Mean",
  return_format = c("terra", "sf", "data.table"),
  extent = NULL,
  ...
)

Arguments

Value

a SpatVector, sf, or data.table object depending on the return_format

Note

Choose date and mode values with caution. 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. AQS data are generally intended for use as dependent variables, so process_aqs() does not have a companion route in calculate_covariates().

See Also

• download_aqs()

• EPA, n.d., AQS Parameter Codes

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
aqs <- process_aqs(
  path = "./data/aqs_daily_example.csv",
  date = c("2022-12-01", "2023-01-31"),
  mode = "date-location",
  return_format = "terra"
)

## End(Not run)

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 Black Marble product. Referencing corner coordinates are necessary as the original h5 data do not include such information.

Usage

process_blackmarble(
  path = NULL,
  date = NULL,
  tile_df = process_blackmarble_corners(),
  subdataset = 3L,
  crs = "EPSG:4326",
  ...
)

Arguments

Value

a SpatRaster object

Author(s)

Insang Song

References

• Wang, Z. (2022). Black Marble User Guide (Version 1.3). NASA.

See Also

• terra::describe

• terra::merge

• process_blackmarble_corners

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
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"
)

## End(Not run)

Process Black Marble corners

Description

Tile corner generator for Black Marble products.

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.

Usage

process_blackmarble_corners(hrange = c(5, 11), vrange = c(3, 6))

Arguments

Value

data.frame with xmin, xmax, ymin, and ymax fields

Author(s)

Insang Song

References

• Wang, Z. (2022). Black Marble User Guide (Version 1.3). NASA.

Examples

process_blackmarble_corners(hrange = c(1, 2), vrange = c(1, 2))

Process GEOS-CF and MERRA2 collection codes

Description

Identify the GEOS-CF or MERRA2 collection based on the file path.

Usage

process_collection(
  path,
  source,
  collection = FALSE,
  date = FALSE,
  datetime = FALSE
)

Arguments

Value

character

Check input assumptions

Description

Check if all of "lon", "lat", and "time" (only if check_time = TRUE) then convert inputs into a SpatVector object.

Usage

process_conformity(locs = NULL, check_time = FALSE, locs_epsg = "EPSG:4326")

Arguments

Value

a SpatVector object

Author(s)

Insang Song

Process raw data wrapper function

Description

This function processes raw data files which have been downloaded by download_data. process_covariates and the underlying source-specific processing functions have been designed to operate on the raw data files. To avoid errors, do not edit the raw data files before passing to process_covariates.

Usage

process_covariates(
  covariate = c("modis_swath", "modis_merge", "mcd14ml", "koppen-geiger", "blackmarble",
    "koeppen-geiger", "koppen", "koeppen", "geos", "goes", "goes_adp", "GOES", "dummies",
    "gmted", "aqs", "hms", "smoke", "sedac_population", "population", "sedac_groads",
    "groads", "roads", "nlcd", "tri", "narr", "nei", "ecoregions", "ecoregion", "merra",
    "merra2", "gridmet", "terraclimate", "huc", "cropscape", "cdl", "prism", "edgar",
    "improve", "IMPROVE", "drought", "spei", "eddi", "usdm"),
  path = NULL,
  ...
)

Arguments

Value

SpatVector, SpatRaster, sf, data.table, or character depending on covariate type and selections.

Author(s)

Insang Song

See Also

• process_modis_swath: "modis_swath"

• process_modis_merge: "modis_merge"

• process_blackmarble: "blackmarble"

• process_koppen_geiger: "koppen-geiger", "koeppen-geiger", "koppen"

• process_ecoregion: "ecoregion", "ecoregions"

• process_nlcd: "nlcd", "NLCD"

• process_tri: "tri", "TRI"

• process_nei: "nei", "NEI"

• process_geos: "geos", "GEOS"

• process_goes: "goes", "goes_adp", "GOES"

• process_gmted: "gmted", "GMTED"

• process_aqs: "aqs", "AQS"

• process_edgar: "edgar"

• process_improve: "improve", "IMPROVE"

• process_hms: "hms", "smoke", "HMS"

• process_narr: "narr", "NARR"

• process_groads: "sedac_groads", "roads", "groads"

• process_population: "sedac_population", "population"

• process_merra2: "merra", "merra2", "MERRA2"

• process_gridmet: "gridmet", "gridMET"

• process_terraclimate: "terraclimate", "TerraClimate"

• process_huc: "huc", "HUC"

• process_cropscape: "cropscape", "cdl"

• process_prism: "prism", "PRISM"

• process_drought: "drought", "spei", "eddi", "usdm"

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
process_covariates(
  covariate = "narr",
  date = c("2018-01-01", "2018-01-10"),
  variable = "weasd",
  path = system.file("extdata", "examples", "narr", "weasd")
)

## End(Not run)

Process CropScape data

Description

This function imports and cleans raw CropScape data, returning a single SpatRaster object.

Reads CropScape file of selected year.

Usage

process_cropscape(path = NULL, year = 2021, extent = NULL, ...)

Arguments

Value

a SpatRaster object

Author(s)

Insang Song

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
cropscape <- process_cropscape(
  path = "./data/cropscape_example.tif",
  year = 2020
)

## End(Not run)

Process drought index data

Description

The process_drought() function imports and cleans raw drought index files returned by download_drought(), producing a harmonized output object ready for calculate_drought():

• SPEI / EDDI — returns a SpatRaster with one layer per time step, layer names in "<source>_<timescale>_YYYY-MM-DD" format, CRS set to EPSG:4326.

• USDM — returns a SpatVector (polygon) with columns DM (drought-monitor class, integer 0–4), date (Date), and source ("usdm"), CRS EPSG:4326.

Usage

process_drought(
  source = c("spei", "eddi", "usdm"),
  path = NULL,
  date = c("2020-01-01", "2020-12-31"),
  timescale = 1L,
  extent = NULL,
  ...
)

Arguments

Value

• SpatRaster for SPEI or EDDI sources.

• SpatVector (polygons) for USDM source.

Note

• SPEI/EDDI files are expected to follow the naming convention produced by download_drought(): spei<timescale>.nc and either legacy eddi<timescale>mn<year>.nc or current EDDI_ETrs_<timescale>mn_<YYYYMMDD>.asc.

• USDM files are expected to be weekly shapefiles named USDM_<YYYYMMDD>.shp.

• Layer/column naming is standardised so that calculate_drought() can operate identically regardless of source.

Author(s)

Insang Song

See Also

download_drought, calculate_drought

Examples

## Not run: 
## SPEI
spei <- process_drought(
  source = "spei",
  path = "./data/drought",
  date = c("2020-01-01", "2020-12-31"),
  timescale = 1L
)
## USDM
usdm <- process_drought(
  source = "usdm",
  path = "./data/drought",
  date = c("2020-01-07", "2020-03-31")
)

## End(Not run)

Process ecoregion data

Description

The process_ecoregion function imports and cleans raw ecoregion data, returning a SpatVector object.

Usage

process_ecoregion(path = NULL, extent = NULL, ...)

Arguments

Value

a SpatVector object

Note

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.

Author(s)

Insang Song

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires a large
##       amount of data which is not included in the package.
## Not run: 
ecoregion <- process_ecoregion(
  path = "./data/epa_ecoregion.gpkg"
)

## End(Not run)

Process EDGAR emissions data

Description

The process_edgar() function imports extracted EDGAR gridded emissions files and returns a single SpatRaster object. Raster formats supported by terra::rast() such as NetCDF (.nc, .nc4) and GeoTIFF (.tif, .tiff) are supported.

Usage

process_edgar(path = NULL, extent = NULL, ...)

Arguments

Value

a SpatRaster object

Note

process_edgar() currently supports gridded raster outputs from download_edgar() such as the default format = "nc". Plain-text EDGAR downloads should be re-downloaded as raster outputs before processing.

Author(s)

Mariana Alifa Kassien, Insang Song

See Also

download_edgar(), calculate_edgar()

Examples

## NOTE: Example is wrapped in `\dontrun{}` as function requires data that is
##       not included in the package.
## Not run: 
edgar <- process_edgar(
  path = "./data/edgar",
  extent = c(-85, -75, 33, 37)
)

## End(Not run)

Process MODIS layers

Description

Aggregate layers in a sub-dataset in sinusoidal MODIS products.

Some MODIS products consist of multi-layer subdatasets. This function aggregates multiple layers into single layer SpatRaster. fun_agg is applied at overlapping cells.

Usage

process_flatten_sds(path = NULL, subdataset = NULL, fun_agg = "mean", ...)

Arguments

Value

a SpatRaster object