ms_load_product: Read MacroSheds data products from disk into R

View source: R/ms_load_product.R

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

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