| Title: | Accessing and Analyzing Large-Scale Environmental Data |
|---|---|
| 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>. |
| Authors: | Mitchell Manware [aut, ctb] (ORCID: <https://orcid.org/0009-0003-6440-6106>), Insang Song [aut, ctb] (ORCID: <https://orcid.org/0000-0001-8732-3256>), Getachew Tedla [aut, ctb] (ORCID: <https://orcid.org/0000-0001-9205-7925>), Nigussie Gemechu [aut, ctb] (ORCID: <https://orcid.org/0000-0001-5285-484X>), Kyle Messier [aut, cre] (ORCID: <https://orcid.org/0000-0001-9508-9623>), Spatiotemporal Exposures and Toxicology Group [cph] |
| Maintainer: | Kyle Messier <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 2.1.0 |
| Built: | 2026-11-13 18:34:24 UTC |
| Source: | https://github.com/niehs/amadeus |
sftime objectCreate a sftime object from one of data.frame,
data.table, sf, sftime, SpatRaster,
SpatRasterDataset, SpatVector
as_mysftime(x, ...)as_mysftime(x, ...)
x |
an object of class |
... |
if x is a data.frame or data.table: lonname, latname, timename and crs arguments are required. If x is a sf or sftime, timename argument is required. If x is a terra::SpatRaster, varname argument is required. |
an sftime object with constrained time column name
Eva Marques
check_mysftime, sf_as_mysftime, data.frame, data.table::data.table, terra::rast, terra::sds, terra::vect
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().
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, ... )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, ... )
covariate |
character(1). Covariate type. |
from |
character, SpatRaster, SpatVector, or data.frame depending on
the selected |
locs |
sf/SpatVector. Unique locations. Should include
a unique identifier field named |
locs_id |
character(1). Name of unique identifier.
Default is |
.by_time |
NULL or character(1). Name of the time column to use
temporal summarization unit token. |
weights |
|
... |
Arguments passed to each covariate calculation function. |
Calculated covariates as a data.frame or SpatVector object
covariate argument value is converted to lowercase.
Insang Song
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"
## 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)## 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)
Extract Cropscape (CDL) values at point locations.
Returns a data.frame
object containing locs_id and crop specific cell fractions.
calculate_cropscape( from, locs, locs_id = "site_id", radius = 0, weights = NULL, geom = FALSE, ... )calculate_cropscape( from, locs, locs_id = "site_id", radius = 0, weights = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame. character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
Insang Song
## 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)## 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)
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.
calculate_drought( from, locs, locs_id = "site_id", radius = 0L, fun = "mean", weights = NULL, geom = FALSE, .by_time = NULL, ... )calculate_drought( from, locs, locs_id = "site_id", radius = 0L, fun = "mean", weights = NULL, geom = FALSE, .by_time = NULL, ... )
from |
SpatRaster or SpatVector. Output of
|
locs |
data.frame, character (path to CSV), |
locs_id |
character(1). Name of the unique location identifier column
in |
radius |
integer(1). Circular buffer radius in metres around each
site location used for extraction. For SPEI/EDDI this controls raster
buffering; for USDM, |
fun |
character(1). Summary function applied to raster cells within
the buffer (SPEI/EDDI only). Default |
weights |
|
geom |
|
.by_time |
NULL or character(1). Name of the time column to use
temporal summarization unit token. |
... |
Reserved for future use; currently ignored. |
A data.frame (default) or SpatVector/sf
object (when geom is set) with columns:
<locs_id>Location identifier.
timeDate 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().
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.
Insang Song
process_drought, download_drought,
calc_summarize_by
## 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)## 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)
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.
calculate_ecoregion( from = NULL, locs, locs_id = "site_id", colnames = c("coded", "full_ecoregion"), frac = FALSE, drop = FALSE, weights = NULL, geom = FALSE, radius = 0, ... )calculate_ecoregion( from = NULL, locs, locs_id = "site_id", colnames = c("coded", "full_ecoregion"), frac = FALSE, drop = FALSE, weights = NULL, geom = FALSE, radius = 0, ... )
from |
SpatVector(1). Output of |
locs |
sf/SpatVector. Unique locs. Should include
a unique identifier field named |
locs_id |
character(1). Name of unique identifier. |
colnames |
character(1). Naming convention for ecoregion indicator
columns. Default is |
frac |
logical(1). Default |
drop |
logical(1). Default |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
radius |
numeric(1). Circular buffer size (meters) around point
locations. Use |
... |
Placeholders. |
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
Insang Song
## 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)## 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)
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.
calculate_edgar( from, locs, locs_id = "site_id", radius = 0, weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_edgar( from, locs, locs_id = "site_id", radius = 0, weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame, character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
numeric(1). Circular buffer distance around site locations.
Default is |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
with |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
Mariana Alifa Kassien, Insang Song
## 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)## 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)
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.
calculate_geos( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_geos( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output of |
locs |
data.frame, characater to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
when |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object. When .by_time is provided,
rows are aggregated using calc_summarize_by().
Mitchell Manware
## 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)## 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)
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).
calculate_gmted( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, geom = FALSE, ... )calculate_gmted( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame. character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders |
a data.frame or SpatVector object
Mitchell Manware
## 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)## 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)
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}).
calculate_goes( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_goes( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame, character file path, |
locs_id |
character(1). Column name for unique location identifier. |
radius |
integer(1). Circular buffer radius in metres around each site (default 0 = point extraction). |
fun |
character(1). Summary function for buffered extractions
(default |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
with |
geom |
|
... |
Placeholders. |
a data.frame or SpatVector object.
Mitchell Manware
## 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)## 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)
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.
calculate_gridmet( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_gridmet( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame. character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
with |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
EDDI uses the same native GRIDMET multi-year workflow as SPEI.
Use eddi14d, eddi30d, eddi90d, eddi180d,
eddi270d, eddi1y, eddi2y, or eddi5y;
eddi defaults to eddi30d. Both indices retain the native
1/24-degree grid and five-day observation dates. Select dataset
gridmet in the wrapper functions to use these products; the
standalone drought source aliases continue to select their separate products.
GRIDMET SPEI rasters from process_gridmet() use the same extraction
workflow as other GRIDMET covariates. Accumulation codes are retained in
output column names (e.g., spei30d), and native five-day observation dates
are preserved when .by_time = NULL; no daily interpolation is
performed.
a data.frame or SpatVector object
Mitchell Manware
## 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)## 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)
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.
calculate_groads( from = NULL, locs = NULL, locs_id = NULL, radius = 1000, fun = "sum", drop = FALSE, weights = NULL, geom = FALSE, ... )calculate_groads( from = NULL, locs = NULL, locs_id = NULL, radius = 1000, fun = "sum", drop = FALSE, weights = NULL, geom = FALSE, ... )
from |
SpatVector(1). Output of |
locs |
data.frame, characater to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 1000). |
fun |
function(1). Function used to summarize the length of roads
within sites location buffer (Default is |
drop |
logical(1). Should locations with zero roads in the extraction
buffer be dropped from results? Default is |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
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.
Insang Song
## 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)## 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)
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.
calculate_hms( from, locs, locs_id = NULL, radius = 0, weights = NULL, .by_time = NULL, frac = FALSE, geom = FALSE, ... )calculate_hms( from, locs, locs_id = NULL, radius = 0, weights = NULL, .by_time = NULL, frac = FALSE, geom = FALSE, ... )
from |
SpatVector(1). Output of |
locs |
data.frame, characater to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
when |
frac |
logical(1). Default |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object. When .by_time is provided,
rows are aggregated using calc_summarize_by().
Mitchell Manware
## 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)## 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)
Extract HUC IDs at point locations. Returns a data.frame
object containing locs_id and HUC IDs.
calculate_huc( from, locs, locs_id = "site_id", weights = NULL, geom = FALSE, ... )calculate_huc( from, locs, locs_id = "site_id", weights = NULL, geom = FALSE, ... )
from |
SpatVector(1). Output from |
locs |
data.frame. character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
Insang Song
## 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)## 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)
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.
calculate_koppen_geiger( from = NULL, locs = NULL, locs_id = "site_id", weights = NULL, geom = FALSE, frac = FALSE, radius = 0, ... )calculate_koppen_geiger( from = NULL, locs = NULL, locs_id = "site_id", weights = NULL, geom = FALSE, frac = FALSE, radius = 0, ... )
from |
SpatRaster(1). Output of |
locs |
sf/SpatVector. Unique locs. Should include
a unique identifier field named |
locs_id |
character(1). Name of unique identifier. |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
frac |
logical(1). Default |
radius |
numeric(1). Circular buffer size (meters) around point
locations. Use |
... |
Placeholders. |
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.
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.
Insang Song
## 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)## 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)
The calculate_lagged() function calculates daily temporal lagged covariates
from the output of calculate_covariates() or calc_*().
calculate_lagged(from, date, lag, locs_id, time_id = "time", geom = FALSE)calculate_lagged(from, date, lag, locs_id, time_id = "time", geom = FALSE)
from |
data.frame(1). A |
date |
character(2). Start and end dates of desired lagged covariates. Length of 10 each, format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
lag |
integer(1). Number of lag days. |
locs_id |
character(1). Name of unique identifier. |
time_id |
character(1). Column containing time values. |
geom |
logical(1). Should the function return a |
a data.frame object
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().
## 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)## 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)
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.
calculate_merra2( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_merra2( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output of |
locs |
data.frame, characater to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
with |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders |
a data.frame or SpatVector object. When .by_time is provided,
rows are aggregated using calc_summarize_by().
Mitchell Manware
calculate_geos(), process_merra2()
## 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)## 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 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.
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"), ... )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"), ... )
from |
character, SpatRaster, or SpatVector. Either a list of
MODIS/VIIRS file paths (raw path mode), a preprocessed raster (direct raster
mode), or processed MODIS fire detections as a SpatVector with |
from_secondary |
character or SpatRaster. Optional secondary input for
fused temporal coverage in raster/path workflows. Type must match |
locs |
sf/SpatVector object. Unique locs where covariates will be calculated. |
locs_id |
character(1). Site identifier. Default is |
radius |
numeric. Radii to calculate covariates.
Default is |
preprocess |
function. Function to handle HDF files in raw path mode.
Ignored when |
name_covariates |
character. Name header of covariates.
e.g., |
subdataset |
Indices, names, or search patterns for subdatasets. Find detail usage of the argument in notes. |
fun_summary |
character or function. Function to summarize extracted raster values. |
.by_time |
NULL or character(1). Optional time grouping key used
with |
weights |
|
package_list_add |
character. Reserved for backward compatibility;
currently not used by |
export_list_add |
character. Reserved for backward compatibility;
currently not used by |
max_cells |
integer(1). Maximum number of cells to be read at once.
Higher values will expedite processing, but will increase memory usage.
Maximum possible value is |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
scale |
character(1). Scale expression to be applied to the raw values.
It is crucial that users review the technical documentation of the MODIS
product
they are using to ensure proper scale.
An example for the MOD11A1 product's LST_Day_1km variable (land surface
temperature)
would be |
fusion_method |
character(1). Fusion method used only when
|
... |
Arguments passed to |
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.
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:
| Raw value | Meaning | Binary fire mask? |
| 0 | not processed, missing input | NA / no observation |
| 1 | obsolete, not used since Collection 1 | NA |
| 2 | not processed, other reason | NA |
| 3 | non-fire water pixel | 0 |
| 4 | cloud, land or water | NA or 0, depending on analysis |
| 5 | non-fire land pixel | 0 |
| 6 | unknown, land or water | NA |
| 7 | fire, low confidence | 1, or exclude for stricter mask |
| 8 | fire, nominal confidence | 1 |
| 9 | fire, high confidence | 1 |
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.
This function leverages the calculation of single-day MODIS covariates:
Also, for preprocessing, please refer to:
## 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)## 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)
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.
calculate_narr( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_narr( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output of |
locs |
data.frame, characater to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
when |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders |
a data.frame or SpatVector object
Mitchell Manware
## 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)## 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
calculate_nei( from = NULL, locs = NULL, locs_id = "site_id", weights = NULL, geom = FALSE, ... )calculate_nei( from = NULL, locs = NULL, locs_id = "site_id", weights = NULL, geom = FALSE, ... )
from |
SpatVector(1). Output of |
locs |
sf/SpatVector. Locations at NEI values are joined. |
locs_id |
character(1). Unique site identifier column name. Unused but kept for compatibility. |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
Insang Song, Ranadeep Daw
## 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)## 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)
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.
calculate_nlcd( from, locs, locs_id = "site_id", mode = c("exact", "terra"), radius = 1000, class_names = c("code", "mrlc"), drop = FALSE, weights = NULL, max_cells = 5e+07, geom = FALSE, ... )calculate_nlcd( from, locs, locs_id = "site_id", mode = c("exact", "terra"), radius = 1000, class_names = c("code", "mrlc"), drop = FALSE, weights = NULL, max_cells = 5e+07, geom = FALSE, ... )
from |
SpatRaster(1). Output of |
locs |
terra::SpatVector of points geometry |
locs_id |
character(1). Unique identifier of locations |
mode |
character(1). One of |
radius |
numeric (non-negative) giving the radius of buffer around points. |
class_names |
character(1). Column naming scheme for categorical NLCD
products. Use |
drop |
logical(1). Default |
weights |
|
max_cells |
integer(1). Maximum number of cells to be read at once.
Higher values may expedite processing, but will increase memory usage.
Maximum possible value is |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
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.
## 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)## 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)
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.
calculate_population( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, geom = FALSE, ... )calculate_population( from, locs, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output of |
locs |
data.frame, characater to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders |
a data.frame or SpatVector object
Mitchell Manware
## 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)## 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)
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.
calculate_prism( from, locs, locs_id = "site_id", radius = 0, weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_prism( from, locs, locs_id = "site_id", radius = 0, weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame. character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
with |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
Insang Song
## 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)## 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 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.
calculate_temporal_dummies( locs, locs_id = "site_id", year = seq(2018L, 2022L), weights = NULL, geom = FALSE, ... )calculate_temporal_dummies( locs, locs_id = "site_id", year = seq(2018L, 2022L), weights = NULL, geom = FALSE, ... )
locs |
data.frame with a temporal field named |
locs_id |
character(1). Unique site identifier column name.
Default is |
year |
integer. Year domain to dummify.
Default is |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
Insang Song
## 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)## 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)
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.
calculate_terraclimate( from = NULL, locs = NULL, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )calculate_terraclimate( from = NULL, locs = NULL, locs_id = NULL, radius = 0, fun = "mean", weights = NULL, .by_time = NULL, geom = FALSE, ... )
from |
SpatRaster(1). Output from |
locs |
data.frame. character to file path, SpatVector, or sf object. |
locs_id |
character(1). Column within |
radius |
integer(1). Circular buffer distance around site locations. (Default = 0). |
fun |
character(1). Function used to summarize multiple raster cells
within sites location buffer (Default = |
weights |
|
.by_time |
NULL or character(1). Optional time grouping key used
with |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
TerraClimate data has monthly temporal resolution, so the $time column
will contain the year and month in YYYYMM format (ie. January, 2018 =
201801).
Mitchell Manware
## 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)## 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 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.
calculate_tri( from = NULL, locs, locs_id = "site_id", decay_range = c(1000L, 10000L, 50000L), C0 = NULL, use_threshold = TRUE, weights = NULL, geom = FALSE, ... )calculate_tri( from = NULL, locs, locs_id = "site_id", decay_range = c(1000L, 10000L, 50000L), C0 = NULL, use_threshold = TRUE, weights = NULL, geom = FALSE, ... )
from |
SpatVector(1). Output of |
locs |
sf/SpatVector. Locations where TRI variables are calculated. |
locs_id |
character(1). Unique site identifier column name.
Default is |
decay_range |
Circular buffer radius.
Default is |
C0 |
|
use_threshold |
logical(1). Passed to |
weights |
|
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
... |
Placeholders. |
a data.frame or SpatVector object
U.S. context.
Insang Song, Mariana Kassien
## 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)## 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)
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.
download_aqs( parameter_code = 88101, resolution_temporal = "daily", year = c(2018, 2022), 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 )download_aqs( parameter_code = 88101, resolution_temporal = "daily", year = c(2018, 2022), 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 )
parameter_code |
integer(1). EPA pollutant parameter code. See Details for a short list of common codes. |
resolution_temporal |
character(1). "daily" or "hourly". |
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
directory_to_save |
character(1). Parent directory. Archives are saved
in |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Extract all planned ZIP archives, including existing
archives, into |
remove_zip |
logical(1). Remove archives and their |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return a combined MD5 hash of all files recursively
under |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
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.
Downloaded and existing archives are extracted into the shared data_files/
directory. The CSV layout is then normalized, followed by optional archive
removal and hashing of the resulting data directory.
With download = FALSE, an invisible preview list containing
urls, destfiles, and n_files. With download = TRUE and
hash = FALSE, an invisible summary from download_run_method() containing
success, failed, skipped, failed_urls, and failed_files. The two
failure vectors are character(0) when no downloads failed, including when
every file was skipped. With download = TRUE and hash = TRUE, a visible
character scalar containing the combined MD5 hash of data_files/.
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().
Mariana Kassien, Insang Song, Mitchell Manware
U.S. Environmental Protection Agency (2023). “Air Quality System Data Mart [internet database].” https://www.epa.gov/outdoor-air-quality-data.
## Not run: download_aqs( parameter_code = 88101, resolution_temporal = "daily", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_aqs( parameter_code = 88101, resolution_temporal = "daily", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
Download annual USDA Cropland Data Layer archives from the USDA National Agricultural Statistics Service or George Mason University. Archives and extracted raster data are stored in separate subdirectories using the shared download workflow.
download_cropscape( year = seq(1997, 2023), source = c("GMU", "USDA"), 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 )download_cropscape( year = seq(1997, 2023), source = c("GMU", "USDA"), 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 )
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
source |
character(1). Data source, either |
directory_to_save |
character(1). Non-empty parent directory.
Archives are downloaded into |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
unzip |
logical(1). Extract downloaded |
remove_zip |
logical(1). Remove downloaded archives and their
|
hash |
logical(1). Return a combined MD5 hash of the files under
|
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file download request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Non-negative throttling interval in seconds,
passed to |
zip_files/ and data_files/ are sibling directories created beneath
directory_to_save, including for previews and when unzip = FALSE.
Both ZIP and compressed TAR downloads are stored in zip_files/.
Each archive is extracted into its own directory under data_files/,
named after the archive with the full .zip or .tar.gz suffix removed:
data_files/YYYY_30m_cdls/ for USDA and data_files/YYYY_cdls/ for GMU.
This isolates duplicate filenames across archives. Paths stored inside
each archive are preserved. Pass the corresponding per-archive directory
or an extracted TIFF path to process_cropscape().
Preview destinations refer to the archive files in zip_files/.
Actual downloads use download_run_method(), which skips existing
non-empty archives and records individual download failures. Existing
archives are still passed to extraction when unzip = TRUE.
Hashing covers all files recursively under data_files/, including the
per-archive subdirectories and existing files, and excludes archives in
zip_files/. With unzip = FALSE, hashing still uses data_files/, which
may be empty or contain previously extracted data.
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files. Otherwise, after downloading and optional
extraction, hash = FALSE returns the download summary from
download_run_method() invisibly. With hash = TRUE, returns a visible
character scalar containing the combined MD5 hash of data_files/.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
Insang Song
download_setup_dir(), download_unzip(), process_cropscape()
## Not run: download_cropscape( year = 2020, source = "GMU", directory_to_save = file.path(tempdir(), "cropscape"), acknowledgement = TRUE, download = FALSE # Preview archive URLs and zip_files/ destinations. ) ## End(Not run)## Not run: download_cropscape( year = 2020, source = "GMU", directory_to_save = file.path(tempdir(), "cropscape"), acknowledgement = TRUE, download = FALSE # Preview archive URLs and zip_files/ destinations. ) ## End(Not run)
The download_data() function accesses and downloads atmospheric,
meteorological, and environmental data from various open-access data
sources.
download_data( dataset_name = c("aqs", "ecoregion", "ecoregions", "geos", "goes", "goes_adp", "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", "drought", "spei", "eddi", "usdm"), directory_to_save = NULL, acknowledgement = FALSE, hash = FALSE, nasa_earth_data_token = NULL, rate_limit = 2, ... )download_data( dataset_name = c("aqs", "ecoregion", "ecoregions", "geos", "goes", "goes_adp", "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", "drought", "spei", "eddi", "usdm"), directory_to_save = NULL, acknowledgement = FALSE, hash = FALSE, nasa_earth_data_token = NULL, rate_limit = 2, ... )
dataset_name |
character(1). Dataset name or alias from the list below.
Matching ignores case and accepts unambiguous partial matches. The default
selects |
directory_to_save |
character(1). Directory to save / unzip (if zip files are downloaded) data. |
acknowledgement |
logical(1). By setting |
hash |
logical(1). Return the source function's combined MD5 directory
hash instead of its download summary. Default is |
nasa_earth_data_token |
character(1) or NULL. NASA EarthData
authentication token. Required for NASA EarthData datasets: |
rate_limit |
numeric(1). Non-negative request-throttling interval in seconds, passed to the source function. Default is 2. This controls the average request rate rather than a strict minimum gap between requests. |
... |
Source-specific selections and download controls, such as |
This wrapper selects a downloader and forwards arguments. The source function performs validation, directory setup, discovery, downloading, and extraction. Previews and directory layouts follow that function's behavior.
The "drought" alias calls download_drought() with its default SPEI source
unless source is supplied. The "spei", "eddi", and "usdm" aliases
call download_spei(), download_eddi(), and download_usdm() directly.
Supply the selected function's required arguments through .... The source
argument selects a drought source only when dataset_name = "drought".
The selected downloader's return value, with its visibility preserved:
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files.
With downloading enabled and hash = FALSE, an invisible summary
containing success, failed, skipped, failed_urls, and
failed_files. The two failure vectors are character(0) when no
downloads failed, including when every file was skipped.
With downloading enabled and hash = TRUE, a visible character scalar
containing the combined MD5 hash of the source's output directory.
All download function names are in download_* formats
Insang Song
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"
download_spei: "spei"
download_eddi: "eddi"
download_usdm: "usdm"
## Not run: download_data( dataset_name = "narr", variables = "weasd", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE, download = FALSE # Deprecated; may still contact the source. ) ## End(Not run)## Not run: download_data( dataset_name = "narr", variables = "weasd", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE, download = FALSE # Deprecated; may still contact the source. ) ## End(Not run)
Dispatch to download_spei(), download_eddi(), or download_usdm().
The selected function validates its arguments, constructs download URLs,
and handles previews, downloads, optional extraction, and return values.
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, download = TRUE, remove_command = FALSE, version = c("2.11", "2.10", "legacy"), ... )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, download = TRUE, remove_command = FALSE, version = c("2.11", "2.10", "legacy"), ... )
source |
character(1). |
date |
character(1 or 2). One date or inclusive range endpoints in
|
timescale |
integer(1). Positive accumulation timescale in months,
used by SPEI and EDDI. Default is |
directory_to_save |
character(1). Non-empty output directory. SPEI
and EDDI save files directly here. USDM uses |
acknowledgement |
logical(1). Must be |
hash |
logical(1). Return a combined MD5 hash of the output directory
instead of the download summary. Uses |
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file request, including
the initial attempt. Must be at least 1. Default is |
rate_limit |
numeric(1). Finite, non-negative request-throttling
interval in seconds, passed to |
unzip |
logical(1). Extract USDM archives into |
remove_zip |
logical(1). Remove USDM archives and their |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
version |
character(1). SPEI selection: |
... |
Additional arguments forwarded to the selected source function.
Its |
Only arguments relevant to the selected source are forwarded. Common validation occurs once in the source function; this wrapper does not repeat validation, directory creation, or download execution.
Previews create the output directories but make no network requests.
They include existing destination files. Actual downloads use
download_run_method(), which skips existing non-empty files and reports
individual failures. See the source functions for endpoint limitations
and extraction behavior.
SPEI retains the flat speiNN.nc filename across versions for compatibility
with process_drought(). Existing-file checks do not distinguish versions.
The date argument does not subset SPEI downloads; temporal selection is
performed during processing.
The selected source function's result, with visibility preserved:
With download = FALSE, an invisible list containing urls,
destfiles, and n_files.
With download = TRUE and hash = FALSE, an invisible download summary
containing success, failed, skipped, failed_urls, and
failed_files. The two failure vectors are character(0) when no
downloads failed, including when every file was skipped.
With download = TRUE and hash = TRUE, a visible character scalar
containing the combined MD5 hash of the source's output directory.
Counts describe file downloads, not extraction or scientific validity. Validation or extraction failures can prevent a normal return.
No authentication is required. SPEI and EDDI provide raster inputs; USDM provides polygon inputs for the downstream drought workflow.
Insang Song
download_spei(), download_eddi(), download_usdm(),
process_drought(), calculate_drought()
## Not run: download_drought( source = "spei", timescale = 1L, version = "2.11", 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)## Not run: download_drought( source = "spei", timescale = 1L, version = "2.11", 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)
The download_ecoregion() function accesses and downloads United
States Ecoregions data from the U.S. Environmental Protection Agency's (EPA)
Ecoregions.
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 )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 )
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. Set to FALSE to skip downloading and return the planned file list. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Unzip zip files (default TRUE). |
remove_zip |
logical(1). Remove zip files after unzipping (default FALSE). |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
When download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts. If the requested archive
already exists and is nonempty, no file is downloaded; the returned list
contains success = 0, failed = 0, and skipped = 1. The list always
contains failed_urls and failed_files character vectors, both
character(0) when no downloads failed, including when the file was skipped.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files = 1 is returned without downloading, regardless of hash.
When download = TRUE and hash = TRUE, a character(1) combined MD5 hash
of the files in the data_files directory is returned instead of a list.
Ecoregion data does not require authentication.
Insang Song
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.
## Not run: download_ecoregion( directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_ecoregion( directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
Construct EDDI ASCII-grid URLs for Tuesdays within a date interval and download the selected accumulation timescale using the shared workflow.
download_eddi( date, timescale, directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 3L, rate_limit = 2, ... )download_eddi( date, timescale, directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 3L, rate_limit = 2, ... )
date |
character(1 or 2). Required date or inclusive range endpoints
in |
timescale |
integer(1). Required positive accumulation timescale in
months. Validation does not establish provider availability. The value
is padded to at least two digits in filenames, such as |
directory_to_save |
character(1). Non-empty directory for downloaded
|
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
hash |
logical(1). Return a combined MD5 hash of all files under
|
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file request, including
the initial attempt. Must be at least 1. Default is |
rate_limit |
numeric(1). Finite, non-negative request-throttling
interval in seconds, passed to |
... |
Reserved for future use; currently ignored. |
URLs use the FTP Projects/EDDI/CONUS_archive/data endpoint with one year
directory per file. Local names follow EDDI_ETrs_NNmn_YYYYMMDD.asc.
All requested Tuesdays are included in the plan; remote availability is
not discovered from directory listings.
A preview creates the output directory and returns all planned URLs and
destinations, including existing files, without contacting the provider.
Actual downloads use download_run_method(), which skips existing non-empty
files and records individual transfer failures.
With download = FALSE, an invisible list containing urls,
destfiles, and n_files. Otherwise, an invisible download summary from
download_run_method() when hash = FALSE, or a visible character scalar
containing the output-directory MD5 hash when hash = TRUE.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
Insang Song
download_drought(), process_drought(), calculate_drought()
## Not run: download_eddi( date = c("2020-01-07", "2020-01-21"), timescale = 1L, directory_to_save = file.path(tempdir(), "eddi"), acknowledgement = TRUE ) ## End(Not run)## Not run: download_eddi( date = c("2020-01-07", "2020-01-21"), timescale = 1L, directory_to_save = file.path(tempdir(), "eddi"), acknowledgement = TRUE ) ## End(Not run)
Construct EDGAR v8.1 air-pollutant or VOC-speciation archive URLs and download them using the shared validation, preview, and download helpers.
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 )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 )
species |
character vector. Air pollutants to download for version
|
version |
character(1). |
temp_res |
character(1) or NULL. Required for version |
sector_yearly |
character vector or NULL. Yearly sectors: |
sector_monthly |
character vector or NULL. Monthly sectors:
|
sector_voc |
character vector or NULL. VOC sectors, using the same
choices as |
format |
character(1). |
output |
character(1). |
year_range |
integer(1 or more) or NULL. One year, two endpoints, or
a non-empty vector of years. Every year from the minimum through the
maximum is selected, including gaps: |
voc |
integer vector, character vector, or NULL. VOC group numbers
from 1 to 25, required for version |
directory_to_save |
character(1). Non-empty parent directory.
Archives are saved in |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
unzip |
logical(1). Extract downloaded or existing archives into
|
remove_zip |
logical(1). Remove archives and their parent |
hash |
logical(1). Return the combined MD5 hash of all files recursively
under |
show_progress |
logical(1). Show per-file download progress. Default
is |
max_tries |
integer(1). Maximum attempts per file request, including the initial attempt. Must be at least 1. Default is 20. |
rate_limit |
numeric(1). Non-negative request-throttling interval in
seconds, passed to |
Scalar selectors version, format, and output use base::match.arg(),
allowing unambiguous partial matches. This also applies to temp_res for
version "8.1"; for VOC speciation, a supplied temp_res is used as-is
in the local archive-name prefix. Sector names require exact,
case-sensitive matches. Only the sector argument for the selected version
and temporal resolution is used; timeseries downloads use no sector argument.
URL construction retains the v8.1 FT2022 archive templates, including
the PM2.5 folder/filename conventions and the SO2 _v2 suffix on full
monthly and timeseries archives. Monthly full-species filenames cover
2000–2022; timeseries and full VOC-group filenames cover 1970–2022.
Available remote files are not discovered by querying directory listings.
Year validation checks the input range, not whether EDGAR provides an
archive for each requested year or combination of arguments.
Timeseries archives are not necessarily raster products. For example,
the NOx timeseries archive contains an Excel workbook (.xlsx) and a
readme, even when format = "nc". process_edgar() currently accepts
raster files only, so this workbook cannot be passed through the
process_edgar() and calculate_edgar() workflow.
Local archive names retain the edgar_<temp_res>_ prefix, or edgar_voc_
when VOC speciation is requested with temp_res = NULL. Preview results
include all constructed URLs and destination paths, including existing
files. A preview creates the output directories but makes no network
requests and does not verify remote availability. No shell-command file
is created.
download_run_method() skips existing non-empty destination files and
records individual download failures in its summary. File downloads use
the shared default timeout.
Extraction and cleanup occur before returning, and extraction errors can
prevent a normal return. Summary counts describe downloads, not extraction.
With download = FALSE, an invisible list containing urls,
destfiles, and n_files, the number of planned archive downloads.
With download = TRUE and hash = FALSE, the invisible summary from
download_run_method() with success, failed, and skipped counts.
It always contains failed_urls and failed_files character vectors,
both character(0) when no downloads failed, including when every file
was skipped. These counts describe archives, not extracted files.
With download = TRUE and hash = TRUE, a visible character(1) combined
MD5 hash of all files under data_files/, including existing files.
Mariana Alifa Kassien
download_data(), download_run_method(), process_edgar()
## Not run: download_edgar( species = "CO", temp_res = "yearly", sector_yearly = "ENE", year_range = c(2021, 2022), directory_to_save = file.path(tempdir(), "edgar"), acknowledgement = TRUE, download = FALSE ) download_edgar( version = "8.1_voc", voc = 1:3, sector_voc = "AGRICULTURE", year_range = 2021, directory_to_save = file.path(tempdir(), "edgar_voc"), acknowledgement = TRUE, download = FALSE ) ## End(Not run)## Not run: download_edgar( species = "CO", temp_res = "yearly", sector_yearly = "ENE", year_range = c(2021, 2022), directory_to_save = file.path(tempdir(), "edgar"), acknowledgement = TRUE, download = FALSE ) download_edgar( version = "8.1_voc", voc = 1:3, sector_voc = "AGRICULTURE", year_range = 2021, directory_to_save = file.path(tempdir(), "edgar_voc"), acknowledgement = TRUE, download = FALSE ) ## End(Not run)
The download_geos() function accesses and downloads various
atmospheric composition collections from NASA's Global Earth Observing
System (GEOS)
compositional forecast model.
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"), hours = 0:23, directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, show_progress = TRUE, hash = FALSE, max_tries = 20, rate_limit = 2 )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"), hours = 0:23, directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, show_progress = TRUE, hash = FALSE, max_tries = 20, rate_limit = 2 )
collection |
character(1). GEOS-CF data collection file name. |
nasa_earth_data_token |
character(1) or NULL. NASA EarthData authentication token. |
date |
character(1 or 2). A single date or inclusive range endpoints
in |
hours |
integer(1 to 24). Hours of day to download for each date,
in UTC. Supply values from 0 through 23. Default is |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be |
download |
logical(1). DEPRECATED. Downloads happen automatically. |
remove_command |
logical(1). Deprecated, ignored. |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
Hour selection uses the timestamps of the requested collection. Hourly
time-averaged collections (_tavg_1hr_) use timestamps at 30 minutes past
the hour, while hourly instantaneous collections (_inst_1hr_) use
timestamps on the hour. For example, hours = c(0, 6) selects 00:30
and 06:30 UTC for time-averaged collections, or 00:00 and 06:00 UTC
for instantaneous collections. The same hour selection applies to every
date in the requested range.
With download = FALSE, an invisible preview list containing
urls, destfiles, and n_files. With download = TRUE and
hash = FALSE, an invisible summary from download_run_method() containing
success, failed, skipped, failed_urls, and failed_files. The two
failure vectors are character(0) when no downloads failed, including when
every file was skipped. With download = TRUE and hash = TRUE, a visible
character scalar containing the combined MD5 hash of the output directory.
Due to NASA data access policies, downloads require a valid NASA
Earthdata token for authentication. Use setup_nasa_token() for setup.
Mitchell Manware, Insang Song
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.
## Not run: download_geos( collection = "aqc_tavg_1hr_g1440x721_v1", date = "2024-01-01", hours = c(0, 6, 12, 18), directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_geos( collection = "aqc_tavg_1hr_g1440x721_v1", date = "2024-01-01", hours = c(0, 6, 12, 18), directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
The download_gmted() function accesses and downloads Global
Multi-resolution Terrain Elevation Data (GMTED2010) from U.S. Geological
Survey.
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 )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 )
statistic |
character(1). One of |
resolution |
character(1). One of |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. Set to FALSE to skip downloading and return the planned file list. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Unzip zip files (default TRUE). |
remove_zip |
logical(1). Remove zip files after unzipping (default FALSE). |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
statistic and resolution each select one value. Matching is
case-sensitive, and unambiguous abbreviations are accepted. If omitted,
each argument uses its first listed choice.
When download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts. If all requested archives
already exist and are nonempty, no files are downloaded; the returned list
contains success = 0, failed = 0, and skipped equal to the number of
requested files. The list always contains failed_urls and failed_files
character vectors, both character(0) when no downloads failed, including
when every file was skipped.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files is returned without downloading, regardless of hash.
When download = TRUE and hash = TRUE, a character(1) combined MD5 hash
of the files in the data_files directory is returned instead of a list.
GMTED data does not require authentication.
Mitchell Manware, Insang Song
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.
## Not run: download_gmted( statistic = "Breakline Emphasis", resolution = "7.5 arc-seconds", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_gmted( statistic = "Breakline Emphasis", resolution = "7.5 arc-seconds", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
Discover and download NOAA GOES-16 or GOES-18 Aerosol Detection Product
(ADP) files from the NOAA Open Data Dissemination (NODD) AWS S3 archive.
Files are in NetCDF format and contain aerosol detection variables
(e.g. "Smoke", "Dust") on the GOES fixed geostationary grid.
download_goes( date = c("2024-01-01", "2024-01-01"), satellite = c("16", "18"), product = c("ADP-C", "ADP-F", "ADP-M"), directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, show_progress = TRUE, hash = FALSE, max_tries = 20, rate_limit = 2 )download_goes( date = c("2024-01-01", "2024-01-01"), satellite = c("16", "18"), product = c("ADP-C", "ADP-F", "ADP-M"), directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, show_progress = TRUE, hash = FALSE, max_tries = 20, rate_limit = 2 )
date |
character(1 or 2). Single date or inclusive range endpoints in
|
satellite |
character(1). GOES satellite number: |
product |
character(1). ADP scan sector: |
directory_to_save |
character(1). Non-empty output directory, created if needed. Files retain their S3 directory structure below this root; see Details. |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
show_progress |
logical(1). Show per-file download progress. Default
is |
hash |
logical(1). Return the combined directory MD5 hash when |
max_tries |
integer(1). Maximum attempts per listing or file request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Non-negative request-throttling interval in
seconds, passed to discovery and downloads. Default is 2. Discovery uses
a capacity-one bucket; 0 disables discovery throttling. File downloads
follow the throttling policy in |
satellite and product are matched with base::match.arg(), allowing
case-sensitive, unambiguous partial matches. Omitted arguments select the
first listed choice. Products "ADP-C", "ADP-F", and "ADP-M" map to
S3 prefixes "ABI-L2-ADPC", "ABI-L2-ADPF", and "ABI-L2-ADPM".
Daily listings supply the actual file names. Files are saved under
directory_to_save/<product-prefix>/<year>/<day-of-year>/<hour>/<filename>.
The day of year uses three digits, such as "001". Existing non-empty
destination files are skipped by download_run_method(); preview results
include them because discovery does not filter local files.
Discovery requests one S3 listing page of up to 1000 keys per day and keeps
keys ending in .nc. Continuation tokens are not followed, so results can
be incomplete when a daily listing spans multiple pages.
A successfully retrieved listing with no matching files emits a message
and contributes no rows. Errors while requesting, parsing, or processing
any listing stop discovery before downloading. Files are not required for
every requested date. If all listings are empty, download = TRUE errors
with "No URLs provided for download.", whereas download = FALSE returns
an empty preview.
Discovery uses a 60-second timeout per request attempt. File downloads use
download_run_method()'s default timeout of 3600 seconds.
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files. Otherwise, with hash = FALSE, the invisible
summary from download_run_method(), including success, failed, and
skipped counts. With hash = TRUE, a visible combined MD5 hash for all
files under directory_to_save, including previously downloaded files.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
GOES data does not require authentication.
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.
Mitchell Manware
download_data(), process_goes(), download_run_method(),
download_preview()
## Not run: download_goes( date = "2024-01-01", satellite = "16", product = "ADP-C", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_goes( date = "2024-01-01", satellite = "16", product = "ADP-C", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
The download_gridmet function accesses and downloads gridded
surface meteorological data from the University of California Merced
Climatology Lab's gridMET dataset.
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 )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 )
variables |
character. Variable(s) name(s). |
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. |
remove_command |
logical(1). Deprecated, ignored. |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
EDDI uses the same native GRIDMET multi-year workflow as SPEI.
Use eddi14d, eddi30d, eddi90d, eddi180d,
eddi270d, eddi1y, eddi2y, or eddi5y;
eddi defaults to eddi30d. Both indices retain the native
1/24-degree grid and five-day observation dates. Select dataset
gridmet in the wrapper functions to use these products; the
standalone drought source aliases continue to select their separate products.
GRIDMET SPEI is available directly from the provider as multi-year files
(one file per accumulation period), at native five-day intervals on the
approximately 4-km grid. Use "spei14d", "spei30d",
"spei90d", "spei180d", "spei270d", "spei1y",
"spei2y", or "spei5y"; "spei" aliases "spei30d".
For SPEI, year does not subset the download: the complete multi-year
file is saved under its resolved code directory (e.g., spei30d/spei30d.nc).
Subset dates with process_gridmet(). These files are several GB each.
This is distinct from the global CSIC SPEI product in
download_drought().
See https://www.northwestknowledge.net/metdata/data/.
With download = FALSE, an invisible preview list containing
urls, destfiles, and n_files. With download = TRUE and
hash = FALSE, an invisible summary from download_run_method() containing
success, failed, skipped, failed_urls, and failed_files. The two
failure vectors are character(0) when no downloads failed, including when
every file was skipped. With download = TRUE and hash = TRUE, a visible
character scalar containing the combined MD5 hash of the output directory.
gridMET data does not require authentication.
Mitchell Manware
Abatzoglou JT (2013). “Development of gridded surface meteorological data for ecological applications and modelling.” International journal of climatology, 33(1), 121–131.
## Not run: download_gridmet( variables = "pr", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_gridmet( variables = "pr", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
The download_groads() function accesses and downloads
roads data from NASA's Global Roads Open Access Data Set (gROADS).
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 )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 )
data_region |
character(1). One of |
data_format |
character(1). Requested format: |
nasa_earth_data_token |
character(1) or NULL. NASA EarthData
authentication token. Can be a token string, a path to a file
containing the token, or |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. Set to FALSE to skip downloading and return the planned file list. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Unzip zip files (default TRUE). |
remove_zip |
logical(1). Remove zip files after unzipping (default FALSE). |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
data_region and data_format each select one value. Matching is
case-sensitive, and unambiguous abbreviations are accepted. If omitted,
each argument uses its first listed choice.
When download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts. If the requested archive
already exists and is nonempty, no file is downloaded; the returned list
contains success = 0, failed = 0, and skipped = 1. The list always
contains failed_urls and failed_files character vectors, both
character(0) when no downloads failed, including when the file was skipped.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files = 1 is returned without downloading, regardless of hash.
When download = TRUE and hash = TRUE, a character(1) combined MD5 hash
of the files in the data_files directory is returned instead of a list.
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.
Mitchell Manware, Insang Song
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.
## Not run: download_groads( data_region = "Americas", data_format = "Shapefile", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_groads( data_region = "Americas", data_format = "Shapefile", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
The download_hms() function accesses and downloads
wildfire smoke plume coverage data from NOAA's Hazard Mapping System Fire
and Smoke Product.
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 )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 )
data_format |
character(1). "Shapefile" or "KML". |
date |
character(1 or 2). A single date or inclusive range endpoints
in |
directory_to_save |
character(1). Parent directory. Shapefile archives
are saved in |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Extract all planned Shapefile ZIP archives,
including existing archives, into the shared |
remove_zip |
logical(1). Remove Shapefile archives and their
|
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return a combined MD5 hash of all files recursively
under |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
With download = FALSE, an invisible preview list containing
urls, destfiles, and n_files. With download = TRUE and
hash = FALSE, an invisible summary from download_run_method() containing
success, failed, skipped, failed_urls, and failed_files. The two
failure vectors are character(0) when no downloads failed, including when
every file was skipped. With download = TRUE and hash = TRUE, a visible
character scalar containing the combined MD5 hash of data_files/.
HMS data does not require authentication.
Mitchell Manware, Insang Song
(????). “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.
## Not run: download_hms( data_format = "Shapefile", date = "2024-01-01", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_hms( data_format = "Shapefile", date = "2024-01-01", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
Download a national NHDPlus Version 2.1 .7z archive from Amazon S3.
The selected region and data type determine the archive to download.
download_huc( region = c("Lower48", "Islands"), type = c("Seamless", "OceanCatchment"), directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, unzip = FALSE, remove_zip = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 20, rate_limit = 2 )download_huc( region = c("Lower48", "Islands"), type = c("Seamless", "OceanCatchment"), directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, unzip = FALSE, remove_zip = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 20, rate_limit = 2 )
region |
character(1). Archive region: |
type |
character(1). Data type: |
directory_to_save |
character(1). Non-empty parent directory.
The |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
unzip |
logical(1). Extract the downloaded |
remove_zip |
logical(1). Remove the downloaded |
hash |
logical(1). Return a combined MD5 hash of the files under
|
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file download request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Request-throttling interval in seconds,
passed to |
region and type each select one value. Matching is case-sensitive, and
unambiguous abbreviations are accepted. If omitted, each argument uses its
first listed choice.
zip_files/ and data_files/ are sibling directories created beneath
directory_to_save, including when unzip = FALSE or download = FALSE.
Preview mode returns the planned archive even if it already exists locally
and does not check remote availability.
During downloading, download_run_method() skips an existing non-empty
archive in zip_files/. That archive is still passed to extraction when
unzip = TRUE. Existing extracted data alone do not cause a download to
be skipped. Archive member names and paths are preserved beneath
data_files/; pass the extracted geodatabase path to process_huc().
Hashing includes all files recursively under data_files/, including
existing files, and excludes archives in zip_files/. With unzip = FALSE,
hashing still uses data_files/, which may be empty or contain previously
extracted data.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files = 1 is returned regardless of hash.
When download = TRUE and hash = FALSE, returns the download summary from
download_run_method() invisibly, including success, failed, and
skipped file counts. The summary always contains failed_urls and
failed_files character vectors, both character(0) when no downloads
failed, including when every file was skipped. Counts describe archive
downloads, not extracted files.
When download = TRUE and hash = TRUE, returns a visible character scalar
containing the combined MD5 hash of the files under data_files/.
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
Insang Song
U.S. Geological Survey (2023). “National Hydrography Dataset (NHD) – USGS National Map Downloadable Data Collection.” https://www.usgs.gov/national-hydrography.
download_setup_dir(), download_unzip(), process_huc()
## Not run: download_huc( region = "Lower48", type = "Seamless", directory_to_save = file.path(tempdir(), "nhdplus"), acknowledgement = TRUE, unzip = TRUE ) ## End(Not run)## Not run: download_huc( region = "Lower48", type = "Seamless", directory_to_save = file.path(tempdir(), "nhdplus"), acknowledgement = TRUE, unzip = TRUE ) ## End(Not run)
Download annual IMPROVE (Interagency Monitoring of Protected Visual
Environments) measurement files from the VIEWS/VIBE data export service
hosted at CIRA/CSU. Files are downloaded as .txt.zip archives and can be
extracted to pipe-delimited .txt files using the shared download workflow.
download_improve( year = c(2018, 2022), product = c("raw", "rhr2", "rhr3"), 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 )download_improve( year = c(2018, 2022), product = c("raw", "rhr2", "rhr3"), 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 )
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
product |
character(1). Product selector: |
directory_to_save |
character(1). Non-empty parent directory.
Archives are downloaded into |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
unzip |
logical(1). Extract downloaded ZIP archives into
|
remove_zip |
logical(1). Remove downloaded archives and their
|
show_progress |
logical(1). Show file download progress. Default is
|
hash |
logical(1). Return a combined MD5 hash of the files under
|
max_tries |
integer(1). Maximum attempts per file download request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Non-negative throttling interval in seconds,
passed to |
The selected product determines the filename prefix. For example,
product = "raw" and year = 2022 request IMPAER_2022.txt.zip.
zip_files/ and data_files/ are sibling directories created beneath
directory_to_save, including when unzip = FALSE or download = FALSE.
Preview mode creates the output directories and makes no network requests.
Individual download failures are recorded by download_run_method() during
file transfers.
All archives share data_files/ as their extraction destination. Names
and paths stored inside each archive are preserved. Pass the directory
containing the extracted PREFIX_YYYY.txt files, normally data_files/,
as path to process_improve().
download_run_method() skips existing non-empty archives in zip_files/.
Those archives are still passed to extraction when unzip = TRUE.
Existing extracted .txt files alone do not cause a download to be skipped.
Hashing covers all files recursively under data_files/, including existing
files, and excludes archives in zip_files/. With unzip = FALSE, hashing
still uses data_files/, which may be empty or contain previously extracted
data.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files is returned regardless of hash. These describe all planned
downloads, including files that already exist locally; n_files is the
number of planned URLs.
When download = TRUE, after downloading and optional extraction,
hash = FALSE returns the download summary from download_run_method()
invisibly, including counts of successful, failed, and skipped files.
With hash = TRUE, returns a visible character scalar containing the
combined MD5 hash of data_files/.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
IMPROVE data does not require authentication. Annual downloads contain
measurement files; site metadata is resolved separately by
process_improve().
Insang Song, Mitchell Manware
download_setup_dir(), download_unzip(), process_improve()
## Not run: download_improve( year = 2022, product = "raw", directory_to_save = file.path(tempdir(), "improve"), acknowledgement = TRUE ) ## End(Not run)## Not run: download_improve( year = 2022, product = "raw", directory_to_save = file.path(tempdir(), "improve"), acknowledgement = TRUE ) ## End(Not run)
The download_koppen_geiger() function accesses and downloads
climate classification data.
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 )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 )
data_resolution |
character(1). One of |
time_period |
character(1). |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. Set to FALSE to skip downloading and return the planned file list. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Unzip zip files (default TRUE). |
remove_zip |
logical(1). Remove zip files after unzipping (default FALSE). |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
data_resolution and time_period each select one value. Matching is
case-sensitive, and unambiguous abbreviations are accepted. If omitted,
each argument uses its first listed choice.
When download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts. If the requested archive
already exists and is nonempty, no file is downloaded; the returned list
contains success = 0, failed = 0, and skipped = 1. The list always
contains failed_urls and failed_files character vectors, both
character(0) when no downloads failed, including when the file was skipped.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files = 1 is returned without downloading, regardless of hash.
When download = TRUE and hash = TRUE, a character(1) combined MD5 hash
of the files in the data_files directory is returned instead of a list.
Köppen-Geiger data does not require authentication.
Mitchell Manware, Insang Song
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.
## Not run: download_koppen_geiger( data_resolution = "0.0083", time_period = "Present", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_koppen_geiger( data_resolution = "0.0083", time_period = "Present", directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
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.
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 )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 )
collection |
character vector. One or more supported MERRA-2 collection
identifiers, or |
nasa_earth_data_token |
character(1) or NULL. NASA Earthdata token,
path to a file containing a token, or |
date |
character(1 or 2). A single day or two range endpoints in
|
directory_to_save |
character(1). Non-empty directory path for downloads.
A path must be supplied despite the |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored. |
hash |
logical(1). If |
show_progress |
logical(1). Show per-file progress messages and download
progress bars. Default is |
max_tries |
integer(1). Maximum attempts per listing or file request, including the initial attempt. Must be at least 1. Default is 20. |
rate_limit |
numeric(1). Non-negative request-throttling interval in seconds. Default is 2. Passed to both discovery and file downloads; their throttling behavior is described below. |
Standard MERRA-2 file URLs are discovered from monthly HTML directory
listings. Published stream and revision prefixes are retained, and all
matching files are included when more than one revision is listed for a
date. Every requested date must have at least one matching .nc4 file in
its directory. Companion .nc4.xml metadata is optional and is included
only when the corresponding data file is also listed. FWI .nc URLs are
constructed directly from the requested dates.
Discovery stops before file downloads if a monthly listing cannot be read,
a requested data date is missing, or different URLs in a listing would
use the same local filename. Once discovery succeeds, download_run_method()
skips existing non-empty files and records individual download failures,
warning after the remaining files have been attempted.
Listing requests to the same host are spaced by at least rate_limit
seconds; 0 disables listing throttling. File downloads use the host-based
token bucket described in download_run_method(). Discovery and file
downloads use their default per-attempt timeout of 3600 seconds; this
function does not expose a timeout argument.
With download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts, plus failed_urls and
failed_files character vectors. All five fields are always present; the
two failure vectors are character(0) when no downloads failed, including
when every file was skipped. Counts include XML metadata files.
With download = TRUE and hash = TRUE, a character scalar containing the
combined directory MD5 hash, returned visibly.
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files, regardless of hash.
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.
Mitchell Manware, Insang Song, Kyle Messier
setup_nasa_token(), get_token(), download_run_method(),
download_hash(), process_merra2(), get_merra2_info()
## Not run: # Configure NASA_EARTHDATA_TOKEN with setup_nasa_token() before downloading. download_merra2( collection = "inst1_2d_int_Nx", date = "2024-01-01", directory_to_save = tempdir(), acknowledgement = TRUE ) # Download two collections for an inclusive date range. download_merra2( collection = c("inst1_2d_int_Nx", "tavg1_2d_slv_Nx"), date = c("2024-01-01", "2024-01-02"), directory_to_save = file.path(tempdir(), "merra2"), acknowledgement = TRUE, max_tries = 3 ) ## End(Not run)## Not run: # Configure NASA_EARTHDATA_TOKEN with setup_nasa_token() before downloading. download_merra2( collection = "inst1_2d_int_Nx", date = "2024-01-01", directory_to_save = tempdir(), acknowledgement = TRUE ) # Download two collections for an inclusive date range. download_merra2( collection = c("inst1_2d_int_Nx", "tavg1_2d_slv_Nx"), date = c("2024-01-01", "2024-01-02"), directory_to_save = file.path(tempdir(), "merra2"), acknowledgement = TRUE, max_tries = 3 ) ## End(Not run)
Query NASA CMR for file URLs, prepare a download table, and download MODIS or VIIRS files using the shared validation, preview, download, and return helpers.
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 )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 )
product |
character(1). Supported MODIS or VIIRS product code. The default selects the first listed product. |
version |
character(1). Requested CMR version, default |
nasa_earth_data_token |
character(1) or NULL. NASA Earthdata token,
token-file path, or |
date |
character(1 or 2). Single date or range endpoints in
|
extent |
numeric(4). Bounding box in decimal degrees, ordered
|
directory_to_save |
character(1). Non-empty output directory. Files are saved directly in this directory. |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
show_progress |
logical(1). Show per-file download progress. Discovery
and summary messages may still be printed when |
hash |
logical(1). Return the combined directory MD5 hash when |
max_tries |
integer(1). Maximum attempts per CMR or file request, including the first attempt. Default is 20. |
rate_limit |
numeric(1). Non-negative request-throttling interval in
seconds, passed to discovery and downloads. Default is 2. Discovery uses
a capacity-one bucket; 0 disables discovery throttling. File downloads
follow the throttling policy in |
Product-specific version overrides and a CM1-to-A2 fallback are applied
before filename date filtering. Files use a flat destination directory.
MOD06_L2 uses "6.1"; MOD14CM1/MYD14CM1 use "005"; MCD64CMQ uses
"006"; MCD14ML uses "6.1NRT"; VNP46A2/VNP64A1 omit the version filter.
An empty CM1 response triggers the existing A2 version "006" fallback.
Cross-year ranges remain restricted to MOD06_L2, MOD14CM1, MYD14CM1,
MCD14ML, MCD64A1, MCD64CMQ, and VNP64A1. Discovery retrieves successive CMR
pages of up to 2000 granules using the CMR-Search-After response header.
There is no 31-day warning or restriction. The query parameters, retry
settings, timeout, and throttle are retained across pages.
When supplied, CMR-Hits is checked against the number of retrieved granule
records before link or date filtering. Discovery stops if a page request
fails, the reported count changes, a required continuation value is missing
or repeated, or the final record count does not match CMR-Hits.
CMR supplies actual file URLs, so a product/date Cartesian grid is not needed. The inclusive date sequence is used to establish ordered query endpoints. A file count is reported without claiming daily or monthly completeness for tiled, swath, or composite products.
Discovery keeps the existing 120-second per-attempt timeout; file downloads
use download_run_method()'s default timeout.
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files. Otherwise, with hash = FALSE, the invisible
download summary from download_run_method(). With hash = TRUE, a visible
combined MD5 hash for all files under directory_to_save.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
Mitchell Manware, Insang Song
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.
download_data(), download_merra2(), download_run_method()
## Not run: download_modis( product = "MOD09GA", date = c("2024-01-01", "2024-01-03"), extent = c(-80, 35, -75, 40), directory_to_save = file.path(tempdir(), "modis"), acknowledgement = TRUE, download = FALSE ) ## End(Not run)## Not run: download_modis( product = "MOD09GA", date = c("2024-01-01", "2024-01-03"), extent = c(-80, 35, -75, 40), directory_to_save = file.path(tempdir(), "modis"), acknowledgement = TRUE, download = FALSE ) ## End(Not run)
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/).
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 )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 )
variables |
character. Variable(s) name acronym. See the Available NARR Variables section below for the complete list of supported abbreviations. |
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
directory_to_save |
character(1). Directory to save downloaded data files. |
acknowledgement |
logical(1). Must be TRUE to proceed with download. |
download |
logical(1). DEPRECATED. Downloads happen automatically. |
remove_command |
logical(1). DEPRECATED, ignored. |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum download retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
With download = FALSE, an invisible preview list containing
urls, destfiles, and n_files. With download = TRUE and
hash = FALSE, an invisible summary from download_run_method() containing
success, failed, skipped, failed_urls, and failed_files. The two
failure vectors are character(0) when no downloads failed, including when
every file was skipped. With download = TRUE and hash = TRUE, a visible
character scalar containing the combined MD5 hash of the output directory.
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):
acpcpConvective precipitation
air.2mAir temperature at 2 m
air.sfcAir temperature at surface
albedoSurface albedo
apcpTotal accumulated precipitation
bgrunBaseflow-groundwater runoff
bmixl.hl1Blackadar mixing length scale at hybrid level 1
capeConvective available potential energy
ccondCanopy conductance
cdconConvective cloud cover
cdlyrNon-convective cloud cover
cfrzrCategorical freezing rain
cicepCategorical ice pellets
cinConvective inhibition
cnwatPlant canopy surface water
crainCategorical rain
csnowCategorical snow
dlwrfDownward longwave radiation flux
dpt.2mDew point temperature at 2 m
dswrfDownward shortwave radiation flux
evapEvaporation
gfluxGround heat flux
hcdcHigh cloud cover
hgt.tropoGeopotential height at tropopause
hlcyStorm relative helicity
hpblPlanetary boundary layer height
lcdcLow cloud cover
lftx4Best (4-layer) lifted index
lhtflLatent heat net flux
mcdcMid-cloud cover
mconv.hl1Horizontal moisture divergence at hybrid level 1
msletMean sea level pressure (ETA model reduction)
mstavMoisture availability
pevapPotential evaporation
pottmp.hl1Potential temperature at hybrid level 1
pottmp.sfcPotential temperature at surface
pratePrecipitation rate
pres.sfcSurface pressure
pres.tropoPressure at tropopause
prmslPressure reduced to mean sea level
pr_wtrPrecipitable water
rcqSpecific humidity tendency from all physics
rcsSnowfall water equivalent tendency
rcsolSolar radiative heating rates
rctTemperature tendency from all physics
rhum.2mRelative humidity at 2 m
shtflSensible heat net flux
shum.2mSpecific humidity at 2 m
snodSnow depth
snohfSnow phase-change heat flux
snomSnow melt
snowcSnow cover
soilmSoil moisture content (0–200 cm layer)
ssrunStorm surface runoff
tcdcTotal cloud cover
tke.hl1Turbulent kinetic energy at hybrid level 1
ulwrf.ntatUpward longwave radiation flux at nominal top of atmosphere
ulwrf.sfcUpward longwave radiation flux at surface
ustmU-component of storm motion
uswrf.ntatUpward shortwave radiation flux at nominal top of atmosphere
uswrf.sfcUpward shortwave radiation flux at surface
uwnd.10mU-component of wind at 10 m
vegVegetation fraction
visVisibility
vstmV-component of storm motion
vvel.hl1Vertical velocity at hybrid level 1
vwnd.10mV-component of wind at 10 m
vwsh.tropoVertical wind shear at tropopause
wcconvConvective wetting of vegetation canopy
wcincWetting of vegetation canopy
wcuflxU-component of convective canopy moisture flux
wcvflxV-component of convective canopy moisture flux
weasdWater-equivalent accumulated snow depth
wvconvConvective column moisture convergence
wvincColumn moisture increase
wvuflxU-component of vertically-integrated moisture flux
wvvflxV-component of vertically-integrated moisture flux
Pressure level variables (29 atmospheric pressure levels from 1000 to 100 hPa; all levels are downloaded together):
airAir temperature
hgtGeopotential height
omegaVertical velocity (pressure / omega)
shumSpecific humidity
tkeTurbulent kinetic energy
uwndU-component of wind
vwndV-component of wind
Subsurface (soil) variables (4 soil layers):
soillLiquid volumetric soil moisture (non-frozen fraction)
soilwVolumetric soil moisture content
tsoilSoil temperature
"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.
Mitchell Manware, Insang Song, Kyle Messier
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.
## 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)## 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 onroad emissions CSV archives from the U.S. Environmental Protection Agency's National Emissions Inventory (NEI). Archives and extracted data are stored in separate subdirectories using the shared download workflow.
download_nei( 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 )download_nei( 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 )
year |
integer(1 or more). Selected inventory years. Supported values
are 2008, 2011, 2014, 2017, 2020, and 2023. Default is
|
directory_to_save |
character(1). Non-empty parent directory.
Archives are downloaded into |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
unzip |
logical(1). Extract downloaded ZIP archives into per-archive
directories under |
remove_zip |
logical(1). Remove downloaded archives and their
|
show_progress |
logical(1). Show file download progress. Default is
|
hash |
logical(1). Return a combined MD5 hash of the files under
|
max_tries |
integer(1). Maximum attempts per file download request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Non-negative throttling interval in seconds,
passed to |
A year-specific lookup selects the provider's archive path and filename. NEI releases use different version directories and naming conventions.
zip_files/ and data_files/ are sibling directories created beneath
directory_to_save, including for previews and when unzip = FALSE.
Each archive is extracted into a directory named after the archive with
its .zip suffix removed. For example, the 2020 archive is saved as
zip_files/2020nei_onroad_byregion.zip and extracted into
data_files/2020nei_onroad_byregion/. This isolates duplicate filenames
across inventories. Paths stored inside each archive are preserved.
Preview destinations refer to the archives in zip_files/, including
files that already exist locally. For actual downloads,
download_run_method() skips existing non-empty archives; they are still
passed to extraction when unzip = TRUE.
Preview mode makes no network requests. Individual download failures are
recorded by the shared runner during file transfers.
Hashing covers all files recursively under data_files/, including the
per-archive subdirectories and existing files, and excludes archives in
zip_files/. With unzip = FALSE, hashing still uses data_files/, which
may be empty or contain previously extracted data.
Download support covers more inventory years than process_nei(), which
currently accepts only 2017 and 2020.
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files. Otherwise, after downloading and optional
extraction, hash = FALSE returns the download summary from
download_run_method() invisibly. With hash = TRUE, returns a visible
character scalar containing the combined MD5 hash of data_files/.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
NEI data does not require authentication.
Kyle Messier, Insang Song
United States Environmental Protection Agency (2024). “Air Emissions Inventories.” https://www.epa.gov/air-emissions-inventories.
download_setup_dir(), download_unzip(), process_nei()
## Not run: download_nei( year = c(2017L, 2020L), directory_to_save = file.path(tempdir(), "nei"), acknowledgement = TRUE, download = FALSE # Preview selected inventory URLs and archive paths. ) ## End(Not run)## Not run: download_nei( year = c(2017L, 2020L), directory_to_save = file.path(tempdir(), "nei"), acknowledgement = TRUE, download = FALSE # Preview selected inventory URLs and archive paths. ) ## End(Not run)
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.
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 )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 )
product |
character(1). NLCD product type. One of:
|
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
directory_to_save |
character(1). Parent directory. Archives are saved
in |
acknowledgement |
logical(1). Must be |
download |
logical(1). DEPRECATED. Downloads now happen automatically. Set to FALSE to skip downloading (generates file list only). |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Extract all planned yearly archives, including
existing archives, into the shared |
remove_zip |
logical(1). Remove archives and their |
show_progress |
logical(1). Show download progress? Default is
|
hash |
logical(1). Return a combined MD5 hash of all files recursively
under |
max_tries |
integer(1). Maximum download retry attempts. Default is 20. |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
When download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts. If all requested archives
already exist and are nonempty, no files are downloaded; the returned list
contains success = 0, failed = 0, and skipped equal to the number of
requested files. The list always contains failed_urls and failed_files
character vectors, both character(0) when no downloads failed, including
when every file was skipped.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files is returned without downloading, regardless of hash.
When download = TRUE and hash = TRUE, a character(1) combined MD5 hash
of the files in the data_files directory is returned instead of a list.
Mitchell Manware, Insang Song, Kyle Messier
Dewitz J (2023). “National Land Cover Database (NLCD) 2021 Products.” doi:10.5066/P9JZ7AO3.
## 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)## 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)
The download_population() function accesses and downloads
population density data from NASA's UN WPP-Adjusted Population Density.
download_population( data_resolution = c("60 minute", "30 second", "2.5 minute", "15 minute", "30 minute"), data_format = c("GeoTIFF", "ASCII", "netCDF"), year = c("2020", "2000", "2005", "2010", "2015", "all"), 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 )download_population( data_resolution = c("60 minute", "30 second", "2.5 minute", "15 minute", "30 minute"), data_format = c("GeoTIFF", "ASCII", "netCDF"), year = c("2020", "2000", "2005", "2010", "2015", "all"), 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 )
data_resolution |
character(1). One of |
data_format |
character(1). Requested format: |
year |
character(1). One year: |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. Set to FALSE to skip downloading and return the planned file list. |
remove_command |
logical(1). Deprecated, ignored. |
unzip |
logical(1). Unzip zip files (default TRUE). |
remove_zip |
logical(1). Remove zip files after unzipping (default FALSE). |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
nasa_earth_data_token |
character(1). NASA EarthData bearer token.
If NULL (default), reads from the |
data_resolution, data_format, and year each select one value.
Matching is case-sensitive, and unambiguous abbreviations are accepted.
If omitted, each argument uses its first listed choice.
When download = TRUE and hash = FALSE, an invisible list containing
success, failed, and skipped file counts. If the requested archive
already exists and is nonempty, no file is downloaded; the returned list
contains success = 0, failed = 0, and skipped = 1. The list always
contains failed_urls and failed_files character vectors, both
character(0) when no downloads failed, including when the file was skipped.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files = 1 is returned without downloading, regardless of hash.
When download = TRUE and hash = TRUE, a character(1) combined MD5 hash
of the files in the data_files directory is returned instead of a list.
Population data may require NASA EarthData authentication depending on access method.
Mitchell Manware, Insang Song
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.
## 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)## 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 one time period and climate element from the PRISM Climate Group Web Service. ZIP archives and extracted data are stored in separate subdirectories using the shared download workflow.
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 )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 )
time |
character(1). Single time-period code, retaining leading zeros.
For |
element |
character(1). Climate element: |
data_type |
character(1). Selected data type: |
format |
character(1). Requested time-series raster format: |
directory_to_save |
character(1). Non-empty parent directory.
Archives are downloaded into |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
unzip |
logical(1). Extract the validated ZIP archive into
|
remove_zip |
logical(1). Remove the downloaded archive and its
|
hash |
logical(1). Return a combined MD5 hash of the files under
|
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file download request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Non-negative throttling interval in seconds,
passed to |
zip_files/ and data_files/ are sibling directories created beneath
directory_to_save, including for previews and when unzip = FALSE.
The local archive name is constructed from the requested element, data
type, time, and, for time series, format. Names and paths inside the
archive are preserved during extraction.
After downloading, the destination archive is checked by listing its
contents with utils::unzip(). This check also applies to existing
non-empty archives skipped by download_run_method(). An unreadable ZIP
raises an error, with a preview of the response text when available.
Listing an archive does not fully verify its members or raster contents.
Hashing covers all files under data_files/, including existing files,
and excludes archives in zip_files/. With unzip = FALSE, hashing still
uses data_files/, which may be empty or contain previously extracted data.
The PRISM Web Service Guide dated 26 March 2025 documents time-series ZIP
downloads, with daily data from 1981 and monthly and annual data from 1895.
It states that normals are unavailable through this service and lists
nc, asc, and bil format conversions, rather than grib2. The normals
and grib2 options remain accepted by this function but are not documented
as supported by the current service. See the guide in References.
With download = FALSE, an invisible preview list containing urls,
destfiles, and n_files. Otherwise, after downloading, validation, and
optional extraction, hash = FALSE returns the download summary from
download_run_method() invisibly. With hash = TRUE, returns a visible
character scalar containing the combined MD5 hash of data_files/.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
Insang Song
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.
download_setup_dir(), download_unzip(), process_prism()
## Not run: download_prism( time = "202104", element = "ppt", data_type = "ts", format = "nc", directory_to_save = file.path(tempdir(), "prism"), acknowledgement = TRUE, download = FALSE # Preview the URL and zip_files/ destination. ) ## End(Not run)## Not run: download_prism( time = "202104", element = "ppt", data_type = "ts", format = "nc", directory_to_save = file.path(tempdir(), "prism"), acknowledgement = TRUE, download = FALSE # Preview the URL and zip_files/ destination. ) ## End(Not run)
Download one multi-year SPEI NetCDF file for a selected accumulation timescale and database version, using the shared download workflow.
download_spei( timescale, version = c("2.11", "2.10", "legacy"), directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 3L, rate_limit = 2, ... )download_spei( timescale, version = c("2.11", "2.10", "legacy"), directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 3L, rate_limit = 2, ... )
timescale |
integer(1). Required positive accumulation timescale in
months. The value is padded to at least two digits in the filename;
for example, |
version |
character(1). |
directory_to_save |
character(1). Non-empty directory for downloaded files. Files retain their provider names directly in this directory; no version-specific subdirectory is created. |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
hash |
logical(1). Return a combined MD5 hash of all files under
|
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file request, including
the initial attempt. Must be at least 1. Default is |
rate_limit |
numeric(1). Finite, non-negative request-throttling
interval in seconds, passed to |
... |
Reserved for future use; currently ignored. |
Version "2.11" uses spei_database_2_11/nc/, version "2.10" uses
spei_database_2_10/nc/, and "legacy" uses files/ on the SPEI server.
Each call constructs one URL. Dates do not select or subset this download;
use process_drought() for temporal selection after downloading.
All versions use the same local speiNN.nc filename. This preserves the
filename expected by drought processing, but existing-file checks do not
identify which version produced a file. Use separate output directories
when retaining multiple versions.
A preview creates the output directory and returns the URL and destination
without contacting the server. Existing files remain in the preview.
Actual downloads use download_run_method(), which skips existing
non-empty files and reports failures without selecting another database
version.
With download = FALSE, an invisible list containing urls,
destfiles, and n_files (one). Otherwise, an invisible download summary
from download_run_method() when hash = FALSE, or a visible character
scalar containing the output-directory MD5 hash when hash = TRUE.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
Insang Song
download_drought(), process_drought(), calculate_drought()
## Not run: download_spei( timescale = 1L, version = "2.11", directory_to_save = file.path(tempdir(), "spei"), acknowledgement = TRUE ) ## End(Not run)## Not run: download_spei( timescale = 1L, version = "2.11", directory_to_save = file.path(tempdir(), "spei"), acknowledgement = TRUE ) ## End(Not run)
The download_terraclimate function accesses and downloads climate
and water balance data from the University of California Merced
Climatology Lab's TerraClimate dataset.
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 )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 )
variables |
character. Variable(s) name(s). |
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
directory_to_save |
character(1). Directory to save data. |
acknowledgement |
logical(1). Must be TRUE to proceed. |
download |
logical(1). DEPRECATED. Downloads happen automatically. |
remove_command |
logical(1). Deprecated, ignored. |
show_progress |
logical(1). Show download progress (default TRUE) |
hash |
logical(1). Return hash of downloaded files (default FALSE) |
max_tries |
integer(1). Maximum retry attempts (default 20) |
rate_limit |
numeric(1). Minimum seconds between requests (default 2) |
With download = FALSE, an invisible preview list containing
urls, destfiles, and n_files. With download = TRUE and
hash = FALSE, an invisible summary from download_run_method() containing
success, failed, skipped, failed_urls, and failed_files. The two
failure vectors are character(0) when no downloads failed, including when
every file was skipped. With download = TRUE and hash = TRUE, a visible
character scalar containing the combined MD5 hash of the output directory.
TerraClimate data does not require authentication.
Mitchell Manware, Insang Song
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.
## Not run: download_terraclimate( variables = "ppt", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)## Not run: download_terraclimate( variables = "ppt", year = 2023, directory_to_save = tempdir(), acknowledgement = TRUE ) ## End(Not run)
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").
download_tri( year = c(2018L, 2022L), jurisdiction = "US", directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, show_progress = TRUE, hash = FALSE, max_tries = 20, rate_limit = 2 )download_tri( year = c(2018L, 2022L), jurisdiction = "US", directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, show_progress = TRUE, hash = FALSE, max_tries = 20, rate_limit = 2 )
year |
integer(1 or more). One year, two endpoints, or a non-empty
vector of years. Every year from the minimum through the maximum is
requested, including gaps: |
jurisdiction |
character(1). TRI file variant to download. Use
|
directory_to_save |
character(1). Non-empty output directory path.
CSV files are saved directly in this directory, which is created if
missing, including when |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
show_progress |
logical(1). Show file download progress. Default is
|
hash |
logical(1). Return a combined MD5 hash of the files under
|
max_tries |
integer(1). Maximum attempts per file download request, including the initial attempt. Default is 20. |
rate_limit |
numeric(1). Request-throttling interval in seconds,
passed to |
File names depend on the selected jurisdiction. For example, requests for
2020 produce tri_raw_2020.csv for "US", tri_raw_2020_NC.csv for "NC",
and tri_raw_2020_TBL.csv for "tbl". Tribal download URLs use lowercase
tbl, while local file names use uppercase TBL.
The output directory is created before returning a preview or downloading.
Preview mode makes no network requests. Individual download failures are
recorded by download_run_method() during file transfers.
Previews include all planned files, including those already present locally.
During downloading, download_run_method() skips existing non-empty files;
missing or empty destination files are downloaded.
Hashing includes all files recursively under directory_to_save, including
existing files and files unrelated to the requested years or jurisdiction.
When download = FALSE, an invisible list containing urls, destfiles,
and n_files is returned regardless of hash. The file count is the number
of planned URLs, including files that already exist locally.
When download = TRUE and hash = FALSE, returns the download summary from
download_run_method() invisibly, including success, failed, and
skipped file counts. The summary always contains failed_urls and
failed_files character vectors, both character(0) when no downloads
failed, including when every file was skipped.
When download = TRUE and hash = TRUE, returns a visible character scalar
containing the combined MD5 hash of the files under directory_to_save.
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.
Mariana Kassien, Insang Song
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.
download_run_method(), process_tri()
## Not run: download_tri( year = 2021L, directory_to_save = tempdir(), jurisdiction = "NC", acknowledgement = TRUE ) ## End(Not run)## Not run: download_tri( year = 2021L, directory_to_save = tempdir(), jurisdiction = "NC", acknowledgement = TRUE ) ## End(Not run)
Download U.S. Drought Monitor ZIP archives for Tuesdays within a date interval, with optional extraction of drought-class shapefiles.
download_usdm( date, directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 3L, rate_limit = 2, unzip = TRUE, remove_zip = FALSE, ... )download_usdm( date, directory_to_save = NULL, acknowledgement = FALSE, download = TRUE, remove_command = FALSE, hash = FALSE, show_progress = TRUE, max_tries = 3L, rate_limit = 2, unzip = TRUE, remove_zip = FALSE, ... )
date |
character(1 or 2). Required date or inclusive range endpoints
in |
directory_to_save |
character(1). Non-empty parent directory.
Archives are saved in |
acknowledgement |
logical(1). Must be |
download |
logical(1). Deprecated. |
remove_command |
logical(1). Deprecated and ignored; |
hash |
logical(1). Return a combined MD5 hash of all files recursively
under |
show_progress |
logical(1). Show file download progress. Default is
|
max_tries |
integer(1). Maximum attempts per file request, including
the initial attempt. Must be at least 1. Default is |
rate_limit |
numeric(1). Finite, non-negative request-throttling
interval in seconds, passed to |
unzip |
logical(1). Extract downloaded or existing archives into
|
remove_zip |
logical(1). Remove archives and their parent |
... |
Reserved for future use; currently ignored. |
Each selected Tuesday maps to a USDM_YYYYMMDD_M.zip archive at the
provider's data/shapefiles_m endpoint. The URL plan does not query
directory listings or establish availability for every selected date.
Both zip_files/ and data_files/ are created before a preview returns,
including when extraction is disabled. Preview results include existing
archive paths and require no network requests.
download_run_method() skips existing non-empty archives and records
individual download failures. All planned archives are subsequently passed
to download_unzip(), including existing archives, with the selected
unzip flag. Paths inside archives are preserved. Extraction errors can
prevent a normal return; download summary counts do not report extraction
success. Pass data_files/ to process_drought() for USDM processing.
With download = FALSE, an invisible list containing urls,
archive destfiles, and n_files. Otherwise, after optional extraction
and cleanup, an invisible summary from download_run_method() when
hash = FALSE, or a visible character scalar containing the combined
MD5 hash of data_files/ when hash = TRUE.
The download summary always contains success, failed, skipped,
failed_urls, and failed_files. The two failure vectors are
character(0) when no files failed, including when every file was skipped.
Insang Song
download_drought(), process_drought(), calculate_drought()
## Not run: download_usdm( date = c("2020-01-07", "2020-01-21"), directory_to_save = file.path(tempdir(), "usdm"), acknowledgement = TRUE ) ## End(Not run)## Not run: download_usdm( date = c("2020-01-07", "2020-01-21"), directory_to_save = file.path(tempdir(), "usdm"), acknowledgement = TRUE ) ## End(Not run)
data.table to an sftime
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.
dt_as_mysftime(x, lonname, latname, timename, crs)dt_as_mysftime(x, lonname, latname, timename, crs)
x |
a |
lonname |
character for longitude column name |
latname |
character for latitude column name |
timename |
character for time column name |
crs |
coordinate reference system |
an sftime object
Eva Marques
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.
get_geos_info(path = NULL, include_file = FALSE, ...)get_geos_info(path = NULL, include_file = FALSE, ...)
path |
character(1+) Path(s) to GEOS file(s) and/or directory(ies)
containing GEOS-CF |
include_file |
logical(1). If |
... |
Placeholders. |
a data.frame with GEOS collection and variable selectors.
Kyle Messier
## Not run: get_geos_info(path = "./data/geos") get_geos_info(path = "./data/geos", include_file = TRUE) ## End(Not run)## Not run: get_geos_info(path = "./data/geos") get_geos_info(path = "./data/geos", include_file = TRUE) ## End(Not run)
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.
get_merra2_info(path = NULL, include_file = FALSE, ...)get_merra2_info(path = NULL, include_file = FALSE, ...)
path |
character(1+) Path(s) to MERRA2 file(s) and/or directory(ies)
containing MERRA2 |
include_file |
logical(1). If |
... |
Placeholders. |
a data.frame with MERRA2 collection and variable selectors.
Kyle Messier
## Not run: get_merra2_info(path = "./data/merra2") get_merra2_info(path = "./data/merra2", include_file = TRUE) ## End(Not run)## Not run: get_merra2_info(path = "./data/merra2") get_merra2_info(path = "./data/merra2", include_file = TRUE) ## End(Not run)
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.
get_modis_info(path = NULL, include_file = FALSE, ...)get_modis_info(path = NULL, include_file = FALSE, ...)
path |
character(1+) Path(s) to MODIS file(s) and/or directory(ies)
containing |
include_file |
logical(1). If |
... |
Placeholders. |
a data.frame with MODIS product and subdataset selectors.
Kyle Messier
## Not run: get_modis_info(path = "./data/modis") get_modis_info(path = "./data/modis", include_file = TRUE) ## End(Not run)## Not run: get_modis_info(path = "./data/modis") get_modis_info(path = "./data/modis", include_file = TRUE) ## End(Not run)
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).
get_tri_info( path = NULL, type = c("chemicals", "industries"), year = NULL, include_na = FALSE, ... )get_tri_info( path = NULL, type = c("chemicals", "industries"), year = NULL, include_na = FALSE, ... )
path |
character(1). Path to the directory with TRI CSV files
(from |
type |
character(1). Lookup table to return. One of |
year |
|
include_na |
logical(1). If |
... |
Placeholders. |
a data.frame containing the requested TRI lookup table.
Kyle Messier
## Not run: get_tri_info(path = "./data") get_tri_info(path = "./data", type = "industries") get_tri_info(path = "./data", year = 2020) ## End(Not run)## Not run: get_tri_info(path = "./data") get_tri_info(path = "./data", type = "industries") get_tri_info(path = "./data", year = 2020) ## End(Not run)
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.
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, resolution_temporal = c("daily", "hourly"), tz = c("local", "gmt"), ... )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, resolution_temporal = c("daily", "hourly"), tz = c("local", "gmt"), ... )
path |
character(1). Directory path to daily measurement data. |
date |
character(1 or 2). Date (1) or start and end dates (2).
Should be in |
mode |
character(1). One of
|
data_field |
character(1). Data field to extract. |
return_format |
character(1). |
extent |
numeric(4). Spatial extent of the resulting object.
The order should be |
resolution_temporal |
character(1). Daily or hourly data, must match
|
tz |
character(1). "local" or "gmt" for time zone associated with hourly data. |
... |
Placeholders. |
a SpatVector, sf, or data.table object depending on the return_format
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().
## 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)## 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)
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.
process_blackmarble( path = NULL, date = NULL, tile_df = process_blackmarble_corners(), subdataset = 3L, crs = "EPSG:4326", ... )process_blackmarble( path = NULL, date = NULL, tile_df = process_blackmarble_corners(), subdataset = 3L, crs = "EPSG:4326", ... )
path |
character. Full paths of h5 files. |
date |
character(1). Date to query. |
tile_df |
data.frame. Contains four corner coordinates in fields named
|
subdataset |
integer(1). Subdataset number to process. Default is 3L. |
crs |
character(1). terra::crs compatible CRS.
Default is |
... |
For internal use. |
a SpatRaster object
Insang Song
## 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)## 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)
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.
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, ... )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, ... )
covariate |
character(1). Covariate type. |
path |
character(1). Directory or file path to raw data
depending on |
... |
Arguments passed to each raw data processing function. |
SpatVector, SpatRaster, sf, data.table, or character depending on
covariate type and selections.
Insang Song
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"
## 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)## 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)
This function imports and cleans raw CropScape data,
returning a single SpatRaster object.
Reads CropScape file of selected year.
process_cropscape(path = NULL, year = 2021, extent = NULL, ...)process_cropscape(path = NULL, year = 2021, extent = NULL, ...)
path |
character giving CropScape data path |
year |
numeric giving the year of CropScape data used |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
Insang Song
## 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)## 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)
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.
process_drought( source = c("spei", "eddi", "usdm"), path = NULL, date = c("2020-01-01", "2020-12-31"), timescale = 1L, extent = NULL, ... )process_drought( source = c("spei", "eddi", "usdm"), path = NULL, date = c("2020-01-01", "2020-12-31"), timescale = 1L, extent = NULL, ... )
source |
character(1). Drought data source. One of |
path |
character(1). Directory containing downloaded drought files
(output of |
date |
character(1 or 2). Single date or start/end dates.
Format |
timescale |
integer(1). Accumulation timescale in months (SPEI/EDDI
only; ignored for USDM). Must match the timescale used in
|
extent |
numeric(4) or |
... |
Reserved for future use; currently ignored. |
SpatRaster for SPEI or EDDI sources.
SpatVector (polygons) for USDM source.
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.
Insang Song
download_drought, calculate_drought
## 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)## 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)
The process_ecoregion function imports and cleans raw ecoregion
data, returning a SpatVector object.
process_ecoregion(path = NULL, extent = NULL, ...)process_ecoregion(path = NULL, extent = NULL, ...)
path |
character(1). Path to Ecoregion Shapefiles |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatVector object
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.
Insang Song
## 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)## 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)
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.
process_edgar(path = NULL, extent = NULL, ...)process_edgar(path = NULL, extent = NULL, ...)
path |
character. Directory containing extracted EDGAR raster files or one or more file paths. |
extent |
numeric(4) or SpatExtent giving the extent of the raster;
if |
... |
Placeholders. |
a SpatRaster object
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.
Mariana Alifa Kassien, Insang Song
download_edgar(), calculate_edgar()
## 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)## 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)
The process_geos() function imports and cleans raw atmospheric
composition data, returning a single SpatRaster object.
process_geos( date = c("2018-01-01", "2018-01-10"), variable = NULL, path = NULL, extent = NULL, daily_agg = FALSE, fun = "mean", ... )process_geos( date = c("2018-01-01", "2018-01-10"), variable = NULL, path = NULL, extent = NULL, daily_agg = FALSE, fun = "mean", ... )
date |
character(1 or 2). Date (1) or start and end dates (2). Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
variable |
character(1). GEOS-CF variable name(s). See Notes for collection-specific variable-name guidance. |
path |
character(1). Directory with downloaded netCDF (.nc4) files. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
daily_agg |
logical(1). If |
fun |
character(1). Aggregation function passed to |
... |
Placeholders. |
GEOS-CF netCDF collections currently supported by download_geos() are:
"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", and
"met_inst_1hr_g1440x721_p23".
a SpatRaster object;
Layer names of the returned SpatRaster object contain the variable,
pressure level, date, and hour when daily_agg = FALSE (default). When
daily_agg = TRUE, layer names contain the variable, pressure level, and
date only, and terra::time() is set to midnight UTC of each date.
Collection-specific variable names accepted by variable:
| Collection | Variables |
aqc_tavg_1hr_g1440x721_v1
|
no2, co, so2, pm25_rh35_gcc, o3
|
chm_tavg_1hr_g1440x721_v1
|
ocpi, bcpo, pm25soa_rh35_gc, dst4, prpe,
macr, pm25ss_rh35_gcc, hno4, ch4, nh3,
h2o2, rcho, hno3, dst1, pan,
pm25oc_rh35_gcc, c3h8, soas, no, tolu,
mvk, xyle, isop, noy, sala, so2,
co, n2o5, eoh, o3, acet, c2h6,
mek, nit, benz, soap, alk4, ocpo,
ald2, hcho, pm25_rh35_gocar, dst3,
pm25su_rh35_gcc, pm25_rh35_gcc, pm25ni_rh35_gcc,
pm25bc_rh35_gcc, dst2, pm25du_rh35_gcc, bcpi,
no2, salc, nh4
|
met_tavg_1hr_g1440x721_x1
|
zl, zpbl, ps, v2m, v, q2m,
u, t2m, troppb, q, t, v10m,
t10m, u2m, q10m, ts, slp, cldtt,
phis, tprec, u10m, rh
|
xgc_tavg_1hr_g1440x721_x1
|
wetdepflx_nh4, aod550_dst6, wetdepflx_dst1,
tropcol_io, totcol_o3, tropcol_hcho,
drydepflx_bcpi, aod550_cloud, aod550_dst5,
wetdepflx_hcho, aod550_salc, aod550_dust,
wetdepflx_so2, wetdepflx_salc, wetdepflx_dst3,
drydepflx_nit, wetdepflx_so4, aod550_sala,
aod550_dst1, tropcol_co, wetdepflx_bcpi,
drydepflx_sala, wetdepflx_nh3, tropcol_no2,
wetdepflx_nit, aod550_sulfate, wetdepflx_ocpi,
drydepflx_hcho, drydepflx_dst4, tropcol_so2,
drydepflx_ocpi, tropcol_o3, drydepflx_nh4,
aod550_dst7, totcol_co, totcol_so2, totcol_io,
drydepflx_nh3, wetdepflx_sala, wetdepflx_dst4,
drydepflx_o3, drydepflx_hno3, aod550_dst4,
aod550_oc, totcol_no2, drydepflx_dst2,
tropcol_bro, wetdepflx_bcpo, drydepflx_bcpo,
wetdepflx_dst2, drydepflx_dst1, aod550_dst2,
aod550_bc, aod550_dst3, wetdepflx_ocpo,
drydepflx_dst3, drydepflx_salc, wetdepflx_hno3,
drydepflx_ocpo, drydepflx_no2, totcol_hcho,
totcol_bro
|
chm_inst_1hr_g1440x721_p23
|
pm25soa_rh35_gc, pm25ss_rh35_gcc, so2, co,
o3, pm25oc_rh35_gcc, pm25du_rh35_gcc, noy,
no2, pm25ni_rh35_gcc, pm25bc_rh35_gcc,
pm25_rh35_gcc, pm25su_rh35_gcc
|
met_inst_1hr_g1440x721_p23
|
omega, t, eth, q, epv, rh,
slp, airdens, ps, h, th, v,
u, airvol_chem
|
variable matching is case-insensitive (for example, "o3"
matches "O3").
Reference: NASA GEOS-CF OpenDAP catalog https://opendap.nccs.nasa.gov/dods/gmao/geos-cf/assim.
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: geos <- process_geos( date = c("2024-01-01", "2024-01-10"), variable = "O3", path = "./data/aqc_tavg_1hr_g1440x721_v1" ) ## daily mean across all sub-daily layers per variable/level geos_daily <- process_geos( date = c("2024-01-01", "2024-01-10"), variable = "O3", path = "./data/aqc_tavg_1hr_g1440x721_v1", daily_agg = TRUE, fun = "mean" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: geos <- process_geos( date = c("2024-01-01", "2024-01-10"), variable = "O3", path = "./data/aqc_tavg_1hr_g1440x721_v1" ) ## daily mean across all sub-daily layers per variable/level geos_daily <- process_geos( date = c("2024-01-01", "2024-01-10"), variable = "O3", path = "./data/aqc_tavg_1hr_g1440x721_v1", daily_agg = TRUE, fun = "mean" ) ## End(Not run)
The process_gmted() function imports and cleans raw elevation data,
returning a single SpatRaster object.
process_gmted(variable = NULL, path = NULL, extent = NULL, ...)process_gmted(variable = NULL, path = NULL, extent = NULL, ...)
variable |
vector(1). Vector containing the GMTED statistic first and the resolution second. (Example: variable = c("Breakline Emphasis", "7.5 arc-seconds")).
|
path |
character(1). Directory with downloaded GMTED "*_grd" folder containing .adf files. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
SpatRaster layer name indicates selected variable and resolution, and year
of release (2010).
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: gmted <- process_gmted( variable = c("Breakline Emphasis", "7.5 arc-seconds"), path = "./data/be75_grd" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: gmted <- process_gmted( variable = c("Breakline Emphasis", "7.5 arc-seconds"), path = "./data/be75_grd" ) ## End(Not run)
The process_goes() function imports and cleans NOAA GOES-16/18
Aerosol Detection Product (ADP) NetCDF files downloaded by
download_goes(), returning a single SpatRaster object with
CRS EPSG:4326.
process_goes( date = c("2024-01-01", "2024-01-01"), variable = NULL, path = NULL, extent = NULL, daily_agg = FALSE, fun = "mean", ... )process_goes( date = c("2024-01-01", "2024-01-01"), variable = NULL, path = NULL, extent = NULL, daily_agg = FALSE, fun = "mean", ... )
date |
character(1 or 2). Date (YYYY-MM-DD) or start and end dates. |
variable |
character(1). Variable name to extract: |
path |
character(1+). Directory with downloaded GOES ADP NetCDF files or a vector of full NetCDF file paths. |
extent |
numeric(4) or SpatExtent. Crop extent
( |
daily_agg |
logical(1). If |
fun |
character(1). Aggregation function passed to |
... |
Placeholders. |
a SpatRaster object
Layer names follow the convention
{variable}_{YYYYMMDD}_{HHMMSS} when daily_agg = FALSE, e.g.
"Smoke_20240101_000000". With daily_agg = TRUE, layer names
contain {variable}_{YYYYMMDD} and terra::time() is set to
midnight UTC.
terra::time() is set to POSIXct UTC for each layer.
Files with GOES geostationary projection are reprojected to EPSG:4326.
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires downloaded ## data files. ## Not run: goes <- process_goes( date = c("2024-01-01", "2024-01-01"), variable = "Smoke", path = "./data/goes/" ) goes_daily <- process_goes( date = c("2024-01-01", "2024-01-01"), variable = "Smoke", path = "./data/goes/", daily_agg = TRUE, fun = "mean" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires downloaded ## data files. ## Not run: goes <- process_goes( date = c("2024-01-01", "2024-01-01"), variable = "Smoke", path = "./data/goes/" ) goes_daily <- process_goes( date = c("2024-01-01", "2024-01-01"), variable = "Smoke", path = "./data/goes/", daily_agg = TRUE, fun = "mean" ) ## End(Not run)
The process_gridmet() function imports and cleans raw gridded surface meteorological
data, returning a single SpatRaster object.
process_gridmet( date = c("2023-09-01", "2023-09-10"), variable = NULL, path = NULL, extent = NULL, ... )process_gridmet( date = c("2023-09-01", "2023-09-10"), variable = NULL, path = NULL, extent = NULL, ... )
date |
character(1 or 2). Date (1) or start and end dates (2). Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
variable |
character(1). Variable name or acronym code. See gridMET Generate Wget File for variable names and acronym codes. (Note: variable "Burning Index" has code "bi" and variable "Energy Release Component" has code "erc"). |
path |
character(1). Directory with downloaded netCDF (.nc) files. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
EDDI uses the same native GRIDMET multi-year workflow as SPEI.
Use eddi14d, eddi30d, eddi90d, eddi180d,
eddi270d, eddi1y, eddi2y, or eddi5y;
eddi defaults to eddi30d. Both indices retain the native
1/24-degree grid and five-day observation dates. Select dataset
gridmet in the wrapper functions to use these products; the
standalone drought source aliases continue to select their separate products.
GRIDMET SPEI uses native five-day observations, not daily values.
Use variable = "spei" (alias for "spei30d") or an explicit
accumulation code: "spei14d", "spei30d", "spei90d",
"spei180d", "spei270d", "spei1y", "spei2y",
or "spei5y". Set path to the code directory created by
download_gridmet() (e.g., spei30d). The multi-year file is subset
using its observation dates; no daily interpolation is performed.
Layer names retain the accumulation period (e.g., spei30d_20200105).
a SpatRaster object
Layer names of the returned SpatRaster object contain the variable acronym,
and date.
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: gridmet <- process_gridmet( date = c("2023-01-01", "2023-01-10"), variable = "Precipitation", path = "./data/pr" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: gridmet <- process_gridmet( date = c("2023-01-01", "2023-01-10"), variable = "Precipitation", path = "./data/pr" ) ## End(Not run)
The process_groads() function imports and cleans raw road data,
returning a single SpatVector object.
process_groads(path = NULL, extent = NULL, ...)process_groads(path = NULL, extent = NULL, ...)
path |
character(1). Path to geodatabase or shapefiles. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatVector object
U.S. context. The returned SpatVector object contains a
$description 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.
Insang Song
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: groads <- process_groads( path = "./data/groads_example.shp" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: groads <- process_groads( path = "./data/groads_example.shp" ) ## End(Not run)
The process_hms() function imports and cleans raw wildfire smoke
plume coverage data, returning a single SpatVector object.
process_hms(date = "2018-01-01", path = NULL, extent = NULL, ...)process_hms(date = "2018-01-01", path = NULL, extent = NULL, ...)
date |
character(1 or 2). Date (1) or start and end dates (2). Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
path |
character(1). Directory with downloaded NOAA HMS data files. |
extent |
numeric(4) or SpatExtent giving the extent of the output
if |
... |
Placeholders. |
a SpatVector or character object
process_hms() will return a character object if there are no wildfire
smoke plumes present for the selected dates and density. The returned
character will contain the density value and the sequence of dates
for which no wildfire smoke plumes were detected (see "Examples").
If multiple density polygons overlap, the function will return the
highest density value.
Mitchell Manware
hms <- process_hms( date = c("2018-12-30", "2019-01-01"), path = "../tests/testdata/hms/" )hms <- process_hms( date = c("2018-12-30", "2019-01-01"), path = "../tests/testdata/hms/" )
Retrieve Hydrologic Unit Code (HUC) data
process_huc( path, layer_name = NULL, huc_level = NULL, huc_header = NULL, extent = NULL, ... )process_huc( path, layer_name = NULL, huc_level = NULL, huc_header = NULL, extent = NULL, ... )
path |
character. Path to the file or the directory containing HUC data. |
layer_name |
character(1). Layer name in the |
huc_level |
character(1). Field name of HUC level |
huc_header |
character(1). The upper level HUC code header to extract lower level HUCs. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Arguments passed to |
a SpatVector object
Insang Song
'hydrogeofetch::get_huc()“
## NOTE: Examples are wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: library(terra) getf <- "WBD_National_GDB.gdb" # check the layer name to read terra::vector_layers(getf) test1 <- process_huc( getf, layer_name = "WBDHU8", huc_level = "huc8" ) test2 <- process_huc( getf, layer_name = "WBDHU8", huc_level = "huc8" ) test3 <- process_huc( "", layer_name = NULL, huc_level = NULL, huc_header = NULL, id = "030202", type = "huc06" ) ## End(Not run)## NOTE: Examples are wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: library(terra) getf <- "WBD_National_GDB.gdb" # check the layer name to read terra::vector_layers(getf) test1 <- process_huc( getf, layer_name = "WBDHU8", huc_level = "huc8" ) test2 <- process_huc( getf, layer_name = "WBDHU8", huc_level = "huc8" ) test3 <- process_huc( "", layer_name = NULL, huc_level = NULL, huc_header = NULL, id = "030202", type = "huc06" ) ## End(Not run)
The process_improve() function reads pipe-delimited IMPROVE
(Interagency Monitoring of Protected Visual Environments) measurement
files downloaded by download_improve() and joins them with a site
metadata table to attach geographic coordinates and auxiliary site
attributes. Returns a
SpatVector, sf, or data.table object.
process_improve( path = NULL, product = c("raw", "rhr2", "rhr3"), date = NULL, sites_file = NULL, return_format = c("terra", "sf", "data.table"), extent = NULL, ... )process_improve( path = NULL, product = c("raw", "rhr2", "rhr3"), date = NULL, sites_file = NULL, return_format = c("terra", "sf", "data.table"), extent = NULL, ... )
path |
character(1). Directory containing downloaded IMPROVE
|
product |
character(1). Product type: |
date |
character(1 or 2). Date ( |
sites_file |
character(1) or |
return_format |
character(1). Return object type: |
extent |
numeric(4) or |
... |
Placeholders. |
Three product types are supported via product:
"raw"IMPAER speciated aerosol mass concentrations.
Key columns: SiteCode, FactDate, ParamCode,
FactValue, Units.
"rhr2"IMPRHR2 Regional Haze Rule II light extinction
(bext, ).
"rhr3"IMPRHR3 Regional Haze Rule III deciview index
(dv).
Measurement values are not filtered by Status; callers
may apply their own validity flags (e.g., keep only Status == "V0").
a SpatVector, sf, or data.table object
depending on return_format.
IMPROVE data are measured on an every-third-day sampling schedule. Gaps between measurement dates are expected.
improve <- process_improve( path = system.file("testdata/improve", package = "amadeus"), product = "raw", date = c("2022-01-01", "2022-01-31"), return_format = "data.table" )improve <- process_improve( path = system.file("testdata/improve", package = "amadeus"), product = "raw", date = c("2022-01-01", "2022-01-31"), return_format = "data.table" )
The process_koppen_geiger() function imports and cleans raw climate
classification data, returning a single SpatRaster object.
process_koppen_geiger(path = NULL, extent = NULL, ...)process_koppen_geiger(path = NULL, extent = NULL, ...)
path |
character(1). Path to Koppen-Geiger climate zone raster file |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
Insang Song
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: kg <- process_koppen_geiger( path = "./data/koppen_geiger_data.tif" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: kg <- process_koppen_geiger( path = "./data/koppen_geiger_data.tif" ) ## End(Not run)
The process_merra2() function imports and cleans raw atmospheric,
meteorological, and MERRA2-based Fire Weather Index data, returning a single
SpatRaster object.
process_merra2( date = c("2018-01-01", "2018-01-10"), variable = NULL, path = NULL, extent = NULL, daily_agg = FALSE, fun = "mean", ... )process_merra2( date = c("2018-01-01", "2018-01-10"), variable = NULL, path = NULL, extent = NULL, daily_agg = FALSE, fun = "mean", ... )
date |
character(1 or 2). Date (1) or start and end dates (2). Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
variable |
character(1). MERRA2 variable name(s). For daily corrected
Fire Weather Index files ( |
path |
character(1). Directory with downloaded netCDF ( |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
daily_agg |
logical(1). If |
fun |
character(1). Aggregation function passed to |
... |
Placeholders. |
a SpatRaster object;
Layer names of the returned SpatRaster object contain the variable,
pressure level, date, and hour for standard MERRA-2 collections when
daily_agg = FALSE (default). When daily_agg = TRUE, layer names contain
the variable, pressure level, and date only, and terra::time() is set to
midnight UTC of each date. For daily Fire Weather Index files, layer names
contain the variable and date only regardless of daily_agg.
Pressure level values utilized for layer names are taken directly from raw
data and are not edited to retain pressure level information.
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: merra2 <- process_merra2( date = c("2024-01-01", "2024-01-10"), variable = "CPT", path = "./data/inst1_2d_int_Nx" ) ## daily mean CPT merra2_daily <- process_merra2( date = c("2024-01-01", "2024-01-10"), variable = "CPT", path = "./data/inst1_2d_int_Nx", daily_agg = TRUE, fun = "mean" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: merra2 <- process_merra2( date = c("2024-01-01", "2024-01-10"), variable = "CPT", path = "./data/inst1_2d_int_Nx" ) ## daily mean CPT merra2_daily <- process_merra2( date = c("2024-01-01", "2024-01-10"), variable = "CPT", path = "./data/inst1_2d_int_Nx", daily_agg = TRUE, fun = "mean" ) ## End(Not run)
Process MODIS HDF/H5 files into day-specific rasters over a requested date range. This helper preserves daily slices instead of flattening a multi-day range into one merged result.
process_modis_daily( path = NULL, date = NULL, subdataset = NULL, fun_agg = "mean", path_secondary = NULL, fusion_method = c("mean", "primary_first", "secondary_first"), return_type = c("stack", "list"), ... )process_modis_daily( path = NULL, date = NULL, subdataset = NULL, fun_agg = "mean", path_secondary = NULL, fusion_method = c("mean", "primary_first", "secondary_first"), return_type = c("stack", "list"), ... )
path |
character. Full list of HDF/H5 file paths. |
date |
character(1:2). Date or date range in |
subdataset |
character(1). Subdataset names to extract.
Should conform to regular expression. See |
fun_agg |
Function name or custom function to aggregate overlapping
cell values. See |
path_secondary |
character. Optional secondary list of HDF/H5 paths
(for example, Aqua files) to fuse with |
fusion_method |
character(1). Fusion method when |
return_type |
character(1). Return |
... |
Additional arguments passed to |
A day-preserving MODIS result as a SpatRaster
(return_type = "stack") or named list (return_type = "list").
Insang Song
process_modis_merge, download_data
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: mod09ga_daily <- process_modis_daily( path = list.files("./data", pattern = "MOD09GA.", full.names = TRUE), date = c("2024-01-01", "2024-01-07"), subdataset = "sur_refl_b01_1", return_type = "list" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: mod09ga_daily <- process_modis_daily( path = list.files("./data", pattern = "MOD09GA.", full.names = TRUE), date = c("2024-01-01", "2024-01-07"), subdataset = "sur_refl_b01_1", return_type = "list" ) ## End(Not run)
Get mosaic or merged raster from multiple MODIS hdf files.
process_modis_merge( path = NULL, date = NULL, subdataset = NULL, fun_agg = "mean", path_secondary = NULL, fusion_method = c("mean", "primary_first", "secondary_first"), ... )process_modis_merge( path = NULL, date = NULL, subdataset = NULL, fun_agg = "mean", path_secondary = NULL, fusion_method = c("mean", "primary_first", "secondary_first"), ... )
path |
character. Full list of hdf file paths.
preferably a recursive search result from |
date |
character(1). date to query. Should be in
|
subdataset |
character(1). subdataset names to extract.
Should conform to regular expression. See |
fun_agg |
Function name or custom function to aggregate overlapping
cell values. See |
path_secondary |
character. Optional secondary list of HDF/H5 paths
(e.g., Aqua files) to fuse with |
fusion_method |
character(1). Fusion method when |
... |
For internal use. |
a SpatRaster object
Curvilinear products (i.e., swaths) will not be accepted.
MODIS products downloaded by functions in amadeus,
MODISTools,
and luna are accepted.
Insang Song
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: mod09ga_merge <- process_modis_merge( path = list.files("./data", pattern = "MOD09GA.", full.names = TRUE), date = "2024-01-01", subdataset = "sur_refl_b01_1", fun_agg = "mean" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: mod09ga_merge <- process_modis_merge( path = list.files("./data", pattern = "MOD09GA.", full.names = TRUE), date = "2024-01-01", subdataset = "sur_refl_b01_1", fun_agg = "mean" ) ## End(Not run)
This function will return a SpatRaster object with
values of selected subdatasets. Swath data include curvilinear
grids, which require warping/rectifying the original curvilinear grids
into rectilinear grids. The function internally warps each of inputs
then mosaic the warped images into one large SpatRaster object.
Users need to select a subdataset to process. The full path looks like
"HDF4_EOS:EOS_SWATH:{file_path}:mod06:subdataset", where file_path is
the full path to the hdf file.
process_modis_swath( path = NULL, date = NULL, subdataset = NULL, suffix = ":mod06:", resolution = 0.05, ... )process_modis_swath( path = NULL, date = NULL, subdataset = NULL, suffix = ":mod06:", resolution = 0.05, ... )
path |
character. Full paths of hdf files. |
date |
character(1). Date to query. |
subdataset |
character. Subdatasets to process.
Unlike other preprocessing functions, this argument should specify
the exact subdataset name. For example, when using MOD06_L2 product,
one may specify |
suffix |
character(1). Should be formatted |
resolution |
numeric(1). Resolution of output raster. Unit is degree (decimal degree in WGS84). |
... |
For internal use. |
a SpatRaster object (crs = "EPSG:4326"): if path is a single file with
full specification of subdataset.
a SpatRaster object (crs = "EPSG:4326"): if path is a list of files. In this case, the returned object will have the maximal extent of multiple warped layers
Insang Song
terra::describe(): to list the full subdataset list with sds = TRUE
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: mod06l2_swath <- process_modis_swath( path = list.files( "./data/mod06l2", full.names = TRUE, pattern = ".hdf" ), date = "2024-01-01", subdataset = "Cloud_Fraction", suffix = ":mod06:", resolution = 0.05 ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: mod06l2_swath <- process_modis_swath( path = list.files( "./data/mod06l2", full.names = TRUE, pattern = ".hdf" ), date = "2024-01-01", subdataset = "Cloud_Fraction", suffix = ":mod06:", resolution = 0.05 ) ## End(Not run)
The process_narr() function imports and cleans raw meteorological
data, returning a single SpatRaster object.
process_narr( date = "2023-09-01", variable = NULL, path = NULL, extent = NULL, ... )process_narr( date = "2023-09-01", variable = NULL, path = NULL, extent = NULL, ... )
date |
character(1 or 2). Date (1) or start and end dates (2). Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
variable |
character(1). Variable name acronym. See List of Variables in NARR Files for variable names and acronym codes. |
path |
character(1). Directory with downloaded netCDF (.nc) files. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
Layer names of the returned SpatRaster object contain the variable acronym,
pressure level, and date.
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: process_narr( date = c("2018-01-01", "2018-01-10"), variable = "weasd", path = "./tests/testdata/narr/weasd" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: process_narr( date = c("2018-01-01", "2018-01-10"), variable = "weasd", path = "./tests/testdata/narr/weasd" ) ## End(Not run)
The process_nei() function imports and cleans raw road emissions data,
returning a single SpatVector object.
NEI data comprises multiple csv files where emissions of 50+ pollutants are recorded at county level. With raw data files, this function will join a combined table of NEI data and county boundary, then perform a spatial join to target locations.
process_nei(path = NULL, county = NULL, year = c(2017, 2020), ...)process_nei(path = NULL, county = NULL, year = c(2017, 2020), ...)
path |
character(1). Directory with NEI csv files. |
county |
|
year |
integer(1) Year to use. Currently only 2017 or 2020 is accepted. |
... |
Placeholders. |
a SpatVector object
Base files for county argument can be downloaded directly from
U.S. Census Bureau
or by using tigris package. This function does not reproject census boundaries.
Users should be aware of the coordinate system of census boundary data for
other analyses.
Insang Song
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: nei <- process_nei( path = "./data", county = system.file("gpkg/nc.gpkg", package = "sf"), year = 2017 ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: nei <- process_nei( path = "./data", county = system.file("gpkg/nc.gpkg", package = "sf"), year = 2017 ) ## End(Not run)
The process_nlcd() function imports and cleans raw land cover data,
returning a single SpatRaster object.
Reads NLCD file of selected year.
process_nlcd(path = NULL, year = 2021, extent = NULL, ...)process_nlcd(path = NULL, year = 2021, extent = NULL, ...)
path |
character giving nlcd data path |
year |
numeric giving the year of NLCD data used |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
Eva Marques, Insang Song
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: nlcd <- process_nlcd( path = "./data/", year = 2021 ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: nlcd <- process_nlcd( path = "./data/", year = 2021 ) ## End(Not run)
The process_secac_population() function imports and cleans raw
population density data, returning a single SpatRaster object.
process_population(path = NULL, extent = NULL, ...)process_population(path = NULL, extent = NULL, ...)
path |
character(1). Path to GeoTIFF (.tif) or netCDF (.nc) file. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: pop <- process_population( path = "./data/sedac_population_example.tif" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: pop <- process_population( path = "./data/sedac_population_example.tif" ) ## End(Not run)
This function imports and cleans raw PRISM data,
returning a single SpatRaster object.
Reads time series or 30-year normal PRISM data.
process_prism(path = NULL, element = NULL, time = NULL, extent = NULL, ...)process_prism(path = NULL, element = NULL, time = NULL, extent = NULL, ...)
path |
character giving PRISM data path Both file and directory path are acceptable. |
element |
character(1). PRISM element name |
time |
character(1). PRISM time name. Should be character in length of 2, 4, 6, or 8. "annual" is acceptable. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object with metadata of time and element.
Insang Song
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: prism <- process_prism( path = "./data/PRISM_ppt_stable_4kmM3_202104_nc.nc", element = "ppt", time = "202104" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: prism <- process_prism( path = "./data/PRISM_ppt_stable_4kmM3_202104_nc.nc", element = "ppt", time = "202104" ) ## End(Not run)
The process_terraclimate() function imports and cleans climate and water balance
data, returning a single SpatRaster object.
process_terraclimate( date = c("2023-09-01", "2023-09-10"), variable = NULL, path = NULL, extent = NULL, ... )process_terraclimate( date = c("2023-09-01", "2023-09-10"), variable = NULL, path = NULL, extent = NULL, ... )
date |
character(1 or 2). Date (1) or start and end dates (2). Format YYYY-MM-DD (ex. September 1, 2023 = "2023-09-01"). |
variable |
character(1). Variable name or acronym code. See TerraClimate Direct Downloads for variable names and acronym codes. |
path |
character(1). Directory with downloaded netCDF (.nc) files. |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatRaster object
Layer names of the returned SpatRaster object contain the variable acronym, year,
and month.
TerraClimate data has monthly temporal resolution, so the first day of each month is used as a placeholder temporal value.
Mitchell Manware
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: terraclimate <- process_terraclimate( date = c("2023-01-01", "2023-01-10"), variable = "Precipitation", path = "./data/ppt" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: terraclimate <- process_terraclimate( date = c("2023-01-01", "2023-01-10"), variable = "Precipitation", path = "./data/ppt" ) ## End(Not run)
This function imports and cleans raw toxic release data,
returning a single SpatVector (points) object for the selected year.
process_tri( path = NULL, year = 2018, variables = "STACK_AIR", chemical = NULL, industry_group = c("none", "industry_sector", "industry_sector_code", "both"), ignore_case = TRUE, extent = NULL, ... )process_tri( path = NULL, year = 2018, variables = "STACK_AIR", chemical = NULL, industry_group = c("none", "industry_sector", "industry_sector_code", "both"), ignore_case = TRUE, extent = NULL, ... )
path |
character(1). Path to the directory with TRI CSV files |
year |
integer(1). Single year to select. |
variables |
character. One or more regular expressions used to select
TRI release variables by column name after normalization to underscore
naming (for example,
|
chemical |
|
industry_group |
character(1). Optional additional grouping level.
One of |
ignore_case |
logical(1). If |
extent |
numeric(4) or SpatExtent giving the extent of the raster
if |
... |
Placeholders. |
a SpatVector object (points) in year
year is stored in a field named "year".
Use get_tri_info() to inspect
available TRI chemical IDs/names/CAS numbers and industry sector codes in
local TRI files. Visit TRI Data and Tools
to view the available years and variables.
Kyle Messier
https://www.epa.gov/toxics-release-inventory-tri-program/tri-toolbox
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: tri <- process_tri( path = "./data", year = 2020, variables = c("STACK_AIR", "FUGITIVE_AIR"), chemical = "benzene", industry_group = "industry_sector" ) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: tri <- process_tri( path = "./data", year = 2020, variables = c("STACK_AIR", "FUGITIVE_AIR"), chemical = "benzene", industry_group = "industry_sector" ) ## End(Not run)
Interactive helper to securely set up NASA EarthData authentication. This function guides users through setting up their token in a secure way that won't be exposed in scripts or version control.
setup_nasa_token(method = c("renviron", "file", "session"), token = NULL)setup_nasa_token(method = c("renviron", "file", "session"), token = NULL)
method |
character(1). Setup method:
|
token |
character(1). Your NASA EarthData token. If NULL, will prompt. |
invisible(NULL). Sets up authentication.
## Not run: # Interactive setup (recommended) setup_nasa_token() # Save to .Renviron for permanent setup setup_nasa_token(method = "renviron", token = "your_token_here") # Save to file setup_nasa_token(method = "file", token = "your_token_here") # Current session only setup_nasa_token(method = "session", token = "your_token_here") ## End(Not run)## Not run: # Interactive setup (recommended) setup_nasa_token() # Save to .Renviron for permanent setup setup_nasa_token(method = "renviron", token = "your_token_here") # Save to file setup_nasa_token(method = "file", token = "your_token_here") # Current session only setup_nasa_token(method = "session", token = "your_token_here") ## End(Not run)
sf to an sftime
Convert an sf object to an sftime object. x must
contain a time-defining column, identified in timename.
sf_as_mysftime(x, timename)sf_as_mysftime(x, timename)
x |
an |
timename |
character: name of time column in x |
an sftime object
Eva Marques
sftime to a mysftime
Convert an sftime object to a mysftime object. x must
contain a time-defining column, identified in timename.
sftime_as_mysftime(x, timename)sftime_as_mysftime(x, timename)
x |
an |
timename |
character: name of time column in |
an sftime object with specific format
Eva Marques
sftime to an sf
Convert an sftime object to an sf object. x must
contain a time-defining column, identified in timename.
sftime_as_sf(x, keeptime = TRUE)sftime_as_sf(x, keeptime = TRUE)
x |
an |
keeptime |
boolean: TRUE if user wants to keep time column as simple column (default = TRUE) |
an sf object
Eva Marques
sftime to a SpatRaster
Convert an sftime object to a SpatRaster object. Returns a
SpatRatser with one layer for each time step in x.
sftime_as_spatraster(x, varname)sftime_as_spatraster(x, varname)
x |
an |
varname |
variable to rasterize |
a SpatRaster object
Running sftime_as_spatraster can take a long time if x is not
spatially structured.
Eva Marques
sftime to a SpatRasterDataset
Convert an sftime object to a SpatRasterDataset object.
sftime_as_spatrds(x)sftime_as_spatrds(x)
x |
an |
an SpatRasterDataset object
Running sftime_as_spatrds can take a long time if x is not
spatially and temporally structured.
Eva Marques
sftime to a SpatVector
Convert an sftime object to a SpatVector object.
sftime_as_spatvector(x)sftime_as_spatvector(x)
x |
an |
a SpatVector object
Eva Marques
SpatRaster to an sftime
Convert a SpatRaster object to an sftime object. x must
contain a time-defining column, identified in timename.
spatraster_as_sftime(x, varname, timename = "time")spatraster_as_sftime(x, varname, timename = "time")
x |
a |
varname |
character for variable column name in the sftime |
timename |
character for time column name in the sftime (default: "time") |
a sftime object
Eva Marques
SpatRasterDataset to an sftime
Convert a SpatRasterDataset object to an sftime object.
x must contain a time-defining column, identified in timename.
spatrds_as_sftime(x, timename = "time")spatrds_as_sftime(x, timename = "time")
x |
a |
timename |
character for time column name in the sftime (default: "time") |
an sftime object
Eva Marques
SpatVector to an sftime
Convert a SpatVector object to an sftime object. x must
contain a time-defining column, identified in timename.
spatvector_as_sftime(x, timename = "time")spatvector_as_sftime(x, timename = "time")
x |
a |
timename |
character for time column name in x (default: "time") |
an sftime object
Eva Marques
Calculate isotropic Sum of Exponentially Decaying Contributions (SEDC) covariates
sum_edc( from = NULL, locs = NULL, locs_id = NULL, decay_range = NULL, target_fields = NULL, C0 = NULL, use_threshold = TRUE, geom = FALSE )sum_edc( from = NULL, locs = NULL, locs_id = NULL, decay_range = NULL, target_fields = NULL, C0 = NULL, use_threshold = TRUE, geom = FALSE )
from |
|
locs |
sf/SpatVector(1). Locations where the sum of exponentially decaying contributions are calculated. |
locs_id |
character(1). Name of the unique id field in |
decay_range |
numeric(1).
Distance at which the source concentration is reduced to
|
target_fields |
character(varying). Field names in characters. |
C0 |
|
use_threshold |
logical(1). If |
geom |
FALSE/"sf"/"terra".. Should the function return with geometry?
Default is |
a data.frame (tibble) or SpatVector object with input field names with
a suffix "_sedc" where the sums of EDC are stored.
Additional attributes are attached for the EDC information.
'attr(result, "decay_range")“: the range where concentration reduces to approximately five percent
'attr(result, "sedc_threshold")“: the threshold distance at which emission source points are excluded beyond that
The function is originally from
chopin
Distance calculation is done with terra functions internally.
Thus, the function internally converts sf objects in
point_* arguments to terra.
The threshold should be carefully chosen by users.
Insang Song
Messier KP, Akita Y, Serre ML (2012). “Integrating Address Geocoding, Land Use Regression, and Spatiotemporal Geostatistical Estimation for Groundwater Tetrachloroethylene.” Environmental Science & Technology, 46(5), 2772–2780. ISSN 0013-936X. doi:10.1021/es203152a.
Wiesner C (????). “Euclidean Sum of Exponentially Decaying Contributions Tutorial.”
## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: set.seed(101) ncpath <- system.file("gpkg/nc.gpkg", package = "sf") nc <- terra::vect(ncpath) nc <- terra::project(nc, "EPSG:5070") pnt_locs <- terra::centroids(nc, inside = TRUE) pnt_locs <- pnt_locs[, "NAME"] pnt_from <- terra::spatSample(nc, 10L) pnt_from$pid <- seq(1, 10) pnt_from <- pnt_from[, "pid"] pnt_from$val1 <- rgamma(10L, 1, 0.05) pnt_from$val2 <- rgamma(10L, 2, 1) vals <- c("val1", "val2") sum_edc(pnt_locs, pnt_from, "NAME", 1e4, vals) ## End(Not run)## NOTE: Example is wrapped in `\dontrun{}` as function requires a large ## amount of data which is not included in the package. ## Not run: set.seed(101) ncpath <- system.file("gpkg/nc.gpkg", package = "sf") nc <- terra::vect(ncpath) nc <- terra::project(nc, "EPSG:5070") pnt_locs <- terra::centroids(nc, inside = TRUE) pnt_locs <- pnt_locs[, "NAME"] pnt_from <- terra::spatSample(nc, 10L) pnt_from$pid <- seq(1, 10) pnt_from <- pnt_from[, "pid"] pnt_from$val1 <- rgamma(10L, 1, 0.05) pnt_from$val2 <- rgamma(10L, 2, 1) vals <- c("val1", "val2") sum_edc(pnt_locs, pnt_from, "NAME", 1e4, vals) ## End(Not run)