diff --git a/.Rbuildignore b/.Rbuildignore index cfb32f7..20ec1ed 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -5,3 +5,5 @@ changelog.txt ^\.Rproj\.user$ README.md +^README\.Rmd$ +^README-.*\.png$ diff --git a/DESCRIPTION b/DESCRIPTION index d174c6f..8ccae42 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: rLakeAnalyzer Title: Lake Physics Tools Maintainer: Luke Winslow -Version: 1.10.0 +Version: 1.11.0 Author: Luke Winslow, Jordan Read, Richard Woolway, Jennifer Brentrup, Taylor Leach, Jake Zwart, Sam Albers, Doug Collinge Description: Standardized methods for calculating common important derived @@ -10,7 +10,11 @@ Description: Standardized methods for calculating common important derived number, Schmidt stability and others. Depends: R (>= 2.10) Imports: - plyr + plyr, + stats, + graphics, + utils, + grDevices Suggests: testthat, knitr, @@ -18,5 +22,7 @@ Suggests: License: GPL (>= 2) Packaged: 2014-07-06 09:09:24 UTC; Luke Repository: https://github.com/GLEON/rLakeAnalyzer +BugReports: https://github.com/GLEON/rLakeAnalyzer/issues Date/Publication: 2015-04-02 12:00:00 RoxygenNote: 6.0.1 +VignetteBuilder: knitr diff --git a/NAMESPACE b/NAMESPACE index 556dacd..4d0c297 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,21 +1,39 @@ -export(wedderburn.number, layer.density, lake.number, uStar, water.density, - thermo.depth, meta.depths, schmidt.stability, ts.meta.depths, - ts.thermo.depth, load.bathy, load.ts, get.offsets, ts.schmidt.stability, - ts.meta.depths, ts.thermo.depth, ts.lake.number, ts.uStar, ts.layer.temperature, - ts.wedderburn.number, ts.buoyancy.freq, buoyancy.freq, layer.temperature, - wtr.heat.map, wtr.lineseries, wtr.heatmap.layers, wtr.plot.temp, lake.number.plot, - schmidt.plot, center.buoyancy, ts.center.buoyancy, internal.energy, - ts.internal.energy, epi.temperature, hypo.temperature, whole.lake.temperature, - approx.bathy) +# Generated by roxygen2: do not edit by hand + +export(approx.bathy) +export(buoyancy.freq) +export(center.buoyancy) export(depth.filter) +export(epi.temperature) +export(get.offsets) +export(hypo.temperature) +export(internal.energy) +export(lake.number) +export(lake.number.plot) +export(layer.density) +export(layer.temperature) +export(load.bathy) +export(load.ts) +export(meta.depths) +export(schmidt.plot) +export(schmidt.stability) +export(thermo.depth) +export(ts.buoyancy.freq) +export(ts.center.buoyancy) +export(ts.internal.energy) +export(ts.lake.number) +export(ts.layer.temperature) +export(ts.meta.depths) +export(ts.schmidt.stability) +export(ts.thermo.depth) +export(ts.uStar) +export(ts.wedderburn.number) +export(uStar) +export(water.density) +export(wedderburn.number) +export(whole.lake.temperature) +export(wtr.heat.map) +export(wtr.heatmap.layers) export(wtr.layer) - -import("plyr") -importFrom("grDevices", "colorRampPalette") -importFrom("graphics", "abline", "axis", "filled.contour", "legend", - "lines", "plot", "segments", "title") -importFrom("stats", "approx") -importFrom("utils", "read.table") - - - +export(wtr.lineseries) +export(wtr.plot.temp) diff --git a/NEWS.md b/NEWS.md new file mode 100644 index 0000000..76e943d --- /dev/null +++ b/NEWS.md @@ -0,0 +1,14 @@ +# rLakeAnalyzer 1.11.0 +* Added a `NEWS.md` file to track changes to the package. +* revamp README with more detail +* convert all documentation to roxygen2 (#44) +* Add top level documentation file (#22) +* Add split and merge vignette + +# rLakeAnalyzer 1.10.0 + + +* Added split and merge algorithm to package which enable auto detection of clines (e.g thermoclines) + + + diff --git a/R/approx.bathy.R b/R/approx.bathy.R index 42f4114..876f6ac 100644 --- a/R/approx.bathy.R +++ b/R/approx.bathy.R @@ -1,4 +1,3 @@ - #' @title Estimate hypsography curve #' #' @description Estimates a depth-area curve for a lake using lake surface area, @@ -40,7 +39,7 @@ approx.bathy <- function(Zmax, lkeArea, Zmean = NULL, method = "cone", zinterval = 1, depths = seq(0, Zmax, by = zinterval)){ Area = c() if(method == "cone"){ - area <- approx(c(0, Zmax), c(lkeArea, 0), depths)$y + area <- stats::approx(c(0, Zmax), c(lkeArea, 0), depths)$y Area = data.frame(depths = depths, Area.at.z = area) } #end of "cone" diff --git a/R/buoyancy.freq.R b/R/buoyancy.freq.R index 7a79b9e..e9488cd 100644 --- a/R/buoyancy.freq.R +++ b/R/buoyancy.freq.R @@ -1,7 +1,34 @@ -# -# Buoyancy Frequency -# Author: Luke Winslow -# +#' @title Calculates buoyancy frequency. +#' +#' @description Calculate the buoyancy frequency (Brunt-Vaisala frequency) for a temperature +#' profile. +#' +#' +#' @param wtr a numeric vector of water temperature in degrees C +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @return Returns a vector of buoyancy frequency in units \code{sec^-2}. +#' Return value has attribute "depths" which define buoyancy frequency depths +#' (which differ from supplied depths). +#' @seealso \code{thermo.depth}, \code{ts.buoyancy.freq} +#' @keywords arith +#' @examples +#' +#' +#' # A vector of water temperatures +#' wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, +#' 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) +#' +#' #A vector defining the depths +#' depths = c(0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, +#' 17, 18, 19, 20) +#' +#' b.f = buoyancy.freq(wtr, depths) +#' +#' plot(b.f, attr(b.f, 'depths'), type='b', +#' ylab='Depth', xlab='Buoyancy Frequency', ylim=c(max(depths), min(depths))) +#' +#' @export buoyancy.freq <- function(wtr, depths){ rhoVar = water.density(wtr) @@ -22,6 +49,48 @@ buoyancy.freq <- function(wtr, depths){ } + + +#' @title Calculate the buoyancy (Brunt-Vaisala) frequency for a temperature profile. +#' +#' @description Function for simplifying the calculation of buoyancy frequency. Can usually +#' be called directly on data loaded directly using \code{\link{load.ts}} and +#' \code{\link{load.bathy}}. +#' +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}} +#' @param at.thermo Boolean indicating if only buoyancy frequency at the +#' thermocline should be returned. If false, full profile is returned. +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will likely return an NA +#' value. If true, best effort will be made to calculate indices despite NA +#' values. +#' @param ... Additional parameters will be passed on to \code{thermo.depth} +#' function when extracting buoyancy frequency at only the thermocline. Common +#' parameters to supply would be \code{seasonal} and \code{slope}. +#' @return Returns a data frame with the timeseries of buoyancy frequency in +#' units \code{sec^-2}. Includes a \sQuote{datetime} column. +#' @seealso \code{buoyancy.freq} +#' @references Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +#' Advances in Applied Mechanics 27, 353-370. +#' @keywords arith +#' @examples +#' +#' +#' #Get the path for the package example file included +#' wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng Lake, Wisconsin. +#' sp.wtr = load.ts(wtr.path) +#' +#' N2 = ts.buoyancy.freq(sp.wtr, seasonal=FALSE) +#' SN2 = ts.buoyancy.freq(sp.wtr, seasonal=TRUE) +#' +#' plot(N2, type='l', ylab='Buoyancy Frequency', xlab='Date') +#' lines(SN2, col='red') +#' +#' @export ts.buoyancy.freq <- function(wtr, at.thermo=TRUE, na.rm=FALSE, ...){ depths = get.offsets(wtr) diff --git a/R/center.buoyancy.R b/R/center.buoyancy.R index c88d13e..51d8c5f 100644 --- a/R/center.buoyancy.R +++ b/R/center.buoyancy.R @@ -1,7 +1,32 @@ -# -# Center of Buoyancy Frequency -# Author: Jordan S Read -# +#' @title Calculates the center of buoyancy. +#' +#' @description Calculate the center of buoyancy using buoyancy frequency with a center of +#' mass analysis. Brunt-Vaisala frequency is used for a temperature profile. +#' Negative values for N2 are set to 0 (as they represent transient +#' instabilities or sensor calibration issues) for this calculation. +#' +#' +#' @param wtr a numeric vector of water temperature in degrees C +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @return Returns a value for the center of buoyancy. +#' @seealso \code{buoyancy.freq}, \code{ts.buoyancy.freq}, +#' \code{center.buoyancy} +#' @keywords arith +#' @examples +#' +#' +#' # A vector of water temperatures +#' wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, +#' 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) +#' +#' #A vector defining the depths +#' depths = c(0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, +#' 17, 18, 19, 20) +#' +#' c.b = center.buoyancy(wtr, depths) +#' +#' @export center.buoyancy <- function(wtr, depths){ if (depths[2] - depths[1] < 0 ){stop('depths must be in descending order')} @@ -23,6 +48,48 @@ center.buoyancy <- function(wtr, depths){ } + + +#' @title Calculates the center of buoyancy for multiple temperature profiles. +#' +#' @description Function for simplifying the calculation of the center of buoyancy. Can +#' usually be called directly on data loaded directly using +#' \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}} +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will return an NA value. If +#' true, best effort will be made to calculate indices despite NA values. +#' @return Returns a data frame with the timeseries of the center of buoyancy +#' frequency. Includes a \sQuote{datetime} column. +#' @seealso \code{center.buoyancy}, \code{load.bathy}, \code{load.ts} +#' @references Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +#' Advances in Applied Mechanics 27, 353-370. +#' @keywords arith +#' @examples +#' +#' +#' #Get the path for the package example file included +#' wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng Lake, Wisconsin. +#' sp.wtr = load.ts(wtr.path) +#' +#' #calculate and plot the thermocline depth +#' t.d = ts.thermo.depth(sp.wtr) +#' +#' center.N2 = ts.center.buoyancy(sp.wtr) +#' +#' plot(center.N2, type='l', ylab='Depth (m)', xlab='Date', ylim=c(19,0), lwd = 1.5) +#' lines(t.d, type='l', col='red', lwd = 1.5) +#' legend(x = t.d[3,1], y = .25, +#' c('center of buoyancy','thermocline depth'), +#' lty=c(1,1), +#' lwd=c(1.5,1.5),col=c("black","red"), bty = "n") +#' +#' @export ts.center.buoyancy <- function(wtr, na.rm=FALSE){ depths = get.offsets(wtr) diff --git a/R/data.R b/R/data.R index 23bd833..5ce2bac 100644 --- a/R/data.R +++ b/R/data.R @@ -1,6 +1,6 @@ -#' Late Summer Profile +#' @title Late Summer Profile #' -#' Late summer water profile taken from Quesnel Lake, British Columbia, Canada. Profile taken with Sea-Bird +#' @description Late summer water profile taken from Quesnel Lake, British Columbia, Canada. Profile taken with Sea-Bird #' SBE19plus. #' #' \describe{ diff --git a/R/epi.temperature.R b/R/epi.temperature.R index cd17db3..b4667d4 100644 --- a/R/epi.temperature.R +++ b/R/epi.temperature.R @@ -1,17 +1,18 @@ #' @title Get volumetrically averaged epilimnion temp #' -#' @description Calculates volumetrically weighted average epilimnetic temperature using -#' the supplied water temperature timeseries. If the lake is not stratified, the bottom -#' of the epilimnion is calculated as the full depth of the lake. -#' -#' @param wtr a numeric vector of water temperature in degrees C. -#' @param depths a numeric vector corresponding to the depths (in m) of the wtr measurements -#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to bthD depths -#' @param bthD a numeric vector of depths (m) which correspond to areal measures in bthA +#' @description Calculates volumetrically weighted average epilimnetic temperature using the +#' supplied water temperature timeseries. If the lake is not stratified, the +#' bottom of the epilimnion is calculated as the full depth of the lake. #' #' -#' @seealso \code{\link{hypo.temperature}}, \code{\link{whole.lake.temperature}} -#' +#' @param wtr a numeric vector of water temperature in degrees C. +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to +#' bthD depths +#' @param bthD a numeric vector of depths (m) which correspond to areal +#' measures in bthA +#' @seealso \code{\link{hypo.temperature}} \code{\link{whole.lake.temperature}} #' @export epi.temperature <- function(wtr, depths, bthA, bthD){ diff --git a/R/helper.functions.R b/R/helper.functions.R index d6f9b30..a35ec8f 100644 --- a/R/helper.functions.R +++ b/R/helper.functions.R @@ -1,27 +1,19 @@ -## Helper functions for Lake Analyzer R - -datetime.pattern = "(datetime|timestamp|time|date)" - - #' @title Gets depths from data frame containing profile info. #' -#' @description -#' Extracts the depth information from a data frame containing multi-depth observation data. -#' Relies on the format of the header to get information and may fail if your file format is incorrect. -#' Please follow 'VAR_##.#' format, where ##.# is the depth of data for that column. VAR is typically -#' 'wtr' to indicate water temperature. -#' -#' @param data Data frame returned from \code{\link{load.ts}}. -#' -#' -#' @return -#' A numeric vector of depth values. Should be the \code{ncol(data) - 1} -#' in length as the first column contains date/time data. +#' @description Extracts the depth information from a data frame containing multi-depth +#' observation data. Relies on the format of the header to get information and +#' may fail if your file format is incorrect. Please follow 'VAR_##.#' format, +#' where ##.# is the depth of data for that column. VAR is typically 'wtr' to +#' indicate water temperature. #' #' +#' @param data Data frame returned from \code{\link{load.ts}}. +#' @return A numeric vector of depth values. Should be the \code{ncol(data) - +#' 1} in length as the first column contains date/time data. #' @seealso \code{\link{load.ts}} +#' @keywords manip +#' @examples #' -#' @examples #' #' #Get the path for the package example file included #' exampleFilePath <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") @@ -33,9 +25,6 @@ datetime.pattern = "(datetime|timestamp|time|date)" #' depths = get.offsets(sparkling.temp) #' #' print(depths) -#' -#' @keywords manip -#' #' @export get.offsets <- function(data){ @@ -81,15 +70,18 @@ get.drho_dz <- function(wtr, depths){ } -#@title Find and drop the datetime column from the datatable -# -#description Liberally looks for a datetime column and drops it, -#returning a data.frame with only water temperature. Errors if datetime column is -#ambiguous. Warns if there is no match. -# -#@return A data.frame with only the data, after datetime has been dropped -# +#' @title Find and drop the datetime column from the datatable +#' +#' @description Liberally looks for a datetime column and drops it, +#' returning a data.frame with only water temperature. Errors if datetime column is +#' ambiguous. Warns if there is no match. +#' @param data data arg +#' @param error defaults to FALSE +#' +#' @return A data.frame with only the data, after datetime has been dropped + drop.datetime = function(data, error=FALSE){ + datetime.pattern = "(datetime|timestamp|time|date)" header = names(data) dt_indx = grep(datetime.pattern, header, ignore.case=TRUE) @@ -109,11 +101,14 @@ drop.datetime = function(data, error=FALSE){ return(data[,-dt_indx, drop=FALSE]) } -#@title Search for and return the datetime column from a ts data.frame -# -#Warns if unavailable then returns NULL. -# +#' @title Search for and return the datetime column from a ts data.frame +#' +#' @description Warns if unavailable then returns NULL. +#' +#' @inheritParams drop.datetime +#' get.datetime = function(data, error=FALSE){ + datetime.pattern = "(datetime|timestamp|time|date)" header = names(data) dt_indx = grep(datetime.pattern, header, ignore.case=TRUE) diff --git a/R/hypo.temperature.R b/R/hypo.temperature.R index 92064a8..23e7bdf 100644 --- a/R/hypo.temperature.R +++ b/R/hypo.temperature.R @@ -1,17 +1,18 @@ #' @title Get volumetrically averaged hypolimnion temp #' #' @description Calculates volumetrically weighted average hypolimnetic temperature using -#' the supplied water temperature timeseries. If the lake is not stratified, an NA -#' value is returned. -#' +#' the supplied water temperature timeseries. If the lake is not stratified, an +#' NA value is returned. +#' +#' #' @param wtr a numeric vector of water temperature in degrees C. -#' @param depths a numeric vector corresponding to the depths (in m) of the wtr measurements -#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to bthD depths -#' @param bthD a numeric vector of depths (m) which correspond to areal measures in bthA -#' -#' +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to +#' bthD depths +#' @param bthD a numeric vector of depths (m) which correspond to areal +#' measures in bthA #' @seealso \code{\link{epi.temperature}}, \code{\link{whole.lake.temperature}} -#' #' @export hypo.temperature <- function(wtr, depths, bthA, bthD){ diff --git a/R/internal.energy.R b/R/internal.energy.R index 946f886..caa0c29 100644 --- a/R/internal.energy.R +++ b/R/internal.energy.R @@ -1,29 +1,31 @@ -#'@title Internal energy function (Joules) -#'@description Calculates the internal energy of the water column with temperature and hypsography -#' -#'@details Internal energy is the thermal energy in the water column, which is calculated by -#'multiplying the specific heat of water (J kg-1 K-1) by the temperature and mass of the water -#'in the lake. -#' -#'@param wtr a numeric vector of water temperature in degrees C -#'@param depths a numeric vector corresponding to the depths (in m) of the wtr measurements -#'@param bthA a numeric vector of cross sectional areas (m^2) corresponding to bthD depths -#'@param bthD a numeric vector of depths (m) which correspond to areal measures in bthA -#' -#'@return internal energy in Joules m-2. (Currently not vectorized..) -#'@author Jordan S. Read -#' -#'@examples -#'bthA <- c(1000,900,864,820,200,10) -#'bthD <- c(0,2.3,2.5,4.2,5.8,7) -#' -#'wtr <- c(28,27,26.4,26,25.4,24,23.3) -#'depths <- c(0,1,2,3,4,5,6) -#' -#'cat('Internal Energy for input is: ') -#'cat(internal.energy(wtr, depths, bthA, bthD)) -#'@export - +#' @title Internal energy function (Joules) +#' +#' @description Calculates the internal energy of the water column with temperature and +#' hypsography +#' +#' Internal energy is the thermal energy in the water column, which is +#' calculated by multiplying the specific heat of water (J kg-1 K-1) by the +#' temperature and mass of the water in the lake. +#' +#' @param wtr a numeric vector of water temperature in degrees C +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to +#' bthD depths +#' @param bthD a numeric vector of depths (m) which correspond to areal +#' measures in bthA +#' @return internal energy in Joules m-2. (Currently not vectorized..) +#' @examples +#' +#' bthA <- c(1000,900,864,820,200,10) +#' bthD <- c(0,2.3,2.5,4.2,5.8,7) +#' +#' wtr <- c(28,27,26.4,26,25.4,24,23.3) +#' depths <- c(0,1,2,3,4,5,6) +#' +#' cat('Internal Energy for input is: ') +#' cat(internal.energy(wtr, depths, bthA, bthD)) +#' @export internal.energy = function(wtr, depths, bthA, bthD){ @@ -41,7 +43,7 @@ internal.energy = function(wtr, depths, bthA, bthD){ depT = c(0, bthD[useI]) } - bthA = approx(bthD, bthA, depT)$y + bthA = stats::approx(bthD, bthA, depT)$y bthD = depT } @@ -72,9 +74,9 @@ internal.energy = function(wtr, depths, bthA, bthD){ #The approx (interp1 in matlab) just does linear interpolation layerD = seq(min(depths), max(depths), by=dz) - layerP = approx(depths, rhoL, layerD)$y - layerT = approx(depths,wtr, layerD)$y - layerA = approx(bthD, bthA, layerD)$y + layerP = stats::approx(depths, rhoL, layerD)$y + layerT = stats::approx(depths,wtr, layerD)$y + layerA = stats::approx(bthD, bthA, layerD)$y v_i = layerA*dz # -- calculate mass of water in each dz layer -- diff --git a/R/lake.number.R b/R/lake.number.R index 65f0538..f2a5052 100644 --- a/R/lake.number.R +++ b/R/lake.number.R @@ -1,6 +1,52 @@ -#----Author: Jordan S Read 2009 ---- -#----converted to R 2013-04-21 ---- - +#' @title Calculate Lake Number +#' +#' @description The Lake Number, defined by Imberger and Patterson (1990), has been used to +#' describe processes relevant to the internal mixing of lakes induced by wind +#' forcings. Lower values of Lake Number represent a higher potential for +#' increased diapycnal mixing, which increases the vertical flux of mass and +#' energy across the metalimnion through the action of non-linear internal +#' waves. Lake Number is a dimensionless index. +#' +#' Lake Number has been used, for example, to estimate the flux of oxygen +#' across the thermocline in a small lake (Robertson and Imberger, 1994), and +#' to explain the magnitude of the vertical flux of ammonium in a lake (Romero +#' et al., 1998). +#' +#' @param bthA a numeric vector of cross sectional areas (m2) corresponding to +#' bthD depths, hypsographic areas +#' @param bthD a numeric vector of depths (m) which correspond to areal +#' measures in bthA, hypsographic depths +#' @param uStar a numeric array of u* (m/s), water friction velocity due to +#' wind stress +#' @param St a numeric array of Schmidt stability (J/m2), as defined by Idso +#' 1973 +#' @param metaT a numeric array of the top of the metalimnion depth (m from the +#' surface) +#' @param metaB a numeric array of the bottom of the metalimnion depth (m from +#' the surface) +#' @param averageHypoDense a numeric array of the average density of the +#' hypolimnion (kg/m3) +#' @return A numeric vector of Lake Number [dimensionless] +#' @seealso \code{\link{ts.lake.number}} \code{\link{wedderburn.number}} +#' @references Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +#' Advances in Applied Mechanics 27, 303-475. +#' +#' Idso, S.B., 1973. \emph{On the concept of lake stability}. Limnology and +#' Oceanography 18, 681-683. +#' @keywords manip +#' @examples +#' +#' bthA <- c(1000,900,864,820,200,10) +#' bthD <- c(0,2.3,2.5,4.2,5.8,7) +#' uStar <- c(0.0032,0.0024) +#' St <- c(140,153) +#' metaT <- c(1.34,1.54) +#' metaB <- c(4.32,4.33) +#' averageHypoDense <- c(999.3,999.32) +#' cat('Lake Number for input vector is: ') +#' cat(lake.number( bthA, bthD, uStar, St, metaT, metaB, averageHypoDense) ) +#' +#' @export lake.number <- function(bthA,bthD,uStar,St,metaT,metaB,averageHypoDense){ g <- 9.81 dz <- 0.1 @@ -16,7 +62,7 @@ lake.number <- function(bthA,bthD,uStar,St,metaT,metaB,averageHypoDense){ #interpolates the bathymetry data layerD <- seq(Zo,max(bthD),dz) - layerA <- approx(bthD,bthA,layerD)$y + layerA <- stats::approx(bthD,bthA,layerD)$y #find depth to the center of volume diff --git a/R/lake.number.plot.R b/R/lake.number.plot.R index ecf4da4..7ff3cc6 100644 --- a/R/lake.number.plot.R +++ b/R/lake.number.plot.R @@ -1,4 +1,36 @@ -# time series of lake number +#' @title Plots time series of Lake Number +#' +#' @description Generates a time series plot of Lake Number for appropriately formatted +#' data. See \code{\link{lake.number}} for more details on Lake Number and +#' reference. +#' +#' +#' @param wtr Data frame of water temperature loaded with \code{\link{load.ts}} +#' @param wnd A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param wh A value indicating the height of the anemometer above lake surface +#' in meters. This value must be specified, there is no default. +#' @param bth A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @seealso \code{\link{wtr.lineseries}} +#' @keywords hplot +#' @examples +#' +#' #Get system data file paths +#' wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") +#' bth.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") +#' wnd.path <- system.file('extdata', 'Sparkling.wnd', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng Lake, Wisconsin. +#' wtr = load.ts(wtr.path) +#' wnd = load.ts(wnd.path) +#' bth = load.bathy(bth.path) +#' wh = 1 # user specified, here as 1 m. +#' \dontrun{ +#' #generate default plot +#' lake.number.plot(wtr,wnd,wh,bth) +#' } +#' @export lake.number.plot = function(wtr,wnd,wh,bth){ ln = ts.lake.number(wtr,wnd,wh,bth) @@ -49,7 +81,7 @@ lake.number.plot = function(wtr,wnd,wh,bth){ xxlab <- " " } - plot(ln[,2]~ln[,1], + graphics::plot(ln[,2]~ln[,1], type='l', lwd = 2, col="black", @@ -61,13 +93,13 @@ lake.number.plot = function(wtr,wnd,wh,bth){ ) # x axis - axis(side = 1, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(ln[,2],na.rm=TRUE)), tck = -0.03) - segments(c(starttime),c(min(ln[,2],na.rm=TRUE)),c(endtime),c(min(ln[,2],na.rm=TRUE)), col = "black", lty = 1) + graphics::axis(side = 1, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(ln[,2],na.rm=TRUE)), tck = -0.03) + graphics::segments(c(starttime),c(min(ln[,2],na.rm=TRUE)),c(endtime),c(min(ln[,2],na.rm=TRUE)), col = "black", lty = 1) # y axis - axis (side = 2, pos = c(starttime), at = NULL, las = 1) - segments(c(starttime),c(min(ln[,2],na.rm=TRUE)),c(starttime),c(max(ln[,2],na.rm=TRUE)), col = "black") + graphics::axis(side = 2, pos = c(starttime), at = NULL, las = 1) + graphics::segments(c(starttime),c(min(ln[,2],na.rm=TRUE)),c(starttime),c(max(ln[,2],na.rm=TRUE)), col = "black") } diff --git a/R/layer.density.R b/R/layer.density.R index 6b3bd4b..277ef87 100644 --- a/R/layer.density.R +++ b/R/layer.density.R @@ -1,17 +1,36 @@ -# ---Author: Jake Zwart, 2013-04-21 --- -# translated from Matlab Script - Author Jordan Read, 2009 -## from layerDensity.m in https://github.com/jread-usgs/Lake-Analyzer/ -# -# top: surface to top of layer -# bottom: surface to bottom of layer -# wtr: water temperature in celsius -# depths: water depth values in meters -# bthA: bathymetry area in meters squared -# bthD: bathymetry depths in meters -# sal: salinity in Pratical Salinity Scale units (dimensionless) -# -# OUTPUT: returns the average average water density of lake layer (i.e. average epilimnion density) - +#' @title Returns the average density of a layer between two depths. +#' +#' @description This function calculates the average density of a layer of water between two +#' depths. +#' +#' +#' @param top Numeric value of the depth (m) of the top of the layer from the +#' water surface +#' @param bottom Numeric value of the depth (m) of the bottom of the layer from +#' the water surface +#' @param wtr Numeric vector of water temperature in degrees C +#' @param depths Numeric vector of depths (m) corresponding to water +#' temperature vector +#' @param bthA Numeric vector of water body cross sectional area (m2) +#' corresponding to bthD depths +#' @param bthD Numeric vector of water body bathymetric depths (m) +#' corresponding to areal bthA values +#' @param sal Optional numeric vector of salinity in Practical Salinity Units +#' corresponding to water temperature vector. If left blank, salinity is set to +#' be zero +#' @return Numeric value of average water density for bounded layer in kg/m^3 +#' @seealso \code{water.density} +#' @keywords manip +#' @examples +#' +#' top <- 2 +#' bottom <- 6 +#' wtr <- c(25.2,25.1,24.1,22.0,19.8,15.3,12.0,11.1) +#' depths <- c(0,1,2,3,4,5,6,7) +#' bthA <- c(10000,8900,5000,3500,2000,1000,300,10) +#' bthD <- c(0,1,2,3,4,5,6,7) +#' layer.density(top,bottom,wtr,depths,bthA,bthD) +#' @export layer.density <- function(top, bottom, wtr, depths, bthA, bthD, sal = wtr*0){ # checking input quality @@ -33,7 +52,7 @@ layer.density <- function(top, bottom, wtr, depths, bthA, bthD, sal = wtr*0){ }else{ depT <- bthD[useI] } - bthA <- approx(bthD,bthA,depT)$y + bthA <- stats::approx(bthD,bthA,depT)$y bthD <- depT } @@ -62,9 +81,9 @@ layer.density <- function(top, bottom, wtr, depths, bthA, bthD, sal = wtr*0){ # iterpolate the bathymetry data layerD <- seq(top,bottom,dz) - layerT <- approx(depths,wtr,layerD)$y - layerS <- approx(depths,sal,layerD)$y - layerA <- approx(bthD,bthA,layerD)$y + layerT <- stats::approx(depths,wtr,layerD)$y + layerS <- stats::approx(depths,sal,layerD)$y + layerA <- stats::approx(bthD,bthA,layerD)$y layerP <- water.density(layerT,layerS) mass <- layerA*layerP*dz diff --git a/R/layer.temperature.R b/R/layer.temperature.R index 5bd36f3..a0522b1 100644 --- a/R/layer.temperature.R +++ b/R/layer.temperature.R @@ -1,16 +1,36 @@ -# ---Author: Jordan Read, 2013-07-26 --- -# translated from Matlab Script - Author Jordan Read, 2013 -## from layertemperature.m in https://github.com/GLEON/Lake-Analyzer/ -# -# top: surface to top of layer -# bottom: surface to bottom of layer -# wtr: water temperature in celsius -# depths: water depth values in meters -# bthA: bathymetry area in meters squared -# bthD: bathymetry depths in meters -# -# OUTPUT: returns the average average water density of lake layer (i.e. average epilimnion density) - +#' Returns the average temperature of a layer between two depths. +#' +#' This function calculates the average temperature of a layer of water between +#' two depths. +#' +#' +#' @param top Numeric value of the depth (m) of the top of the layer from the +#' water surface +#' @param bottom Numeric value of the depth (m) of the bottom of the layer from +#' the water surface +#' @param wtr Numeric vector of water temperature in degrees C +#' @param depths Numeric vector of depths (m) corresponding to water +#' temperature vector +#' @param bthA Numeric vector of water body cross sectional area (m2) +#' corresponding to bthD depths +#' @param bthD Numeric vector of water body bathymetric depths (m) +#' corresponding to areal bthA values +#' @return Numeric value of average water temperature +#' @seealso \code{layer.density} +#' @keywords manip +#' @examples +#' +#' # Supply input data +#' top <- 2 +#' bottom <- 6 +#' wtr <- c(25.2,25.1,24.1,22.0,19.8,15.3,12.0,11.1) +#' depths <- c(0,1,2,3,4,5,6,7) +#' bthA <- c(10000,8900,5000,3500,2000,1000,300,10) +#' bthD <- c(0,1,2,3,4,5,6,7) +#' +#' #Return the average temperature of the water column between 2 and 6 meters. +#' layer.temperature(top,bottom,wtr,depths,bthA,bthD) +#' @export layer.temperature <- function(top, bottom, wtr, depths, bthA, bthD){ # checking input quality @@ -32,7 +52,7 @@ layer.temperature <- function(top, bottom, wtr, depths, bthA, bthD){ }else{ depT <- bthD[useI] } - bthA <- approx(bthD,bthA,depT)$y + bthA <- stats::approx(bthD,bthA,depT)$y bthD <- depT } @@ -61,8 +81,8 @@ layer.temperature <- function(top, bottom, wtr, depths, bthA, bthD){ # iterpolate the bathymetry data layerD <- seq(top,bottom,dz) - layerT <- approx(depths,wtr,layerD)$y - layerA <- approx(bthD,bthA,layerD)$y + layerT <- stats::approx(depths,wtr,layerD)$y + layerA <- stats::approx(bthD,bthA,layerD)$y weightedT <- layerA*layerT*dz diff --git a/R/load.data.R b/R/load.data.R index 32010e2..d7aa623 100644 --- a/R/load.data.R +++ b/R/load.data.R @@ -1,10 +1,32 @@ -## Data load functions - +#' @title Import lake bathymetry data. +#' +#' @description Imports lake bathymetry data. Bathymetric data file must be a 2 column array +#' where depth (in meters) and area (in meters^2) information are provided in +#' columns with headers containing the words "depths" and "areas" respectively. +#' +#' +#' @param fPath File path to the bathymetry file. +#' @return data.frame of depth and area for given lake. +#' @seealso \code{\link{load.ts}} +#' @keywords file +#' @examples +#' +#' #Get the path for the package example file included +#' exampleFilePath <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") +#' +#' #Load and plot the hypsometric curve +#' sparkling.bathy = load.bathy(exampleFilePath) +#' +#' #If successful, there will be two colums. "depths", and "areas". +#' plot(sparkling.bathy$areas, sparkling.bathy$depths, type='l', ylim=c(20,0), +#' ylab='Depths (m)', xlab='Areas (m^2)') +#' +#' @export load.bathy <- function(fPath){ - d = read.table(fPath, sep=c(','), header=TRUE) + d = utils::read.table(fPath, sep=c(','), header=TRUE) if(ncol(d) < 2){ - d = read.table(fPath, sep=c('\t'), header=TRUE) + d = utils::read.table(fPath, sep=c('\t'), header=TRUE) } if(ncol(d) < 2){ @@ -28,9 +50,45 @@ load.bathy <- function(fPath){ return(d) } + + +#' @title Load timeseries from properly formatted text file. +#' +#' @description A convenience function to load timeseries data into R based on the +#' standardized format used by Lake Analyzer. +#' +#' Timeseries files must follow a common format. The first column must have the +#' label 'datetime' and be of the format \emph{yyyy-mm-dd HH:MM:SS} (ISO 8601 +#' without the "T" delimiter). The second can be skipped if not using +#' sub-minute data. +#' +#' @param fPath The file path as a string. +#' @param tz Timezone string to be supplied to \code{\link{as.POSIXct}}. +#' Defaults to GMT (UTC-0). This often can be left to the default unless +#' timezone support is specifically required. +#' @return A data frame in the required format for use with other rLakeAnalyzer +#' timeseries functions. +#' @seealso For dataloading \code{\link{ts.meta.depths}}, \cr For analyzing +#' timeseries data, see \code{\link{ts.meta.depths}}, +#' \code{\link{ts.thermo.depth}}, \code{\link{ts.schmidt.stability}}, +#' \code{\link{ts.lake.number}}. +#' @keywords file +#' @examples +#' +#' #Get the path for the package example file included +#' exampleFilePath <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") +#' +#' #Load +#' sparkling.temp = load.ts(exampleFilePath) +#' +#' #calculate and plot the thermocline depth +#' t.d = ts.thermo.depth(sparkling.temp) +#' +#' plot(t.d$datetime, t.d$thermo.depth, type='l', ylab='Thermocline Depth (m)', xlab='Date') +#' @export load.ts <- function(fPath, tz='GMT'){ #Load data - d = read.table(fPath, sep='\t', header=TRUE, as.is=TRUE) + d = utils::read.table(fPath, sep='\t', header=TRUE, as.is=TRUE) #Just standardize all headers as lowercase names(d) = tolower(names(d)) @@ -49,4 +107,4 @@ load.ts <- function(fPath, tz='GMT'){ #} return(d) -} \ No newline at end of file +} diff --git a/R/meta.depths.R b/R/meta.depths.R index 8ba148e..b6a5afe 100644 --- a/R/meta.depths.R +++ b/R/meta.depths.R @@ -1,55 +1,42 @@ -#'@title Calculate the Top and Bottom Depths of the Metalimnion -#' -#'@description -#'Calculates the top and bottom depths of the metalimnion -#' in a stratified lake. The metalimnion is defined as the -#' water stratum in a stratified lake with the steepest thermal -#' gradient and is demarcated by the bottom of the epilimnion and top -#' of the hypolimnion. -#' -#' -#'@param wtr -#'a numeric vector of water temperature in degrees C -#'@param depths -#'a numeric vector corresponding to the depths (in m) of the wtr measurements -#'@param slope -#'a numeric vector corresponding to the minimum slope -#'@param seasonal -#'a logical value indicating whether the seasonal thermocline should be -#'returned. This is fed to thermo.depth, which is used as the starting point. -#'The seasonal thermocline is defined as the deepest density gradient found -#'in the profile. If \code{FALSE}, the depth of the maximum density gradient is used -#'as the starting point. -#'@param mixed.cutoff -#'A cutoff (deg C) where below this threshold, thermo.depth and meta.depths -#'are not calculated (NaN is returned). Defaults to 1 deg C. -#' -#'@return -#'A numeric vector of the top and bottom metalimnion depths in meters. -#'Returns the bottom depth if no distinct metalimion top and bottom found. -#' -#'@references -#'Wetzel, R. G. 2001. Limnology: Lake and River Ecosystems, 3rd ed. Academic Press. -#' -#'@author Jennifer Brentrup, Luke Winslow -#' -#'@seealso -#' -#'\code{\link{ts.meta.depths}}, \code{\link{thermo.depth}} -#' -#'@examples -#' wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, -#' 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) -#' -#' depths = c(0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, -#' 17, 18, 19, 20) -#' -#' m.d = meta.depths(wtr, depths, slope=0.1, seasonal=FALSE) -#' cat('The top depth of the metalimnion is:', m.d[1]) -#' cat('The bottom depth of the metalimnion is:', m.d[2]) -#' -#'@keywords manip -#'@export +#' @title Calculate the Top and Bottom Depths of the Metalimnion +#' +#' @description Calculates the top and bottom depths of the metalimnion in a stratified +#' lake. The metalimnion is defined as the water stratum in a stratified lake +#' with the steepest thermal gradient and is demarcated by the bottom of the +#' epilimnion and top of the hypolimnion. +#' +#' +#' @param wtr a numeric vector of water temperature in degrees C +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param slope a numeric vector corresponding to the minimum slope +#' @param seasonal a logical value indicating whether the seasonal thermocline +#' should be returned. This is fed to thermo.depth, which is used as the +#' starting point. The seasonal thermocline is defined as the deepest density +#' gradient found in the profile. If \code{FALSE}, the depth of the maximum +#' density gradient is used as the starting point. +#' @param mixed.cutoff A cutoff (deg C) where below this threshold, +#' thermo.depth and meta.depths are not calculated (NaN is returned). Defaults +#' to 1 deg C. +#' @return A numeric vector of the top and bottom metalimnion depths in meters. +#' Returns the bottom depth if no distinct metalimion top and bottom found. +#' @seealso \code{\link{ts.meta.depths}}, \code{\link{thermo.depth}} +#' @references Wetzel, R. G. 2001. Limnology: Lake and River Ecosystems, 3rd +#' ed. Academic Press. +#' @keywords manip +#' @examples +#' +#' wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, +#' 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) +#' +#' depths = c(0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, +#' 17, 18, 19, 20) +#' +#' m.d = meta.depths(wtr, depths, slope=0.1, seasonal=FALSE) +#' cat('The top depth of the metalimnion is:', m.d[1]) +#' cat('The bottom depth of the metalimnion is:', m.d[2]) +#' +#' @export meta.depths = function(wtr, depths, slope=0.1, seasonal=TRUE, mixed.cutoff=1){ if(any(is.na(wtr))){ @@ -99,7 +86,7 @@ meta.depths = function(wtr, depths, slope=0.1, seasonal=TRUE, mixed.cutoff=1){ sortDepth = tmp$x sortInd = tmp$ix numDepths = length(sortDepth) #set numDepths again, it could have changed above - drho_dz = approx(Tdepth, drho_dz, sortDepth) + drho_dz = stats::approx(Tdepth, drho_dz, sortDepth) drho_dz = drho_dz$y #find the thermocline index @@ -114,7 +101,7 @@ meta.depths = function(wtr, depths, slope=0.1, seasonal=TRUE, mixed.cutoff=1){ } if (i-thermo_index >= 1 && (!is.na(drho_dz[thermo_index]) && drho_dz[thermo_index] > slope)){ - metaBot_depth = approx(drho_dz[thermo_index:i], + metaBot_depth = stats::approx(drho_dz[thermo_index:i], sortDepth[thermo_index:i],slope) metaBot_depth = metaBot_depth$y } @@ -131,7 +118,7 @@ meta.depths = function(wtr, depths, slope=0.1, seasonal=TRUE, mixed.cutoff=1){ } if(thermo_index - i >= 1 && (!is.na(drho_dz[thermo_index]) && drho_dz[thermo_index] > slope)){ - metaTop_depth = approx(drho_dz[i:thermo_index], sortDepth[i:thermo_index], slope); + metaTop_depth = stats::approx(drho_dz[i:thermo_index], sortDepth[i:thermo_index], slope); metaTop_depth = metaTop_depth$y } diff --git a/R/rLakeAnalyzer.R b/R/rLakeAnalyzer.R new file mode 100644 index 0000000..e767a2a --- /dev/null +++ b/R/rLakeAnalyzer.R @@ -0,0 +1,10 @@ +#' @title Lake Physics Tools +#' +#' @description Standardized methods for calculating common important derived +#' physical features of lakes including water density based based on +#' temperature, thermal layers, thermocline depth, lake number, Wedderburn +#' number, Schmidt stability and others. +#' @docType package +#' @name rLakeAnalyzer +#' +NULL \ No newline at end of file diff --git a/R/schmidt.plot.R b/R/schmidt.plot.R index cea711f..9e251cf 100644 --- a/R/schmidt.plot.R +++ b/R/schmidt.plot.R @@ -1,4 +1,31 @@ -# time series plot of Schmidt's stability +#' @title Creates a time series plot of Schmidt's stability +#' +#' @description Generates a time series of Schmidt's stability where each value represents +#' water column stability for each time step of data. See +#' \code{\link{schmidt.stability}} for more details and reference. +#' +#' +#' @param wtr Data frame of water temperature loaded with \code{\link{load.ts}} +#' @param bth A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @seealso \code{\link{schmidt.stability}} +#' @references See \code{\link{schmidt.stability}} +#' @keywords hplot +#' @examples +#' +#' # Get system data file paths +#' wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") +#' bth.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") +#' +#' # Load data for example lake, Sparkilng Lake, Wisconsin. +#' wtr = load.ts(wtr.path) +#' bth = load.bathy(bth.path) +#' +#' \dontrun{ +#' # Generate default plot +#' schmidt.plot(wtr,bth) +#' } +#' @export schmidt.plot = function(wtr,bth){ ss = ts.schmidt.stability(wtr,bth) @@ -49,7 +76,7 @@ schmidt.plot = function(wtr,bth){ xxlab <- " " } - plot(ss[,2]~ss[,1], + graphics::plot(ss[,2]~ss[,1], type='l', lwd = 2, col="black", @@ -61,11 +88,11 @@ schmidt.plot = function(wtr,bth){ ) # x axis - axis(side = 1, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(ss[,2],na.rm=TRUE)), tck = -0.03) - segments(c(starttime),c(min(ss[,2],na.rm=TRUE)),c(endtime),c(min(ss[,2],na.rm=TRUE)), col = "black", lty = 1) + graphics::axis(side = 1, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(ss[,2],na.rm=TRUE)), tck = -0.03) + graphics::segments(c(starttime),c(min(ss[,2],na.rm=TRUE)),c(endtime),c(min(ss[,2],na.rm=TRUE)), col = "black", lty = 1) # y axis - axis (side = 2, pos = c(starttime), at = NULL, las = 1) - segments(c(starttime),c(min(ss[,2],na.rm=TRUE)),c(starttime),c(max(ss[,2],na.rm=TRUE)), col = "black") + graphics::axis (side = 2, pos = c(starttime), at = NULL, las = 1) + graphics::segments(c(starttime),c(min(ss[,2],na.rm=TRUE)),c(starttime),c(max(ss[,2],na.rm=TRUE)), col = "black") } diff --git a/R/schmidt.stability.R b/R/schmidt.stability.R index 742a873..62a792f 100644 --- a/R/schmidt.stability.R +++ b/R/schmidt.stability.R @@ -1,18 +1,45 @@ -### R Lake Analyzer -# Author: J. Brentrup May 2013 -# Sources: Iso, S.B. 1973. On the concept of lake stability. Limnol. and Oceanogr. 18: 683-681. -# J.S. Read - Matlab code 2009 (Adapted) - -### Equation: St = (g/A0)*[Integral from 0 to zm:(z-zp)*pz*Az*dz] -#St = Schmidt stability -#g = gravity (9.81 m/s2) -#A0 = surface area -#z = depth -#zm = max. depth -#zp = mean density - uses Richard's function water.density.R -#pz = observed denisty at depth z -#Az = area at depth z - +#' @title Calculate the Schmidt stability +#' +#' @description Schmidt stability, or the resistance to mechanical mixing due to the +#' potential energy inherent in the stratification of the water column. +#' +#' Schmidt stability was first defined by Schmidt (1928) and later modified by +#' Hutchinson (1957). This stability index was formalized by Idso (1973) to +#' reduce the effects of lake volume on the calculation (resulting in a mixing +#' energy requirement per unit area). +#' +#' @param wtr a numeric vector of water temperature in degrees C +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to +#' bthD depths +#' @param bthD a numeric vector of depths (m) which correspond to areal +#' measures in bthA +#' @param sal a numeric vector of salinity in Practical Salinity Scale units +#' @return a numeric vector of Schmidt stability (J/m^2) +#' @seealso \code{\link{ts.schmidt.stability}} \code{\link{lake.number}} +#' \code{\link{wedderburn.number}} +#' @references Schmidt, W., 1928. \emph{Ueber Temperatur and +#' Stabilitaetsverhaltnisse von Seen}. Geo- graphiska Annaler 10, 145-177. +#' +#' Hutchinson, G.E., 1957. \emph{A Treatise on Limnology}, vol. 1. John Wiley & +#' Sons, Inc., New York. +#' +#' Idso, S.B., 1973. \emph{On the concept of lake stability}. Limnology and +#' Oceanography 18, 681-683. +#' @keywords arith +#' @examples +#' +#' +#' bthA <- c(1000,900,864,820,200,10) +#' bthD <- c(0,2.3,2.5,4.2,5.8,7) +#' +#' wtr <- c(28,27,26.4,26,25.4,24,23.3) +#' depths <- c(0,1,2,3,4,5,6) +#' +#' cat('Schmidt stability for input is: ') +#' cat(schmidt.stability(wtr, depths, bthA, bthD)) +#' @export schmidt.stability = function(wtr, depths, bthA, bthD, sal = 0){ if(length(wtr) != length(depths)){ @@ -46,7 +73,7 @@ schmidt.stability = function(wtr, depths, bthA, bthD, sal = 0){ depT = c(0, bthD[useI]) } - bthA = approx(bthD, bthA, depT)$y + bthA = stats::approx(bthD, bthA, depT)$y bthD = depT } @@ -79,8 +106,8 @@ schmidt.stability = function(wtr, depths, bthA, bthD, sal = 0){ #The approx (interp1 in matlab) just does linear interpolation layerD = seq(min(depths), max(depths), by=dz) - layerP = approx(depths, rhoL, layerD)$y - layerA = approx(bthD, bthA, layerD)$y + layerP = stats::approx(depths, rhoL, layerD)$y + layerA = stats::approx(bthD, bthA, layerD)$y Zcv <- layerD %*% layerA / sum(layerA) St <- layerP %*% ((layerD - as.vector(Zcv)) * layerA) * dz * g / Ao diff --git a/R/sm-utils.R b/R/sm-utils.R index bf4e9b2..b401c04 100644 --- a/R/sm-utils.R +++ b/R/sm-utils.R @@ -1,4 +1,4 @@ -#' Service subroutine for determining Mixed Layer Depth for a SPECIFIED ERROR NORM VALUE +#' @title Service subroutine for determining Mixed Layer Depth for a SPECIFIED ERROR NORM VALUE #' @description Service subroutine for determining Mixed Layer Depth for a SPECIFIED ERROR NORM VALUE #' #' @param thres error norm; @@ -61,7 +61,7 @@ by_s_m <- function(thres=thres, z0=z0, zmax=zmax, z=z, sigma=sigma) { } -#' Service subroutine for determining Mixed Layer Depth for a SPECIFIED NUMBER OF SEGMENTS +#' @title Service subroutine for determining Mixed Layer Depth for a SPECIFIED NUMBER OF SEGMENTS #' @description Service subroutine for determining Mixed Layer Depth for a SPECIFIED ERROR NORM VALUE #' #' @param nr fixed number of segments @@ -127,18 +127,24 @@ by_s_m3 <- function(nr, z0, zmax, z, sigma) { list(eps = s_mNresults$eps, by_s_m = ss, smz = smz, sms = sms) } + + #' @title Calculate cline of series of segments +#' +#' @description Cline depth is defined as the midpoint of the segment connecting inflection +#' points that has the maximum slope. A cline cannot occur over a depth range +#' of less than 1m and also cannot be the shallowest segment. Violating both +#' conditions will thrown warnings though this function handles both +#' differently. Used mostly with \code{wtr_layer} +#' +#' #' @param z_seg depth in metres; should be an increasing vector #' @param sigma_seg parameter measured in the water column profile #' @return the depth of the cline -#' @description Cline depth is defined as the midpoint of the segment connecting inflection points that has the maximum slope. A cline cannot occur over a depth range of less than 1m and also cannot be the shallowest segment. Violating both conditions will thrown warnings though this function handles both differently. Used mostly with \code{wtr_layer} -#' @references Fiedler, Paul C. Comparison of objective descriptions of the thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325. +#' @seealso \code{wtr_layer()} +#' @references Fiedler, Paul C. Comparison of objective descriptions of the +#' thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325. #' @keywords internal -#' -#' @seealso -#' \code{wtr_layer()} -#' -#' cline_calc <- function(z_seg = z_seg, sigma_seg = sigma_seg) { ## index top of segment with greatest change of measure (sigma) over depth (z) - metalimnion top <- which.max(diff(z_seg) / diff(sigma_seg)) diff --git a/R/thermo.depth.R b/R/thermo.depth.R index 379fcb4..eb613d5 100644 --- a/R/thermo.depth.R +++ b/R/thermo.depth.R @@ -1,54 +1,44 @@ - -#'@title Calculate depth of the thermocline from a temperature profile. -#' -#'@param wtr -#'a numeric vector of water temperature in degrees C -#'@param depths -#'a numeric vector corresponding to the depths (in m) of the wtr measurements -#'@param Smin -#'Optional paramter defining minimum density gradient for thermocline -#'@param seasonal -#'a logical value indicating whether the seasonal thermocline should be -#'returned. This is fed to thermo.depth, which is used as the starting point. -#'The seasonal thermocline is defined as the deepest density gradient found -#'in the profile. If \code{FALSE}, the depth of the maximum density gradient is used -#'as the starting point. -#'@param index -#'Boolean value indicated if index of the thermocline depth, instead of the depth value, should be returned. -#'@param mixed.cutoff -#'A cutoff (deg C) where below this threshold, thermo.depth and meta.depths -#'are not calculated (NaN is returned). Defaults to 1 deg C. -#'@return -#'Depth of thermocline. If no thermocline found, value is NaN. -#' -#'@description -#'This function calculates the location of the thermocline from a temperature profile. -#'It uses a special technique to estimate where the thermocline lies even between two -#'temperature measurement depths, giving a potentially finer-scale estimate than usual techniques. -#' -#' -#'@author -#'Luke Winslow -#' -#'@seealso -#'\code{\link{ts.thermo.depth}}, \code{water.density} -#' -#'@examples -#' # A vector of water temperatures -#' wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, -#' 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) -#' +#' @title Calculate depth of the thermocline from a temperature profile. +#' +#' @description This function calculates the location of the thermocline from a temperature +#' profile. It uses a special technique to estimate where the thermocline lies +#' even between two temperature measurement depths, giving a potentially +#' finer-scale estimate than usual techniques. +#' +#' +#' @param wtr a numeric vector of water temperature in degrees C +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param Smin Optional paramter defining minimum density gradient for +#' thermocline +#' @param seasonal a logical value indicating whether the seasonal thermocline +#' should be returned. This is fed to thermo.depth, which is used as the +#' starting point. The seasonal thermocline is defined as the deepest density +#' gradient found in the profile. If \code{FALSE}, the depth of the maximum +#' density gradient is used as the starting point. +#' @param index Boolean value indicated if index of the thermocline depth, +#' instead of the depth value, should be returned. +#' @param mixed.cutoff A cutoff (deg C) where below this threshold, +#' thermo.depth and meta.depths are not calculated (NaN is returned). Defaults +#' to 1 deg C. +#' @return Depth of thermocline. If no thermocline found, value is NaN. +#' @seealso \code{\link{ts.thermo.depth}}, \code{water.density} +#' @keywords manip +#' @examples +#' +#' # A vector of water temperatures +#' wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, +#' 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) +#' #' #A vector defining the depths #' depths = c(0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, #' 17, 18, 19, 20) -#' +#' #' t.d = thermo.depth(wtr, depths, seasonal=FALSE) -#' +#' #' cat('The thermocline depth is:', t.d) -#' -#'@keywords manip -#' -#'@export +#' +#' @export thermo.depth <- function(wtr, depths, Smin = 0.1, seasonal=TRUE, index=FALSE, mixed.cutoff=1){ if(any(is.na(wtr))){ diff --git a/R/timeseries.functions.R b/R/timeseries.functions.R index 3ccb339..d7d975f 100644 --- a/R/timeseries.functions.R +++ b/R/timeseries.functions.R @@ -1,4 +1,52 @@ -#Timeseries functions for r Lake Analyzer +#' @title Calculate physical indices for a timeseries. +#' +#' @description Functions for simplifying the calculation of physical indices for a +#' timeseries of observation data. Can usually be called directly on data +#' loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' These are wrapper functions that accept a timeseries of data and call the +#' core physical metric functions (like \code{\link{schmidt.stability}}) on +#' each timestep. +#' +#' @family Timeseries functions for r Lake Analyzer +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +#' where ##.# is depth in meters. +#' @param slope The minimum density gradient (kg/m^3/m) that can be called the +#' thermocline +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will return an NA value. If +#' true, best effort will be made to calculate indices despite NA values. +#' @param ... Additional parameters passed to underlying base function (e.g., +#' index=TRUE for thermo.depth) +#' @return Returns a data frame with the timeseries of calculated derivatives. +#' All include a \sQuote{datetime} column, but derivative columns differ +#' between functions. +#' @seealso For loading input data \code{\link{load.ts}}, +#' \code{\link{load.bathy}}. +#' +#' For the underlying functions operating at each timestep +#' \code{\link{meta.depths}}, \code{\link{thermo.depth}}, +#' \code{\link{schmidt.stability}}, \code{\link{lake.number}}, +#' \code{\link{internal.energy}}. +#' @keywords manip +#' @examples +#' +#' #Get the path for the package example file included +#' exampleFilePath <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' +#' #Load +#' sparkling.temp = load.ts(exampleFilePath) +#' +#' #calculate and plot the metalimnion depths +#' m.d = ts.meta.depths(sparkling.temp) +#' +#' plot(m.d$datetime, m.d$top, type='l', ylab='Meta Depths (m)', xlab='Date', col='blue') +#' lines(m.d$datetime, m.d$bottom, col='red') +#' +#' +#' @export ts.meta.depths <- function(wtr, slope=0.1, na.rm=FALSE, ...){ @@ -25,6 +73,57 @@ ts.meta.depths <- function(wtr, slope=0.1, na.rm=FALSE, ...){ } + +#' @title Calculate physical indices for a timeseries. +#' +#' @description Functions for simplifying the calculation of physical indices for a +#' timeseries of observation data. Can usually be called directly on data +#' loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' These are wrapper functions that accept a timeseries of data and call the +#' core physical metric functions (like \code{\link{schmidt.stability}}) on +#' each timestep. +#' +#' @family Timeseries functions for r Lake Analyzer +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +#' where ##.# is depth in meters. +#' @param Smin The minimum density gradient cutoff (kg/m^3/m) defining the +#' metalimion +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will return an NA value. If +#' true, best effort will be made to calculate indices despite NA values. +#' @param ... Additional parameters passed to underlying base function (e.g., +#' index=TRUE for thermo.depth) +#' @return Returns a data frame with the timeseries of calculated derivatives. +#' All include a \sQuote{datetime} column, but derivative columns differ +#' between functions. +#' @seealso For loading input data \code{\link{load.ts}}, +#' \code{\link{load.bathy}}. +#' +#' For the underlying functions operating at each timestep +#' \code{\link{meta.depths}}, \code{\link{thermo.depth}}, +#' \code{\link{schmidt.stability}}, \code{\link{lake.number}}, +#' \code{\link{internal.energy}}. +#' @keywords manip +#' @examples +#' +#' #Get the path for the package example file included +#' exampleFilePath <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' +#' #Load +#' sparkling.temp = load.ts(exampleFilePath) +#' +#' +#' #calculate and plot the thermocline depth +#' t.d = ts.thermo.depth(sparkling.temp) +#' +#' plot(t.d$datetime, t.d$thermo.depth, type='l', ylab='Thermocline Depth (m)', xlab='Date') +#' +#' @export +#' + ts.thermo.depth <- function(wtr, Smin = 0.1, na.rm=FALSE, ...){ depths = get.offsets(wtr) @@ -57,6 +156,38 @@ ts.thermo.depth <- function(wtr, Smin = 0.1, na.rm=FALSE, ...){ return(output) } +#' @title Calculate physical indices for a timeseries. +#' +#' @description Functions for simplifying the calculation of physical indices for a +#' timeseries of observation data. Can usually be called directly on data +#' loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' These are wrapper functions that accept a timeseries of data and call the +#' core physical metric functions (like \code{\link{schmidt.stability}}) on +#' each timestep. +#' +#' @family Timeseries functions for r Lake Analyzer +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +#' where ##.# is depth in meters. +#' @param bathy A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will return an NA value. If +#' true, best effort will be made to calculate indices despite NA values. +#' @return Returns a data frame with the timeseries of calculated derivatives. +#' All include a \sQuote{datetime} column, but derivative columns differ +#' between functions. +#' @seealso For loading input data \code{\link{load.ts}}, +#' \code{\link{load.bathy}}. +#' +#' For the underlying functions operating at each timestep +#' \code{\link{meta.depths}}, \code{\link{thermo.depth}}, +#' \code{\link{schmidt.stability}}, \code{\link{lake.number}}, +#' \code{\link{internal.energy}}. +#' @keywords manip +#' @export ts.schmidt.stability <- function(wtr, bathy, na.rm=FALSE){ depths = get.offsets(wtr) @@ -93,6 +224,43 @@ ts.schmidt.stability <- function(wtr, bathy, na.rm=FALSE){ } +#' @title Calculate physical indices for a timeseries. +#' +#' @description Functions for simplifying the calculation of physical indices for a +#' timeseries of observation data. Can usually be called directly on data +#' loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' These are wrapper functions that accept a timeseries of data and call the +#' core physical metric functions (like \code{\link{schmidt.stability}}) on +#' each timestep. +#' +#' @family Timeseries functions for r Lake Analyzer +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +#' where ##.# is depth in meters. +#' @param bathy A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param wnd A data frame of wind speeds (in m/s). Loaded using +#' \code{\link{load.ts}} +#' @param wnd.height Height of the anemometer above the lake surface in meters +#' @param seasonal Boolean indicating if seasonal thermocline should be used in +#' calculation. +#' @return Returns a data frame with the timeseries of calculated derivatives. +#' All include a \sQuote{datetime} column, but derivative columns differ +#' between functions. +#' @seealso For loading input data \code{\link{load.ts}}, +#' \code{\link{load.bathy}}. +#' +#' For the underlying functions operating at each timestep +#' \code{\link{meta.depths}}, \code{\link{thermo.depth}}, +#' \code{\link{schmidt.stability}}, \code{\link{lake.number}}, +#' \code{\link{internal.energy}}. +#' @keywords manip +#' @export +#' + + ts.lake.number <- function(wtr, wnd, wnd.height, bathy, seasonal=TRUE){ depths = get.offsets(wtr) @@ -138,7 +306,40 @@ ts.lake.number <- function(wtr, wnd, wnd.height, bathy, seasonal=TRUE){ return(output) } - +#' @title Calculate physical indices for a timeseries. +#' +#' @description Functions for simplifying the calculation of physical indices for a +#' timeseries of observation data. Can usually be called directly on data +#' loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' These are wrapper functions that accept a timeseries of data and call the +#' core physical metric functions (like \code{\link{schmidt.stability}}) on +#' each timestep. +#' +#' @family Timeseries functions for r Lake Analyzer +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +#' where ##.# is depth in meters. +#' @param bathy A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param wnd A data frame of wind speeds (in m/s). Loaded using +#' \code{\link{load.ts}} +#' @param wnd.height Height of the anemometer above the lake surface in meters +#' @param seasonal Boolean indicating if seasonal thermocline should be used in +#' calculation. +#' @return Returns a data frame with the timeseries of calculated derivatives. +#' All include a \sQuote{datetime} column, but derivative columns differ +#' between functions. +#' @seealso For loading input data \code{\link{load.ts}}, +#' \code{\link{load.bathy}}. +#' +#' For the underlying functions operating at each timestep +#' \code{\link{meta.depths}}, \code{\link{thermo.depth}}, +#' \code{\link{schmidt.stability}}, \code{\link{lake.number}}, +#' \code{\link{internal.energy}}. +#' @keywords manip +#' @export ts.uStar <- function(wtr, wnd, wnd.height, bathy, seasonal=TRUE){ depths = get.offsets(wtr) @@ -179,6 +380,52 @@ ts.uStar <- function(wtr, wnd, wnd.height, bathy, seasonal=TRUE){ } + + +#' Calculate Wedderburn number for a timeseries. +#' +#' Function for simplifying the calculation of Wedderburn Number. Can usually +#' be called directly on data loaded directly using \code{\link{load.ts}} and +#' \code{\link{load.bathy}}. +#' +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}} +#' @param wnd A data frame of wind speeds (in m/s). Loaded using +#' \code{\link{load.ts}} +#' @param wnd.height Height of the anemometer above the lake surface in meters +#' @param bathy A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param Ao Numeric value for the water body surface area (m^2) at zero meters +#' depth +#' @param seasonal Boolean indicating if seasonal thermocline should be used in +#' calculation. +#' @return Returns a data frame with the timeseries of Wedderburn number. +#' Includes a \sQuote{datetime} column. +#' @seealso \code{wedderburn.number},\code{ts.lake.number} +#' @references Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +#' Advances in Applied Mechanics 27, 353-370. +#' @keywords arith +#' @examples +#' +#' +#' #Get the path for the package example file included +#' wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' wnd.path <- system.file('extdata', 'Sparkling.daily.wnd', package="rLakeAnalyzer") +#' bathy.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng lake, in Wisconsin. +#' sp.wtr = load.ts(wtr.path) +#' sp.wnd = load.ts(wnd.path) +#' sp.bathy = load.bathy(bathy.path) +#' +#' sp.area = 64e4 #Area of Sparkling lake in m^2 +#' wnd.height = 2 #Height of Sparkling lake anemometer +#' +#' w.n = ts.wedderburn.number(sp.wtr, sp.wnd, wnd.height, sp.bathy, sp.area) +#' plot(w.n$datetime, w.n$wedderburn.number, type='l', ylab='Wedderburn Number', xlab='Date') +#' +#' @export ts.wedderburn.number <- function(wtr, wnd, wnd.height, bathy, Ao, seasonal=TRUE){ depths = get.offsets(wtr) @@ -229,6 +476,52 @@ ts.wedderburn.number <- function(wtr, wnd, wnd.height, bathy, Ao, seasonal=TRUE) } + + +#' Calculate volume-weighted average water temperature across a range of depths +#' for a timeseries. +#' +#' Function for simplifying the calculation of Wedderburn Number. Can usually +#' be called directly on data loaded directly using \code{\link{load.ts}} and +#' \code{\link{load.bathy}}. +#' +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}} +#' @param top Either a single numeric depth value to be used across the entire +#' timeseries, or a vector of same length as the timeseries (e.g., +#' \code{nrow(wtr)}). This is useful when calculating a time-varying layer +#' average, like average epilimnion temperature. +#' @param bottom Either a single numeric depth value to be used across the +#' entire timeseries, or a vector of same length as the timeseries (e.g., +#' \code{nrow(wtr)}). This is useful when calculating a time-varying layer +#' average, like average epilimnion temperature. +#' @param bathy A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will return an NA value. If +#' true, best effort will be made to calculate indices despite NA values. +#' @return Returns a data frame with the timeseries of the average layer +#' temperature. Includes \sQuote{datetime} and \sQuote{layer.temp} columns. +#' @seealso \code{layer.temperature} +#' @keywords arith +#' @examples +#' +#' +#' #Get the path for the package example file included +#' wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' bathy.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng lake, in Wisconsin. +#' sp.wtr = load.ts(wtr.path) +#' sp.bathy = load.bathy(bathy.path) +#' +#' +#' l.t = ts.layer.temperature(sp.wtr, 0, 18, sp.bathy) +#' plot(l.t$datetime, l.t$layer.temp, type='l', +#' ylab='Volumetrically averaged lake temperature', xlab='Date') +#' +#' @export ts.layer.temperature <- function(wtr, top, bottom, bathy, na.rm=FALSE){ depths = get.offsets(wtr) @@ -278,6 +571,38 @@ ts.layer.temperature <- function(wtr, top, bottom, bathy, na.rm=FALSE){ return(data.frame(datetime=get.datetime(wtr), layer.temp=l.t)) } +#' @title Calculate physical indices for a timeseries. +#' +#' @description Functions for simplifying the calculation of physical indices for a +#' timeseries of observation data. Can usually be called directly on data +#' loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. +#' +#' These are wrapper functions that accept a timeseries of data and call the +#' core physical metric functions (like \code{\link{schmidt.stability}}) on +#' each timestep. +#' +#' @family Timeseries functions for r Lake Analyzer +#' +#' @param wtr A data frame of water temperatures (in Celsius). Loaded using +#' \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +#' where ##.# is depth in meters. +#' @param bathy A data frame containing hypsometric data. Loaded using +#' \code{\link{load.bathy}} +#' @param na.rm Boolean indicated if step-by-step removal of NA's should be +#' tried. If false, a timestep with any NA values will return an NA value. If +#' true, best effort will be made to calculate indices despite NA values. +#' @return Returns a data frame with the timeseries of calculated derivatives. +#' All include a \sQuote{datetime} column, but derivative columns differ +#' between functions. +#' @seealso For loading input data \code{\link{load.ts}}, +#' \code{\link{load.bathy}}. +#' +#' For the underlying functions operating at each timestep +#' \code{\link{meta.depths}}, \code{\link{thermo.depth}}, +#' \code{\link{schmidt.stability}}, \code{\link{lake.number}}, +#' \code{\link{internal.energy}}. +#' @keywords manip +#' @export ts.internal.energy <- function(wtr, bathy, na.rm=FALSE){ depths = get.offsets(wtr) diff --git a/R/uStar.R b/R/uStar.R index d0ba1ee..0ac4cd0 100644 --- a/R/uStar.R +++ b/R/uStar.R @@ -1,9 +1,43 @@ -# wndSpeed: wind speed in m/s -# wndHeight: height of wind measurement in m -# averageEpiDense: average epilimnion density in kg m-3 - -#----Author: R. Iestyn. Woolway ---- - +#' @title Calculates the water friction velocity, uStar +#' +#' @description uStar is the water friction velocity due to wind stress at the lake surface, +#' it is calculated following the methods of Imberger (1985) as a function of +#' the shear stress of air (Fischer et al., 1979), drag coefficient for +#' momentum (Hicks, 1972), and a dimensionless constant (von Karman constant) +#' that decribes the logarithmic velocity profile at the air-water interface +#' +#' +#' @param wndSpeed a numeric vector of wind speed in m s-1 +#' @param wndHeight a numeric vector of wind measurement height in m +#' @param averageEpiDense a numeric vector of epilimnion density in kg m-3 +#' @return a numeric vector of uStar +#' @seealso \code{\link{ts.uStar}} \code{\link{layer.density}} +#' @references +#' +#' Hicks, B.B., 1972. \emph{A procedure for the formulation of bulk transfer +#' coefficients over water bodies of different sizes}. Boundary-Layer +#' Meterology 3: 201-213. +#' +#' Amorocho, J., DeVries, J.J., 1980. \emph{A new evaluation of the wind stress +#' coefficient over water surfaces}. Journal of Geophysical Research 85: +#' 433-442. +#' +#' Fischer, H.B., List, E.J., Koh, R.C.Y., Imberger, J., Brooks, N.H., 1979. +#' \emph{Mixing in inland and coastal waters}. Academic Press. +#' +#' Imberger, J., 1985. \emph{The diurnal mixed layer}. Limnology and +#' Oceanography 30: 737-770. +#' @keywords manip +#' @examples +#' +#' +#' wndSpeed <- c(5.1,6.3,6.3,5.2,7,7.2) +#' wndHeight <- 2 +#' averageEpiDense <- c(14,15,14.2,13,12,12) +#' +#' cat('uStar for input vector is: ') +#' cat(uStar(wndSpeed,wndHeight,averageEpiDense)) +#' @export uStar <- function(wndSpeed,wndHeight,averageEpiDense){ # define constants diff --git a/R/water.density.R b/R/water.density.R index 9af040c..ac735f8 100644 --- a/R/water.density.R +++ b/R/water.density.R @@ -1,11 +1,25 @@ -# T is in ?C -# S is in Pratical Salinity Scale units (dimensionless) -# water.density is in grams/Liter - -# <<--- Effective range of function: 0-40?C, 0.5-43 Salinity--->> - -# -- Author: R. Iestyn. Woolway ---- - +#' @title Estimate Water Density +#' +#' @description Density of water from temperature and salinity +#' +#' +#' @param wtr a numeric vector of water temperature in degrees Celsius +#' @param sal a numeric vector of salinity in Practical Salinity Scale units +#' @return A numeric vector of water densities in kg/m^3. +#' @references Martin, J.L., McCutcheon, S.C., 1999. \emph{Hydrodynamics and +#' Transport for Water Quality Modeling.} Lewis Publications, Boca Raton, FL, +#' 794pp. +#' +#' Millero, F.J., Poisson, A., 1981. \emph{International one-atmosphere +#' equation of state of seawater.} UNESCO Technical Papers in Marine Science. +#' No. 36. +#' @keywords arith +#' @examples +#' +#' #Plot water density for water between 1 and 30 deg C +#' dens = water.density(1:30) +#' plot(1:30, dens, xlab="Temp(deg C)", ylab="Density(kg/m^3)") +#' @export water.density <- function(wtr, sal = wtr*0){ if(length(wtr) != length(sal)){ diff --git a/R/wedderburn.number.R b/R/wedderburn.number.R index 1d2b991..93a0b7c 100644 --- a/R/wedderburn.number.R +++ b/R/wedderburn.number.R @@ -1,7 +1,42 @@ -# ---Author: Jake Zwart, 2013-04-21 --- -#translated from Matlab Script - Author Jordan Read, 2009 -## from wedderburnNumber.m in https://github.com/jread-usgs/Lake-Analyzer/ - +#' @title Calculates Wedderburn Number for a lake. +#' +#' @description Wedderburn Number (Wn) is a dimensionless parameter measuring the balance +#' between wind stress and bouyancy force and is used to estimate the amount of +#' upwelling occuring in a lake. When Wn is much greater than 1, the bouyancy +#' force is much greater than the wind stress and therefore there is a strong +#' vertical stratification with little horizontal variation in the +#' stratification. When Wn is much less than 1, the wind stress is much greater +#' than the bouyancy force and upwelling is likely occuring at the upwind end +#' of the lake. When Wn is near 1, the bouyance force and wind stress are +#' nearly equal and horizontal mixing is considered important +#' +#' +#' @param delta_rho Numeric value for the water density difference between the +#' epilimnion and hypolimnion (kg/m^3) +#' @param metaT Numeric value for the thickness of the water body's surface +#' layer (m) +#' @param uSt Numeric value for the water friction velocity due to wind stress +#' (m/s) +#' @param Ao Numeric value for the water body surface area (m^2) at zero meters +#' depth +#' @param AvHyp_rho Numeric value for the average water density of the +#' hypolimnion layer (kg/m^3) +#' @return The dimensionless numeric value of Wedderburn Number +#' @seealso \code{\link{ts.wedderburn.number}} \code{\link{lake.number}} +#' @references Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +#' Advances in Applied Mechanics 27, 353-370. +#' @keywords arith +#' @examples +#' +#' delta_rho <- c(3.1,1.5) +#' metaT <- c(5.5,2.4) +#' uSt <- c(0.0028,0.0032) +#' Ao <- c(80300,120000) +#' AvHyp_rho <- c(999.31,999.1) +#' wedderburn.number(delta_rho, metaT, uSt, Ao, AvHyp_rho) +#' +#' @export +#' wedderburn.number <- function(delta_rho,metaT,uSt,Ao,AvHyp_rho){ # Calculates the Wedderburn number for a particular system using the following equation: diff --git a/R/whole.lake.temperature.R b/R/whole.lake.temperature.R index 3102730..3510f54 100644 --- a/R/whole.lake.temperature.R +++ b/R/whole.lake.temperature.R @@ -1,17 +1,17 @@ #' @title Get volumetrically averaged whole lake temperature -#' -#' @description Calculates volumetrically weighted average whole lake temperature using -#' the supplied water temperature timeseries. -#' +#' +#' @description Calculates volumetrically weighted average whole lake temperature using the +#' supplied water temperature timeseries. +#' +#' #' @param wtr a numeric vector of water temperature in degrees C. -#' @param depths a numeric vector corresponding to the depths (in m) of the wtr measurements -#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to bthD depths -#' @param bthD a numeric vector of depths (m) which correspond to areal measures in bthA -#' -#' @import rLakeAnalyzer -#' +#' @param depths a numeric vector corresponding to the depths (in m) of the wtr +#' measurements +#' @param bthA a numeric vector of cross sectional areas (m^2) corresponding to +#' bthD depths +#' @param bthD a numeric vector of depths (m) which correspond to areal +#' measures in bthA #' @seealso \code{\link{hypo.temperature}}, \code{\link{epi.temperature}} -#' #' @export whole.lake.temperature <- function(wtr, depths, bthA, bthD){ diff --git a/R/wtr.heatmap.layers.R b/R/wtr.heatmap.layers.R index dcbe637..8734d3c 100644 --- a/R/wtr.heatmap.layers.R +++ b/R/wtr.heatmap.layers.R @@ -1,4 +1,35 @@ -#heat map with lines for thermocline, meta top and bottom depths +#' @title Plots water temperature heatmap with major limnetic layers indicated +#' +#' @description This creates a heat map of water temperature similar to +#' \code{\link{wtr.heat.map}} with additional lines drawn to denote the +#' thermocline, and the top and bottom of the metalimnion as calculated using +#' \code{\link{ts.meta.depths}} and \code{\link{thermo.depth}}. +#' +#' +#' @param wtr Data frame of water temperature loaded with +#' \code{\link{load.ts}}. +#' @param \dots Additional parameters supplied to \code{\link{filled.contour}} +#' to modify defaults. Common examples include \code{zlim} and +#' \code{plot.title}. +#' @note This plot cannot be used in customized multi-panel figures +#' using\code{\link{layout}} as layout is already used in the filled.contour +#' plotting function. +#' @seealso \code{\link{wtr.heat.map}} \code{\link{load.ts}} +#' \code{\link{ts.meta.depths}} \code{\link{ts.thermo.depth}} +#' @keywords hplot +#' @examples +#' +#' #Get the path for the package example file included +#' wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng Lake, Wisconsin. +#' wtr = load.ts(wtr.path) +#' +#' # generate default plot +#' \dontrun{ +#' wtr.heatmap.layers(wtr) +#' } +#' @export wtr.heatmap.layers <- function(wtr, ...){ td = ts.thermo.depth(wtr) @@ -47,7 +78,7 @@ wtr.heatmap.layers <- function(wtr, ...){ } df = list(wtr,td,md) ##Create list of data frame to join - wtr.all = join_all(df, by="datetime") ##Joins thermodepths, metadepths with temp data + wtr.all = plyr::join_all(df, by="datetime") ##Joins thermodepths, metadepths with temp data nn = ncol(wtr.all) -3 depths = get.offsets(wtr.all[,2:nn]) @@ -60,22 +91,24 @@ wtr.heatmap.layers <- function(wtr, ...){ y = depths - filled.contour(wtr.dates + graphics::filled.contour(wtr.dates , y , wtr.mat , ylim=c(max(depths),0) , zlim=c(min(wtr.mat,na.rm=TRUE) , max(wtr.mat,na.rm=TRUE)) , nlevels=100 - , color.palette=colorRampPalette(c("violet","blue","cyan", "green3", "yellow", "orange", "red") + , color.palette = grDevices::colorRampPalette(c("violet","blue","cyan", "green3", "yellow", "orange", "red") , bias = 1 , space = "rgb") , ylab="Depth (m)" - , key.title=title((main="Temperature (\u00B0C)") + , key.title=graphics::title((main="Temperature (\u00B0C)") ,adj=0.2, cex.main=1) - ,plot.axes = {lines(x=wtr.dates,y=wtr.all$thermo.depth,col="black",lwd = 2) - lines(x=wtr.dates,y=wtr.all$top, col="gray50", lwd = 2) - lines(x=wtr.dates,y=wtr.all$bottom,col="gray80", lwd = 2) - axis(side = 2) - axis(side = 3, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(depths)), tck = -0.03)}) + ,plot.axes = {graphics::lines(x=wtr.dates,y=wtr.all$thermo.depth,col="black",lwd = 2) + graphics::lines(x=wtr.dates,y=wtr.all$top, col="gray50", lwd = 2) + graphics::lines(x=wtr.dates,y=wtr.all$bottom,col="gray80", lwd = 2) + graphics::axis(side = 2) + graphics::axis(side = 3, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(depths)), tck = -0.03)}) + + } diff --git a/R/wtr-layer-segments.R b/R/wtr.layer.segments.R similarity index 65% rename from R/wtr-layer-segments.R rename to R/wtr.layer.segments.R index 7e69a87..4bdcaa5 100644 --- a/R/wtr-layer-segments.R +++ b/R/wtr.layer.segments.R @@ -1,33 +1,42 @@ -#' @export #' @title Exploration of lake water column layers -#' @description Extract water column parameters of a given parameter from a profile using the split-and-merge algorithm. -#' The cline is defined as the midpoint of the layer of water where the physical property change in the greatest over a -#' small difference. The exact cline depends on the specification of measure. For example if temperature is specified, -#' then we can expect cline to output the thermocline. +#' +#' @description Extract water column parameters of a given parameter from a profile using +#' the split-and-merge algorithm. The cline is defined as the midpoint of the +#' layer of water where the physical property change in the greatest over a +#' small difference. The exact cline depends on the specification of measure. +#' For example if temperature is specified, then we can expect cline to output +#' the thermocline. +#' +#' #' @param data data supplied as a bare (unquoted) value -#' @param depth depth in metres; should be an increasing vector; supplied as a bare (unquoted) value -#' @param measure parameter measured in the water column profile; supplied as a bare (unquoted) value +#' @param depth depth in metres; should be an increasing vector; supplied as a +#' bare (unquoted) value +#' @param measure parameter measured in the water column profile; supplied as a +#' bare (unquoted) value #' @param thres error norm; defaults to 0.1 #' @param z0 initial depth in metres. Defaults to 2.5m #' @param zmax maximum depth in metres: defaults to 150m -#' @param nseg optional parameter to define the number of segments a priori; defaults to an unconstrained approach whereby -#' the algorithm determines segmentations by minimzing the error norm over each segment -#' @return a dataframes with a list column. This includes: nseg (number of segments), mld (mix layer depth), cline (the -#' midpoint of the segment connecting inflection points that has the maximum slope; thermocline for temperature measures) -#' and segments calculated by the sm algorithm. - -#' @references Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from Oceanic Profile Data. Journal of -#' Atmospheric and Oceanic Technology. 20(2), 319-329. +#' @param nseg optional parameter to define the number of segments a priori; +#' defaults to an unconstrained approach whereby the algorithm determines +#' segmentations by minimzing the error norm over each segment +#' @return a dataframes with a list column. This includes: nseg (number of +#' segments), mld (mix layer depth), cline (the midpoint of the segment +#' connecting inflection points that has the maximum slope; thermocline for +#' temperature measures) and segments calculated by the sm algorithm. +#' @references Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from +#' Oceanic Profile Data. Journal of Atmospheric and Oceanic Technology. 20(2), +#' 319-329. #' @examples +#' #' data("latesummer") #' df1 <- wtr.layer(depth=latesummer$depth, measure = latesummer$temper) #' df1$mld #' df1$segments -#' +#' #' wtr.layer(data = latesummer, depth=depth, measure = temper, nseg=4) -#' - - +#' +#' +#' @export wtr.layer wtr.layer <- function(data, depth, @@ -81,26 +90,30 @@ wtr.layer <- } -#' @export #' @title Data filter to remove soak, heave and upcast +#' +#' @description \itemize{ \item Soak period: water profiling instruments typically require a +#' soak period where you let the instrument rest submerged at the surface. +#' While it is "soaking" it is collecting data. We don't want that data \item +#' Upcast versus downcast: typically instruments are turned on before you put +#' them in the water and turn them off once you pull them out. The data +#' consequence of that is that you collect both the "downcast" and the +#' "upcast". In some case the upcast is of interest but usually it isn't. And +#' because we would prefer increasing depth data it is better to remove an +#' upcast if it is present. \item Heave: when lowering the instrument in rough +#' weather a boat will heave side to side. Sometimes it will heave enough that +#' you get small data groupings where the decreases a little while the boat +#' heaves then go down. The overall trend is still down but those slight +#' upticks in depth cause problems for our algorithm. } +#' +#' #' @param z0 depth vector #' @param run_length Length of run upon which to start the soak removal -#' @param index Logical: Should the function return an index value or actual value? -#' @return index values of z0 of filtered data. Will return a warning if the function removed more than 10% of the data -#' @description -#' \itemize{ -#' \item Soak period: water profiling instruments typically require a soak period where you let the instrument rest -#' submerged at the surface. While it is "soaking" it is collecting data. We don't want that data -#' \item Upcast versus downcast: typically instruments are turned on before you put them in the water and turn them off -#' once you pull them out. The data consequence of that is that you collect both the "downcast" and the "upcast". In some -#' case the upcast is of interest but usually it isn't. And because we would prefer increasing depth data it is better to -#' remove an upcast if it is present. -#' \item Heave: when lowering the instrument in rough weather a boat will heave side to side. Sometimes it will heave -#' enough that you get small data groupings where the decreases a little while the boat heaves then go down. The overall -#' trend is still down but those slight upticks in depth cause problems for our algorithm. -#' } - - +#' @param index Logical: Should the function return an index value or actual +#' value? +#' @return index values of z0 of filtered data. Will return a warning if the +#' function removed more than 10% of the data +#' @export depth.filter depth.filter <- function(z0, run_length=20, index = FALSE) { n_start <- length(z0) diff --git a/R/wtr.lineseries.R b/R/wtr.lineseries.R index 7988688..a38b07a 100644 --- a/R/wtr.lineseries.R +++ b/R/wtr.lineseries.R @@ -1,3 +1,25 @@ +#' @title Creates a line based plot of temperature profile time series +#' +#' @description A non-heat map approach to visualizing a water temperature profile useful +#' for identify temperature trends over time at discrete depths and diagnosing +#' issues with data. +#' +#' +#' @param wtr Data frame of water temperature loaded with +#' \code{\link{load.ts}}. +#' @param ylab y axis title +#' @param \dots Additional parameters supplied to the plot function +#' @seealso See \code{\link{load.ts}} and \code{\link{wtr.heat.map}} +#' @keywords hplot +#' @examples +#' +#' exampleFilePath <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") +#' wtr= load.ts(exampleFilePath) +#' \dontrun{ +#' wtr.lineseries(wtr, ylab = "Temperature C") +#' } +#' @export +#' wtr.lineseries = function(wtr, ylab = "Temperature C",...){ nn = ncol(wtr) # number of columns in data set @@ -6,7 +28,7 @@ wtr.lineseries = function(wtr, ylab = "Temperature C",...){ starttime = min(wtr[,1]) #earliest date endtime = max(wtr[,1]) #latest date - colors1 = colorRampPalette(c("red" + colors1 = grDevices::colorRampPalette(c("red" ,"orange" ,"yellow" ,"green3" @@ -61,7 +83,7 @@ wtr.lineseries = function(wtr, ylab = "Temperature C",...){ } #tiff('wtf2.tiff',width=1600, height=900, res=300, compression='lzw') #plot temp over time; each depth as a unique line - plot(wtr[,1], + graphics::plot(wtr[,1], wtr[,2] ,type='l' ,col=colors[1] @@ -75,19 +97,19 @@ wtr.lineseries = function(wtr, ylab = "Temperature C",...){ , ... ) for( i in 3:ncol(wtr)){ - lines(wtr[,1], wtr[,i], type='l', col=colors[i]) + graphics::lines(wtr[,1], wtr[,i], type='l', col=colors[i]) } # x axis - axis(side = 1, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(mmin), tck = -0.03) - abline(h = mmin, col = "black", lty = 1) + graphics::axis(side = 1, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(mmin), tck = -0.03) + graphics::abline(h = mmin, col = "black", lty = 1) # y axis - axis (side = 2, pos = c(starttime), at = NULL, las = 1) - abline(v = starttime, col = "black") + graphics::axis (side = 2, pos = c(starttime), at = NULL, las = 1) + graphics::abline(v = starttime, col = "black") # generate and place legend - legend( "top" + graphics::legend( "top" , col = colors[c(1, nn)] , lty = 1, bty = "n" , legend = c("Surface", "Bottom") diff --git a/R/wtr.plot.temp.R b/R/wtr.plot.temp.R index 424780a..98a9a3e 100644 --- a/R/wtr.plot.temp.R +++ b/R/wtr.plot.temp.R @@ -1,33 +1,29 @@ - -#'@title -#'Creates a time series plot of the thermocline and top and -#'bottom of the metalimnion -#' -#'@description -#' A line based plot of calculated depths of the thermocline, and -#' top and bottom of the metalimnion from a temperature profile time series. -#' -#'@param wtr Data frame of water temperature loaded with \code{\link{load.ts}}. -#'@param ... Additional paramters supplied to \code{\link{ts.meta.depths}} and \code{\link{ts.thermo.depth}} -#' -#'@author Jennifer Brentrup, Taylor Leach, Luke Winslow -#' -#'@seealso \code{\link{load.ts}} and \code{\link{wtr.lineseries}} -#' -#'@keywords hplot -#' -#'@examples -#' -#'wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") -#' -#'#Load data for example lake, Sparkilng Lake, Wisconsin. -#'wtr = load.ts(wtr.path) -#' -#'\dontrun{ -#'wtr.plot.temp(wtr) -#'} -#' -#'@export +#' @title Creates a time series plot of the thermocline and top and bottom of the +#' metalimnion +#' +#' @description A line based plot of calculated depths of the thermocline, and top and +#' bottom of the metalimnion from a temperature profile time series. +#' +#' +#' @param wtr Data frame of water temperature loaded with +#' \code{\link{load.ts}}. +#' @param ... Additional paramters supplied to \code{\link{ts.meta.depths}} and +#' \code{\link{ts.thermo.depth}} +#' @seealso \code{\link{load.ts}} and \code{\link{wtr.lineseries}} +#' @keywords hplot +#' @examples +#' +#' +#' wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng Lake, Wisconsin. +#' wtr = load.ts(wtr.path) +#' +#' \dontrun{ +#' wtr.plot.temp(wtr) +#' } +#' +#' @export wtr.plot.temp = function(wtr, ...){ depths = get.offsets(wtr[,-1]) @@ -35,7 +31,7 @@ wtr.plot.temp = function(wtr, ...){ md = ts.meta.depths(wtr, ...) df = list(wtr,td,md) ##Create list of data frame to join - wtr.all = join_all(df, by="datetime") ##Joins thermodepths, metadepths with temp data + wtr.all = plyr::join_all(df, by="datetime") ##Joins thermodepths, metadepths with temp data nn = ncol(wtr) # number of columns in data set starttime = min(wtr[,1]) #earliest date @@ -84,7 +80,7 @@ wtr.plot.temp = function(wtr, ...){ xxlab <- " " } - plot(wtr.all[,nn+1]~wtr.all[,1], + graphics::plot(wtr.all[,nn+1]~wtr.all[,1], type='l', col="black", ylab="Depth (m)", @@ -94,19 +90,19 @@ wtr.plot.temp = function(wtr, ...){ xlim=c(starttime,endtime), axes=F ) - lines(wtr.all[,nn+2]~wtr.all[,1], type='l',col="orangered") - lines(wtr.all[,nn+3]~wtr.all[,1], type='l',col="navy") + graphics::lines(wtr.all[,nn+2]~wtr.all[,1], type='l',col="orangered") + graphics::lines(wtr.all[,nn+3]~wtr.all[,1], type='l',col="navy") # x axis - axis(side = 3, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(depths)), tck = -0.03) - segments(c(starttime),c(min(depths)),c(endtime),c(min(depths)), col = "black", lty = 1) + graphics::axis(side = 3, labels=format(datestoshow, ttformat), at = datestoshow, pos = c(min(depths)), tck = -0.03) + graphics::segments(c(starttime),c(min(depths)),c(endtime),c(min(depths)), col = "black", lty = 1) # y axis - axis (side = 2, pos = c(starttime), at = NULL, las = 1) - segments(c(starttime),c(min(depths)),c(starttime),c(max(depths)), col = "black") + graphics::axis (side = 2, pos = c(starttime), at = NULL, las = 1) + graphics::segments(c(starttime),c(min(depths)),c(starttime),c(max(depths)), col = "black") # generate and place legend - legend( "bottom" + graphics::legend( "bottom" , col = c("orangered", "black","navy") , lty = 1, lwd = 3, bty = "n" , legend = c("Metalimnion Top (m)","Thermocline Depth (m)", "Metalimnion Bottom (m)") diff --git a/R/wtr.plotting.R b/R/wtr.plotting.R index 315daf4..c47bf83 100644 --- a/R/wtr.plotting.R +++ b/R/wtr.plotting.R @@ -1,3 +1,29 @@ +#' @title Plots a heat-map of water temperature. +#' +#' @description This creates a simple, default heatmap of water temperature. +#' +#' +#' @param wtr Data frame of water temperature loaded with +#' \code{\link{load.ts}}. +#' @param ... Additional parameters supplied to \code{\link{filled.contour}} +#' to modify defaults. Common examples include \code{zlim} and +#' \code{plot.title}. +#' @seealso \code{\link{load.ts}} +#' @keywords hplot +#' @examples +#' +#' #Get the path for the package example file included +#' wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") +#' +#' #Load data for example lake, Sparkilng Lake, Wisconsin. +#' sp.wtr = load.ts(wtr.path) +#' +#' #Plot default figure +#' wtr.heat.map(sp.wtr) +#' +#' #Change defaults supplied to filled.contour +#' wtr.heat.map(sp.wtr, zlim=c(0,15), plot.title="Sparkling Water Temp (C)") +#' @export wtr.heat.map <- function(wtr, ...){ depths = get.offsets(wtr) @@ -10,8 +36,8 @@ wtr.heat.map <- function(wtr, ...){ y = depths - filled.contour(wtr.dates, y, wtr.mat, ylim=c(max(depths),0), nlevels=100, - color.palette=colorRampPalette(c("violet","blue","cyan", "green3", "yellow", "orange", "red"), + graphics::filled.contour(wtr.dates, y, wtr.mat, ylim=c(max(depths),0), nlevels=100, + color.palette=grDevices::colorRampPalette(c("violet","blue","cyan", "green3", "yellow", "orange", "red"), bias = 1, space = "rgb"), ylab='Depths (m)', ...) #Sets range and value of color hues } diff --git a/README-example-1.png b/README-example-1.png new file mode 100644 index 0000000..c01eacf Binary files /dev/null and b/README-example-1.png differ diff --git a/README-example-2.png b/README-example-2.png new file mode 100644 index 0000000..3b958a3 Binary files /dev/null and b/README-example-2.png differ diff --git a/README.Rmd b/README.Rmd new file mode 100644 index 0000000..5eca9cb --- /dev/null +++ b/README.Rmd @@ -0,0 +1,71 @@ +--- +output: github_document +--- + + + +```{r, echo = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#>", + fig.path = "README-" +) +``` + +[![Build Status](https://travis-ci.org/GLEON/rLakeAnalyzer.svg?branch=master)](https://travis-ci.org/GLEON/rLakeAnalyzer) +[![Download Count](http://cranlogs.r-pkg.org/badges/rLakeAnalyzer)]( https://cran.r-project.org/web/packages/rLakeAnalyzer/index.html) +[![DOI](https://zenodo.org/badge/23404/GLEON/rLakeAnalyzer.svg)](https://zenodo.org/badge/latestdoi/23404/GLEON/rLakeAnalyzer) + +# rLakeAnalyzer + +The `rLakeAnalyzer` package is an R implementation of the Lake Analyzer, a tool that allows users to calculate common metrics for lake physical states. + +## Installation + +You can install a stable version of rLakeAnalyzer with: +```{r cran-install, eval = FALSE} +install.packages("rLakeAnalyzer") +``` + +You can install the development version rLakeAnalyzer from github with: + +```{r gh-installation, eval = FALSE} +# install.packages("devtools") +devtools::install_github("boshek/rLakeAnalyzer") +``` + +## Usage +First the package must be loaded into R: +```{r load_in} +library(rLakeAnalyzer) +``` + +You can view a list of functions available in rLakeAnalyzer with: +```{r, eval = FALSE} +help(package = "rLakeAnalyzer") +``` + +An example application of this functionality is illustrated with `wtr.heat.map()` function: + +```{r example} +#Get the path for the package example file included +wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") + +#Load data for example lake, Sparkilng Lake, Wisconsin. +sp.wtr = load.ts(wtr.path) + +#Plot default figure +wtr.heat.map(sp.wtr) + +#Change defaults supplied to filled.contour +wtr.heat.map(sp.wtr, zlim=c(0,15), plot.title="Sparkling Water Temp (C)") +``` + +## Getting Help or Reporting an Issue + +To report bugs/issues/feature requests, please file an [issue](https://github.com/GLEON/rLakeAnalyzer/issues/). + +These are very welcome! + +## Contributors +Luke Winslow, Richard Woolway, Jordan Read, Jennie Brentrup, Jake Zwart, Craig Snortheim, Taylor Leach, Sam Albers, Doug Collinge \ No newline at end of file diff --git a/README.md b/README.md index 6fa7bf1..48d3759 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,74 @@ + + +[![Build Status](https://travis-ci.org/GLEON/rLakeAnalyzer.svg?branch=master)](https://travis-ci.org/GLEON/rLakeAnalyzer) [![Download Count](http://cranlogs.r-pkg.org/badges/rLakeAnalyzer)](https://cran.r-project.org/web/packages/rLakeAnalyzer/index.html) [![DOI](https://zenodo.org/badge/23404/GLEON/rLakeAnalyzer.svg)](https://zenodo.org/badge/latestdoi/23404/GLEON/rLakeAnalyzer) + rLakeAnalyzer -=============== -[![Build Status](https://travis-ci.org/GLEON/rLakeAnalyzer.svg?branch=master)](https://travis-ci.org/GLEON/rLakeAnalyzer) -[![Download Count](http://cranlogs.r-pkg.org/badges/rLakeAnalyzer)]( https://cran.r-project.org/web/packages/rLakeAnalyzer/index.html) -[![DOI](https://zenodo.org/badge/23404/GLEON/rLakeAnalyzer.svg)](https://zenodo.org/badge/latestdoi/23404/GLEON/rLakeAnalyzer) +============= + +The `rLakeAnalyzer` package is an R implementation of the Lake Analyzer, a tool that allows users to calculate common metrics for lake physical states. + +Installation +------------ + +You can install a stable version of rLakeAnalyzer with: + +``` r +install.packages("rLakeAnalyzer") +``` + +You can install the development version rLakeAnalyzer from github with: + +``` r +# install.packages("devtools") +devtools::install_github("boshek/rLakeAnalyzer") +``` + +Usage +----- + +First the package must be loaded into R: + +``` r +library(rLakeAnalyzer) +``` + +You can view a list of functions available in rLakeAnalyzer with: + +``` r +help(package = "rLakeAnalyzer") +``` + +An example application of this functionality is illustrated with `wtr.heat.map()` function: + +``` r +#Get the path for the package example file included +wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") + +#Load data for example lake, Sparkilng Lake, Wisconsin. +sp.wtr = load.ts(wtr.path) + +#Plot default figure +wtr.heat.map(sp.wtr) +``` + +![](README-example-1.png) + +``` r + +#Change defaults supplied to filled.contour +wtr.heat.map(sp.wtr, zlim=c(0,15), plot.title="Sparkling Water Temp (C)") +``` + +![](README-example-2.png) + +Getting Help or Reporting an Issue +---------------------------------- + +To report bugs/issues/feature requests, please file an [issue](https://github.com/GLEON/rLakeAnalyzer/issues/). +These are very welcome! -An R version of Lake Analyzer +Contributors +------------ -Contributors: Luke Winslow, Richard Woolway, Jordan Read, Jennie Brentrup, Jake Zwart, Craig Snortheim, Taylor Leach +Luke Winslow, Richard Woolway, Jordan Read, Jennie Brentrup, Jake Zwart, Craig Snortheim, Taylor Leach, Sam Albers, Doug Collinge diff --git a/inst/doc/data.handling.R b/inst/doc/data.handling.R new file mode 100644 index 0000000..fb3cfc4 --- /dev/null +++ b/inst/doc/data.handling.R @@ -0,0 +1,26 @@ +## ---- echo = FALSE------------------------------------------------------- +library(knitr) + +## ---- echo = FALSE------------------------------------------------------- +df2 <- data.frame(datetime = c("2008-07-01 01:00","2008-07-01 02:00","2008-07-01 03:00","2008-07-01 04:00"), + doobs_0.5= c("8.3","8.2","8.2","8.1")) +kable(df2) + +## ---- echo = FALSE------------------------------------------------------- +df1 <- data.frame(datetime = c("2008-07-01 01:00","2008-07-01 02:00","2008-07-01 03:00","2008-07-01 04:00"), + wtr_0.5= c("22.3","22.31","22.31","22.32"), + wtr_1 = c("22.3","22.31","22.31","22.32"), + wtr_2 = rep(21, 4)) +kable(df1) + +## ---- echo = FALSE------------------------------------------------------- +df <- data.frame(Abbreviation = c("doobs","wtr","wnd","airT","rh"), + Variable = c("Dissolved Oxygen Concentration","Water Temperature","Wind Speed", + "Air Temperature","Relative Humidity"), + `Assumed Units` = c("mg/L ","C","m/s","C","%")) +kable(df) + +## ---- eval = FALSE------------------------------------------------------- +# tmp = data.frame() +# write.table(tmp, "test.wtr", sep='\t', row.names=FALSE) + diff --git a/vignettes/data.handling.Rnw b/inst/doc/data.handling.Rmd similarity index 63% rename from vignettes/data.handling.Rnw rename to inst/doc/data.handling.Rmd index dc1d264..deedea4 100644 --- a/vignettes/data.handling.Rnw +++ b/inst/doc/data.handling.Rmd @@ -1,95 +1,73 @@ -% !Rnw weave = Sweave -\documentclass{article} -\usepackage[margin=1in]{geometry} -\usepackage{gensymb} -\usepackage[noae]{Sweave} - -\newcommand{\code}[1]{\mbox{\texttt{#1}}} - -\begin{document} -\SweaveOpts{concordance=TRUE} -%% \VignetteIndexEntry{Introduction to file formats and data handling} - -\title{Introduction to file and data formats in rLakeAnalyzer} -\author{Luke Winslow} -\maketitle - - - -\section{Introduction} - -This document is an introduction to handling the type of data typically used in rLakeAnalyzer. It will hopefully give the reader enough information to be able to quickly and effectively format your own data to take advantage of the more powerful features. - -\section{File Format} - -We have tried to use a simple but standard file format that eases import and parsing of data while still being easy to generate and edit using commonly available tools like Microsoft Excel. Below is a very simple example of how the files are structured. - -\begin{center} - -\begin{tabular}{ l c } - \textbf{datetime} & \textbf{doobs\_0.5} \\ -\hline - 2008-07-01 01:00 & 8.3 \\ - 2008-07-01 02:00 & 8.2 \\ - 2008-07-01 03:00 & 8.2 \\ - 2008-07-01 04:00 & 8.1 \\ - -\end{tabular} -\end{center} - -There are a few key aspects to these file structure to note. The date/time format, the format of the header, and the file naming scheme. These key points are discussed here. - -\subsection{DateTime Format} - -The date and time of all observations is stored in a single, string column. The header of this column must be the word "datetime" without quotes. It is also case insensitive so "DateTime" and other variations will work. - -The datetime format itself is exclusively in an ISO-like format (ISO-8601). It is in most-to-least significant order. It requires a "-" (dash) delimited date format and a ":" (colon) delimited time. "yyyy-mm-dd HH:MM:SS". The date must come first and is separated from the time with a single space. Seconds are optional. This format can easily be created in Excel using a custom date/time format of "yyyy-mm-dd hh:mm:ss" without quotes. - -Note: This format differs from the ISO-8601 format in that a space is used to separate the date and time. This is done to support the use of Microsoft Excel as Excel does not natively recognize the ISO format. - -\subsection{Header Format} - -The header is used to help identify both the variable type as well as the depth of observation of the data as well as distinguish the data columns from the datetime column. As mentioned above, a "datetime" column is required using the format described above. - -The data columns must be identified with a variable type and optionally, a depth. For example, a water temperature collected at 1 meter depth would have the column header "wtr\_1". The usefulness of this simple format can be seen when dealing with profile data taken at many depths (see below). - -\begin{center} - -\begin{tabular}{ l c c c } - \textbf{datetime} & \textbf{wtr\_0.5} & \textbf{wtr\_1} & \textbf{wtr\_2}\\ -\hline - 2008-07-01 01:00 & 22.3 & 22.3 & 21 \\ - 2008-07-01 02:00 & 22.31 & 22.31 & 21 \\ - 2008-07-01 03:00 & 22.31 & 22.31 & 21 \\ - 2008-07-01 04:00 & 22.32 & 22.32 & 21 \\ - -\end{tabular} -\end{center} - -While any text can be used to describe a variable, the table below lists the current "standard" variables that are used by rLakeAnalyzer and other toolboxes for identifying commonly collected data in the most common units. If these standards are adhered to, many of the more helpful functions will work natively. For example, water.density expects temperature to be supplied in celsius, the default unit used for the "wtr" abbreviation. - -\begin{center} -\begin{tabular}{ l l l } - -\textbf{Abbreviation} & \textbf{Variable} & \textbf{Assumed Units} \\ -\hline -doobs & Dissolved Oxygen Concentration & mg/L \\ -wtr & Water Temperature & \degree C \\ -wnd & Wind Speed & m/s \\ -airT & Air Temperature & \degree C \\ -rh & Relative Humidity & \% \\ - -\end{tabular} -\end{center} - - -\subsection{File Format} - -The file format is a simple tab-delimited file. It is easy to export files of this format using Excel or even R itself. To export the appropriate format from R, use "write.table" as in the following example. - -<<>>= -tmp = data.frame() -write.table(tmp, "test.wtr", sep='\t', row.names=FALSE) -@ - -\end{document} \ No newline at end of file +--- +title: "Introduction to file and data formats in rLakeAnalyzer" +author: "Luke Winslow" +date: "July 6, 2014" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Vignette Title} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +header-includes: + - \usepackage{gensymb} +--- + +```{r, echo = FALSE} +library(knitr) +``` + +## Introduction +This document is an introduction to handling the type of data typically used in rLakeAnalyzer. It will hopefully give the reader enough information to be able to quickly and effectively format your own data to take advantage of the more powerful features. + +## File Format + +We have tried to use a simple but standard file format that eases import and parsing of data while still being easy to generate and edit using commonly available tools like Microsoft Excel. Below is a very simple example of how the files are structured. + +```{r, echo = FALSE} +df2 <- data.frame(datetime = c("2008-07-01 01:00","2008-07-01 02:00","2008-07-01 03:00","2008-07-01 04:00"), + doobs_0.5= c("8.3","8.2","8.2","8.1")) +kable(df2) +``` + +There are a few key aspects to these file structure to note. The date/time format, the format of the header, and the file naming scheme. These key points are discussed here. + +## DateTime Format + +The date and time of all observations is stored in a single, string column. The header of this column must be the word "datetime" without quotes. It is also case insensitive so "DateTime" and other variations will work. + +The datetime format itself is exclusively in an ISO-like format (ISO-8601). It is in most-to-least significant order. It requires a "-" (dash) delimited date format and a ":" (colon) delimited time. "yyyy-mm-dd HH:MM:SS". The date must come first and is separated from the time with a single space. Seconds are optional. This format can easily be created in Excel using a custom date/time format of "yyyy-mm-dd hh:mm:ss" without quotes. + +Note: This format differs from the ISO-8601 format in that a space is used to separate the date and time. This is done to support the use of Microsoft Excel as Excel does not natively recognize the ISO format. + +## Header Format + +The header is used to help identify both the variable type as well as the depth of observation of the data as well as distinguish the data columns from the datetime column. As mentioned above, a "datetime" column is required using the format described above. + +The data columns must be identified with a variable type and optionally, a depth. For example, a water temperature collected at 1 meter depth would have the column header "wtr\_1". The usefulness of this simple format can be seen when dealing with profile data taken at many depths (see below). + +```{r, echo = FALSE} +df1 <- data.frame(datetime = c("2008-07-01 01:00","2008-07-01 02:00","2008-07-01 03:00","2008-07-01 04:00"), + wtr_0.5= c("22.3","22.31","22.31","22.32"), + wtr_1 = c("22.3","22.31","22.31","22.32"), + wtr_2 = rep(21, 4)) +kable(df1) +``` + +While any text can be used to describe a variable, the table below lists the current "standard" variables that are used by rLakeAnalyzer and other toolboxes for identifying commonly collected data in the most common units. If these standards are adhered to, many of the more helpful functions will work natively. For example, water.density expects temperature to be supplied in celsius, the default unit used for the "wtr" abbreviation. + +```{r, echo = FALSE} +df <- data.frame(Abbreviation = c("doobs","wtr","wnd","airT","rh"), + Variable = c("Dissolved Oxygen Concentration","Water Temperature","Wind Speed", + "Air Temperature","Relative Humidity"), + `Assumed Units` = c("mg/L ","°C","m/s","°C","%")) +kable(df) +``` + + +## File Format + +The file format is a simple tab-delimited file. It is easy to export files of this format using Excel or even R itself. To export the appropriate format from R, use "write.table" as in the following example. + +```{r, eval = FALSE} +tmp = data.frame() +write.table(tmp, "test.wtr", sep='\t', row.names=FALSE) +``` diff --git a/inst/doc/data.handling.html b/inst/doc/data.handling.html new file mode 100644 index 0000000..68bee8a --- /dev/null +++ b/inst/doc/data.handling.html @@ -0,0 +1,217 @@ + + + + + + + + + + + + + + + +Introduction to file and data formats in rLakeAnalyzer + + + + + + + + + + + + + + + + + + +

Introduction to file and data formats in rLakeAnalyzer

+

Luke Winslow

+

July 6, 2014

+ + + +
## Warning: package 'knitr' was built under R version 3.4.1
+
+

Introduction

+

This document is an introduction to handling the type of data typically used in rLakeAnalyzer. It will hopefully give the reader enough information to be able to quickly and effectively format your own data to take advantage of the more powerful features.

+
+
+

File Format

+

We have tried to use a simple but standard file format that eases import and parsing of data while still being easy to generate and edit using commonly available tools like Microsoft Excel. Below is a very simple example of how the files are structured.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
datetimedoobs_0.5
2008-07-01 01:008.3
2008-07-01 02:008.2
2008-07-01 03:008.2
2008-07-01 04:008.1
+

There are a few key aspects to these file structure to note. The date/time format, the format of the header, and the file naming scheme. These key points are discussed here.

+
+
+

DateTime Format

+

The date and time of all observations is stored in a single, string column. The header of this column must be the word “datetime” without quotes. It is also case insensitive so “DateTime” and other variations will work.

+

The datetime format itself is exclusively in an ISO-like format (ISO-8601). It is in most-to-least significant order. It requires a “-” (dash) delimited date format and a “:” (colon) delimited time. “yyyy-mm-dd HH:MM:SS”. The date must come first and is separated from the time with a single space. Seconds are optional. This format can easily be created in Excel using a custom date/time format of “yyyy-mm-dd hh:mm:ss” without quotes.

+

Note: This format differs from the ISO-8601 format in that a space is used to separate the date and time. This is done to support the use of Microsoft Excel as Excel does not natively recognize the ISO format.

+
+
+

Header Format

+

The header is used to help identify both the variable type as well as the depth of observation of the data as well as distinguish the data columns from the datetime column. As mentioned above, a “datetime” column is required using the format described above.

+

The data columns must be identified with a variable type and optionally, a depth. For example, a water temperature collected at 1 meter depth would have the column header “wtr_1”. The usefulness of this simple format can be seen when dealing with profile data taken at many depths (see below).

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
datetimewtr_0.5wtr_1wtr_2
2008-07-01 01:0022.322.321
2008-07-01 02:0022.3122.3121
2008-07-01 03:0022.3122.3121
2008-07-01 04:0022.3222.3221
+

While any text can be used to describe a variable, the table below lists the current “standard” variables that are used by rLakeAnalyzer and other toolboxes for identifying commonly collected data in the most common units. If these standards are adhered to, many of the more helpful functions will work natively. For example, water.density expects temperature to be supplied in celsius, the default unit used for the “wtr” abbreviation.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AbbreviationVariableAssumed.Units
doobsDissolved Oxygen Concentrationmg/L
wtrWater Temperature°C
wndWind Speedm/s
airTAir Temperature°C
rhRelative Humidity%
+
+
+

File Format

+

The file format is a simple tab-delimited file. It is easy to export files of this format using Excel or even R itself. To export the appropriate format from R, use “write.table” as in the following example.

+
tmp = data.frame()
+write.table(tmp, "test.wtr", sep='\t', row.names=FALSE)
+
+ + + + + + + + diff --git a/inst/doc/data.handling.pdf b/inst/doc/data.handling.pdf deleted file mode 100644 index 16755ff..0000000 Binary files a/inst/doc/data.handling.pdf and /dev/null differ diff --git a/inst/doc/sm_algorithm.R b/inst/doc/sm_algorithm.R new file mode 100644 index 0000000..20b3d4c --- /dev/null +++ b/inst/doc/sm_algorithm.R @@ -0,0 +1,21 @@ +## ---- message=FALSE------------------------------------------------------ +library(rLakeAnalyzer) +library(knitr) + +## ------------------------------------------------------------------------ +data("latesummer") +wldf <- wtr.layer(depth = latesummer$depth, measure = latesummer$temper) +knitr::kable(wldf) + +## ---- eval = TRUE, echo=TRUE--------------------------------------------- +wldf$segments + +## ---- fig.show = "hold", fig.width = 8, fig.height = 6------------------- +plot(y = latesummer$depth, x = latesummer$temper, ylim = rev(range(latesummer$depth))) +abline(h = wldf$cline, col='blue') +abline(h = wldf$mld, col='red') +abline(h = wldf$min_depth, col='green') +text(16, wldf$cline+3, "Thermocline", col = 'blue') +text(16, wldf$mld+3, "Mix Layer Depth", col = 'red') +text(16, wldf$min_depth+3, "Minimum Depth", col = 'green') + diff --git a/inst/doc/sm_algorithm.Rmd b/inst/doc/sm_algorithm.Rmd new file mode 100644 index 0000000..3275364 --- /dev/null +++ b/inst/doc/sm_algorithm.Rmd @@ -0,0 +1,51 @@ +--- +title: "Split and Merge Algorithm Usage" +author: "Sam Albers and Doug Collinge" +date: "`r Sys.Date()`" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Vignette Title} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + + +## Packages needing loading +```{r, message=FALSE} +library(rLakeAnalyzer) +library(knitr) +``` + + +## Split and merge algorithm +Water column identification is provided by the split-and-merge algorithm. Implementation of the split-and-merge algorithm for a water profile occurs within the `wtr.layer()` function: + +## Simple application of the split and merge algorithm +Below is a simple one profile example of determining key water column parameters using the split-and-merge algorithm. The default behaviour for `wtr.layer` is to run the algorithm *without* specifying the number of segments. `wtr.layer()` adopt as defaults the convention of a minimum depth (z0) of 2.5 m, a maximum depth (zmax) of 150 m and a error threshold (thres) of 0.1. +```{r} +data("latesummer") +wldf <- wtr.layer(depth = latesummer$depth, measure = latesummer$temper) +knitr::kable(wldf) +``` + +In this example, you'll note that `wldf$cline` is formatted as a list-column. A thorough demonstration of a list column can be found [here](https://jennybc.github.io/purrr-tutorial/ls13_list-columns.html). This type of data format has been included here to consolidate split and merge results and align the output to work well with [tidyverse](https://www.tidyverse.org/) tools. If you are interested in working with the segments data from `wtr.layer()`, use this approach: +```{r, eval = TRUE, echo=TRUE} +wldf$segments +``` + +Note that the axes of the water column profile have been reversed and flipped to better visualize the water column and conform to standard limnological displays. +```{r, fig.show = "hold", fig.width = 8, fig.height = 6} +plot(y = latesummer$depth, x = latesummer$temper, ylim = rev(range(latesummer$depth))) +abline(h = wldf$cline, col='blue') +abline(h = wldf$mld, col='red') +abline(h = wldf$min_depth, col='green') +text(16, wldf$cline+3, "Thermocline", col = 'blue') +text(16, wldf$mld+3, "Mix Layer Depth", col = 'red') +text(16, wldf$min_depth+3, "Minimum Depth", col = 'green') +``` + +## Important references +- Pavlidis, T., and S. L. Horowitz, 1974: Segmentation of plan curves.IEEE Trans. Comput., C-23, 860–870. +- Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from Oceanic Profile Data. Journal of Atmospheric and Oceanic Technology. 20(2), 319-329. +- Fiedler, Paul C. "Comparison of objective descriptions of the thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325. + diff --git a/inst/doc/sm_algorithm.html b/inst/doc/sm_algorithm.html new file mode 100644 index 0000000..29f311c --- /dev/null +++ b/inst/doc/sm_algorithm.html @@ -0,0 +1,152 @@ + + + + + + + + + + + + + + + + +Split and Merge Algorithm Usage + + + + + + + + + + + + + + + + + +

Split and Merge Algorithm Usage

+

Sam Albers and Doug Collinge

+

2017-09-29

+ + + +
+

Packages needing loading

+
library(rLakeAnalyzer)
+library(knitr)
+
+
+

Split and merge algorithm

+

Water column identification is provided by the split-and-merge algorithm. Implementation of the split-and-merge algorithm for a water profile occurs within the wtr.layer() function:

+
+
+

Simple application of the split and merge algorithm

+

Below is a simple one profile example of determining key water column parameters using the split-and-merge algorithm. The default behaviour for wtr.layer is to run the algorithm without specifying the number of segments. wtr.layer() adopt as defaults the convention of a minimum depth (z0) of 2.5 m, a maximum depth (zmax) of 150 m and a error threshold (thres) of 0.1.

+
data("latesummer")
+wldf <- wtr.layer(depth = latesummer$depth, measure = latesummer$temper)
+knitr::kable(wldf)
+ + + + + + + + + + + + + + + + + + + +
min_depthnsegmldclinesegments
2.547.056516.390252.59800, 7.05650, 25.72400, 98.13900, 17.94060, 17.38405, 5.51445, 4.46375
+

In this example, you’ll note that wldf$cline is formatted as a list-column. A thorough demonstration of a list column can be found here. This type of data format has been included here to consolidate split and merge results and align the output to work well with tidyverse tools. If you are interested in working with the segments data from wtr.layer(), use this approach:

+
wldf$segments
+
## [[1]]
+##   segment_depth segment_measure
+## 1        2.5980        17.94060
+## 2        7.0565        17.38405
+## 3       25.7240         5.51445
+## 4       98.1390         4.46375
+

Note that the axes of the water column profile have been reversed and flipped to better visualize the water column and conform to standard limnological displays.

+
plot(y = latesummer$depth, x = latesummer$temper, ylim = rev(range(latesummer$depth)))
+abline(h = wldf$cline, col='blue')
+abline(h = wldf$mld, col='red')
+abline(h = wldf$min_depth, col='green')
+text(16, wldf$cline+3, "Thermocline", col = 'blue')
+text(16, wldf$mld+3, "Mix Layer Depth", col = 'red')
+text(16, wldf$min_depth+3, "Minimum Depth", col = 'green')
+

+
+
+

Important references

+
    +
  • Pavlidis, T., and S. L. Horowitz, 1974: Segmentation of plan curves.IEEE Trans. Comput., C-23, 860–870.
    • +
  • Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from Oceanic Profile Data. Journal of Atmospheric and Oceanic Technology. 20(2), 319-329.
    • +
  • Fiedler, Paul C. “Comparison of objective descriptions of the thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325.
    • +
+
+ + + + + + + + diff --git a/man/buoyancy.freq.Rd b/man/buoyancy.freq.Rd index 153d37b..af0b1c1 100644 --- a/man/buoyancy.freq.Rd +++ b/man/buoyancy.freq.Rd @@ -1,43 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/buoyancy.freq.R \name{buoyancy.freq} \alias{buoyancy.freq} - -\title{ - Calculates buoyancy frequency. -} -\description{ - Calculate the buoyancy frequency (Brunt-Vaisala frequency) for a temperature profile. -} - +\title{Calculates buoyancy frequency.} \usage{ - buoyancy.freq(wtr, depths) +buoyancy.freq(wtr, depths) } - \arguments{ - \item{wtr}{ - a numeric vector of water temperature in degrees C - } - \item{depths}{ - a numeric vector corresponding to the depths (in m) of the wtr measurements - } -} +\item{wtr}{a numeric vector of water temperature in degrees C} -\value{ - Returns a vector of buoyancy frequency in units \code{sec^-2}. Return value - has attribute "depths" which define buoyancy frequency depths (which - differ from supplied depths). +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} } - -\author{ - Luke Winslow +\value{ +Returns a vector of buoyancy frequency in units \code{sec^-2}. +Return value has attribute "depths" which define buoyancy frequency depths +(which differ from supplied depths). } - - -%% ~Make other sections like Warning with \section{Warning }{....} ~ - -\seealso{\code{thermo.depth}, \code{ts.buoyancy.freq} +\description{ +Calculate the buoyancy frequency (Brunt-Vaisala frequency) for a temperature +profile. } \examples{ + # A vector of water temperatures wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) @@ -52,6 +38,7 @@ ylab='Depth', xlab='Buoyancy Frequency', ylim=c(max(depths), min(depths))) } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. +\seealso{ +\code{thermo.depth}, \code{ts.buoyancy.freq} +} \keyword{arith} diff --git a/man/center.buoyancy.Rd b/man/center.buoyancy.Rd index e6b9f92..fa0a9ce 100644 --- a/man/center.buoyancy.Rd +++ b/man/center.buoyancy.Rd @@ -1,44 +1,29 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/center.buoyancy.R \name{center.buoyancy} \alias{center.buoyancy} - -\title{ - Calculates the center of buoyancy. -} -\description{ - Calculate the center of buoyancy using buoyancy frequency with a - center of mass analysis. Brunt-Vaisala frequency is used for a temperature profile. - Negative values for N2 are set to 0 (as they represent transient instabilities or - sensor calibration issues) for this calculation. -} - +\title{Calculates the center of buoyancy.} \usage{ - center.buoyancy(wtr, depths) +center.buoyancy(wtr, depths) } - \arguments{ - \item{wtr}{ - a numeric vector of water temperature in degrees C - } - \item{depths}{ - a numeric vector corresponding to the depths (in m) of the wtr measurements - } -} +\item{wtr}{a numeric vector of water temperature in degrees C} -\value{ - Returns a value for the center of buoyancy. +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} } - -\author{ - Jordan S Read +\value{ +Returns a value for the center of buoyancy. } - - -%% ~Make other sections like Warning with \section{Warning }{....} ~ - -\seealso{\code{buoyancy.freq}, \code{ts.buoyancy.freq}, \code{center.buoyancy} +\description{ +Calculate the center of buoyancy using buoyancy frequency with a center of +mass analysis. Brunt-Vaisala frequency is used for a temperature profile. +Negative values for N2 are set to 0 (as they represent transient +instabilities or sensor calibration issues) for this calculation. } \examples{ + # A vector of water temperatures wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) @@ -50,6 +35,8 @@ c.b = center.buoyancy(wtr, depths) } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. -\keyword{arith} \ No newline at end of file +\seealso{ +\code{buoyancy.freq}, \code{ts.buoyancy.freq}, +\code{center.buoyancy} +} +\keyword{arith} diff --git a/man/cline_calc.Rd b/man/cline_calc.Rd index e829b0a..0e30195 100644 --- a/man/cline_calc.Rd +++ b/man/cline_calc.Rd @@ -15,10 +15,15 @@ cline_calc(z_seg = z_seg, sigma_seg = sigma_seg) the depth of the cline } \description{ -Cline depth is defined as the midpoint of the segment connecting inflection points that has the maximum slope. A cline cannot occur over a depth range of less than 1m and also cannot be the shallowest segment. Violating both conditions will thrown warnings though this function handles both differently. Used mostly with \code{wtr_layer} +Cline depth is defined as the midpoint of the segment connecting inflection +points that has the maximum slope. A cline cannot occur over a depth range +of less than 1m and also cannot be the shallowest segment. Violating both +conditions will thrown warnings though this function handles both +differently. Used mostly with \code{wtr_layer} } \references{ -Fiedler, Paul C. Comparison of objective descriptions of the thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325. +Fiedler, Paul C. Comparison of objective descriptions of the +thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325. } \seealso{ \code{wtr_layer()} diff --git a/man/depth.filter.Rd b/man/depth.filter.Rd index 371568f..5121f64 100644 --- a/man/depth.filter.Rd +++ b/man/depth.filter.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/wtr-layer-segments.R +% Please edit documentation in R/wtr.layer.segments.R \name{depth.filter} \alias{depth.filter} \title{Data filter to remove soak, heave and upcast} @@ -11,21 +11,25 @@ depth.filter(z0, run_length = 20, index = FALSE) \item{run_length}{Length of run upon which to start the soak removal} -\item{index}{Logical: Should the function return an index value or actual value?} +\item{index}{Logical: Should the function return an index value or actual +value?} } \value{ -index values of z0 of filtered data. Will return a warning if the function removed more than 10% of the data +index values of z0 of filtered data. Will return a warning if the +function removed more than 10% of the data } \description{ -\itemize{ - \item Soak period: water profiling instruments typically require a soak period where you let the instrument rest - submerged at the surface. While it is "soaking" it is collecting data. We don't want that data - \item Upcast versus downcast: typically instruments are turned on before you put them in the water and turn them off - once you pull them out. The data consequence of that is that you collect both the "downcast" and the "upcast". In some - case the upcast is of interest but usually it isn't. And because we would prefer increasing depth data it is better to - remove an upcast if it is present. - \item Heave: when lowering the instrument in rough weather a boat will heave side to side. Sometimes it will heave - enough that you get small data groupings where the decreases a little while the boat heaves then go down. The overall - trend is still down but those slight upticks in depth cause problems for our algorithm. -} +\itemize{ \item Soak period: water profiling instruments typically require a +soak period where you let the instrument rest submerged at the surface. +While it is "soaking" it is collecting data. We don't want that data \item +Upcast versus downcast: typically instruments are turned on before you put +them in the water and turn them off once you pull them out. The data +consequence of that is that you collect both the "downcast" and the +"upcast". In some case the upcast is of interest but usually it isn't. And +because we would prefer increasing depth data it is better to remove an +upcast if it is present. \item Heave: when lowering the instrument in rough +weather a boat will heave side to side. Sometimes it will heave enough that +you get small data groupings where the decreases a little while the boat +heaves then go down. The overall trend is still down but those slight +upticks in depth cause problems for our algorithm. } } diff --git a/man/drop.datetime.Rd b/man/drop.datetime.Rd new file mode 100644 index 0000000..a30aa16 --- /dev/null +++ b/man/drop.datetime.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/helper.functions.R +\name{drop.datetime} +\alias{drop.datetime} +\title{Find and drop the datetime column from the datatable} +\usage{ +drop.datetime(data, error = FALSE) +} +\arguments{ +\item{data}{data arg} + +\item{error}{defaults to FALSE} +} +\value{ +A data.frame with only the data, after datetime has been dropped +} +\description{ +Liberally looks for a datetime column and drops it, + returning a data.frame with only water temperature. Errors if datetime column is + ambiguous. Warns if there is no match. +} diff --git a/man/epi.temperature.Rd b/man/epi.temperature.Rd index eefbb39..01a2a20 100644 --- a/man/epi.temperature.Rd +++ b/man/epi.temperature.Rd @@ -9,17 +9,20 @@ epi.temperature(wtr, depths, bthA, bthD) \arguments{ \item{wtr}{a numeric vector of water temperature in degrees C.} -\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr measurements} +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} -\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to bthD depths} +\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to +bthD depths} -\item{bthD}{a numeric vector of depths (m) which correspond to areal measures in bthA} +\item{bthD}{a numeric vector of depths (m) which correspond to areal +measures in bthA} } \description{ -Calculates volumetrically weighted average epilimnetic temperature using -the supplied water temperature timeseries. If the lake is not stratified, the bottom -of the epilimnion is calculated as the full depth of the lake. +Calculates volumetrically weighted average epilimnetic temperature using the +supplied water temperature timeseries. If the lake is not stratified, the +bottom of the epilimnion is calculated as the full depth of the lake. } \seealso{ -\code{\link{hypo.temperature}}, \code{\link{whole.lake.temperature}} +\code{\link{hypo.temperature}} \code{\link{whole.lake.temperature}} } diff --git a/man/get.datetime.Rd b/man/get.datetime.Rd new file mode 100644 index 0000000..5909f63 --- /dev/null +++ b/man/get.datetime.Rd @@ -0,0 +1,16 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/helper.functions.R +\name{get.datetime} +\alias{get.datetime} +\title{Search for and return the datetime column from a ts data.frame} +\usage{ +get.datetime(data, error = FALSE) +} +\arguments{ +\item{data}{data arg} + +\item{error}{defaults to FALSE} +} +\description{ +Warns if unavailable then returns NULL. +} diff --git a/man/get.offsets.Rd b/man/get.offsets.Rd index 460d54c..e008381 100644 --- a/man/get.offsets.Rd +++ b/man/get.offsets.Rd @@ -10,17 +10,19 @@ get.offsets(data) \item{data}{Data frame returned from \code{\link{load.ts}}.} } \value{ -A numeric vector of depth values. Should be the \code{ncol(data) - 1} -in length as the first column contains date/time data. +A numeric vector of depth values. Should be the \code{ncol(data) - +1} in length as the first column contains date/time data. } \description{ -Extracts the depth information from a data frame containing multi-depth observation data. -Relies on the format of the header to get information and may fail if your file format is incorrect. -Please follow 'VAR_##.#' format, where ##.# is the depth of data for that column. VAR is typically -'wtr' to indicate water temperature. +Extracts the depth information from a data frame containing multi-depth +observation data. Relies on the format of the header to get information and +may fail if your file format is incorrect. Please follow 'VAR_##.#' format, +where ##.# is the depth of data for that column. VAR is typically 'wtr' to +indicate water temperature. } \examples{ + #Get the path for the package example file included exampleFilePath <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") @@ -31,7 +33,6 @@ sparkling.temp = load.ts(exampleFilePath) depths = get.offsets(sparkling.temp) print(depths) - } \seealso{ \code{\link{load.ts}} diff --git a/man/hypo.temperature.Rd b/man/hypo.temperature.Rd index 3ac07b4..3b814e6 100644 --- a/man/hypo.temperature.Rd +++ b/man/hypo.temperature.Rd @@ -9,16 +9,19 @@ hypo.temperature(wtr, depths, bthA, bthD) \arguments{ \item{wtr}{a numeric vector of water temperature in degrees C.} -\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr measurements} +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} -\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to bthD depths} +\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to +bthD depths} -\item{bthD}{a numeric vector of depths (m) which correspond to areal measures in bthA} +\item{bthD}{a numeric vector of depths (m) which correspond to areal +measures in bthA} } \description{ Calculates volumetrically weighted average hypolimnetic temperature using -the supplied water temperature timeseries. If the lake is not stratified, an NA -value is returned. +the supplied water temperature timeseries. If the lake is not stratified, an +NA value is returned. } \seealso{ \code{\link{epi.temperature}}, \code{\link{whole.lake.temperature}} diff --git a/man/internal.energy.Rd b/man/internal.energy.Rd index d8bf9b2..0bbf12d 100644 --- a/man/internal.energy.Rd +++ b/man/internal.energy.Rd @@ -9,24 +9,28 @@ internal.energy(wtr, depths, bthA, bthD) \arguments{ \item{wtr}{a numeric vector of water temperature in degrees C} -\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr measurements} +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} -\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to bthD depths} +\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to +bthD depths} -\item{bthD}{a numeric vector of depths (m) which correspond to areal measures in bthA} +\item{bthD}{a numeric vector of depths (m) which correspond to areal +measures in bthA} } \value{ internal energy in Joules m-2. (Currently not vectorized..) } \description{ -Calculates the internal energy of the water column with temperature and hypsography -} -\details{ -Internal energy is the thermal energy in the water column, which is calculated by -multiplying the specific heat of water (J kg-1 K-1) by the temperature and mass of the water -in the lake. +Calculates the internal energy of the water column with temperature and +hypsography + +Internal energy is the thermal energy in the water column, which is +calculated by multiplying the specific heat of water (J kg-1 K-1) by the +temperature and mass of the water in the lake. } \examples{ + bthA <- c(1000,900,864,820,200,10) bthD <- c(0,2.3,2.5,4.2,5.8,7) @@ -36,6 +40,3 @@ depths <- c(0,1,2,3,4,5,6) cat('Internal Energy for input is: ') cat(internal.energy(wtr, depths, bthA, bthD)) } -\author{ -Jordan S. Read -} diff --git a/man/lake.number.Rd b/man/lake.number.Rd index 4e0d4ce..a4469bd 100644 --- a/man/lake.number.Rd +++ b/man/lake.number.Rd @@ -1,42 +1,51 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/lake.number.R \name{lake.number} \alias{lake.number} -%- Also NEED an '\alias' for EACH other topic documented here. \title{Calculate Lake Number} -\description{The Lake Number, defined by Imberger and Patterson (1990), has been used to describe processes relevant to the internal mixing of lakes induced by wind forcings. Lower values of Lake Number represent a higher potential for increased diapycnal mixing, which increases the vertical flux of mass and energy across the metalimnion through the action of non-linear internal waves. Lake Number is a dimensionless index. -} \usage{ lake.number(bthA, bthD, uStar, St, metaT, metaB, averageHypoDense) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{bthA}{ a numeric vector of cross sectional areas (m2) corresponding to bthD depths, hypsographic areas} - \item{bthD}{ a numeric vector of depths (m) which correspond to areal measures in bthA, hypsographic depths} - \item{uStar}{ a numeric array of u* (m/s), water friction velocity due to wind stress} - \item{St}{ a numeric array of Schmidt stability (J/m2), as defined by Idso 1973} - \item{metaT}{ a numeric array of the top of the metalimnion depth (m from the surface)} - \item{metaB}{ a numeric array of the bottom of the metalimnion depth (m from the surface)} - \item{averageHypoDense}{ a numeric array of the average density of the hypolimnion (kg/m3)} -} -\details{ -Lake Number has been used, for example, to estimate the flux of oxygen across the thermocline in a small lake (Robertson and Imberger, 1994), and to explain the magnitude of the vertical flux of ammonium in a lake (Romero et al., 1998). +\item{bthA}{a numeric vector of cross sectional areas (m2) corresponding to +bthD depths, hypsographic areas} + +\item{bthD}{a numeric vector of depths (m) which correspond to areal +measures in bthA, hypsographic depths} + +\item{uStar}{a numeric array of u* (m/s), water friction velocity due to +wind stress} + +\item{St}{a numeric array of Schmidt stability (J/m2), as defined by Idso +1973} + +\item{metaT}{a numeric array of the top of the metalimnion depth (m from the +surface)} + +\item{metaB}{a numeric array of the bottom of the metalimnion depth (m from +the surface)} + +\item{averageHypoDense}{a numeric array of the average density of the +hypolimnion (kg/m3)} } \value{ A numeric vector of Lake Number [dimensionless] } +\description{ +The Lake Number, defined by Imberger and Patterson (1990), has been used to +describe processes relevant to the internal mixing of lakes induced by wind +forcings. Lower values of Lake Number represent a higher potential for +increased diapycnal mixing, which increases the vertical flux of mass and +energy across the metalimnion through the action of non-linear internal +waves. Lake Number is a dimensionless index. -\references{Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. Advances in Applied -Mechanics 27, 303-475. - -Idso, S.B., 1973. \emph{On the concept of lake stability}. Limnology and Oceanography 18, 681-683.} - -\author{ -Jordan S. Read, Luke Winslow -} -\seealso{ - \code{\link{ts.lake.number}} - \code{\link{wedderburn.number}} +Lake Number has been used, for example, to estimate the flux of oxygen +across the thermocline in a small lake (Robertson and Imberger, 1994), and +to explain the magnitude of the vertical flux of ammonium in a lake (Romero +et al., 1998). } \examples{ + bthA <- c(1000,900,864,820,200,10) bthD <- c(0,2.3,2.5,4.2,5.8,7) uStar <- c(0.0032,0.0024) @@ -48,6 +57,14 @@ Jordan S. Read, Luke Winslow cat(lake.number( bthA, bthD, uStar, St, metaT, metaB, averageHypoDense) ) } +\references{ +Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +Advances in Applied Mechanics 27, 303-475. +Idso, S.B., 1973. \emph{On the concept of lake stability}. Limnology and +Oceanography 18, 681-683. +} +\seealso{ +\code{\link{ts.lake.number}} \code{\link{wedderburn.number}} +} \keyword{manip} - diff --git a/man/lake.number.plot.Rd b/man/lake.number.plot.Rd index 2168a75..7abebb2 100644 --- a/man/lake.number.plot.Rd +++ b/man/lake.number.plot.Rd @@ -1,38 +1,30 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/lake.number.plot.R \name{lake.number.plot} \alias{lake.number.plot} - -\title{ - Plots time series of Lake Number -} -\description{ - Generates a time series plot of Lake Number for appropriately formatted data. - See \code{\link{lake.number}} for more details on Lake Number and reference. -} +\title{Plots time series of Lake Number} \usage{ - lake.number.plot(wtr, wnd, wh, bth) +lake.number.plot(wtr, wnd, wh, bth) } \arguments{ - \item{wtr}{ - Data frame of water temperature loaded with \code{\link{load.ts}} - } - \item{wnd}{ - A data frame containing hypsometric data. Loaded using \code{\link{load.bathy}} - } - \item{wh}{ - A value indicating the height of the anemometer above lake surface in meters. - This value must be specified, there is no default. - } - \item{bth}{ - A data frame containing hypsometric data. Loaded using \code{\link{load.bathy}} - } -} -\author{ - Jennifer Brentrup, Taylor Leach +\item{wtr}{Data frame of water temperature loaded with \code{\link{load.ts}}} + +\item{wnd}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} + +\item{wh}{A value indicating the height of the anemometer above lake surface +in meters. This value must be specified, there is no default.} + +\item{bth}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} } -\seealso{ - \code{\link{wtr.lineseries}} +\description{ +Generates a time series plot of Lake Number for appropriately formatted +data. See \code{\link{lake.number}} for more details on Lake Number and +reference. } \examples{ + #Get system data file paths wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") bth.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") @@ -48,5 +40,7 @@ lake.number.plot(wtr,wnd,wh,bth) } } - -\keyword{ hplot } +\seealso{ +\code{\link{wtr.lineseries}} +} +\keyword{hplot} diff --git a/man/latesummer.Rd b/man/latesummer.Rd index 9915f87..73b877a 100644 --- a/man/latesummer.Rd +++ b/man/latesummer.Rd @@ -11,8 +11,7 @@ latesummer \description{ Late summer water profile taken from Quesnel Lake, British Columbia, Canada. Profile taken with Sea-Bird SBE19plus. -} -\details{ + \describe{ \item{depth}{Depth, m} \item{temper}{Temperature, degC} diff --git a/man/layer.density.Rd b/man/layer.density.Rd index 3cd046c..1f26541 100644 --- a/man/layer.density.Rd +++ b/man/layer.density.Rd @@ -1,37 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/layer.density.R \name{layer.density} \alias{layer.density} -\title{ - Returns the average density of a layer between two depths. -} -\description{ -This function calculates the average density of a layer of water between two depths. -} +\title{Returns the average density of a layer between two depths.} \usage{ -layer.density(top, bottom, wtr, depths, bthA, bthD, sal) +layer.density(top, bottom, wtr, depths, bthA, bthD, sal = wtr * 0) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{top}{ Numeric value of the depth (m) of the top of the layer from the water surface} - \item{bottom}{ Numeric value of the depth (m) of the bottom of the layer from the water surface} - \item{wtr}{ Numeric vector of water temperature in degrees C} - \item{depths}{ Numeric vector of depths (m) corresponding to water temperature vector} - \item{bthA}{ Numeric vector of water body cross sectional area (m2) corresponding to bthD depths} - \item{bthD}{ Numeric vector of water body bathymetric depths (m) corresponding to areal bthA values} - \item{sal}{ Optional numeric vector of salinity in Practical Salinity Units corresponding to water temperature vector. If left blank, salinity is set to be zero} -} +\item{top}{Numeric value of the depth (m) of the top of the layer from the +water surface} + +\item{bottom}{Numeric value of the depth (m) of the bottom of the layer from +the water surface} + +\item{wtr}{Numeric vector of water temperature in degrees C} +\item{depths}{Numeric vector of depths (m) corresponding to water +temperature vector} + +\item{bthA}{Numeric vector of water body cross sectional area (m2) +corresponding to bthD depths} + +\item{bthD}{Numeric vector of water body bathymetric depths (m) +corresponding to areal bthA values} + +\item{sal}{Optional numeric vector of salinity in Practical Salinity Units +corresponding to water temperature vector. If left blank, salinity is set to +be zero} +} \value{ Numeric value of average water density for bounded layer in kg/m^3 } - -\author{ -Jake Zwart -} - -\seealso{ -\code{water.density} +\description{ +This function calculates the average density of a layer of water between two +depths. } \examples{ + top <- 2 bottom <- 6 wtr <- c(25.2,25.1,24.1,22.0,19.8,15.3,12.0,11.1) @@ -40,5 +45,7 @@ bthA <- c(10000,8900,5000,3500,2000,1000,300,10) bthD <- c(0,1,2,3,4,5,6,7) layer.density(top,bottom,wtr,depths,bthA,bthD) } - +\seealso{ +\code{water.density} +} \keyword{manip} diff --git a/man/layer.temperature.Rd b/man/layer.temperature.Rd index 25b351a..3a80a36 100644 --- a/man/layer.temperature.Rd +++ b/man/layer.temperature.Rd @@ -1,38 +1,38 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/layer.temperature.R \name{layer.temperature} \alias{layer.temperature} -\title{ - Returns the average temperature of a layer between two depths. -} -\description{ - This function calculates the average temperature of a layer of water between two depths. -} +\title{Returns the average temperature of a layer between two depths.} \usage{ layer.temperature(top, bottom, wtr, depths, bthA, bthD) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{top}{ Numeric value of the depth (m) of the top of the layer from the water surface} - \item{bottom}{ Numeric value of the depth (m) of the bottom of the layer from the water surface} - \item{wtr}{ Numeric vector of water temperature in degrees C} - \item{depths}{ Numeric vector of depths (m) corresponding to water temperature vector} - \item{bthA}{ Numeric vector of water body cross sectional area (m2) corresponding to bthD depths} - \item{bthD}{ Numeric vector of water body bathymetric depths (m) corresponding to areal bthA values} -} +\item{top}{Numeric value of the depth (m) of the top of the layer from the +water surface} -\value{ -Numeric value of average water temperature -} +\item{bottom}{Numeric value of the depth (m) of the bottom of the layer from +the water surface} -\author{ -Jordan Read -} +\item{wtr}{Numeric vector of water temperature in degrees C} -%% ~Make other sections like Warning with \section{Warning }{....} ~ +\item{depths}{Numeric vector of depths (m) corresponding to water +temperature vector} -\seealso{ -\code{layer.density} +\item{bthA}{Numeric vector of water body cross sectional area (m2) +corresponding to bthD depths} + +\item{bthD}{Numeric vector of water body bathymetric depths (m) +corresponding to areal bthA values} +} +\value{ +Numeric value of average water temperature +} +\description{ +This function calculates the average temperature of a layer of water between +two depths. } \examples{ + # Supply input data top <- 2 bottom <- 6 @@ -44,5 +44,7 @@ Jordan Read #Return the average temperature of the water column between 2 and 6 meters. layer.temperature(top,bottom,wtr,depths,bthA,bthD) } - -\keyword{manip} \ No newline at end of file +\seealso{ +\code{layer.density} +} +\keyword{manip} diff --git a/man/load.bathy.Rd b/man/load.bathy.Rd index b7f0ded..ba8c373 100644 --- a/man/load.bathy.Rd +++ b/man/load.bathy.Rd @@ -1,38 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/load.data.R \name{load.bathy} \alias{load.bathy} -%- Also NEED an '\alias' for EACH other topic documented here. -\title{ - Import lake bathmynetry data. -} -\description{ - Imports lake bathymetry data. Bathymetric data file must be a 2 column array - where depth (in meters) and area (in meters^2) information are provided in columns - with headers containing the words "depths" and "areas" respectively. -} +\title{Import lake bathymetry data.} \usage{ - load.bathy(fPath) +load.bathy(fPath) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{fPath}{ - File path to the bathymetry file. - } +\item{fPath}{File path to the bathymetry file.} } - \value{ - data.frame of depth and area for given lake. +data.frame of depth and area for given lake. } - -\author{ - Luke Winslow -} - -%% ~Make other sections like Warning with \section{Warning }{....} ~ - -\seealso{ - \code{\link{load.ts}} +\description{ +Imports lake bathymetry data. Bathymetric data file must be a 2 column array +where depth (in meters) and area (in meters^2) information are provided in +columns with headers containing the words "depths" and "areas" respectively. } \examples{ + #Get the path for the package example file included exampleFilePath <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") @@ -44,6 +30,7 @@ ylab='Depths (m)', xlab='Areas (m^2)') } - +\seealso{ +\code{\link{load.ts}} +} \keyword{file} - diff --git a/man/load.ts.Rd b/man/load.ts.Rd index 2a12e6f..02ef681 100644 --- a/man/load.ts.Rd +++ b/man/load.ts.Rd @@ -1,44 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/load.data.R \name{load.ts} \alias{load.ts} - -\title{ - Load timeseries from properly formatted text file. -} -\description{ - A convenience function to load timeseries data into R based on the standardized format used by Lake Analyzer. -} +\title{Load timeseries from properly formatted text file.} \usage{ -load.ts(fPath, tz="GMT") +load.ts(fPath, tz = "GMT") } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{fPath}{ - The file path as a string. -} - \item{tz}{ - Timezone string to be supplied to \code{\link{as.POSIXct}}. Defaults to GMT (UTC-0). This often can - be left to the default unless timezone support is specifically required. - } -} -\details{ - Timeseries files must follow a common format. The first column must have the label 'datetime' and - be of the format \emph{yyyy-mm-dd HH:MM:SS} (ISO 8601 without the "T" delimiter). The second can be skipped - if not using sub-minute data. +\item{fPath}{The file path as a string.} + +\item{tz}{Timezone string to be supplied to \code{\link{as.POSIXct}}. +Defaults to GMT (UTC-0). This often can be left to the default unless +timezone support is specifically required.} } \value{ - A data frame in the required format for use with other rLakeAnalyzer timeseries functions. +A data frame in the required format for use with other rLakeAnalyzer +timeseries functions. } +\description{ +A convenience function to load timeseries data into R based on the +standardized format used by Lake Analyzer. -\author{ - Luke Winslow -} - -\seealso{ -For dataloading \code{\link{ts.meta.depths}}, \cr -For analyzing timeseries data, see \code{\link{ts.meta.depths}}, \code{\link{ts.thermo.depth}}, \code{\link{ts.schmidt.stability}}, -\code{\link{ts.lake.number}}. +Timeseries files must follow a common format. The first column must have the +label 'datetime' and be of the format \emph{yyyy-mm-dd HH:MM:SS} (ISO 8601 +without the "T" delimiter). The second can be skipped if not using +sub-minute data. } \examples{ + #Get the path for the package example file included exampleFilePath <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") @@ -50,7 +39,10 @@ For analyzing timeseries data, see \code{\link{ts.meta.depths}}, \code{\link{ts. plot(t.d$datetime, t.d$thermo.depth, type='l', ylab='Thermocline Depth (m)', xlab='Date') } - - +\seealso{ +For dataloading \code{\link{ts.meta.depths}}, \cr For analyzing +timeseries data, see \code{\link{ts.meta.depths}}, +\code{\link{ts.thermo.depth}}, \code{\link{ts.schmidt.stability}}, +\code{\link{ts.lake.number}}. +} \keyword{file} - diff --git a/man/meta.depths.Rd b/man/meta.depths.Rd index 03e3711..b7a3956 100644 --- a/man/meta.depths.Rd +++ b/man/meta.depths.Rd @@ -9,31 +9,33 @@ meta.depths(wtr, depths, slope = 0.1, seasonal = TRUE, mixed.cutoff = 1) \arguments{ \item{wtr}{a numeric vector of water temperature in degrees C} -\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr measurements} +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} \item{slope}{a numeric vector corresponding to the minimum slope} -\item{seasonal}{a logical value indicating whether the seasonal thermocline should be -returned. This is fed to thermo.depth, which is used as the starting point. -The seasonal thermocline is defined as the deepest density gradient found -in the profile. If \code{FALSE}, the depth of the maximum density gradient is used -as the starting point.} +\item{seasonal}{a logical value indicating whether the seasonal thermocline +should be returned. This is fed to thermo.depth, which is used as the +starting point. The seasonal thermocline is defined as the deepest density +gradient found in the profile. If \code{FALSE}, the depth of the maximum +density gradient is used as the starting point.} -\item{mixed.cutoff}{A cutoff (deg C) where below this threshold, thermo.depth and meta.depths -are not calculated (NaN is returned). Defaults to 1 deg C.} +\item{mixed.cutoff}{A cutoff (deg C) where below this threshold, +thermo.depth and meta.depths are not calculated (NaN is returned). Defaults +to 1 deg C.} } \value{ -A numeric vector of the top and bottom metalimnion depths in meters. +A numeric vector of the top and bottom metalimnion depths in meters. Returns the bottom depth if no distinct metalimion top and bottom found. } \description{ -Calculates the top and bottom depths of the metalimnion -in a stratified lake. The metalimnion is defined as the -water stratum in a stratified lake with the steepest thermal -gradient and is demarcated by the bottom of the epilimnion and top -of the hypolimnion. +Calculates the top and bottom depths of the metalimnion in a stratified +lake. The metalimnion is defined as the water stratum in a stratified lake +with the steepest thermal gradient and is demarcated by the bottom of the +epilimnion and top of the hypolimnion. } \examples{ + wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) @@ -46,12 +48,10 @@ cat('The bottom depth of the metalimnion is:', m.d[2]) } \references{ -Wetzel, R. G. 2001. Limnology: Lake and River Ecosystems, 3rd ed. Academic Press. +Wetzel, R. G. 2001. Limnology: Lake and River Ecosystems, 3rd +ed. Academic Press. } \seealso{ \code{\link{ts.meta.depths}}, \code{\link{thermo.depth}} } -\author{ -Jennifer Brentrup, Luke Winslow -} \keyword{manip} diff --git a/man/rLakeAnalyzer.Rd b/man/rLakeAnalyzer.Rd new file mode 100644 index 0000000..eb42586 --- /dev/null +++ b/man/rLakeAnalyzer.Rd @@ -0,0 +1,13 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/rLakeAnalyzer.R +\docType{package} +\name{rLakeAnalyzer} +\alias{rLakeAnalyzer} +\alias{rLakeAnalyzer-package} +\title{Lake Physics Tools} +\description{ +Standardized methods for calculating common important derived +physical features of lakes including water density based based on +temperature, thermal layers, thermocline depth, lake number, Wedderburn +number, Schmidt stability and others. +} diff --git a/man/schmidt.plot.Rd b/man/schmidt.plot.Rd index 66cb74d..525fc0e 100644 --- a/man/schmidt.plot.Rd +++ b/man/schmidt.plot.Rd @@ -1,32 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/schmidt.plot.R \name{schmidt.plot} \alias{schmidt.plot} -\title{ Creates a time series plot of Schmidt's stability -} -\description{ Generates a time series of Schmidt's stability where each value represents water column stability for each time step of data. See \code{\link{schmidt.stability}} for more details and reference. -} +\title{Creates a time series plot of Schmidt's stability} \usage{ schmidt.plot(wtr, bth) } \arguments{ - \item{wtr}{ - Data frame of water temperature loaded with \code{\link{load.ts}} - } - \item{bth}{ - A data frame containing hypsometric data. Loaded using \code{\link{load.bathy}} - } -} - -\references{ - See \code{\link{schmidt.stability}} -} +\item{wtr}{Data frame of water temperature loaded with \code{\link{load.ts}}} -\author{ - Taylor Leach, Jennifer Brentrup +\item{bth}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} } -\seealso{ - \code{\link{schmidt.stability}} +\description{ +Generates a time series of Schmidt's stability where each value represents +water column stability for each time step of data. See +\code{\link{schmidt.stability}} for more details and reference. } \examples{ + # Get system data file paths wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") bth.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") @@ -40,4 +32,10 @@ schmidt.plot(wtr, bth) schmidt.plot(wtr,bth) } } -\keyword{ hplot } +\references{ +See \code{\link{schmidt.stability}} +} +\seealso{ +\code{\link{schmidt.stability}} +} +\keyword{hplot} diff --git a/man/schmidt.stability.Rd b/man/schmidt.stability.Rd index c9fc98c..b9099c4 100644 --- a/man/schmidt.stability.Rd +++ b/man/schmidt.stability.Rd @@ -1,42 +1,40 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/schmidt.stability.R \name{schmidt.stability} -\alias{schmidt.stability} -%- Also NEED an '\alias' for EACH other topic documented here. +\alias{schmidt.stability} \title{Calculate the Schmidt stability} -\description{Schmidt stability, or the resistance to mechanical mixing due to the potential energy inherent in the stratification of the water column. -} \usage{ schmidt.stability(wtr, depths, bthA, bthD, sal = 0) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{wtr}{ a numeric vector of water temperature in degrees C} - \item{depths}{ a numeric vector corresponding to the depths (in m) of the wtr measurements} - \item{bthA}{ a numeric vector of cross sectional areas (m^2) corresponding to bthD depths} - \item{bthD}{ a numeric vector of depths (m) which correspond to areal measures in bthA} - \item{sal}{ a numeric vector of salinity in Practical Salinity Scale units} -} -\details{ -Schmidt stability was first defined by Schmidt (1928) and later modified by Hutchinson (1957). This stability index was formalized by Idso (1973) to reduce the effects of lake volume on the calculation (resulting in a mixing energy requirement per unit area). -} -\value{ a numeric vector of Schmidt stability (J/m^2)} -\references{ -Schmidt, W., 1928. \emph{Ueber Temperatur and Stabilitaetsverhaltnisse von Seen}. Geo- graphiska Annaler 10, 145-177. +\item{wtr}{a numeric vector of water temperature in degrees C} -Hutchinson, G.E., 1957. \emph{A Treatise on Limnology}, vol. 1. John Wiley & Sons, Inc., New York. +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} -Idso, S.B., 1973. \emph{On the concept of lake stability}. Limnology and Oceanography 18, 681-683. +\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to +bthD depths} + +\item{bthD}{a numeric vector of depths (m) which correspond to areal +measures in bthA} + +\item{sal}{a numeric vector of salinity in Practical Salinity Scale units} } -\author{ -Luke Winslow +\value{ +a numeric vector of Schmidt stability (J/m^2) } +\description{ +Schmidt stability, or the resistance to mechanical mixing due to the +potential energy inherent in the stratification of the water column. -\seealso{ -\code{\link{ts.schmidt.stability}} -\code{\link{lake.number}} -\code{\link{wedderburn.number}} +Schmidt stability was first defined by Schmidt (1928) and later modified by +Hutchinson (1957). This stability index was formalized by Idso (1973) to +reduce the effects of lake volume on the calculation (resulting in a mixing +energy requirement per unit area). } \examples{ + bthA <- c(1000,900,864,820,200,10) bthD <- c(0,2.3,2.5,4.2,5.8,7) @@ -46,6 +44,18 @@ Luke Winslow cat('Schmidt stability for input is: ') cat(schmidt.stability(wtr, depths, bthA, bthD)) } +\references{ +Schmidt, W., 1928. \emph{Ueber Temperatur and +Stabilitaetsverhaltnisse von Seen}. Geo- graphiska Annaler 10, 145-177. -\keyword{arith} +Hutchinson, G.E., 1957. \emph{A Treatise on Limnology}, vol. 1. John Wiley & +Sons, Inc., New York. +Idso, S.B., 1973. \emph{On the concept of lake stability}. Limnology and +Oceanography 18, 681-683. +} +\seealso{ +\code{\link{ts.schmidt.stability}} \code{\link{lake.number}} +\code{\link{wedderburn.number}} +} +\keyword{arith} diff --git a/man/thermo.depth.Rd b/man/thermo.depth.Rd index 8f898e3..7fd0e14 100644 --- a/man/thermo.depth.Rd +++ b/man/thermo.depth.Rd @@ -10,30 +10,36 @@ thermo.depth(wtr, depths, Smin = 0.1, seasonal = TRUE, index = FALSE, \arguments{ \item{wtr}{a numeric vector of water temperature in degrees C} -\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr measurements} +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} -\item{Smin}{Optional paramter defining minimum density gradient for thermocline} +\item{Smin}{Optional paramter defining minimum density gradient for +thermocline} -\item{seasonal}{a logical value indicating whether the seasonal thermocline should be -returned. This is fed to thermo.depth, which is used as the starting point. -The seasonal thermocline is defined as the deepest density gradient found -in the profile. If \code{FALSE}, the depth of the maximum density gradient is used -as the starting point.} +\item{seasonal}{a logical value indicating whether the seasonal thermocline +should be returned. This is fed to thermo.depth, which is used as the +starting point. The seasonal thermocline is defined as the deepest density +gradient found in the profile. If \code{FALSE}, the depth of the maximum +density gradient is used as the starting point.} -\item{index}{Boolean value indicated if index of the thermocline depth, instead of the depth value, should be returned.} +\item{index}{Boolean value indicated if index of the thermocline depth, +instead of the depth value, should be returned.} -\item{mixed.cutoff}{A cutoff (deg C) where below this threshold, thermo.depth and meta.depths -are not calculated (NaN is returned). Defaults to 1 deg C.} +\item{mixed.cutoff}{A cutoff (deg C) where below this threshold, +thermo.depth and meta.depths are not calculated (NaN is returned). Defaults +to 1 deg C.} } \value{ Depth of thermocline. If no thermocline found, value is NaN. } \description{ -This function calculates the location of the thermocline from a temperature profile. -It uses a special technique to estimate where the thermocline lies even between two -temperature measurement depths, giving a potentially finer-scale estimate than usual techniques. +This function calculates the location of the thermocline from a temperature +profile. It uses a special technique to estimate where the thermocline lies +even between two temperature measurement depths, giving a potentially +finer-scale estimate than usual techniques. } \examples{ + # A vector of water temperatures wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, 15.15, 14.24, 13.35, 10.94, 10.43, 10.36, 9.94, 9.45, 9.1, 8.91, 8.58, 8.43) @@ -50,7 +56,4 @@ wtr = c(22.51, 22.42, 22.4, 22.4, 22.4, 22.36, 22.3, 22.21, 22.11, 21.23, 16.42, \seealso{ \code{\link{ts.thermo.depth}}, \code{water.density} } -\author{ -Luke Winslow -} \keyword{manip} diff --git a/man/ts.buoyancy.freq.Rd b/man/ts.buoyancy.freq.Rd index 5cff56e..4437329 100644 --- a/man/ts.buoyancy.freq.Rd +++ b/man/ts.buoyancy.freq.Rd @@ -1,54 +1,39 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/buoyancy.freq.R \name{ts.buoyancy.freq} \alias{ts.buoyancy.freq} - -\title{ - Calculate the buoyancy (Brunt-Vaisala) frequency for a temperature profile. -} -\description{ -Function for simplifying the calculation of buoyancy frequency. Can usually be called directly on data loaded directly using \code{\link{load.ts}} and - \code{\link{load.bathy}}. -} - - +\title{Calculate the buoyancy (Brunt-Vaisala) frequency for a temperature profile.} \usage{ -ts.buoyancy.freq(wtr, at.thermo=TRUE, na.rm=FALSE, ...) +ts.buoyancy.freq(wtr, at.thermo = TRUE, na.rm = FALSE, ...) } - \arguments{ - \item{wtr}{ - A data frame of water temperatures (in Celsius). Loaded using \code{\link{load.ts}} - } - \item{at.thermo}{ - Boolean indicating if only buoyancy frequency at the thermocline should be returned. If false, full profile is returned. - } - \item{na.rm}{ - Boolean indicated if step-by-step removal of NA's should be tried. If false, a timestep with any NA values - will likely return an NA value. If true, best effort will be made to calculate indices despite NA values. - } - \item{...}{ - Additional parameters will be passed on to \code{thermo.depth} function when extracting buoyancy frequency at only the thermocline. - Common parameters to supply would be \code{seasonal} and \code{slope}. - } -} +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}} -\value{Returns a data frame with the timeseries of buoyancy frequency in units \code{sec^-2}. Includes a \sQuote{datetime} column.} - -\references{ -Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. Advances in Applied -Mechanics 27, 353-370. -} -\author{ - Luke Winslow -} +\item{at.thermo}{Boolean indicating if only buoyancy frequency at the +thermocline should be returned. If false, full profile is returned.} -%% ~Make other sections like Warning with \section{Warning }{....} ~ +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will likely return an NA +value. If true, best effort will be made to calculate indices despite NA +values.} -\seealso{ - \code{buoyancy.freq} +\item{...}{Additional parameters will be passed on to \code{thermo.depth} +function when extracting buoyancy frequency at only the thermocline. Common +parameters to supply would be \code{seasonal} and \code{slope}.} +} +\value{ +Returns a data frame with the timeseries of buoyancy frequency in +units \code{sec^-2}. Includes a \sQuote{datetime} column. +} +\description{ +Function for simplifying the calculation of buoyancy frequency. Can usually +be called directly on data loaded directly using \code{\link{load.ts}} and +\code{\link{load.bathy}}. } - \examples{ + #Get the path for the package example file included wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") @@ -62,6 +47,11 @@ Mechanics 27, 353-370. lines(SN2, col='red') } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. +\references{ +Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +Advances in Applied Mechanics 27, 353-370. +} +\seealso{ +\code{buoyancy.freq} +} \keyword{arith} diff --git a/man/ts.center.buoyancy.Rd b/man/ts.center.buoyancy.Rd index 561b4b5..698f3a5 100644 --- a/man/ts.center.buoyancy.Rd +++ b/man/ts.center.buoyancy.Rd @@ -1,46 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/center.buoyancy.R \name{ts.center.buoyancy} \alias{ts.center.buoyancy} - -\title{ - Calculates the center of buoyancy for multiple temperature profiles. -} -\description{ -Function for simplifying the calculation of the center of buoyancy. Can usually be called directly on data loaded directly using \code{\link{load.ts}} and - \code{\link{load.bathy}}. -} - +\title{Calculates the center of buoyancy for multiple temperature profiles.} \usage{ -ts.center.buoyancy(wtr, na.rm=FALSE) +ts.center.buoyancy(wtr, na.rm = FALSE) } - \arguments{ - \item{wtr}{ - A data frame of water temperatures (in Celsius). Loaded using \code{\link{load.ts}} - } - \item{na.rm}{ - Boolean indicated if step-by-step removal of NA's should be tried. If false, a timestep with any NA values - will return an NA value. If true, best effort will be made to calculate indices despite NA values. - } -} +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}} -\value{Returns a data frame with the timeseries of the center of buoyancy frequency. Includes a \sQuote{datetime} column.} - -\references{ -Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. Advances in Applied -Mechanics 27, 353-370. +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will return an NA value. If +true, best effort will be made to calculate indices despite NA values.} } -\author{ - Jordan S Read +\value{ +Returns a data frame with the timeseries of the center of buoyancy +frequency. Includes a \sQuote{datetime} column. } - -%% ~Make other sections like Warning with \section{Warning }{....} ~ - -\seealso{ - \code{center.buoyancy}, \code{load.bathy}, \code{load.ts} +\description{ +Function for simplifying the calculation of the center of buoyancy. Can +usually be called directly on data loaded directly using +\code{\link{load.ts}} and \code{\link{load.bathy}}. } - \examples{ + #Get the path for the package example file included wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") @@ -60,6 +45,11 @@ Mechanics 27, 353-370. lwd=c(1.5,1.5),col=c("black","red"), bty = "n") } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. +\references{ +Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +Advances in Applied Mechanics 27, 353-370. +} +\seealso{ +\code{center.buoyancy}, \code{load.bathy}, \code{load.ts} +} \keyword{arith} diff --git a/man/ts.internal.energy.Rd b/man/ts.internal.energy.Rd new file mode 100644 index 0000000..2d5c55d --- /dev/null +++ b/man/ts.internal.energy.Rd @@ -0,0 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R +\name{ts.internal.energy} +\alias{ts.internal.energy} +\title{Calculate physical indices for a timeseries.} +\usage{ +ts.internal.energy(wtr, bathy, na.rm = FALSE) +} +\arguments{ +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +where ##.# is depth in meters.} + +\item{bathy}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} + +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will return an NA value. If +true, best effort will be made to calculate indices despite NA values.} +} +\value{ +Returns a data frame with the timeseries of calculated derivatives. +All include a \sQuote{datetime} column, but derivative columns differ +between functions. +} +\description{ +Functions for simplifying the calculation of physical indices for a +timeseries of observation data. Can usually be called directly on data +loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. + +These are wrapper functions that accept a timeseries of data and call the +core physical metric functions (like \code{\link{schmidt.stability}}) on +each timestep. +} +\seealso{ +For loading input data \code{\link{load.ts}}, +\code{\link{load.bathy}}. + +For the underlying functions operating at each timestep +\code{\link{meta.depths}}, \code{\link{thermo.depth}}, +\code{\link{schmidt.stability}}, \code{\link{lake.number}}, +\code{\link{internal.energy}}. + +Other Timeseries functions for r Lake Analyzer: \code{\link{ts.lake.number}}, + \code{\link{ts.meta.depths}}, + \code{\link{ts.schmidt.stability}}, + \code{\link{ts.thermo.depth}}, \code{\link{ts.uStar}} +} +\keyword{manip} diff --git a/man/ts.lake.number.Rd b/man/ts.lake.number.Rd new file mode 100644 index 0000000..1eed6fb --- /dev/null +++ b/man/ts.lake.number.Rd @@ -0,0 +1,53 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R +\name{ts.lake.number} +\alias{ts.lake.number} +\title{Calculate physical indices for a timeseries.} +\usage{ +ts.lake.number(wtr, wnd, wnd.height, bathy, seasonal = TRUE) +} +\arguments{ +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +where ##.# is depth in meters.} + +\item{wnd}{A data frame of wind speeds (in m/s). Loaded using +\code{\link{load.ts}}} + +\item{wnd.height}{Height of the anemometer above the lake surface in meters} + +\item{bathy}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} + +\item{seasonal}{Boolean indicating if seasonal thermocline should be used in +calculation.} +} +\value{ +Returns a data frame with the timeseries of calculated derivatives. +All include a \sQuote{datetime} column, but derivative columns differ +between functions. +} +\description{ +Functions for simplifying the calculation of physical indices for a +timeseries of observation data. Can usually be called directly on data +loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. + +These are wrapper functions that accept a timeseries of data and call the +core physical metric functions (like \code{\link{schmidt.stability}}) on +each timestep. +} +\seealso{ +For loading input data \code{\link{load.ts}}, +\code{\link{load.bathy}}. + +For the underlying functions operating at each timestep +\code{\link{meta.depths}}, \code{\link{thermo.depth}}, +\code{\link{schmidt.stability}}, \code{\link{lake.number}}, +\code{\link{internal.energy}}. + +Other Timeseries functions for r Lake Analyzer: \code{\link{ts.internal.energy}}, + \code{\link{ts.meta.depths}}, + \code{\link{ts.schmidt.stability}}, + \code{\link{ts.thermo.depth}}, \code{\link{ts.uStar}} +} +\keyword{manip} diff --git a/man/ts.layer.temperature.Rd b/man/ts.layer.temperature.Rd index 90b3796..ac3b723 100644 --- a/man/ts.layer.temperature.Rd +++ b/man/ts.layer.temperature.Rd @@ -1,55 +1,45 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R \name{ts.layer.temperature} \alias{ts.layer.temperature} - -\title{ - Calculate volume-weighted average water temperature across a range of depths for a timeseries. -} -\description{ -Function for simplifying the calculation of Wedderburn Number. Can usually be called directly on data loaded directly using \code{\link{load.ts}} and - \code{\link{load.bathy}}. -} - - +\title{Calculate volume-weighted average water temperature across a range of depths +for a timeseries.} \usage{ - ts.layer.temperature(wtr, top, bottom, bathy, na.rm=FALSE) +ts.layer.temperature(wtr, top, bottom, bathy, na.rm = FALSE) } - \arguments{ - \item{wtr}{ - A data frame of water temperatures (in Celsius). Loaded using \code{\link{load.ts}} - } - \item{top}{ - Either a single numeric depth value to be used across the entire timeseries, or a vector of same - length as the timeseries (e.g., \code{nrow(wtr)}). This is useful when calculating a time-varying layer - average, like average epilimnion temperature. - } - \item{bottom}{ - Either a single numeric depth value to be used across the entire timeseries, or a vector of same - length as the timeseries (e.g., \code{nrow(wtr)}). This is useful when calculating a time-varying layer - average, like average epilimnion temperature. - } - \item{bathy}{ - A data frame containing hypsometric data. Loaded using \code{\link{load.bathy}} - } - \item{na.rm}{ - Boolean indicated if step-by-step removal of NA's should be tried. If false, a timestep with any NA values - will return an NA value. If true, best effort will be made to calculate indices despite NA values. - } -} +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}} -\value{Returns a data frame with the timeseries of the average layer temperature. Includes - \sQuote{datetime} and \sQuote{layer.temp} columns.} - -\author{ - Luke Winslow -} +\item{top}{Either a single numeric depth value to be used across the entire +timeseries, or a vector of same length as the timeseries (e.g., +\code{nrow(wtr)}). This is useful when calculating a time-varying layer +average, like average epilimnion temperature.} + +\item{bottom}{Either a single numeric depth value to be used across the +entire timeseries, or a vector of same length as the timeseries (e.g., +\code{nrow(wtr)}). This is useful when calculating a time-varying layer +average, like average epilimnion temperature.} -%% ~Make other sections like Warning with \section{Warning }{....} ~ +\item{bathy}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} -\seealso{\code{layer.temperature} +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will return an NA value. If +true, best effort will be made to calculate indices despite NA values.} +} +\value{ +Returns a data frame with the timeseries of the average layer +temperature. Includes \sQuote{datetime} and \sQuote{layer.temp} columns. +} +\description{ +Function for simplifying the calculation of Wedderburn Number. Can usually +be called directly on data loaded directly using \code{\link{load.ts}} and +\code{\link{load.bathy}}. } \examples{ + #Get the path for the package example file included wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") bathy.path <- system.file('extdata', 'Sparkling.bth', package="rLakeAnalyzer") @@ -64,6 +54,7 @@ Function for simplifying the calculation of Wedderburn Number. Can usually be ca ylab='Volumetrically averaged lake temperature', xlab='Date') } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. +\seealso{ +\code{layer.temperature} +} \keyword{arith} diff --git a/man/ts.meta.depths.Rd b/man/ts.meta.depths.Rd index 7cdf662..68715d1 100644 --- a/man/ts.meta.depths.Rd +++ b/man/ts.meta.depths.Rd @@ -1,85 +1,42 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R \name{ts.meta.depths} \alias{ts.meta.depths} -\alias{ts.thermo.depth} -\alias{ts.schmidt.stability} -\alias{ts.lake.number} -\alias{ts.uStar} -\alias{ts.internal.energy} - -\title{ - Calculate physical indices for a timeseries. -} -\description{ - Functions for simplifying the calculation of physical indices for a timeseries of observation data. - Can usually be called directly on data loaded directly using \code{\link{load.ts}} and - \code{\link{load.bathy}}. -} +\title{Calculate physical indices for a timeseries.} \usage{ - ts.meta.depths(wtr, slope = 0.1, na.rm=FALSE, ...) - - ts.thermo.depth(wtr, Smin = 0.1, na.rm=FALSE, ...) - - ts.schmidt.stability(wtr, bathy, na.rm=FALSE) +ts.meta.depths(wtr, slope = 0.1, na.rm = FALSE, ...) +} +\arguments{ +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +where ##.# is depth in meters.} - ts.lake.number(wtr, wnd, wnd.height, bathy, seasonal=TRUE) - - ts.uStar(wtr, wnd, wnd.height, bathy, seasonal=TRUE) +\item{slope}{The minimum density gradient (kg/m^3/m) that can be called the +thermocline} - ts.internal.energy(wtr, bathy, na.rm=FALSE) -} +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will return an NA value. If +true, best effort will be made to calculate indices despite NA values.} -\arguments{ - \item{wtr}{ - A data frame of water temperatures (in Celsius). Loaded using \code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} where ##.# is depth in meters. - } - \item{slope}{ - The minimum density gradient (kg/m^3/m) that can be called the thermocline - } - \item{Smin}{ - The minimum density gradient cutoff (kg/m^3/m) defining the metalimion - } - \item{bathy}{ - A data frame containing hypsometric data. Loaded using \code{\link{load.bathy}} - } - \item{wnd}{ - A data frame of wind speeds (in m/s). Loaded using \code{\link{load.ts}} - } - \item{wnd.height}{ - Height of the anemometer above the lake surface in meters - } - \item{seasonal}{ - Boolean indicating if seasonal thermocline should be used in calculation. - } - \item{na.rm}{ - Boolean indicated if step-by-step removal of NA's should be tried. If false, a timestep with any NA values - will return an NA value. If true, best effort will be made to calculate indices despite NA values. - } - \item{...}{ - Additional parameters passed to underlying base function (e.g., index=TRUE for thermo.depth) - } -} -\details{ - These are wrapper functions that accept a timeseries of data and call the core - physical metric functions (like \code{\link{schmidt.stability}}) on each timestep. - +\item{...}{Additional parameters passed to underlying base function (e.g., +index=TRUE for thermo.depth)} } \value{ - Returns a data frame with the timeseries of calculated derivatives. All include - a \sQuote{datetime} column, but derivative columns differ between functions. +Returns a data frame with the timeseries of calculated derivatives. +All include a \sQuote{datetime} column, but derivative columns differ +between functions. } +\description{ +Functions for simplifying the calculation of physical indices for a +timeseries of observation data. Can usually be called directly on data +loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. -\author{ - Luke Winslow +These are wrapper functions that accept a timeseries of data and call the +core physical metric functions (like \code{\link{schmidt.stability}}) on +each timestep. } - -\seealso{ - For loading input data \code{\link{load.ts}}, \code{\link{load.bathy}}. - - For the underlying functions operating at each timestep \code{\link{meta.depths}}, - \code{\link{thermo.depth}}, \code{\link{schmidt.stability}}, \code{\link{lake.number}}, \code{\link{internal.energy}}. -} - \examples{ + #Get the path for the package example file included exampleFilePath <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") @@ -93,12 +50,19 @@ lines(m.d$datetime, m.d$bottom, col='red') - #calculate and plot the thermocline depth - t.d = ts.thermo.depth(sparkling.temp) - - plot(t.d$datetime, t.d$thermo.depth, type='l', ylab='Thermocline Depth (m)', xlab='Date') - } +\seealso{ +For loading input data \code{\link{load.ts}}, +\code{\link{load.bathy}}. -\keyword{manip} +For the underlying functions operating at each timestep +\code{\link{meta.depths}}, \code{\link{thermo.depth}}, +\code{\link{schmidt.stability}}, \code{\link{lake.number}}, +\code{\link{internal.energy}}. +Other Timeseries functions for r Lake Analyzer: \code{\link{ts.internal.energy}}, + \code{\link{ts.lake.number}}, + \code{\link{ts.schmidt.stability}}, + \code{\link{ts.thermo.depth}}, \code{\link{ts.uStar}} +} +\keyword{manip} diff --git a/man/ts.schmidt.stability.Rd b/man/ts.schmidt.stability.Rd new file mode 100644 index 0000000..958687a --- /dev/null +++ b/man/ts.schmidt.stability.Rd @@ -0,0 +1,49 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R +\name{ts.schmidt.stability} +\alias{ts.schmidt.stability} +\title{Calculate physical indices for a timeseries.} +\usage{ +ts.schmidt.stability(wtr, bathy, na.rm = FALSE) +} +\arguments{ +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +where ##.# is depth in meters.} + +\item{bathy}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} + +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will return an NA value. If +true, best effort will be made to calculate indices despite NA values.} +} +\value{ +Returns a data frame with the timeseries of calculated derivatives. +All include a \sQuote{datetime} column, but derivative columns differ +between functions. +} +\description{ +Functions for simplifying the calculation of physical indices for a +timeseries of observation data. Can usually be called directly on data +loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. + +These are wrapper functions that accept a timeseries of data and call the +core physical metric functions (like \code{\link{schmidt.stability}}) on +each timestep. +} +\seealso{ +For loading input data \code{\link{load.ts}}, +\code{\link{load.bathy}}. + +For the underlying functions operating at each timestep +\code{\link{meta.depths}}, \code{\link{thermo.depth}}, +\code{\link{schmidt.stability}}, \code{\link{lake.number}}, +\code{\link{internal.energy}}. + +Other Timeseries functions for r Lake Analyzer: \code{\link{ts.internal.energy}}, + \code{\link{ts.lake.number}}, + \code{\link{ts.meta.depths}}, + \code{\link{ts.thermo.depth}}, \code{\link{ts.uStar}} +} +\keyword{manip} diff --git a/man/ts.thermo.depth.Rd b/man/ts.thermo.depth.Rd new file mode 100644 index 0000000..14d1e2b --- /dev/null +++ b/man/ts.thermo.depth.Rd @@ -0,0 +1,68 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R +\name{ts.thermo.depth} +\alias{ts.thermo.depth} +\title{Calculate physical indices for a timeseries.} +\usage{ +ts.thermo.depth(wtr, Smin = 0.1, na.rm = FALSE, ...) +} +\arguments{ +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +where ##.# is depth in meters.} + +\item{Smin}{The minimum density gradient cutoff (kg/m^3/m) defining the +metalimion} + +\item{na.rm}{Boolean indicated if step-by-step removal of NA's should be +tried. If false, a timestep with any NA values will return an NA value. If +true, best effort will be made to calculate indices despite NA values.} + +\item{...}{Additional parameters passed to underlying base function (e.g., +index=TRUE for thermo.depth)} +} +\value{ +Returns a data frame with the timeseries of calculated derivatives. +All include a \sQuote{datetime} column, but derivative columns differ +between functions. +} +\description{ +Functions for simplifying the calculation of physical indices for a +timeseries of observation data. Can usually be called directly on data +loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. + +These are wrapper functions that accept a timeseries of data and call the +core physical metric functions (like \code{\link{schmidt.stability}}) on +each timestep. +} +\examples{ + + #Get the path for the package example file included + exampleFilePath <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") + + #Load + sparkling.temp = load.ts(exampleFilePath) + + + #calculate and plot the thermocline depth + t.d = ts.thermo.depth(sparkling.temp) + + plot(t.d$datetime, t.d$thermo.depth, type='l', ylab='Thermocline Depth (m)', xlab='Date') + +} +\seealso{ +For loading input data \code{\link{load.ts}}, +\code{\link{load.bathy}}. + +For the underlying functions operating at each timestep +\code{\link{meta.depths}}, \code{\link{thermo.depth}}, +\code{\link{schmidt.stability}}, \code{\link{lake.number}}, +\code{\link{internal.energy}}. + +Other Timeseries functions for r Lake Analyzer: \code{\link{ts.internal.energy}}, + \code{\link{ts.lake.number}}, + \code{\link{ts.meta.depths}}, + \code{\link{ts.schmidt.stability}}, + \code{\link{ts.uStar}} +} +\keyword{manip} diff --git a/man/ts.uStar.Rd b/man/ts.uStar.Rd new file mode 100644 index 0000000..8224c9d --- /dev/null +++ b/man/ts.uStar.Rd @@ -0,0 +1,54 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R +\name{ts.uStar} +\alias{ts.uStar} +\title{Calculate physical indices for a timeseries.} +\usage{ +ts.uStar(wtr, wnd, wnd.height, bathy, seasonal = TRUE) +} +\arguments{ +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}. Must have columns \code{datetime}, \code{wtr_##.#} +where ##.# is depth in meters.} + +\item{wnd}{A data frame of wind speeds (in m/s). Loaded using +\code{\link{load.ts}}} + +\item{wnd.height}{Height of the anemometer above the lake surface in meters} + +\item{bathy}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} + +\item{seasonal}{Boolean indicating if seasonal thermocline should be used in +calculation.} +} +\value{ +Returns a data frame with the timeseries of calculated derivatives. +All include a \sQuote{datetime} column, but derivative columns differ +between functions. +} +\description{ +Functions for simplifying the calculation of physical indices for a +timeseries of observation data. Can usually be called directly on data +loaded directly using \code{\link{load.ts}} and \code{\link{load.bathy}}. + +These are wrapper functions that accept a timeseries of data and call the +core physical metric functions (like \code{\link{schmidt.stability}}) on +each timestep. +} +\seealso{ +For loading input data \code{\link{load.ts}}, +\code{\link{load.bathy}}. + +For the underlying functions operating at each timestep +\code{\link{meta.depths}}, \code{\link{thermo.depth}}, +\code{\link{schmidt.stability}}, \code{\link{lake.number}}, +\code{\link{internal.energy}}. + +Other Timeseries functions for r Lake Analyzer: \code{\link{ts.internal.energy}}, + \code{\link{ts.lake.number}}, + \code{\link{ts.meta.depths}}, + \code{\link{ts.schmidt.stability}}, + \code{\link{ts.thermo.depth}} +} +\keyword{manip} diff --git a/man/ts.wedderburn.number.Rd b/man/ts.wedderburn.number.Rd index e43cb59..bed5f95 100644 --- a/man/ts.wedderburn.number.Rd +++ b/man/ts.wedderburn.number.Rd @@ -1,59 +1,41 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/timeseries.functions.R \name{ts.wedderburn.number} \alias{ts.wedderburn.number} - -\title{ - Calculate Wedderburn number for a timeseries. -} -\description{ -Function for simplifying the calculation of Wedderburn Number. Can usually be called directly on data loaded directly using \code{\link{load.ts}} and - \code{\link{load.bathy}}. -} - - +\title{Calculate Wedderburn number for a timeseries.} \usage{ -ts.wedderburn.number(wtr, wnd, wnd.height, bathy, Ao, seasonal=TRUE) +ts.wedderburn.number(wtr, wnd, wnd.height, bathy, Ao, seasonal = TRUE) } - \arguments{ - \item{wtr}{ - A data frame of water temperatures (in Celsius). Loaded using \code{\link{load.ts}} - } - \item{wnd}{ - A data frame of wind speeds (in m/s). Loaded using \code{\link{load.ts}} - } - \item{wnd.height}{ - Height of the anemometer above the lake surface in meters - } - \item{bathy}{ - A data frame containing hypsometric data. Loaded using \code{\link{load.bathy}} - } - \item{Ao}{ - Numeric value for the water body surface area (m^2) at zero meters depth - } - \item{seasonal}{ - Boolean indicating if seasonal thermocline should be used in calculation. - } - -} +\item{wtr}{A data frame of water temperatures (in Celsius). Loaded using +\code{\link{load.ts}}} -\value{Returns a data frame with the timeseries of Wedderburn number. Includes - a \sQuote{datetime} column.} - -\references{ -Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. Advances in Applied -Mechanics 27, 353-370. -} -\author{ - Luke Winslow -} +\item{wnd}{A data frame of wind speeds (in m/s). Loaded using +\code{\link{load.ts}}} + +\item{wnd.height}{Height of the anemometer above the lake surface in meters} +\item{bathy}{A data frame containing hypsometric data. Loaded using +\code{\link{load.bathy}}} -%% ~Make other sections like Warning with \section{Warning }{....} ~ +\item{Ao}{Numeric value for the water body surface area (m^2) at zero meters +depth} -\seealso{\code{wedderburn.number},\code{ts.lake.number} +\item{seasonal}{Boolean indicating if seasonal thermocline should be used in +calculation.} +} +\value{ +Returns a data frame with the timeseries of Wedderburn number. +Includes a \sQuote{datetime} column. +} +\description{ +Function for simplifying the calculation of Wedderburn Number. Can usually +be called directly on data loaded directly using \code{\link{load.ts}} and +\code{\link{load.bathy}}. } \examples{ + #Get the path for the package example file included wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") wnd.path <- system.file('extdata', 'Sparkling.daily.wnd', package="rLakeAnalyzer") @@ -71,6 +53,11 @@ Mechanics 27, 353-370. plot(w.n$datetime, w.n$wedderburn.number, type='l', ylab='Wedderburn Number', xlab='Date') } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. +\references{ +Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +Advances in Applied Mechanics 27, 353-370. +} +\seealso{ +\code{wedderburn.number},\code{ts.lake.number} +} \keyword{arith} diff --git a/man/uStar.Rd b/man/uStar.Rd index 1c61183..6c7447e 100644 --- a/man/uStar.Rd +++ b/man/uStar.Rd @@ -1,39 +1,31 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/uStar.R \name{uStar} \alias{uStar} - \title{Calculates the water friction velocity, uStar} -\description{uStar is the water friction velocity due to wind stress at the lake surface, it is calculated following the methods of Imberger (1985) as a function of the shear stress of air (Fischer et al., 1979), drag coefficient for momentum (Hicks, 1972), and a dimensionless constant (von Karman constant) that decribes the logarithmic velocity profile at the air-water interface} \usage{ uStar(wndSpeed, wndHeight, averageEpiDense) } - \arguments{ - \item{wndSpeed}{a numeric vector of wind speed in m s-1} - \item{wndHeight}{a numeric vector of wind measurement height in m} - \item{averageEpiDense}{a numeric vector of epilimnion density in kg m-3} -} +\item{wndSpeed}{a numeric vector of wind speed in m s-1} -\value{a numeric vector of uStar} -\references{ - - Hicks, B.B., 1972. \emph{A procedure for the formulation of bulk transfer coefficients over water bodies of different sizes}. Boundary-Layer Meterology 3: 201-213. - - Amorocho, J., DeVries, J.J., 1980. \emph{A new evaluation of the wind stress coefficient over water surfaces}. Journal of Geophysical Research 85: 433-442. - - Fischer, H.B., List, E.J., Koh, R.C.Y., Imberger, J., Brooks, N.H., 1979. \emph{Mixing in inland and coastal waters}. Academic Press. - - Imberger, J., 1985. \emph{The diurnal mixed layer}. Limnology and Oceanography 30: 737-770. -} +\item{wndHeight}{a numeric vector of wind measurement height in m} -\author{R. Iestyn. Woolway} - -\seealso{ - \code{\link{ts.uStar}} - \code{\link{layer.density}} +\item{averageEpiDense}{a numeric vector of epilimnion density in kg m-3} +} +\value{ +a numeric vector of uStar +} +\description{ +uStar is the water friction velocity due to wind stress at the lake surface, +it is calculated following the methods of Imberger (1985) as a function of +the shear stress of air (Fischer et al., 1979), drag coefficient for +momentum (Hicks, 1972), and a dimensionless constant (von Karman constant) +that decribes the logarithmic velocity profile at the air-water interface } - \examples{ + wndSpeed <- c(5.1,6.3,6.3,5.2,7,7.2) wndHeight <- 2 averageEpiDense <- c(14,15,14.2,13,12,12) @@ -41,5 +33,22 @@ uStar(wndSpeed, wndHeight, averageEpiDense) cat('uStar for input vector is: ') cat(uStar(wndSpeed,wndHeight,averageEpiDense)) } +\references{ +Hicks, B.B., 1972. \emph{A procedure for the formulation of bulk transfer +coefficients over water bodies of different sizes}. Boundary-Layer +Meterology 3: 201-213. + +Amorocho, J., DeVries, J.J., 1980. \emph{A new evaluation of the wind stress +coefficient over water surfaces}. Journal of Geophysical Research 85: +433-442. +Fischer, H.B., List, E.J., Koh, R.C.Y., Imberger, J., Brooks, N.H., 1979. +\emph{Mixing in inland and coastal waters}. Academic Press. + +Imberger, J., 1985. \emph{The diurnal mixed layer}. Limnology and +Oceanography 30: 737-770. +} +\seealso{ +\code{\link{ts.uStar}} \code{\link{layer.density}} +} \keyword{manip} diff --git a/man/water.density.Rd b/man/water.density.Rd index 4b4e57e..ba75a4d 100644 --- a/man/water.density.Rd +++ b/man/water.density.Rd @@ -1,31 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/water.density.R \name{water.density} \alias{water.density} \title{Estimate Water Density} -\description{Density of water from temperature and salinity} \usage{ -water.density(wtr, sal = wtr*0) +water.density(wtr, sal = wtr * 0) } \arguments{ -\item{wtr}{ a numeric vector of water temperature in degrees Celsius} -\item{sal}{ a numeric vector of salinity in Practical Salinity Scale units} -} +\item{wtr}{a numeric vector of water temperature in degrees Celsius} +\item{sal}{a numeric vector of salinity in Practical Salinity Scale units} +} \value{ A numeric vector of water densities in kg/m^3. } -\author{ -R. Iestyn. Woolway, Luke Winslow +\description{ +Density of water from temperature and salinity } \examples{ + #Plot water density for water between 1 and 30 deg C dens = water.density(1:30) plot(1:30, dens, xlab="Temp(deg C)", ylab="Density(kg/m^3)") } - \references{ -Martin, J.L., McCutcheon, S.C., 1999. \emph{Hydrodynamics and Transport for Water Quality Modeling.} Lewis Publications, Boca Raton, FL, 794pp. +Martin, J.L., McCutcheon, S.C., 1999. \emph{Hydrodynamics and +Transport for Water Quality Modeling.} Lewis Publications, Boca Raton, FL, +794pp. -Millero, F.J., Poisson, A., 1981. \emph{International one-atmosphere equation of state of seawater.} UNESCO Technical Papers in Marine Science. No. 36. +Millero, F.J., Poisson, A., 1981. \emph{International one-atmosphere +equation of state of seawater.} UNESCO Technical Papers in Marine Science. +No. 36. } - \keyword{arith} diff --git a/man/wedderburn.number.Rd b/man/wedderburn.number.Rd index ee55e8d..610b74b 100644 --- a/man/wedderburn.number.Rd +++ b/man/wedderburn.number.Rd @@ -1,46 +1,56 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/wedderburn.number.R \name{wedderburn.number} \alias{wedderburn.number} - -\title{ -Calculates Wedderburn Number for a lake. -} -\description{ Wedderburn Number (Wn) is a dimensionless parameter measuring the balance between -wind stress and bouyancy force and is used to estimate the amount of upwelling occuring in a lake. -When Wn is much greater than 1, the bouyancy force is much greater than the wind stress and therefore there is a strong vertical stratification with little horizontal variation in the stratification. When Wn is much less than 1, the wind stress is much greater than the bouyancy force and upwelling is likely occuring at the upwind end of the lake. When Wn is near 1, the bouyance force and wind stress are nearly equal and horizontal mixing is considered important} +\title{Calculates Wedderburn Number for a lake.} \usage{ wedderburn.number(delta_rho, metaT, uSt, Ao, AvHyp_rho) } - \arguments{ - \item{delta_rho}{ Numeric value for the water density difference between the epilimnion and hypolimnion (kg/m^3)} - \item{metaT}{ Numeric value for the thickness of the water body's surface layer (m)} - \item{uSt}{ Numeric value for the water friction velocity due to wind stress (m/s)} - \item{Ao}{ Numeric value for the water body surface area (m^2) at zero meters depth} - \item{AvHyp_rho}{ Numeric value for the average water density of the hypolimnion layer (kg/m^3)} -} +\item{delta_rho}{Numeric value for the water density difference between the +epilimnion and hypolimnion (kg/m^3)} -\value{ The dimensionless numeric value of Wedderburn Number} -\references{ -Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. Advances in Applied -Mechanics 27, 353-370. -} -\author{Jake Zwart} +\item{metaT}{Numeric value for the thickness of the water body's surface +layer (m)} +\item{uSt}{Numeric value for the water friction velocity due to wind stress +(m/s)} -%% ~Make other sections like Warning with \section{Warning }{....} ~ +\item{Ao}{Numeric value for the water body surface area (m^2) at zero meters +depth} -\seealso{ - \code{\link{ts.wedderburn.number}} - \code{\link{lake.number}} +\item{AvHyp_rho}{Numeric value for the average water density of the +hypolimnion layer (kg/m^3)} +} +\value{ +The dimensionless numeric value of Wedderburn Number +} +\description{ +Wedderburn Number (Wn) is a dimensionless parameter measuring the balance +between wind stress and bouyancy force and is used to estimate the amount of +upwelling occuring in a lake. When Wn is much greater than 1, the bouyancy +force is much greater than the wind stress and therefore there is a strong +vertical stratification with little horizontal variation in the +stratification. When Wn is much less than 1, the wind stress is much greater +than the bouyancy force and upwelling is likely occuring at the upwind end +of the lake. When Wn is near 1, the bouyance force and wind stress are +nearly equal and horizontal mixing is considered important } - \examples{ + delta_rho <- c(3.1,1.5) metaT <- c(5.5,2.4) uSt <- c(0.0028,0.0032) Ao <- c(80300,120000) AvHyp_rho <- c(999.31,999.1) wedderburn.number(delta_rho, metaT, uSt, Ao, AvHyp_rho) -} +} +\references{ +Imberger, J., Patterson, J.C., 1990. \emph{Physical limnology}. +Advances in Applied Mechanics 27, 353-370. +} +\seealso{ +\code{\link{ts.wedderburn.number}} \code{\link{lake.number}} +} \keyword{arith} diff --git a/man/whole.lake.temperature.Rd b/man/whole.lake.temperature.Rd index d32c614..ba97b1c 100644 --- a/man/whole.lake.temperature.Rd +++ b/man/whole.lake.temperature.Rd @@ -9,15 +9,18 @@ whole.lake.temperature(wtr, depths, bthA, bthD) \arguments{ \item{wtr}{a numeric vector of water temperature in degrees C.} -\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr measurements} +\item{depths}{a numeric vector corresponding to the depths (in m) of the wtr +measurements} -\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to bthD depths} +\item{bthA}{a numeric vector of cross sectional areas (m^2) corresponding to +bthD depths} -\item{bthD}{a numeric vector of depths (m) which correspond to areal measures in bthA} +\item{bthD}{a numeric vector of depths (m) which correspond to areal +measures in bthA} } \description{ -Calculates volumetrically weighted average whole lake temperature using -the supplied water temperature timeseries. +Calculates volumetrically weighted average whole lake temperature using the +supplied water temperature timeseries. } \seealso{ \code{\link{hypo.temperature}}, \code{\link{epi.temperature}} diff --git a/man/wtr.heat.map.Rd b/man/wtr.heat.map.Rd index 96e9dd9..8332936 100644 --- a/man/wtr.heat.map.Rd +++ b/man/wtr.heat.map.Rd @@ -1,35 +1,24 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/wtr.plotting.R \name{wtr.heat.map} \alias{wtr.heat.map} - -\title{ - Plots a heat-map of water temperature. -} -\description{ - This creates a simple, default heatmap of water temperature. -} +\title{Plots a heat-map of water temperature.} \usage{ - wtr.heat.map(wtr, ...) +wtr.heat.map(wtr, ...) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{wtr}{ - Data frame of water temperature loaded with \code{\link{load.ts}}. - } - \item{...}{ - Additional parameters supplied to \code{\link{filled.contour}} to modify defaults. Common examples - include \code{zlim} and \code{plot.title}. - } -} +\item{wtr}{Data frame of water temperature loaded with +\code{\link{load.ts}}.} -\author{ - Jennifer Brentrup, Luke Winslow +\item{...}{Additional parameters supplied to \code{\link{filled.contour}} +to modify defaults. Common examples include \code{zlim} and +\code{plot.title}.} } - -\seealso{ - \code{\link{load.ts}} +\description{ +This creates a simple, default heatmap of water temperature. } - \examples{ + #Get the path for the package example file included wtr.path <- system.file('extdata', 'Sparkling.daily.wtr', package="rLakeAnalyzer") @@ -42,7 +31,7 @@ #Change defaults supplied to filled.contour wtr.heat.map(sp.wtr, zlim=c(0,15), plot.title="Sparkling Water Temp (C)") } -% Add one or more standard keywords, see file 'KEYWORDS' in the -% R documentation directory. +\seealso{ +\code{\link{load.ts}} +} \keyword{hplot} - diff --git a/man/wtr.heatmap.layers.Rd b/man/wtr.heatmap.layers.Rd index 12567f8..dc56c78 100644 --- a/man/wtr.heatmap.layers.Rd +++ b/man/wtr.heatmap.layers.Rd @@ -1,44 +1,32 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/wtr.heatmap.layers.R \name{wtr.heatmap.layers} \alias{wtr.heatmap.layers} -\title{ - Plots water temperature heatmap with major limnetic layers indicated -} -\description{ - This creates a heat map of water temperature similar to \code{\link{wtr.heat.map}} - with additional lines drawn to denote the thermocline, and the top and bottom of - the metalimnion as calculated using \code{\link{ts.meta.depths}} - and \code{\link{thermo.depth}}. -} +\title{Plots water temperature heatmap with major limnetic layers indicated} \usage{ wtr.heatmap.layers(wtr, ...) } - \arguments{ - \item{wtr}{ - Data frame of water temperature loaded with \code{\link{load.ts}}. - } - \item{\dots}{ - Additional parameters supplied to \code{\link{filled.contour}} to modify defaults. - Common examples include \code{zlim} and \code{plot.title}. - } -} +\item{wtr}{Data frame of water temperature loaded with +\code{\link{load.ts}}.} -\author{ - Jennifer Brentrup, Luke Winslow and Taylor Leach +\item{\dots}{Additional parameters supplied to \code{\link{filled.contour}} +to modify defaults. Common examples include \code{zlim} and +\code{plot.title}.} } - -\note{ - This plot cannot be used in customized multi-panel figures using\code{\link{layout}} as layout is - already used in the filled.contour plotting function. +\description{ +This creates a heat map of water temperature similar to +\code{\link{wtr.heat.map}} with additional lines drawn to denote the +thermocline, and the top and bottom of the metalimnion as calculated using +\code{\link{ts.meta.depths}} and \code{\link{thermo.depth}}. } - -\seealso{ - \code{\link{wtr.heat.map}} - \code{\link{load.ts}} - \code{\link{ts.meta.depths}} - \code{\link{ts.thermo.depth}} +\note{ +This plot cannot be used in customized multi-panel figures +using\code{\link{layout}} as layout is already used in the filled.contour +plotting function. } \examples{ + #Get the path for the package example file included wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") @@ -50,4 +38,8 @@ wtr.heatmap.layers(wtr, ...) wtr.heatmap.layers(wtr) } } -\keyword{ hplot } +\seealso{ +\code{\link{wtr.heat.map}} \code{\link{load.ts}} +\code{\link{ts.meta.depths}} \code{\link{ts.thermo.depth}} +} +\keyword{hplot} diff --git a/man/wtr.layer.Rd b/man/wtr.layer.Rd index 5292f17..b33175c 100644 --- a/man/wtr.layer.Rd +++ b/man/wtr.layer.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/wtr-layer-segments.R +% Please edit documentation in R/wtr.layer.segments.R \name{wtr.layer} \alias{wtr.layer} \title{Exploration of lake water column layers} @@ -10,9 +10,11 @@ wtr.layer(data, depth, measure, thres = 0.1, z0 = 2.5, zmax = 150, \arguments{ \item{data}{data supplied as a bare (unquoted) value} -\item{depth}{depth in metres; should be an increasing vector; supplied as a bare (unquoted) value} +\item{depth}{depth in metres; should be an increasing vector; supplied as a +bare (unquoted) value} -\item{measure}{parameter measured in the water column profile; supplied as a bare (unquoted) value} +\item{measure}{parameter measured in the water column profile; supplied as a +bare (unquoted) value} \item{thres}{error norm; defaults to 0.1} @@ -20,21 +22,26 @@ wtr.layer(data, depth, measure, thres = 0.1, z0 = 2.5, zmax = 150, \item{zmax}{maximum depth in metres: defaults to 150m} -\item{nseg}{optional parameter to define the number of segments a priori; defaults to an unconstrained approach whereby -the algorithm determines segmentations by minimzing the error norm over each segment} +\item{nseg}{optional parameter to define the number of segments a priori; +defaults to an unconstrained approach whereby the algorithm determines +segmentations by minimzing the error norm over each segment} } \value{ -a dataframes with a list column. This includes: nseg (number of segments), mld (mix layer depth), cline (the - midpoint of the segment connecting inflection points that has the maximum slope; thermocline for temperature measures) - and segments calculated by the sm algorithm. +a dataframes with a list column. This includes: nseg (number of +segments), mld (mix layer depth), cline (the midpoint of the segment +connecting inflection points that has the maximum slope; thermocline for +temperature measures) and segments calculated by the sm algorithm. } \description{ -Extract water column parameters of a given parameter from a profile using the split-and-merge algorithm. - The cline is defined as the midpoint of the layer of water where the physical property change in the greatest over a - small difference. The exact cline depends on the specification of measure. For example if temperature is specified, - then we can expect cline to output the thermocline. +Extract water column parameters of a given parameter from a profile using +the split-and-merge algorithm. The cline is defined as the midpoint of the +layer of water where the physical property change in the greatest over a +small difference. The exact cline depends on the specification of measure. +For example if temperature is specified, then we can expect cline to output +the thermocline. } \examples{ + data("latesummer") df1 <- wtr.layer(depth=latesummer$depth, measure = latesummer$temper) df1$mld @@ -42,8 +49,10 @@ df1$segments wtr.layer(data = latesummer, depth=depth, measure = temper, nseg=4) + } \references{ -Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from Oceanic Profile Data. Journal of - Atmospheric and Oceanic Technology. 20(2), 319-329. +Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from +Oceanic Profile Data. Journal of Atmospheric and Oceanic Technology. 20(2), +319-329. } diff --git a/man/wtr.lineseries.Rd b/man/wtr.lineseries.Rd index 4469167..ed14a75 100644 --- a/man/wtr.lineseries.Rd +++ b/man/wtr.lineseries.Rd @@ -1,44 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/wtr.lineseries.R \name{wtr.lineseries} \alias{wtr.lineseries} -%- Also NEED an '\alias' for EACH other topic documented here. -\title{ - Creates a line based plot of temperature profile time series -} -\description{ -A non-heat map approach to visualizing a water temperature profile useful for -identify temperature trends over time at discrete depths and diagnosing issues with data. -} +\title{Creates a line based plot of temperature profile time series} \usage{ wtr.lineseries(wtr, ylab = "Temperature C", ...) } -%- maybe also 'usage' for other objects documented here. \arguments{ - \item{wtr}{ -Data frame of water temperature loaded with \code{\link{load.ts}}. -} - \item{ylab}{ -y axis title -} - \item{\dots}{ -Additional parameters supplied to the plot function -} -} +\item{wtr}{Data frame of water temperature loaded with +\code{\link{load.ts}}.} -\author{ -Taylor Leach, Luke Winslow -} +\item{ylab}{y axis title} -\seealso{ See -\code{\link{load.ts}} and -\code{\link{wtr.heat.map}} +\item{\dots}{Additional parameters supplied to the plot function} +} +\description{ +A non-heat map approach to visualizing a water temperature profile useful +for identify temperature trends over time at discrete depths and diagnosing +issues with data. } \examples{ + exampleFilePath <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") wtr= load.ts(exampleFilePath) \dontrun{ wtr.lineseries(wtr, ylab = "Temperature C") } - } - -\keyword{ hplot } +\seealso{ +See \code{\link{load.ts}} and \code{\link{wtr.heat.map}} +} +\keyword{hplot} diff --git a/man/wtr.plot.temp.Rd b/man/wtr.plot.temp.Rd index da7de4c..187306b 100644 --- a/man/wtr.plot.temp.Rd +++ b/man/wtr.plot.temp.Rd @@ -2,22 +2,25 @@ % Please edit documentation in R/wtr.plot.temp.R \name{wtr.plot.temp} \alias{wtr.plot.temp} -\title{Creates a time series plot of the thermocline and top and -bottom of the metalimnion} +\title{Creates a time series plot of the thermocline and top and bottom of the +metalimnion} \usage{ wtr.plot.temp(wtr, ...) } \arguments{ -\item{wtr}{Data frame of water temperature loaded with \code{\link{load.ts}}.} +\item{wtr}{Data frame of water temperature loaded with +\code{\link{load.ts}}.} -\item{...}{Additional paramters supplied to \code{\link{ts.meta.depths}} and \code{\link{ts.thermo.depth}}} +\item{...}{Additional paramters supplied to \code{\link{ts.meta.depths}} and +\code{\link{ts.thermo.depth}}} } \description{ -A line based plot of calculated depths of the thermocline, and -top and bottom of the metalimnion from a temperature profile time series. +A line based plot of calculated depths of the thermocline, and top and +bottom of the metalimnion from a temperature profile time series. } \examples{ + wtr.path <- system.file('extdata', 'Sparkling.wtr', package="rLakeAnalyzer") #Load data for example lake, Sparkilng Lake, Wisconsin. @@ -31,7 +34,4 @@ wtr.plot.temp(wtr) \seealso{ \code{\link{load.ts}} and \code{\link{wtr.lineseries}} } -\author{ -Jennifer Brentrup, Taylor Leach, Luke Winslow -} \keyword{hplot} diff --git a/tests/testthat.R b/tests/testthat.R index 350fd1c..9a88054 100644 --- a/tests/testthat.R +++ b/tests/testthat.R @@ -1,3 +1,4 @@ library(testthat) +library(rLakeAnalyzer) test_check('rLakeAnalyzer') diff --git a/vignettes/data.handling.Rmd b/vignettes/data.handling.Rmd new file mode 100644 index 0000000..deedea4 --- /dev/null +++ b/vignettes/data.handling.Rmd @@ -0,0 +1,73 @@ +--- +title: "Introduction to file and data formats in rLakeAnalyzer" +author: "Luke Winslow" +date: "July 6, 2014" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Vignette Title} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +header-includes: + - \usepackage{gensymb} +--- + +```{r, echo = FALSE} +library(knitr) +``` + +## Introduction +This document is an introduction to handling the type of data typically used in rLakeAnalyzer. It will hopefully give the reader enough information to be able to quickly and effectively format your own data to take advantage of the more powerful features. + +## File Format + +We have tried to use a simple but standard file format that eases import and parsing of data while still being easy to generate and edit using commonly available tools like Microsoft Excel. Below is a very simple example of how the files are structured. + +```{r, echo = FALSE} +df2 <- data.frame(datetime = c("2008-07-01 01:00","2008-07-01 02:00","2008-07-01 03:00","2008-07-01 04:00"), + doobs_0.5= c("8.3","8.2","8.2","8.1")) +kable(df2) +``` + +There are a few key aspects to these file structure to note. The date/time format, the format of the header, and the file naming scheme. These key points are discussed here. + +## DateTime Format + +The date and time of all observations is stored in a single, string column. The header of this column must be the word "datetime" without quotes. It is also case insensitive so "DateTime" and other variations will work. + +The datetime format itself is exclusively in an ISO-like format (ISO-8601). It is in most-to-least significant order. It requires a "-" (dash) delimited date format and a ":" (colon) delimited time. "yyyy-mm-dd HH:MM:SS". The date must come first and is separated from the time with a single space. Seconds are optional. This format can easily be created in Excel using a custom date/time format of "yyyy-mm-dd hh:mm:ss" without quotes. + +Note: This format differs from the ISO-8601 format in that a space is used to separate the date and time. This is done to support the use of Microsoft Excel as Excel does not natively recognize the ISO format. + +## Header Format + +The header is used to help identify both the variable type as well as the depth of observation of the data as well as distinguish the data columns from the datetime column. As mentioned above, a "datetime" column is required using the format described above. + +The data columns must be identified with a variable type and optionally, a depth. For example, a water temperature collected at 1 meter depth would have the column header "wtr\_1". The usefulness of this simple format can be seen when dealing with profile data taken at many depths (see below). + +```{r, echo = FALSE} +df1 <- data.frame(datetime = c("2008-07-01 01:00","2008-07-01 02:00","2008-07-01 03:00","2008-07-01 04:00"), + wtr_0.5= c("22.3","22.31","22.31","22.32"), + wtr_1 = c("22.3","22.31","22.31","22.32"), + wtr_2 = rep(21, 4)) +kable(df1) +``` + +While any text can be used to describe a variable, the table below lists the current "standard" variables that are used by rLakeAnalyzer and other toolboxes for identifying commonly collected data in the most common units. If these standards are adhered to, many of the more helpful functions will work natively. For example, water.density expects temperature to be supplied in celsius, the default unit used for the "wtr" abbreviation. + +```{r, echo = FALSE} +df <- data.frame(Abbreviation = c("doobs","wtr","wnd","airT","rh"), + Variable = c("Dissolved Oxygen Concentration","Water Temperature","Wind Speed", + "Air Temperature","Relative Humidity"), + `Assumed Units` = c("mg/L ","°C","m/s","°C","%")) +kable(df) +``` + + +## File Format + +The file format is a simple tab-delimited file. It is easy to export files of this format using Excel or even R itself. To export the appropriate format from R, use "write.table" as in the following example. + +```{r, eval = FALSE} +tmp = data.frame() +write.table(tmp, "test.wtr", sep='\t', row.names=FALSE) +``` diff --git a/vignettes/sm_algorithm.Rmd b/vignettes/sm_algorithm.Rmd new file mode 100644 index 0000000..3275364 --- /dev/null +++ b/vignettes/sm_algorithm.Rmd @@ -0,0 +1,51 @@ +--- +title: "Split and Merge Algorithm Usage" +author: "Sam Albers and Doug Collinge" +date: "`r Sys.Date()`" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{Vignette Title} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +--- + + +## Packages needing loading +```{r, message=FALSE} +library(rLakeAnalyzer) +library(knitr) +``` + + +## Split and merge algorithm +Water column identification is provided by the split-and-merge algorithm. Implementation of the split-and-merge algorithm for a water profile occurs within the `wtr.layer()` function: + +## Simple application of the split and merge algorithm +Below is a simple one profile example of determining key water column parameters using the split-and-merge algorithm. The default behaviour for `wtr.layer` is to run the algorithm *without* specifying the number of segments. `wtr.layer()` adopt as defaults the convention of a minimum depth (z0) of 2.5 m, a maximum depth (zmax) of 150 m and a error threshold (thres) of 0.1. +```{r} +data("latesummer") +wldf <- wtr.layer(depth = latesummer$depth, measure = latesummer$temper) +knitr::kable(wldf) +``` + +In this example, you'll note that `wldf$cline` is formatted as a list-column. A thorough demonstration of a list column can be found [here](https://jennybc.github.io/purrr-tutorial/ls13_list-columns.html). This type of data format has been included here to consolidate split and merge results and align the output to work well with [tidyverse](https://www.tidyverse.org/) tools. If you are interested in working with the segments data from `wtr.layer()`, use this approach: +```{r, eval = TRUE, echo=TRUE} +wldf$segments +``` + +Note that the axes of the water column profile have been reversed and flipped to better visualize the water column and conform to standard limnological displays. +```{r, fig.show = "hold", fig.width = 8, fig.height = 6} +plot(y = latesummer$depth, x = latesummer$temper, ylim = rev(range(latesummer$depth))) +abline(h = wldf$cline, col='blue') +abline(h = wldf$mld, col='red') +abline(h = wldf$min_depth, col='green') +text(16, wldf$cline+3, "Thermocline", col = 'blue') +text(16, wldf$mld+3, "Mix Layer Depth", col = 'red') +text(16, wldf$min_depth+3, "Minimum Depth", col = 'green') +``` + +## Important references +- Pavlidis, T., and S. L. Horowitz, 1974: Segmentation of plan curves.IEEE Trans. Comput., C-23, 860–870. +- Thomson, R. and I. Fine. 2003. Estimating Mixed Layer Depth from Oceanic Profile Data. Journal of Atmospheric and Oceanic Technology. 20(2), 319-329. +- Fiedler, Paul C. "Comparison of objective descriptions of the thermocline. Limnology and Oceanography: Methods 8.6 (2010): 313-325. +