ms_load_product: Read MacroSheds data products from disk into R
View source: R/ms_load_product.R
| ms_load_product | R Documentation |
Read MacroSheds data products from disk into R
Description
Loads MacroSheds core time-series products and watershed attributes from the
MacroSheds dataset after components have been downloaded using ms_download_core_data()
or ms_download_ws_attr(). For watershed boundaries and gauge locations, see ms_load_spatial_product().
Complete documentation is available on EDI.
Usage
ms_load_product(
macrosheds_root,
prodname,
version = "latest",
filter_vars,
networks,
domains,
site_codes,
sort_result = FALSE,
warn = TRUE
)
Arguments
macrosheds_root |
character. The path to the MacroSheds dataset's parent
directory, established with |
prodname |
character. A MacroSheds product name. Files associated with this product name will be read and combined. See details for footnotes. Available prodnames are (for core time-series products):
(and for watershed attribute products):
|
version |
numeric or "latest". The MacroSheds dataset version from which to load data. |
filter_vars |
character vector of variable codes. for products like stream_chemistry that include
multiple variables, this filters to just the ones specified
Ignored if requesting discharge, precipitation, or watershed attributes.
To see a catalog of variable codes, run |
networks, domains, site_codes |
character vectors of MacroSheds networks/domains/sites to load. Omit to load all.
To see a catalog of site codes, run |
sort_result |
logical. Ignored if requesting watershed attributes. If TRUE, and requesting core time-series data, output will be sorted by site_code, var, datetime. this may add considerable loading time for large datasets. |
warn |
logical. If TRUE, no more than 1 GiB will be loaded into memory without permission, and you'll get notifications about more recent versions of the MacroSheds dataset, if available. |
Details
*"instantaneous" (i.e. daily) flux, scaled by watershed area and reported in kg/ha/d.
Note that flux products can also be computed from component products using
ms_calc_flux() and ms_calc_flux_rsfme().
**load = flux aggregated by water-year (Oct 1 to Sept 30). Load is computed by various methods,
with MacroSheds-recommended method identified for each site_code-variable-water_year combination.
Scaled by watershed area and reported in kg/ha/yr. See ms_calc_flux for method details.
For some domains, it is possible to request "custom" variants of products, which
are analogous to their standard types, but are calculated according to the methods
employed by the primary source data provider. Examples are Panola stream flux, which
can be loaded via prodname = "CUSTOMstream_flux_inst_scaled". Consider these
products to be "secret menu items" for now. You may identify them by searching for the
word "CUSTOM" in your macrosheds_root directory.
Value
For all core timeseries products except load, returns a tibble in MacroSheds format.
This format is often required in inputs to macrosheds tools, but usually only date, site_code, var, and val columns are required.
| header value | column_definition |
| date | Date in YYYY-mm-dd |
| site_code | A unique identifier for each MacroSheds site, identical to primary source site code where possible. See ms_load_sites(). |
| grab_sample | Boolean integer indicating whether the observation was obtained via grab sample or installed sensor. 1 = TRUE (grab sample), 0 = FALSE (installed sensor). |
| var | Variable code. See ms_load_variables(). |
| val | Data value. See ms_load_variables() for units. |
| ms_status | Boolean integer. 0 = clean value. 1 = questionable value. See "Technical Validation" section of the MacroSheds data paper for details. |
| ms_interp | Boolean integer. 0 = measured or imputed by primary source. 1 = interpolated by MacroSheds. See "Temporal Imputation and Aggregation" section of the MacroSheds data paper for details. |
| val_err | The combined standard uncertainty associated with the corresponding data point, if estimable. See "Detection Limits and Propagation of Uncertainty" section of the MacroSheds data paper for details. |
For other products, returns a tibble with one of several formats. Visit EDI. for complete column descriptions.
Author(s)
Spencer Rhea
Mike Vlah, vlahm13@gmail.com
Wes Slaughter
See Also
ms_download_core_data(), ms_download_ws_attr(), ms_load_spatial_product(), ms_load_variables(), ms_load_sites()
Examples
ms_root = 'data/macrosheds'
ms_download_core_data(macrosheds_root = ms_root, domains = c('niwot', 'hjandrews'))
ms_download_ws_attr(macrosheds_root = ms_root, dataset = 'time series')
macrosheds_data <- ms_load_product(macrosheds_root = ms_root,
prodname = 'stream_chemistry',
filter_vars = 'NO3_N')
macrosheds_data <- ms_load_product(macrosheds_root = ms_root,
prodname = 'ws_attr_timeseries:all')
