Package 'elfgen'

Identify breakpoint location with PWIT

Description

This applies the Piecewise Iterative elfgen method. This approach uses an iterative algorithm to identify shifts in the relation between maximum richness and stream size. A user specifies a "quantile" for isolating an upper subset of the data. A user also identifies a bounding range between two x-values ("blo" = "bound low", "bhi" = "bound high") in which the upper subest of data is believed to contain a breakpoint. (Note: Small datasets may not contain a breakpoint)

Usage

bkpt_pwit(watershed.df, quantile, blo, bhi)

Arguments

watershed.df	A dataframe of sites with ecological and hydrologic data
quantile	Specified value for the quantile of interest - 0.95 refers to the 95th percentile
blo	A "bound low" value, or the lower bound of the piecewise range
bhi	A "bound high" value, or the upper bound of the piecewise range

Details

See: Lemoine, N. 2012. "R for Ecologists: Putting Together a Piecewise Regression." https://www.r-bloggers.com/r-for-ecologists-putting-together-a-piecewise-regression/ The R Book, Second Edition. Michael J. Crawley. 2013 John Wiley & Sons, Ltd. Published 2013 by John Wiley & Sons, Ltd.

Value

Breakpoint value is returned

Examples

#elfdata(watershed.code = '0208020104', ichthy.localpath = tempdir(), use_cache = FALSE)
bkpt_pwit(watershed.df,0.85,100,300)

---

Identify breakpoint location with Ymax

Description

This applies the Ymax elfgen method. This approach treats the maximum observed species richness value as the breakpoint. This function begins by locating the point with the highest y-value in the full dataset, then utilizing the associated x-value as the breakpoint.

Usage

bkpt_ymax(watershed.df)

Arguments

watershed.df

A dataframe of sites with ecological and hydrologic data

Value

Breakpoint value is returned

Examples

#elfdata(watershed.code = '0208020104', ichthy.localpath = tempdir(), use_cache = FALSE)
bkpt_ymax(watershed.df)

---

Clean dataset of ecological and hydrologic data

Description

Given a dataframe of flow metric and richness metric data (Typically retrieved from the DEQ VAHydro database), removes all sites where the ratio of Drainage Area:Mean Annual Flow is greater than 1000, also aggregates to the maximum richness value at each x-metric value

Usage

clean_vahydro(watershed.df)

Arguments

watershed.df

A dataframe of sites with ecological and hydrologic data

Value

A cleaned dataframe of sites with ecological and hydrologic data

Examples

# Retrieve dataset of interest
watershed.df <- data.frame(
    MAF = c(100, 200, 300, 400, 526, 600, 700, 800, 400, 900, 1000, 100, 100),
    NT.TOTAL.UNIQUE = c(10, 20, 30, 40, 50, 40, 30 , 20, 50, 10, 10,99999,87),
    watershed.code = "test_testcode",
    hydrocode = c("t1","t2","t3","t4","t5","t6","t7","t8","t9","t10","t11","t12","t13"),
    DA_SQMI = c(110, 220000, 280, 360, 530, 604, 712, 698, 40000, 905, 1087, 98, 87),
    x.metric = c(100, 200, 300, 400, 526, 600, 700, 800, 400, 900, 1000, 100, 100)
    )
# Clean the dataset
clean_vahydro(watershed.df)

---

Plot percent richness change for various percent flow reductions

Description

Calculates and plots percent richness change resulting from streamflow reductions

Usage

elfchange(stats, yaxis_thresh, xlabel = FALSE, ylabel = FALSE)

Arguments

stats	A dataframe of ELF statistics
yaxis_thresh	Value used for specifying y-axis max limit
xlabel	Used to overwrite default x-axis label
ylabel	Used to overwrite default y-axis label

Value

Plot of percent decreases in richness from flow reductions

Examples

#elfdata(watershed.code = '0208020104', ichthy.localpath = tempdir(), use_cache = FALSE)
breakpt <- 500
elf <- elfgen(
   "watershed.df" = watershed.df,
   "quantile" = 0.95,
   "breakpt" = breakpt,
   "xlabel" = "Mean Annual Flow (ft3/s)",
   "ylabel" = "Fish Species Richness"
   )
elfchange(elf$stats, "yaxis_thresh" = 25)

---

Retrieve and format data for ELF generation

Description

Given a HUC code, provides a dataframe of all contained nhdplus segments and their individual NT Total and Mean Annual Flow MAF values

Usage

elfdata(
  watershed.code,
  ichthy.localpath,
  use_cache = TRUE,
  update_cache = FALSE
)

Arguments

watershed.code	Hydrologic unit code, either HUC6, HUC8, HUC10, or HUC12 (e.g. HUC10 code '0208020101').
ichthy.localpath	Local file path for storing downloaded ichthy data. Defaults to a temp directory.
use_cache	Should the function look for a file with the same name in the file directory? This allows users to use the same Icthy dataset each time rather than needing to download separately when running multiple analyses
update_cache	Should the file be written out to use for future caching?

Value

A dataframe of nhdplus segments containing species richness data (NT Total values) and mean annual flow (MAF) data.

Examples

# We don't run this example by R CMD check, because it takes >10s

# Retrieve dataset of interest
# You may enter either a 6, 8, 10, or 12-digit HUC code.
# By default the ichthy dataset is downloaded to a temp directory, however this may be overridden by
# supplying a local path of interest using the input parameter 'ichthy.localpath'
watershed_df <- tryCatch({elfdata(watershed.code = '0208020104',
 ichthy.localpath = tempdir(), use_cache = FALSE)}, warning = function(w){print(w)},
 error = function(e){"internet resource error"})

---

Retrieve data from DEQ VAHydro database and format data for ELF generation. Contact Virginia DEQ Office of Water Supply to request access to the VAHydro database.

Description

Given a set of VAHydro input parameters, outputs a dataframe of flow metric and richness metric data for hydrologic unit supplied

Usage

elfdata_vahydro(
  watershed.code,
  watershed.bundle,
  watershed.ftype,
  x.metric,
  y.metric,
  y.sampres,
  datasite,
  EDAS.localpath = tempdir()
)

Arguments

watershed.code	Hydrologic unit code, either HUC6, HUC8, HUC10, or HUC12 (e.g. HUC10 code '0208020101').
watershed.bundle	dH bundle of hydrologic unit
watershed.ftype	dH ftype of hydrologic unit
x.metric	x-metric, i.e. streamflow or drainage area
y.metric	y-metric, most commonly species richness
y.sampres	Sample resolution of y.metric (e.g. 'species')
datasite	VAHydro database URL
EDAS.localpath	Local file path for storing downloaded EDAS data. Defaults to a temp directory.

Value

A dataframe of sites containing species richness data (NT Total values) and mean annual flow (MAF) data.

Examples

# Retrieve dataset of interest
watershed.df <- elfdata_vahydro(
   'nhd_huc8_02080201',
   'watershed',
   'nhd_huc8',
   'nhdp_drainage_sqmi',
   'aqbio_nt_total',
   'species'
   )
elfdata_vahydro(watershed.df)

---

Generate Ecological Limit Function (ELF)

Description

Generate ELF models by supplying a dataframe of richness and stream size data (streamflow or drainage area), a quantile for evaluating the ecological limit, and a breakpoint threshold.

Usage

elfgen(
  watershed.df,
  quantile,
  breakpt,
  yaxis_thresh,
  xlabel = FALSE,
  ylabel = FALSE,
  plot_title = FALSE,
  break_var = "x_var"
)

Arguments

watershed.df	A dataframe of sites with ecological and hydrologic data
quantile	A specified value for the quantile of interest - 0.95 equals the 95th percentile
breakpt	A breakpoint - either user-supplied fixed value or derived using elfgen breakpoint functions bkpt_pwit() or bkpt_ymax
yaxis_thresh	Value used for specifying y-axis max limit
xlabel	Used to overwrite default x-axis label
ylabel	Used to overwrite default y-axis label
plot_title	A plot title used to title the ggplot. If left as the default (FALSE), the plot will be titled using the name of the HUC from nhdPlus
break_var	The name of the variable in watershed.df to be filtered for by the breakpt, defaults to the expected name "x_var"

Value

Object containing plot image and dataframe of ELF statistics

Examples

#elfdata(watershed.code = '0208020104', ichthy.localpath = tempdir(), use_cache = FALSE)
breakpt <- 500
elfgen(
   "watershed.df" = watershed.df,
   "quantile" = 0.80,
   "breakpt" = breakpt,
   "xlabel" = "Mean Annual Flow (ft3/s)",
   "ylabel" = "Fish Species Richness"
   )

---

Calculate change in richness resulting from a percent reduction in flow

Description

Calculates absolute or percent richness change from streamflow reduction

Usage

richness_change(stats, pctchg, xval = FALSE)

Arguments

stats	A dataframe of ELF statistics
pctchg	Decrease in flow as a percent (e.g. 10 equals 10 percent reduction in flow).
xval	x-axis value for assessing percent change in richness. When supplied, the function will calculate percent change in richness at a specific stream size (e.g. 50 equals a stream size with mean annual flow of 50 cfs).

Value

Richness change value is returned

Examples

#elfdata(watershed.code = '0208020104', ichthy.localpath = tempdir(), use_cache = FALSE)
breakpt <- 500
elf <- elfgen(
   "watershed.df" = watershed.df,
   "quantile" = 0.95,
   "breakpt" = breakpt,
   "xlabel" = "Mean Annual Flow (ft3/s)",
   "ylabel" = "Fish Species Richness"
   )
# Calculate absolute richness change
richness_change(elf$stats, "pctchg" = 10)
# Calculate percent richness change at a specific stream size
richness_change(elf$stats, "pctchg" = 10, "xval" = 50)

---

elfdata for NHD Watershed HUC 0208020104

Description

An example watershed data frame derived from elfdata() using the HUC '0208020104'

Usage

watershed.df

Format

## 'watershed.df' A data frame with 81 rows and 15 columns:

MAF

Mean annual flow, as estimated from NHD estimation via nhdPlusTools

Q01,Q02, Q03, Q04, Q05, Q06, Q07, Q08, Q09, Q10, Q11, Q12

Monthly estimated mean flow derived from NHD estimation via nhdPlusTools

NT.TOTAL.UNIQUE

Total number of unique taxa

watershed.code

Watershed NHD Code

Source

elfdata(watershed.code = '0208020104', ichthy.localpath = tempdir(), use_cache = FALSE)

---