ms_load_product: Read MacroSheds data products from disk into R

In MacroSHEDS/macrosheds: Tools for interfacing with the MacroSheds dataset

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 ms_download_core_data() and/or ms_download_ws_attr(). If you specified different locations with each of these functions, you'll need to refer to them separately when loading time-series data vs. watershed attribute data.
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): discharge stream_chemistry stream_flux_inst_scaled* precipitation, precip_chemistry precip_flux_inst_scaled* stream_load_annual_scaled** (and for watershed attribute products): ws_attr_summaries ws_attr_timeseries:all ws_attr_timeseries:climate ws_attr_timeseries:hydrology ws_attr_timeseries:landcover ws_attr_timeseries:parentmaterial ws_attr_timeseries:terrain ws_attr_timeseries:vegetation ws_attr_CAMELS_summaries ws_attr_CAMELS_Daymet_forcings
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 ms_load_variables() or visit macrosheds.org.
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 ms_load_sites() or visit macrosheds.org.
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, [e-mail]

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')

MacroSHEDS/macrosheds documentation built on Oct. 30, 2024, 11:15 a.m.