EPGMr

R implementation of the Everglades Phosphorus Gradient Model

https://github.com/swampthingpaul/epgmr

Repository

R implementation of the Everglades Phosphorus Gradient Model

README.Rmd

---
title: "EPGMr"
output: github_document
editor_options: 
  chunk_output_type: console
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  echo = TRUE,
  fig.path="man/figures/README-"
  )
#devtools::install_github("GuangchuangYu/badger")
library(EPGMr)
library(rmarkdown)
options(continue=" ")
options(width=60)
library(knitr)
```

[![DOI](https://zenodo.org/badge/234599925.svg)](https://zenodo.org/badge/latestdoi/234599925) [![CRAN](https://www.r-pkg.org/badges/version/EPGMr)](https://cran.r-project.org/web/packages/EPGMr/) `r badger::badge_cran_download("EPGMr", "grand-total", "blue")`

__Contact Info:__  [Webpage](http://swampthingecology.org) - [Twitter](https://twitter.com/SwampThingPaul) - [Email](mailto:pauljulianphd@gmail.com)

***

## Table of Contents

* [Task List](#tasks)
* [Background](#background)
* [Introduction](#intro)
* [Citing package](#cite)
* [Installation](#install)
* [Functions](#func)
  * [_Distance Profile_](#profile)
  * [_Time Profile_](#time)
  * [_Threshold Evaluation_](#threshold)
  * [_User input example_](#user)
* [Potential errors](#errors)
  


***

## Task List 

- [x] Distance profile function, `EPGMProfile()` with plots.
- [x] Add summary reults table to distance profile function, `EPGMProfile()`.
- [x] Develop time-series function, `EPGMTime()`.
  - [x] Develope time-series results summary function.
- [x] Develop threshold evaluation function.
- [x] Figure out how to code greek (i.e. mu) and superscript for `.Rd` files.
- [x] ~~[rOpenSci](https://ropensci.org/) presubmission inquiry. [Link](https://github.com/ropensci/software-review/issues/365)~~
- [ ] ~~Submit to [rOpenSci](https://ropensci.org/) for community peer-review.~~
- [x] Submit to [CRAN](https://cran.r-project.org/submit.html), [EPGMr](https://cran.r-project.org/web/packages/EPGMr/).

### Version 2.0 planning
- [ ] optimize functionality
- [ ] expand functionality to include soil depth profile model. 

***

## Background 

This package is an R-version of the original Everglades Phosphorus Gradient Model developed by Walker and Kadlec and implements the model described in:

* Walker WW, Kadlec, R.H. (1996) A Model for Simulating Phosphorus Concentrations in Waters and Soils Downstream of Everglades Stormwater Treatment Areas. U.S. Department of the Interior. Links to: [Report](http://www.wwwalker.net/epgm/epgm_Aug_1996_1_of_2.pdf); [Appendix](http://www.wwwalker.net/epgm/epgm_Aug_1996_2_of_2.pdf).
 
The model is further discussed in:

* Kadlec RH, Walker WW (1999) Management models to evaluate phosphorus impacts on wetlands. In: Reddy KR, O’Conner GA, Schelske CL (eds) Phosphorus Biogeochemistry in Subtropical Ecosystems. Lewis Publishers, Boca Raton, FL, pp 621–639.

* Walker WW, Kadlec RH (2011) Modeling Phosphorus Dynamics in Everglades Wetlands and Stormwater Treatment Areas. Critical Reviews in Environmental Science and Technology 41:430–446. 


## Introduction 

Everglades Phosphorus Gradient Model (EPGM; Fig. 1) predicts variations in water-column phosphorus (P) concentration, peat accretion rate, and soil P concentration along a horizontal gradient imposed by an external P load and sheet-flow conditions. Cattail densities and total areas are predicted based upon correlations with soil P and are surrogates for impacts on ecosystem components which respond to soil P variations in similar concentration ranges. The model is calibrated to soil and vegetation data from Water Conservation Area - 2 (WCA-2; primarily), WCA-1, and WCA-3A. The model successfully simulates observed [longitudinal gradients in soil P concentration below the S10 structures in WCA-2A](http://www.wwwalker.net/epgm/wca2a_gradient.htm) after ~28 years of external P loading (1962 to 1990). Observed expansion of cattail populations in this region between 1973 and 1991 is also simulated, though somewhat over-predicted during the first 20 years. Model results suggest a linear relationship between marsh water-column and soil P concentrations over long time scales. Estimated soil response times range from 20 to 40 years, depending on soil depth, and are inversely related to water-column concentration.

```{r figs, out.width="90%",echo=FALSE,fig.align="center"}
knitr::include_graphics("http://www.wwwalker.net/epgm/epgmpic.gif")
```

**Figure 1:** Generalized model structure of the Everglades Phosphorus Gradient Model as originally developed by Walker and Kadlec. The model embodies water and phosphorus mass conservation specific to wetland ecosystems designed for phosphorus management.


## Citing package 
A lot of time and effort went into the development of the original [EPGM](http://wwwalker.net/epgm/index.htm) and it is important to give the authors proper credit. This is the ultimate foundation of this `R` package.

* Walker WW, Kadlec, R.H. (1996) A Model for Simulating Phosphorus Concentrations in Waters and Soils Downstream of Everglades Stormwater Treatment Areas. U.S. Department of the Interior

It also took time in developement of the `EPGMr`, translating the spreadsheet model into the `R` environment. To see a current citation for `EPGMr`, use the following command in `R`:
```{r}
citation('EPGMr')
```


## Installation 

```{r,eval=F}
install.packages("devtools");# if you do not have it installed on your PC
devtools::install_github("SwampThingPaul/EPGMr")
```

## Functions 

For the examples below we are going to use an internal dataset within this package. This is also the data provided in the orginal [EPGM](http://www.wwwalker.net/epgm/) as case study examples. To see these data use the `data()` function. This internal package data is a table of variables from data provided in the original EPGM model. This data (and the original) has 12 examples (cases) of phosphorus inputs, hydrologic information (inflow volume, rainfall, evapotranspiration and hydroperiod), soil depth of interest, soil characteristics, and soil gradient values. Examples include dicharges from Stormwater Treatment Area (STA) 2, 3/4, 5, 6 and the S10 structures. 

```{r}
data("casedat")
```

Case number 11 is data from the S10 structures that discharge into northeast Water Conservation area 2A, the historic eutrophication gradient within the Everglades ecosystem.

```{r}
#I transposed the data for easy viewing. 
t(casedat[casedat$case.number==11,])
```


`EPGMr` is broken into three functions. 

* `EPGMProfile` simulates the phopshorus gradient (distance downstream) during a specified simulation period (default: 30 years). The function as defaulted also provides a summary results output and plot of water column total P, soil P and cattail density along the gradient. Graphical output includes steady state simulation and time at the simulation period (default: 30 years). 

* `EPGMTime` uses `EPGMProfile` to simulate yearly P dynamics along the gradient for a specified period (default: 200 years) thereby simulating changes in P along the gradient over time. Similar to `EPGMProfile` as defaulted a summary table is provided based on distance intervals specified in the `Dist.slice` argument in the function (default is `c(0,0.5,1,2,5,10)`). Also as a default a series of time plots are generated for soil P and cattail density. 

* `EPGMThreshold` evaluates raw outputs from `EPGMTime` relative to thresholds for water column, soil and cattail density. As a default it provides a summary table and plot. 


_Distance Profile_

This will run the example case number 11, plot the distance profile depicited below and provide a summary results table. If `raw.output` was set to `TRUE`, the raw data behind the plots and summary tables would be printed in the console. If `results.table` was set to `TRUE` then a summary results table will be printed (default). The results output table under `$DistanceProfile` provides a summary of the simulation period at several user input distances, however the default argument in the function is `summary.distance=c(0,0.5,1,2,4,8,10)`. Other information in the summary result tab include, simulation inputs, water budget, phosphorus mass balance and information on regarding soils for the simulation period (default is 30 years). 

```{r DistanceProfilePlot, echo=TRUE, fig.width=8,fig.height=5,fig.align='center'}
EPGMProfile(case.no=11,plot.profile=TRUE,summary.distance=c(0,1,2,4,10))
```

_Time Profile_

This function will run the EPGM model over a determined period of time (with specificied time increment). If `raw.time.output` is set to `TRUE`, the raw data behind the plots and summary tables will be printed in the console and/or saved as an object. This will results in a `data.frame` with data specific to space (i.e. distance) and time (i.e. year).

```{r TimeProfilePlot, echo=TRUE, fig.width=8,fig.height=5,align='center'}
EPGMTime(case.no=11)
```

_Threshold Evaluation_

This function will calculate, summarise and plot area exceedance for results from `EPGMTime()`. Currently the function is configured to evaluate three threshold for water column, soil and cattail density within the modelled flow-path. Much like the other functions, If `raw.area.output` is set to `TRUE`, then the raw results summarized in the summary table and plots will be provided as a `data.frame`. 

```{r ThresholdPlot, echo=TRUE, fig.width=7,fig.height=5.25,align='center'}
example<-EPGMTime(case.no=11,raw.time.output=TRUE,plot.profile=FALSE)

EPGMThreshold(example)
```

_User input example_

Below is an example of the `EPGMProfile` function with user input data rather than case specific data. 

```{r DistanceProfilePlot_user, echo=TRUE, fig.width=8,fig.height=5,fig.align='center'}
#User defined inputs
Discharge.Yr <- 1962
Out.TPconc <- 122
out.Q <- 281.3
FP.width <- 10.5
HP.per <- 91.4
Soil.z <- 10
Soil.BDi <- 0.102
Soil.TPi <- 198
TPGradient.i <- -0.0018
Soil.BDf <- 0.08
k <- 10.2
P.dep <- 42.9
RF <- 1.23
ET <- 1.38

EPGMProfile(
  Start.Discharge = Discharge.Yr,
  STA.outflow.TPconc = Out.TPconc, 
  STA.outflow.vol = out.Q, 
  FlowPath.width = FP.width,
  Hydroperiod = HP.per, 
  Soil.Depth = Soil.z, 
  Soil.BulkDensity.initial = Soil.BDi,
  Soil.TPConc.initial = Soil.TPi, 
  Vertical.SoilTPGradient.initial = TPGradient.i,
  Soil.BulkDensity.final = Soil.BDf, 
  PSettlingRate = k, 
  P.AtmoDep = P.dep,
  Rainfall = RF, ET = ET,
  summary.distance=c(0,1,5,10))

```


## Potential errors 

1. If internal data is being used to run the model and the user selects a case number not in the list. 

```{r, error=TRUE}
EPGMProfile(case.no=14)
```

2. If `raw.output=TRUE` and `results.table=TRUE` at its current stands the function will default to the results table and plot with a warning.  

```{r ProfilePlot_witherror, error=TRUE,fig.width=8,fig.height=5,fig.align='center'}
EPGMProfile(
  case.no=11,
  summary.distance=c(0,1,5,10),
  raw.output=TRUE,
  results.table=TRUE)
```

3. If the `Dist.increment.km` is greater than the `Max.Dist` arguments, the function will stop and provide a warning. 

```{r, error=TRUE}
EPGMProfile(
  case.no=11,
  Dist.increment.km=16,
  Max.Dist=15)
```

4. `summary.distance` values must be positve, so can't back look behind the discharge with this model.

```{r, error=TRUE}
EPGMProfile(
  case.no=11,
  summary.distance=-1)
```

Owner

GitHub Events

Committers

Last synced: over 3 years ago

Packages