plot_metab function added, some tweaks to ecometab to reduce output a…

…nd clearer docs

NAMESPACE

@@ -1,13 +1,15 @@
 # Generated by roxygen2 (4.1.0): do not edit by hand
 
+S3method(aggregate_metab,swmpr)
 S3method(comb,swmpr)
 S3method(ecometab,swmpr)
-S3method(plot_met,swmpr)
+S3method(plot_metab,swmpr)
 S3method(setstep,swmpr)
 export(aggregate.swmpr)
+export(aggregate_metab)
 export(all_params)
 export(all_params_dtrng)
-export(calcKL)
+export(calckl)
 export(comb)
 export(decomp)
 export(decomp.swmpr)
@@ -18,12 +20,12 @@ export(hist.swmpr)
 export(import_local)
 export(lines.swmpr)
 export(map_reserve)
-export(met_day)
+export(metab_day)
 export(na.approx.swmpr)
 export(param_names)
 export(parser)
 export(plot.swmpr)
-export(plot_met)
+export(plot_metab)
 export(plot_summary)
 export(plot_summary.swmpr)
 export(qaqc)

R/swmpr_misc.R

@@ -11,7 +11,7 @@
 #' @return Returns a swmpr object to be used with S3 methods
 #' 
 #' @details 
-#' This function is a simple wrapper to \code{\link[base]{structure}} that is used internally within other functions to create a swmpr object.  The function does not have to be used explicitly.  Attributes of a swmpr object include \code{names}, \code{row.names}, \code{class}, \code{station}, \code{parameters}, \code{qaqc_cols}, \code{date_rng}, \code{timezone}, \code{stamp_class}, \code{metabolism} (if present), and \code{met_units} (if present). 
+#' This function is a simple wrapper to \code{\link[base]{structure}} that is used internally within other functions to create a swmpr object.  The function does not have to be used explicitly.  Attributes of a swmpr object include \code{names}, \code{row.names}, \code{class}, \code{station}, \code{parameters}, \code{qaqc_cols}, \code{date_rng}, \code{timezone}, \code{stamp_class}, \code{metabolism} (if present), and \code{metab_units} (if present). 
 #' 
 swmpr <- function(stat_in, meta_in){
 
@@ -45,7 +45,7 @@ swmpr <- function(stat_in, meta_in){
     timezone = timezone, 
     stamp_class = class(stat_in$datetimestamp),
     metabolism = NULL, 
-    met_units = NULL
+    metab_units = NULL
     )
 
 }
@@ -490,7 +490,7 @@ map_reserve <- function(nerr_site_id, zoom = 11, text_sz = 6, text_col = 'black'
 #' @seealso 
 #' \code{\link{ecometab}}
 #' 
-met_day <- function(dat_in, stat_in){
+metab_day <- function(dat_in, stat_in){
 
   stat_meta <- stat_locs[grep(gsub('wq$', '', stat_in), stat_locs$station_code),]
 
@@ -531,14 +531,14 @@ met_day <- function(dat_in, stat_in){
   ss_dat <- ss_dat[!duplicated(strftime(ss_dat[, 1], format = '%Y-%m_%d')), ]
   ss_dat <- data.frame(
     ss_dat,
-    met_date = as.Date(ss_dat$sunrise, tz = tz)
+    metab_date = as.Date(ss_dat$sunrise, tz = tz)
     )
-  ss_dat <- melt(ss_dat, id.vars = 'met_date')
+  ss_dat <- melt(ss_dat, id.vars = 'metab_date')
   if(!"POSIXct" %in% class(ss_dat$value))
     ss_dat$value <- as.POSIXct(ss_dat$value, origin='1970-01-01',tz=tz)
   ss_dat <- ss_dat[order(ss_dat$value),]
   ss_dat$day_hrs <- unlist(lapply(
-    split(ss_dat, ss_dat$met_date),
+    split(ss_dat, ss_dat$metab_date),
     function(x) rep(as.numeric(x[2, 'value'] - x[1, 'value']), 2) 
     ))
   names(ss_dat)[names(ss_dat) %in% c('variable', 'value')] <- c('solar_period', 'solar_time')
@@ -577,7 +577,7 @@ met_day <- function(dat_in, stat_in){
 #' @seealso 
 #' \code{\link{ecometab}}
 #' 
-calcKL <- function(temp, sal, atemp, wspd, bp, height = 10){
+calckl <- function(temp, sal, atemp, wspd, bp, height = 10){
 
   #celsius to kelvin conversion
   CtoK <- function(val) val + 273.15 

README.Rmd

@@ -353,14 +353,14 @@ dat <- qaqc(apacpnut)
 plot_summary(dat, param = 'chla_n')
 ```
 
-Estimates of ecosystem metabolism provide a useful measure of overall system productivity.  These estimates are commonly used to evaluate whether an ecosystem is a net source or sink of organic material.  The open-water method is a common approach to quantify net ecosystem metabolism using a mass balance equation that describes the change in dissolved oxygen over time from the balance between photosynthetic and respiration rates, corrected for air-sea gas diffusion at the surface.  The diffusion-corrected DO flux estimates are averaged during day and night for each 24 hour period in the time series, where flux is an hourly rate of DO change. DO flux is averaged during night hours for respiration and averaged during day hours for net production. Respiration rates are assumed constant during day and night such that total daily rates are calculated as hourly respiration multiplied by 24. The metabolic day is considered the approximate 24 hour period between sunsets on two adjacent calendar days.  Respiration is subtracted from daily net production estimates to yield gross production.  
+Estimates of ecosystem metabolism provide a useful measure of overall system productivity.  These estimates are commonly used to evaluate whether an ecosystem is a net source or sink of organic material.  The open-water method is a common approach to quantify net ecosystem metabolism using a mass balance equation that describes the change in dissolved oxygen over time from the balance between photosynthetic and respiration rates, corrected for air-sea gas diffusion at the surface.  The diffusion-corrected DO flux estimates are averaged during day and night for each 24 hour period in the time series, where flux is an hourly rate of DO change. DO flux is averaged during night hours for respiration and averaged during day hours for net production. Respiration rates are assumed constant during day and night such that total daily rates are calculated as hourly respiration multiplied by 24. The metabolic day is considered the 24 hour period between sunsets on two adjacent calendar days.  Respiration is subtracted from daily net production estimates to yield gross production.  
 
 The `ecometab` function is used to implement an adaptation of the open-water method.  
 Several assumptions must be met for a valid interpretation of the results.  In general, the dissolved oxygen time series is assumed to represent the same water mass over time.  Tidal advection may have a significant influence on the time series, which can contribute to a significant amount of noise in metabolic estimates.  The extent to which tidal advection influences the dissolved oxygen signal depends on various site-level characteristics and an intimate knowledge of the site may be required.  Volumetric rates for gross production and total respiration are also based on total depth of the water column, which is assumed to be mixed.  Water column depth is based on mean value for the depth variable across the time series and is floored at 1 meter for very shallow stations.  Additionally, the volumetric reaeration coefficient requires an estimate of the anemometer height of the weather station, which is set as 10 meters by default.  The metadata should be consulted for exact height. Other assumptions may apply and the user should consult the relevant literature (see the references in the help file).  All estimates are in mmol of oxygen but can be converted  to grams by changing the default arguments (i.e., 1mmol O2 = 32 mg O2, 1000 mg = 1g, multiply all estimates by 32/1000). 
 
-The following is an example that shows how to use the function from a combined water quality and weather data set.
+The following is an example that shows how to use the function from a combined water quality and weather data set.  The results can be plotted using `plot_metab`.
 
-```{r eval = FALSE}
+```{r eval = TRUE, cache = TRUE, fig.height = 4, fig.width = 8, warning = FALSE}
 ## import water quality and weather data
 data(apadbwq)
 data(apaebmet)
@@ -371,7 +371,8 @@ met <- qaqc(apaebmet)
 dat <- comb(wq, met)
 
 ## estimate metabolism
-res <- ecometab(dat, trace = TRUE)
+res <- ecometab(dat, trace = FALSE)
+plot_metab(res)
 ```
 
 #Function list
@@ -406,6 +407,8 @@ See help documentation for more details on each function (e.g., `?all_params`).
 
 `aggregate.swmpr` Aggregate swmpr objects for different time periods - years, quarters, months,  weeks, days, or hours.  Aggregation function is user-supplied but defaults to mean. 
 
+`aggregate_metab` Aggregate metabolism data from a swmpr object.  This is primarly used within `plot_metab` but may be useful for simple summaries of raw daily data.
+
 `ecometab.swmpr` Estimate ecosystem metabolism for a combined water quality and weatehr dataset using the open-water method.
 
 `decomp.swmpr` Decompose a swmpr time series into trend, seasonal, and residual components.  This is a simple wrapper to `decompose`.  Decomposition of monthly or daily trends is possible.
@@ -420,6 +423,8 @@ See help documentation for more details on each function (e.g., `?all_params`).
 
 `plot.swmpr` Plot a univariate  time series for a swmpr object.  The parameter name must be specified.
 
+`plot_metab` Plot ecosystem metabolism estimates after running `ecometab` on a swmpr object.  
+
 `plot_summary` Create summary plots of seasonal/annual trends and anomalies for a water quality or weather parameter.
 
 `smoother.swmpr` Smooth swmpr objects with a moving window average.  Window size and sides can be specified, passed to `filter`.
@@ -430,7 +435,7 @@ See help documentation for more details on each function (e.g., `?all_params`).
 
 `map_reserve` Create a map of all stations in a reserve using the ggmap package.
 
-`met_day` Identify the metabolic day for each approximate 24 period in an hourly time series.  This is only used within the `ecometab` function.
+`metab_day` Identify the metabolic day for each approximate 24 period in an hourly time series.  This is only used within the `ecometab` function.
 
 `param_names` Returns column names as a list for the parameter type(s) (nutrients, weather, or water quality).  Includes QAQC columns with 'f_' prefix. Used internally in other functions.
 

README.html

@@ -340,9 +340,9 @@ <h1>An overview of methods for swmpr objects</h1>
 ## plot
 plot_summary(dat, param = &#39;chla_n&#39;)</code></pre>
 <p><img src="README_files/figure-html/unnamed-chunk-21.png" alt="plot of chunk unnamed-chunk-21" /></p>
-<p>Estimates of ecosystem metabolism provide a useful measure of overall system productivity. Such estimates are commonly used to evaluate whether an ecosystem is a net source or sink of organic material. The open-water method is used to infer net ecosystem metabolism using a mass balance equation that describes the change in dissolved oxygen over time as a function of photosynthetic rate, minus respiration rate, corrected for air-sea gas diffusion at the surface. The diffusion-corrected DO flux estimates are averaged during day and night for each 24 hour period in the time series, where flux is an hourly rate of DO change. DO flux is averaged during night hours for respiration and averaged during day hours for net production. Respiration rates are assumed constant during day and night such that total daily rates are calculated as hourly respiration multiplied by 24. The metabolic day is considered the approximate 24 hour period between sunsets on two adjacent calendar days. Respiration is subtracted from daily net production estimates to yield gross production.</p>
+<p>Estimates of ecosystem metabolism provide a useful measure of overall system productivity. These estimates are commonly used to evaluate whether an ecosystem is a net source or sink of organic material. The open-water method is a common approach to quantify net ecosystem metabolism using a mass balance equation that describes the change in dissolved oxygen over time from the balance between photosynthetic and respiration rates, corrected for air-sea gas diffusion at the surface. The diffusion-corrected DO flux estimates are averaged during day and night for each 24 hour period in the time series, where flux is an hourly rate of DO change. DO flux is averaged during night hours for respiration and averaged during day hours for net production. Respiration rates are assumed constant during day and night such that total daily rates are calculated as hourly respiration multiplied by 24. The metabolic day is considered the 24 hour period between sunsets on two adjacent calendar days. Respiration is subtracted from daily net production estimates to yield gross production.</p>
 <p>The <code>ecometab</code> function is used to implement an adaptation of the open-water method.<br />Several assumptions must be met for a valid interpretation of the results. In general, the dissolved oxygen time series is assumed to represent the same water mass over time. Tidal advection may have a significant influence on the time series, which can contribute to a significant amount of noise in metabolic estimates. The extent to which tidal advection influences the dissolved oxygen signal depends on various site-level characteristics and an intimate knowledge of the site may be required. Volumetric rates for gross production and total respiration are also based on total depth of the water column, which is assumed to be mixed. Water column depth is based on mean value for the depth variable across the time series and is floored at 1 meter for very shallow stations. Additionally, the volumetric reaeration coefficient requires an estimate of the anemometer height of the weather station, which is set as 10 meters by default. The metadata should be consulted for exact height. Other assumptions may apply and the user should consult the relevant literature (see the references in the help file). All estimates are in mmol of oxygen but can be converted to grams by changing the default arguments (i.e., 1mmol O2 = 32 mg O2, 1000 mg = 1g, multiply all estimates by 32/1000).</p>
-<p>The following is an example that shows how to use wihte function from a combined water quality and weather data set.</p>
+<p>The following is an example that shows how to use the function from a combined water quality and weather data set. The results can be plotted using <code>plot_metab</code>.</p>
 <pre class="r"><code>## import water quality and weather data
 data(apadbwq)
 data(apaebmet)
@@ -353,7 +353,9 @@ <h1>An overview of methods for swmpr objects</h1>
 dat &lt;- comb(wq, met)
 
 ## estimate metabolism
-res &lt;- ecometab(dat, trace = TRUE)</code></pre>
+res &lt;- ecometab(dat, trace = FALSE)
+plot_metab(res)</code></pre>
+<p><img src="README_files/figure-html/unnamed-chunk-22.png" alt="plot of chunk unnamed-chunk-22" /></p>
 </div>
 <div id="function-list" class="section level1">
 <h1>Function list</h1>
@@ -377,21 +379,23 @@ <h2>Organize</h2>
 <div id="analyze" class="section level2">
 <h2>Analyze</h2>
 <p><code>aggregate.swmpr</code> Aggregate swmpr objects for different time periods - years, quarters, months, weeks, days, or hours. Aggregation function is user-supplied but defaults to mean.</p>
+<p><code>aggregate_metab</code> Aggregate metabolism data from a swmpr object. This is primarly used within <code>plot_metab</code> but may be useful for simple summaries of raw daily data.</p>
 <p><code>ecometab.swmpr</code> Estimate ecosystem metabolism for a combined water quality and weatehr dataset using the open-water method.</p>
 <p><code>decomp.swmpr</code> Decompose a swmpr time series into trend, seasonal, and residual components. This is a simple wrapper to <code>decompose</code>. Decomposition of monthly or daily trends is possible.</p>
 <p><code>decomp_cj.swmpr</code> Decompose a swmpr time series into grandmean, annual, seasonal, and events components. This is a simple wrapper to <code>decompTs</code> in the wq package. Only monthly decomposition is possible.</p>
 <p><code>hist.swmpr</code> Plot a histogram for a swmpr object.</p>
 <p><code>lines.swmpr</code> Add lines to an existing swmpr plot.</p>
 <p><code>na.approx.swmpr</code> Linearly interpolate missing data (<code>NA</code> values) in a swmpr object. The maximum gap size that is interpolated is defined as a maximum number of records with missing data.</p>
 <p><code>plot.swmpr</code> Plot a univariate time series for a swmpr object. The parameter name must be specified.</p>
+<p><code>plot_metab</code> Plot ecosystem metabolism estimates after running <code>ecometab</code> on a swmpr object.</p>
 <p><code>plot_summary</code> Create summary plots of seasonal/annual trends and anomalies for a water quality or weather parameter.</p>
 <p><code>smoother.swmpr</code> Smooth swmpr objects with a moving window average. Window size and sides can be specified, passed to <code>filter</code>.</p>
 </div>
 <div id="miscellaneous" class="section level2">
 <h2>Miscellaneous</h2>
 <p><code>calcKL</code> Estimate the reaeration coefficient for air-sea gas exchange. This is only used within the <code>ecometab</code> function.</p>
 <p><code>map_reserve</code> Create a map of all stations in a reserve using the ggmap package.</p>
-<p><code>met_day</code> Identify the metabolic day for each approximate 24 period in an hourly time series. This is only used within the <code>ecometab</code> function.</p>
+<p><code>metab_day</code> Identify the metabolic day for each approximate 24 period in an hourly time series. This is only used within the <code>ecometab</code> function.</p>
 <p><code>param_names</code> Returns column names as a list for the parameter type(s) (nutrients, weather, or water quality). Includes QAQC columns with ‘f_’ prefix. Used internally in other functions.</p>
 <p><code>parser</code> Parses html returned from CDMO web services, used internally in retrieval functions.</p>
 <p><code>site_codes</code> Metadata for all stations, wrapper to <code>exportStationCodesXMLNew</code> function on web services.</p>