Merge pull request #86 from boshek/master

Some general updates and housekeeping

.Rbuildignore

@@ -5,3 +5,5 @@ changelog.txt
 ^\.Rproj\.user$
 README.md
 
+^README\.Rmd$
+^README-.*\.png$

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: rLakeAnalyzer
 Title: Lake Physics Tools
 Maintainer: Luke Winslow <[email protected]>
-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,13 +10,19 @@ 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,
     rmarkdown
 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

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)

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)
+
+
+

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"
 

R/buoyancy.freq.R

@@ -1,7 +1,34 @@
-#
-# Buoyancy Frequency
-# Author: Luke Winslow <[email protected]>
-#
+#' @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)

R/center.buoyancy.R

@@ -1,7 +1,32 @@
-#
-# Center of Buoyancy Frequency
-# Author: Jordan S Read <[email protected]>
-#
+#' @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)

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{

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){