minor updates for next release

.gitignore

@@ -1,3 +1,4 @@
+.Renviron
 .Rproj.user
 .Rhistory
 .RData

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: hydraulics
 Type: Package
 Title: Basic Pipe and Open Channel Hydraulics
-Version: 0.6.1
+Version: 0.6.2
 Author: Ed Maurer [aut, cre], Irucka Embry [aut, ctb] (iemisc code)
 Maintainer: Ed Maurer <[email protected]>
 Description: Functions for basic hydraulic calculations related to 
@@ -17,7 +17,7 @@ Description: Functions for basic hydraulic calculations related to
     flow, the Manning equation is used, again solving for missing parameters. 
     The derivation of and solutions using the Darcy-Weisbach equation and the
     Manning equation are outlined in many fluid mechanics texts such as 
-    Finnemore and Franzini (2002, ISBN:978-0072432022). Some gradually- and 
+    Finnemore and Maurer (2024, ISBN:978-1-264-78729-6). Some gradually- and 
     rapidly-varied flow functions are included. For the Manning equation
     solutions, this package uses modifications of original code from the 'iemisc' 
     package by Irucka Embry.
@@ -36,9 +36,9 @@ Imports:
     tibble,
     units
 Suggests:
-    docxtools,
+    formatdown,
     kableExtra,
     knitr,
     rmarkdown
-RoxygenNote: 7.2.1
+RoxygenNote: 7.3.1
 VignetteBuilder: knitr, rmarkdown

NEWS.md

@@ -1,5 +1,12 @@
 <!-- NEWS.md is generated from NEWS.Rmd. Please edit that file -->
 
+## hydraulics 0.6.2
+
+- Update vignette and DESCRIPTION to replace package docxtools with
+  formatdown
+- Modify the spec_energy_trap plotting function to include more than one
+  added depth line
+
 ## hydraulics 0.6.1
 
 - Modifications for R 4.2 change from warning to error for if()

R/spec_energy_trap.R

@@ -7,7 +7,7 @@
 #' @param Q flow rate [\eqn{m^3 s^{-1}}{m^3/s} or \eqn{ft^3 s^{-1}}{ft^3/s}]
 #' @param b bottom width [\eqn{m}{m} or \eqn{ft}{ft}]
 #' @param m side slope (H:1) [unitless]
-#' @param y depth of flow [\eqn{m}{m} or \eqn{ft}{ft}] (optional)
+#' @param y depth(s) of flow (a numeric vector of length <= 2) [\eqn{m}{m} or \eqn{ft}{ft}] (optional)
 #' @param scale multiplier (of yc) for axis scales (default is 3)
 #' @param units character vector that contains the system of units [options are
 #'   \code{SI} for International System of Units and \code{Eng} for English (US customary)
@@ -27,9 +27,12 @@
 #'
 #' @examples
 #'
-#' # Draw a specific cross-section with flow 1, width 2, side slope 3:1 (H:V)
+#' # Draw a specific energy diagram for a cross-section with flow 1, width 2, side slope 3:1 (H:V)
 #' spec_energy_trap(Q = 1.0, b = 2.0, m = 3.0, scale = 4, units = "SI")
 #'
+#' # Draw the same specific energy diagram adding lines for depths, y = 0.5 and 0.8 m
+#' spec_energy_trap(Q = 1.0, b = 2.0, m = 3.0, scale = 4, y = c(0.5, 0.8), units = "SI")
+#' 
 #' @import ggplot2
 #' @import grid
 #'
@@ -84,15 +87,26 @@ spec_energy_trap <- function(Q = NULL, b = NULL, m = NULL, y = NULL, scale = 3,
   Emin <- yc + ((Q ^ 2) / (2 * g * Ac ^ 2))
 
   ylim <- yc*scalefact
-  yalt <- E1 <- NULL
+  yalt <- E1 <- yalt2 <- E2 <- NULL
   #if y is given, find alternate depth
-  if ( ! missing (y) ) {
-    E1 <- y + (Q ^ 2) / (2 * g * (y * (b + m * y))^2)
-    if ( y > yc ) interv <- c(0.0000001, yc)
-    if ( y < yc ) interv <- c(yc, 200)
+  if (length(y) > 2) {
+    stop("y cannot be greater than 2")
+  }
+  if ( length(y) >= 1 ) {
+    E1 <- y[1] + (Q ^ 2) / (2 * g * (y[1] * (b + m * y[1]))^2)
+    if ( y[1] > yc ) interv <- c(0.0000001, yc)
+    if ( y[1] < yc ) interv <- c(yc, 200)
     yaltfun <- function(ya) { E1 - (ya + (Q ^ 2) / (2 * g * (ya * (b + m * ya))^2)) }
     yalt <- uniroot(yaltfun, interval = interv, extendInt = "yes")$root
-    ylim <- max(ylim, y, yalt)
+    ylim <- max(ylim, y[1], yalt)
+    if ( length(y) == 2 ) {
+      E2 <- y[2] + (Q ^ 2) / (2 * g * (y[2] * (b + m * y[2]))^2)
+      if ( y[2] > yc ) interv <- c(0.0000001, yc)
+      if ( y[2] < yc ) interv <- c(yc, 200)
+      yaltfun2 <- function(ya) { E2 - (ya + (Q ^ 2) / (2 * g * (ya * (b + m * ya))^2)) }
+      yalt2 <- uniroot(yaltfun2, interval = interv, extendInt = "yes")$root
+      ylim <- max(ylim, y[1], y[2], yalt)
+    }
   }
 
   #round up ylim a little
@@ -114,7 +128,7 @@ spec_energy_trap <- function(Q = NULL, b = NULL, m = NULL, y = NULL, scale = 3,
   offst <- ymax*0.0275
 
   p <- ggplot2::ggplot() +
-    ggplot2::geom_path(data=eycurve,ggplot2::aes(x=xx, y=yy),color="black", size=1.5) +
+    ggplot2::geom_path(data=eycurve,ggplot2::aes(x=xx, y=yy),color="black", linewidth=1.5) +
     ggplot2::scale_x_continuous(txtx, limits = c(0, ymax), expand = c(0,0)) +
     ggplot2::scale_y_continuous(txty, limits = c(0, ymax), expand = c(0,0)) +
     ggplot2::geom_abline(slope = 1, intercept = 0 ,color="black",linetype = "dashed") +
@@ -124,16 +138,27 @@ spec_energy_trap <- function(Q = NULL, b = NULL, m = NULL, y = NULL, scale = 3,
     ggplot2::annotate(geom="text", x=Emin/2, y=yc+offst, label=txt2, angle = 0, size = 3) +
     ggplot2::coord_fixed(ratio = 1) +
     ggplot2::theme_bw()
-  if ( ! missing (y) ) {
-    txt3 <- sprintf("y=%.3f",y)
+  if ( ! is.null(yalt) ) {
+    txt3 <- sprintf("y=%.3f",y[1])
     txt4 <- sprintf("y=%.3f",yalt)
     txt5 <- sprintf("E=%.3f",E1)
-    p <- p + ggplot2::geom_segment(ggplot2::aes(x=E1, xend=E1, y=0, yend=max(y,yalt)),linetype=3) +
+    p <- p + ggplot2::geom_segment(ggplot2::aes(x=E1, xend=E1, y=0, yend=max(y[1],yalt)),linetype=3) +
       ggplot2::geom_segment(ggplot2::aes(x=0, xend=E1, y=yalt, yend=yalt), linetype=3) +
-      ggplot2::geom_segment(ggplot2::aes(x=0, xend=E1, y=y, yend=y), linetype=3) +
-      ggplot2::annotate(geom="text", x=min(Emin/2,E1/2), y=y+offst, label=txt3, angle = 0, size = 3,hjust = "left") +
+      ggplot2::geom_segment(ggplot2::aes(x=0, xend=E1, y=y[1], yend=y[1]), linetype=3) +
+      ggplot2::annotate(geom="text", x=min(Emin/2,E1/2), y=y[1]+offst, label=txt3, angle = 0, size = 3,hjust = "left") +
       ggplot2::annotate(geom="text", x=min(Emin/2,E1/2), y=yalt+offst, label=txt4, angle = 0, size = 3,hjust = "left") +
-      ggplot2::annotate(geom="text", x=E1+offst, y=(y+yalt)/2, label=txt5, angle = 90, size = 3)
+      ggplot2::annotate(geom="text", x=E1+offst, y=(y[1]+yalt)/2, label=txt5, angle = 90, size = 3)
+  }
+  if ( ! is.null(yalt2) ) {
+    txt3 <- sprintf("y=%.3f",y[2])
+    txt4 <- sprintf("y=%.3f",yalt2)
+    txt5 <- sprintf("E=%.3f",E2)
+    p <- p + ggplot2::geom_segment(ggplot2::aes(x=E2, xend=E2, y=0, yend=max(y[2],yalt2)),linetype=3) +
+      ggplot2::geom_segment(ggplot2::aes(x=0, xend=E2, y=yalt2, yend=yalt2), linetype=3) +
+      ggplot2::geom_segment(ggplot2::aes(x=0, xend=E2, y=y[2], yend=y[2]), linetype=3) +
+      ggplot2::annotate(geom="text", x=min(Emin/2,E2/2), y=y[2]+offst, label=txt3, angle = 0, size = 3,hjust = "left") +
+      ggplot2::annotate(geom="text", x=min(Emin/2,E2/2), y=yalt2+offst, label=txt4, angle = 0, size = 3,hjust = "left") +
+      ggplot2::annotate(geom="text", x=E2+offst, y=(y[2]+yalt2)/2, label=txt5, angle = 90, size = 3)
   }
   return(p)
 }

vignettes/hydraulics_vignette.Rmd

@@ -54,7 +54,7 @@ par(cex=0.8, mgp = c(2,0.7,0))
 plot(Ts, nus, xlab = xlbl, ylab = ylbl, type="l")
 ```
 
-The water property functions can also be called with the _ret_units_ parameter, in which case the function returns an object of class _units_, as designated by the package `units`. This enables capabilities for new units being deduced as operations are performed on the values. Concise examples are in the [vignettes for the 'units' package](https://cran.r-project.org/package=units).
+The water property functions can also be called with the _ret_units_ parameter, in which case the function returns an object of class _units_, as designated by the package [units](https://cran.r-project.org/package=units). This enables capabilities for new units being deduced as operations are performed on the values. Concise examples are in the [vignettes for the 'units' package](https://cran.r-project.org/package=units).
 
 ```{r waterprops-4}
 T <- 25
@@ -98,11 +98,23 @@ tbl <- water_table(units = "SI")
 tbl
 ```
 
-The table can be reformatted to something more attractive using the _kableExtra_ and _docxtools_ packages.
+The table can be reformatted to something more attractive using the [kableExtra](https://cran.r-project.org/package=kableExtra) and [formatdown](https://cran.r-project.org/package=formatdown) packages.
 ```{r waterprops-table2}
 unitlist <- sapply(unname(tbl),units::deparse_unit)
 colnames <- names(tbl)
-tbl <- docxtools::format_engr(units::drop_units(tbl), sigdig = c(0, 4, 4, 4, 4, 4, 3, 3))
+tbl <- units::drop_units(tbl)
+# Format column as integer
+tbl$Temp <- formatdown::format_decimal(tbl$Temp, digits = 0)
+# Format column with one decimal
+tbl$Density <- formatdown::format_decimal(tbl$Density, digits = 1)
+# Format multiple columns using power-of-ten notation to 4 significant digits
+cols_we_want = c("Spec_Weight", "Viscosity", "Kinem_Visc", "Sat_VP")
+tbl[, cols_we_want] <- lapply(tbl[, cols_we_want], function (x) {formatdown::format_power(x, digits = 4, format = "sci", omit_power = c(-1, 4))}
+)
+# Format multiple columns using power-of-ten notation to 3 significant digits
+cols_we_want = c("Surf_Tens", "Bulk_Mod")
+tbl[, cols_we_want] <- lapply(tbl[, cols_we_want], function (x) {formatdown::format_power(x, digits = 3, format = "sci", omit_power = c(-1, 4))}
+)
 tbl2 <- knitr::kable(tbl, col.names = unitlist, align = "c", format = "html")
 kableExtra::add_header_above(tbl2, header = colnames, line = F, align = "c")
 ```