Package 'isoWater' reference manual

Title:	Discovery, Retrieval, and Analysis of Water Isotope Data
Description:	The wiDB...() functions provide an interface to the public API of the wiDB <https://github.com/SPATIAL-Lab/isoWater/blob/master/Protocol.md>: build, check and submit queries, and receive and unpack responses. Data analysis functions support Bayesian inference of the source and source isotope composition of water samples that may have experienced evaporation. Algorithms adapted from Bowen et al. (2018, <doi:10.1007/s00442-018-4192-5>).
Authors:	Gabe Bowen [aut, cre]
Maintainer:	Gabe Bowen <[email protected]>
License:	GPL-3
Version:	1.2.0
Built:	2024-11-21 06:46:42 UTC
Source:	CRAN

Deuterium excess

Description

Calculates deuterium excess or line-conditioned excess.

Usage

dex(HO, form = "dex", MWL = NULL)
dex(HO, form = "dex", MWL = NULL)

Arguments

`HO`	data.frame. Hydrogen (column 1) and oxygen (column 2) isotope values for 1 or more water samples.
`form`	character. Calculate deuterium excess (“dex”), line-conditioned excess (“lcex”), or “both”.
`MWL`	numeric. Vector the first two elements of which contain the meteoric water line slope and intercept (e.g., as created by `mwl`). The default value (if `MWL = NULL`) reflects the Global Meteoric Water Line estimated from a global precipitation compilation in Bowen, et al. (2019). Ignored for `form = "dex"`.

Value

Returns a copy of HO with an added field(s) “dex” and/or “lcex” containing the calculated values. Deuterium excess is calculated following Dansgaard (1964) as: dex = $\delta$ 2H - 8 * $\delta$ 18O, and lc-excess following Landwehr & Coplen (2006) as lcex = $\delta$ 2H - m * $\delta$ 18O - b, where m and b are the slope and intercept of MWL, respectively.

References

Bowen et al. (2019) Isotopes in the water cycle: Regional- to global-Scale patterns and applications. Annual Review of Earth and Planetary Sciences 47 453–479. doi:10.1146/annurev-earth-053018-060220.

Dansgaard (1964) Stable isotopes in precipitation. Tellus 16 436–468. doi:10.1111/j.2153-3490.1964.tb00181.x.

Landwehr & Coplen (2006) Line-conditioned excess: A new method for characterizing stable hydrogen and oxygen isotope ratios in hydrologic systems. In Isotopes in Environmental Studies, International Atomic Energy Agency, 132–135. http://www-pub.iaea.org/MTCD/publications/PDF/CSP_26_web.pdf.

Examples

O = runif(10, -15, -2)
H = O * 8 + 10 + rnorm(10, 0, 6)
d = dex(data.frame(H, O), form = "both")
print(d)
O = runif(10, -15, -2)
H = O * 8 + 10 + rnorm(10, 0, 6)
d = dex(data.frame(H, O), form = "both")
print(d)

Global Meteoric Water Line

Description

Parameters for the Global Meteoric Water Line fit to a global precipitation compilation in Bowen, et al. (2019).

Usage

data("GMWL")data("GMWL")

Format

The format is: num [1:6] slope, intercept, average d18O, sum of squares in d18O, root mean square error, number of samples

Source

Examples

data(GMWL)
data(GMWL)

Iso Object

Description

Creates objects of type "iso"

Usage

iso(H, O = 0, Hsd = 0, Osd = 0, HOc = 0)
iso(H, O = 0, Hsd = 0, Osd = 0, HOc = 0)

Arguments

`H`	numeric or data.frame. If numeric, hydrogen isotope value or vector of hydrogen isotope values. If data.frame, data frame including five numeric fields that contain the H, O, Hsd, Osd, and HOc values (respectively).
`O`	numeric. Oxygen isotope value or vector of oxygen isotope values.
`Hsd`	numeric. 1 standard deviation uncertainty of `H` (value or vector of values).
`Osd`	numeric. 1 standard deviation uncertainty of `O` (value or vector of values).
`HOc`	numeric. Covariance of `H` and `O` uncertainties (value or vector of values).

Details

For numeric vector arguments, values in Hsd, Osd, and HOc are recycled if their length is shorter than that of H and O.

Value

Returns an object of class “iso”, a data.frame containing the provided values.

Examples

obs = iso(-30, -5, 2, 0.2, 0.3)
str(obs)
obs = iso(-30, -5, 2, 0.2, 0.3)
str(obs)

Discovery, Retrieval, and Analysis of Water Isotope Data

Description

wiDB_ functions provide interface to the public API of the wiDB: https://github.com/SPATIAL-Lab/isoWater/blob/master/Protocol.md. Build, check and submit queries, and receive and unpack responses. Data analysis functions support Bayesian inference of the source and source isotope composition of water samples that may have experienced evaporation. Algorithms adapted from Bowen et al. (2018, doi:10.1007/s00442-018-4192-5).

Author(s)

Maintainer: Gabriel Bowen [email protected] Authors: Gabriel Bowen

Water Source as a Mixture

Description

Given isotopic compositions of two or more potential sources, generate a posterior sample of source mixtures conditioned on one or more sample values.

Usage

mixSource(obs, sources, slope, prior=rep(1,nrow(sources)), 
  shp = 1, edist = "unif", eprior = NULL, ngens = 1e5, ncores = 1)
mixSource(obs, sources, slope, prior=rep(1,nrow(sources)), 
  shp = 1, edist = "unif", eprior = NULL, ngens = 1e5, ncores = 1)

Arguments

`obs`	`iso` object containing isotope values for one or more samples.
`sources`	`iso` object containing isotope values for two or more sources which may have contributed to the observed samples.
`slope`	numeric. Vector of length two specifying prior parameters for the evaporation line slope (mean, standard deviation).
`prior`	numeric. Vector of length equal to the number of sources, giving prior estimates of relative contributions of different sources.
`shp`	numeric. Shape parameter constant used in specifying prior estimates of source contributions (see Details).
`edist`	character. One of `"unif"` or `"gamma"`, specifying whether the evaporation prior is modeled using a uniform or gamma distribution.
`eprior`	numeric. Vector of length 2 giving prior parameter estimates for the oxygen isotope evaporation effect. For `edist = "unif"` these are maximum and minimum values and the default values are `c(0, 15)`. For `edist = "gamma"` these are shape and rate parameters, and the defaults are `c(1, 1)`.
`ngens`	integer. Number of posterior samples to obtain (per chain).
`ncores`	integer. Number of cores to use for parallel processing.

Details

The Dirichlet distribution is used to represent the fractional contribution of each source. The prior estimate is a Dirchlet where the shape parameter for source i is given by prior[i] / min(prior) * shp.

If ncores = 1, three chains will be run on a single core. If ncores > 1, ncores chains will be run in parallel on ncores cores.

Value

Returns an object of class “mixSource”, a list containing:

summary

matrix. Summary table of JAGS MCMC results, including parameter posterior distributions and convergence statistics.

results

data.frame. Posterior samples of model parameters.

mixture_d2H: Hydrogen isotopic composition of unevaporated source mixture.
mixture_d18O: Oxygen isotopic composition of unevaporated source mixture.
sX_fraction: Fractional contribution of each source.
S: Evaporation line slope.
E: Evaporation index, equal to the difference between the sample and unevaporated source mixture oxygen isotope values.

Examples

#Prep sources
O = runif(3, -15, -2)
H = O * 8 + 10 + rnorm(3, 0, 6)
sources = iso(H, O, 1, 0.2, 0.17)

#Sample data
obs = iso(-60, -6, 0.5, 0.1, 0)

#Evaporation slope
slope = c(5, 0.3)

#Run and report...likely not converged!
ws = mixSource(obs, sources, slope, ngens = 1e3)
ws$summary

#A traceplot
plot(ws$results$mixture_d18O[1:1000], type = "l")
lines(ws$results$mixture_d18O[1001:2000], col = 2)
lines(ws$results$mixture_d18O[2001:3000], col = 3)
#Prep sources
O = runif(3, -15, -2)
H = O * 8 + 10 + rnorm(3, 0, 6)
sources = iso(H, O, 1, 0.2, 0.17)

#Sample data
obs = iso(-60, -6, 0.5, 0.1, 0)

#Evaporation slope
slope = c(5, 0.3)

#Run and report...likely not converged!
ws = mixSource(obs, sources, slope, ngens = 1e3)
ws$summary

#A traceplot
plot(ws$results$mixture_d18O[1:1000], type = "l")
lines(ws$results$mixture_d18O[1001:2000], col = 2)
lines(ws$results$mixture_d18O[2001:3000], col = 3)

Mwl Object

Description

Creates objects of type "mwl" containing statistics for a meteoric water line in H and O isotope space.

Usage

mwl(HO, plot = TRUE)
mwl(HO, plot = TRUE)

Arguments

`HO`	data.frame. Hydrogen (column 1) and oxygen (column 2) isotope values for 3 or more water samples.
`plot`	logical. Plot the data, MWL, and standard error of prediction?

Details

mwl will return an error if fewer than 3 sample values are provided and a warning if fewer than 10 samples are provided or if the correlation coefficient between H and O values is less than 0.7. Sample values should span a broad enough range of isotope values to strongly constrain the MWL.

Model II (reduced major axis) regression is used to accommodate errors on both isotope values.

Value

Returns an object of class “mwl”, a numeric vector containing meteoric water line statistics. See mwlSource.

Examples

O = runif(10, -15, -2)
H = O * 8 + 10 + rnorm(10, 0, 6)
MWL = mwl(data.frame(H, O))
str(MWL)
O = runif(10, -15, -2)
H = O * 8 + 10 + rnorm(10, 0, 6)
MWL = mwl(data.frame(H, O))
str(MWL)

Water Source Using Meteoric Water Line

Description

Given parameters describing a meteoric water line in H-O isotope space, generate a posterior sample of unevaporated source water values conditioned on one or more sample values.

Usage

mwlSource(obs, MWL = NULL, slope, stype = 1, edist = "unif", 
  eprior = NULL, ngens=1e4, ncores = 1)
mwlSource(obs, MWL = NULL, slope, stype = 1, edist = "unif", 
  eprior = NULL, ngens=1e4, ncores = 1)

Arguments

`obs`	`iso` object containing isotope values for one or more samples.
`MWL`	numeric. Vector of length 6 containing parameters describing a meteoric water line (see Details).
`slope`	numeric. Vector of length two specifying prior parameters for the evaporation line slope (mean, standard deviation).
`stype`	integer. Line statistic used to constrain the source prior: 1 = confidence interval, 2 = prediction interval (see Details).
`edist`	character. One of `"unif"` or `"gamma"`, specifying whether the evaporation prior is modeled using a uniform or gamma distribution.
`eprior`	numeric. Vector of length 2 giving prior parameter estimates for the oxygen isotope evaporation effect. For `edist = "unif"` these are maximum and minimum values and the default values are `c(0, 15)`. For `edist = "gamma"` these are shape and rate parameters, and the defaults are `c(1, 1)`.
`ngens`	integer. Number of posterior samples to obtain (per chain).
`ncores`	integer. Number of cores to use for parallel processing.

Details

The prior distribution of source values is constrained by MWL, which contains the parameters: slope, intercept, average d18O, sum of squares in d18O, root mean square error, and number of samples for an empirically-determined meteoric water line. This object can be created from a H and O isotope dataset using the function mwl. The default value (if MWL = NULL) reflects the Global Meteoric Water Line estimated from a global precipitation compilation in Bowen, et al. (2019). stype determines how the source uncertainty about the MWL is calculated; the default (1, confidence interval) is appropriate if the source is best represented as an integrated mixture of the samples defining the MWL, whereas option 2 (prediction interval) is appropriate if the source is best represented as a single sample.

If ncores = 1, three chains will be run on a single core. If ncores > 1, ncores chains will be run in parallel on ncores cores.

Value

Returns an object of class “mwlSource”, a list containing:

summary

matrix. Summary table of JAGS MCMC results, including parameter posterior distributions and convergence statistics.

results

data.frame. Posterior samples of model parameters.

source_d2H: Hydrogen isotopic composition of unevaporated source.
source_d18O: Oxygen isotopic composition of unevaporated source.
S: Evaporation line slope.
E: Evaporation index, equal to the difference between the sample and unevaporated source mixture oxygen isotope values.

References

Examples

#Prep MWL
O = runif(10, -15, -2)
H = O * 8 + 10 + rnorm(10, 0, 6)
MWL = mwl(data.frame(H, O), plot = FALSE)

#Sample data
obs = iso(-60, -6, 0.5, 0.1, 0)

#Evaporation slope
slope = c(5, 0.3)

#Run and report...likely not converged!
ws = mwlSource(obs, MWL, slope, ngens = 1e3)
ws$summary

#A traceplot 
plot(ws$results$source_d18O[1:1000], type = "l")
lines(ws$results$source_d18O[1001:2000], col = 2)
lines(ws$results$source_d18O[2001:3000], col = 3)
#Prep MWL
O = runif(10, -15, -2)
H = O * 8 + 10 + rnorm(10, 0, 6)
MWL = mwl(data.frame(H, O), plot = FALSE)

#Sample data
obs = iso(-60, -6, 0.5, 0.1, 0)

#Evaporation slope
slope = c(5, 0.3)

#Run and report...likely not converged!
ws = mwlSource(obs, MWL, slope, ngens = 1e3)
ws$summary

#A traceplot 
plot(ws$results$source_d18O[1:1000], type = "l")
lines(ws$results$source_d18O[1001:2000], col = 2)
lines(ws$results$source_d18O[2001:3000], col = 3)

Obtain data from wiDB using a query

Description

Obtain data from wiDB using a query

Usage

wiDB_data(minLat = NULL, maxLat = NULL, minLong = NULL, 
  maxLong = NULL, minElev = NULL, maxElev = NULL, minDate = NULL, 
  maxDate = NULL, countries = NULL, states = NULL, types = NULL, 
  projects = NULL, fields = NULL, tmpdir = tempdir(), clean = TRUE)
wiDB_data(minLat = NULL, maxLat = NULL, minLong = NULL, 
  maxLong = NULL, minElev = NULL, maxElev = NULL, minDate = NULL, 
  maxDate = NULL, countries = NULL, states = NULL, types = NULL, 
  projects = NULL, fields = NULL, tmpdir = tempdir(), clean = TRUE)

Arguments

`minLat`	numeric. Minimum latitude for query region, in decimal degrees. South negative.
`maxLat`	numeric. Maximum latitude for query region, in decimal degrees. South negative.
`minLong`	numeric. Minimum longitude for query region, in decimal degrees. West negative.
`maxLong`	numeric. Maximum longitude for query region, in decimal degrees. West negative.
`minElev`	numeric. Minimum elevation for query. Meters.
`maxElev`	numeric. Maximum elevation for query. Meters.
`minDate`	character. Minimum date for query. Format: "YYYY-MM-DD"
`maxDate`	character. Maximum date for query. Format: "YYYY-MM-DD"
`countries`	character. Vector of one or more two-letter country codes for query.
`states`	character. Vector of one or more two-letter state or province codes for query.
`types`	character. Vector of one or more sample types for query. See vocabulary in the wiDB template.
`projects`	character. Vector of one or more project codes for query.
`fields`	character. Vector of one or more data fields to return from database. If omitted, returns all default fields. See here for details.
`tmpdir`	character. Directory path to use for unpacking data object.
`clean`	logical. Remove working files after data object is unpacked?

Details

One or more arguments must be provided.

Value

named list. See here for details.

`data`	dataframe. Data records for isotope samples returned by query.
`projects`	dataframe. Provenance information associated with samples returned by query.

Note that some data are embargoed or have been shared under a license that prohibits redistribution. In dataframe data values of 9999 indicate that a measurement is available but can't be obtained directly from the wiDB. Project information in projects can be used to contact or visit the primary data source to learn about access to these data. Values of -9999 in data indicate no measurement.

Examples

#Download data for US precipitation in the 1990s
vals = wiDB_data(minDate = "1990-01-01", maxDate = "2000-01-01", 
  countries = "US", types = "Precipitation")

#Download data for US Rivers and streams, requesting a subset of data fields
vals = wiDB_data(minDate = "1980-01-01", maxDate = "2000-01-01", 
  countries = "US", types = "River_or_stream", 
  fields = "Site_Name,Latitude,Longitude,d2H")
#Download data for US precipitation in the 1990s
vals = wiDB_data(minDate = "1990-01-01", maxDate = "2000-01-01", 
  countries = "US", types = "Precipitation")

#Download data for US Rivers and streams, requesting a subset of data fields
vals = wiDB_data(minDate = "1980-01-01", maxDate = "2000-01-01", 
  countries = "US", types = "River_or_stream", 
  fields = "Site_Name,Latitude,Longitude,d2H")

Obtain information on wiDB sites using a query

Description

Obtain information on wiDB sites using a query

Usage

wiDB_sites(minLat = NULL, maxLat = NULL, minLong = NULL, maxLong = NULL,
  minElev = NULL, maxElev = NULL, minDate = NULL, maxDate = NULL, 
  countries = NULL, states = NULL, types = NULL, projects = NULL)
wiDB_sites(minLat = NULL, maxLat = NULL, minLong = NULL, maxLong = NULL,
  minElev = NULL, maxElev = NULL, minDate = NULL, maxDate = NULL, 
  countries = NULL, states = NULL, types = NULL, projects = NULL)

Arguments

`minLat`	numeric. Minimum latitude for query region, in decimal degrees. South negative.
`maxLat`	numeric. Maximum latitude for query region, in decimal degrees. South negative.
`minLong`	numeric. Minimum longitude for query region, in decimal degrees. West negative.
`maxLong`	numeric. Maximum longitude for query region, in decimal degrees. West negative.
`minElev`	numeric. Minimum elevation for query. Meters.
`maxElev`	numeric. Maximum elevation for query. Meters.
`minDate`	character. Minimum date for query. Format: "YYYY-MM-DD"
`maxDate`	character. Maximum date for query. Format: "YYYY-MM-DD"
`countries`	character. Vector of one or more two-letter country codes for query.
`states`	character. Vector of one or more two-letter state or province codes for query.
`types`	character. Vector of one or more sample types for query. See vocabulary in the wiDB template.
`projects`	character. Vector of one or more project codes for query.

Details

One or more arguments must be provided.

Value

dataframe. Contains location and summary information for all wiDB sites returned by query. See here for details.

Examples

#Find all sites with tap water data since September, 2019
sites = wiDB_sites(minDate = "2019-09-01", types = "Tap")
#Find all sites with tap water data since September, 2019
sites = wiDB_sites(minDate = "2019-09-01", types = "Tap")

Obtain value lists for categorical fields in wiDB

Description

Obtain value lists for categorical fields in wiDB

Usage

wiDB_values(fields)
wiDB_values(fields)

Arguments

fields

character. One or more field names for which to obtain value lists. Limited to: "countries", "states", "types", and "projects".

Value

named list. Each element is a vector or dataframe containing values for the named field.

Examples

#List all projects in the wiDB
wiDB_values("projects")
#List all projects in the wiDB
wiDB_values("projects")

Package 'isoWater'

Help Index

Deuterium excess

Description

Usage

Arguments

Value

References

Examples

Global Meteoric Water Line

Description

Usage

Format

Source

Examples

Iso Object

Description

Usage

Arguments

Details

Value

Examples

Discovery, Retrieval, and Analysis of Water Isotope Data

Description

Author(s)

Water Source as a Mixture

Description

Usage

Arguments

Details

Value

Examples

Mwl Object

Description

Usage

Arguments

Details

Value

Examples

Water Source Using Meteoric Water Line

Description

Usage

Arguments

Details

Value

References

Examples

Obtain data from wiDB using a query

Description

Usage

Arguments

Details

Value

Examples

Obtain information on wiDB sites using a query

Description

Usage

Arguments

Details

Value

Examples

Obtain value lists for categorical fields in wiDB

Description

Usage

Arguments

Value

Examples