Package 'amadeus'

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

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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