ms_calc_watershed_precip: Spatially interpolate precipitation gauge data to whole...

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

Spatially interpolate precipitation gauge data to whole watersheds (i.e. basins).

Description

Using precipitation gauge recordings (depth and/or chemistry) and locations, this function interpolates an estimated value at each cell of an automatically retrieved digital elevation model (DEM), then averages cell values to generate a watershed average at every time step. The local relationship between elevation and precipitation depth may also be leveraged for better prediction. If precipitation chemistry is supplied in addition to depth, then watershed-average precipitation depth, chemistry, and chemical flux estimates will all be generated.

Usage

ms_calc_watershed_precip(
  precip,
  ws_boundary,
  precip_gauge,
  pchem,
  parallel = TRUE,
  maxcores = Inf,
  out_path,
  elevation_agnostic = TRUE,
  verbose = TRUE
)

Arguments

precip	optional data.frame in MacroSheds format (see details), containing precipitation depth time series in mm. A tibble fitting these specifications can be generated by ms_load_product(). If precip is supplied and pchem is not, only watershed-average precip is returned. If both are supplied, both are returned, as well as watershed-average chemical flux, computed from the cell-wise product of precip and pchem after imputation.
ws_boundary	sf object or path to a directory containing directories, each in turn containing individual shapefiles of watershed boundaries. Object/files must have site_code and geometry features (columns). See ms_delineate_watershed().
precip_gauge	sf object or path to a directory containing directories, each in turn containing shapefiles of precipitation gauge locations. Object/files must have site_code and geometry features (columns). All supplied precip gauges will be used for imputation, even if they are far from the watershed of interest.
pchem	optional data.frame in MacroSheds format (see details), containing precipitation chemistry time series in mg/L. A tibble fitting these specifications can be generated by by ms_load_product(). If pchem is supplied and precip is not, only watershed-average pchem is returned. If both are supplied, both are returned, as well as watershed-average precipitation chemical flux, computed from the cell-wise product of precip and pchem after imputation.
parallel	logical. If TRUE (default), interpolation attempts to use maxcores CPU cores/threads.
maxcores	numeric. Default Inf; the maximum number of cores (or hyperthreads) used in parallel processing. Ignored if parallel is FALSE. If greater than the available number of cores/hyperthreads, all available cores/hyperthreads will be used.
out_path	character. Directory to which output data will be saved.
elevation_agnostic	Logical. Should elevation data be ignored when interpolating precipitation data? TRUE means "ignore elevation." See details for more information.
verbose	Logical. If TRUE (default), prints more information during run.

Details

This function uses inverse distance weighted interpolation to extend gauge measurements to every cell of a watershed DEM. If elevation_agnostic is set to TRUE, the resulting watershed average will be a simple arithmetic mean of all watershed cell values, ignoring the local relationship between precipitation and elevation. If FALSE (the default), the resulting watershed average will be a weighted mean of two separate estimates: the mean of cell values (weight: 1) and the prediction of a linear regression with elevation (weight: absolute value of adjusted R^2 of modeled data). At least 3 gauges must record at a given time step for the regression to be leveraged in generating the final prediction. Note that these computations are performed at every time step, using all available (non-missing, non-NA) gauges.

This function will interpolate only precipitation depth if no pchem is supplied. It will only interpolate precipitation chemistry if no precip data is supplied. If both precip and pchem are supplied, then precipitation depth, chemical concentrations, and precipitation chemical fluxes will all be calculated.

In general, elevation is a relevant predictor for precipitation depth, but not necessarily concentration or flux of precip chemical components. As such, elevation_agnostic is always set to TRUE (ignore the elev-precip relationship) when determining watershed-average precipitation chemistry in the case of both precip and pchem being supplied. If only pchem or precipis supplied and elevation_agnostic is FALSE, then the elevation-pchem relationship will be incorporated into the final estimate of the watershed average for each time step.

Note that this function does not return the imputed watershed grid for each timestep–only the watershed-average estimate(s) as tibbles.

MacroSheds format (only date, site_code, var, and val are required as inputs. all are written to output files):

• "date" in YYYY-mm-dd format

• "site_code": Short name for MacroSheds site. 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 the MacroSheds data paper for details.

• "ms_interp": Boolean integer. 0 = measured or imputed by primary source. 1 = interpolated by MacroSheds. See the MacroSheds data paper for details.

• "val_err": The combined standard uncertainty associated with the corresponding data point, or NA if unknown. See "Detection limits and propagation of uncertainty" section of See the MacroSheds data paper for details.

Value

Saves watershed-average precipitation depth and/or chemistry, and chemical flux (if both precip and pchem are supplied) to out_path as feather files in MacroSheds format (see details). Output units for flux are kg/d. See ms_scale_flux_by_area() to convert to kg/ha/d.

Author(s)

Spencer Rhea

Mike Vlah, [e-mail]

Wes Slaughter

See Also

ms_load_product(), ms_delineate_watershed(), ms_scale_flux_by_area()

Examples

See vignette: https://github.com/MacroSHEDS/macrosheds/blob/master/vignettes/ms_interpolate_precip.md

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