Preparing for v0.10.1

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: FSA
-Version: 0.10.0
-Date: 2025-5-6
+Version: 0.10.1
+Date: 2026-1-7
 Title: Simple Fisheries Stock Assessment Methods
 Description: A variety of simple fish stock assessment methods.
 Authors@R: c(
@@ -45,7 +45,7 @@ Suggests:
     tidyr,
     covr
 Encoding: UTF-8
-RoxygenNote: 7.3.2
+RoxygenNote: 7.3.3
 Config/testthat/edition: 3
 Config/Needs/website:
     r-lib/pkgdown,

NEWS.md

@@ -1,3 +1,15 @@
+# FSA 0.10.1
+* Updated the PSD and Relative Weight computation articles to reflect the changes to `psdVal()`, `psdAdd()`, `wsVal()`, and `wrAdd()`.
+* `chapmanRobson()`: Added catch for when n+T<1 and n+T<2. This addresses [#131](https://github.com/fishR-Core-Team/FSA/issues/131)).
+* `metaM()`: Added `method="HamelCope"` to address [#133](https://github.com/fishR-Core-Team/FSA/issues/133). A few minor edits to documentation.
+* `psdAdd()`: Addressed bugs as described in [#136](https://github.com/fishR-Core-Team/FSA/issues/136)) and [#137](https://github.com/fishR-Core-Team/FSA/issues/137). Added `thesaurus` functionality. Reworked examples in documentation. Reworked testing framework. Thanks to Dave Glover.
+* `PSDlit`: Added info for Flier and Longear Sunfish to address [#122](https://github.com/fishR-Core-Team/FSA/issues/122)) and Northern Pikeminnow. Also updated information for Alabama Bass and Spotted Bass. Duplicated lines that combine `species` and `group` to partially address [#137](https://github.com/fishR-Core-Team/FSA/issues/137).
+* `psdVal()`: Added `dat=` to allow more flexibility when called from `psdAdd()`.
+* `PSDWRTest`: Added for testing PSD and relative weight functions.
+* `wrAdd()`: Addressed bugs similar to those for `psdAdd()`. Added `thesaurus` functionality. Reworked examples in documentation. Reworked testing framework (especially expanded validation of results with hand-calculations).
+* `wSlit`: Added info for Flier and Longear Sunfish to address [#122](https://github.com/fishR-Core-Team/FSA/issues/122)). Also updated information for Alabama Bass (further removed Spotted Bass (Alabama subspecies)), Spotted Bass, and Northern Pikeminnow (further removed Northern Squawfish (synonym of Northern Pikeminnow that is no longer used)). Duplicated lines that combine `species` and `group` to partially address [#137](https://github.com/fishR-Core-Team/FSA/issues/137).
+* `wsVal()`: Added `dat=` to allow more flexibility when called from `wrAdd()`.
+
 # FSA 0.10.0
 * Updated `test-coverage.yaml` and moved a `# nocov start` and `# nocov end` in `bootstrap.r` to address the errors with `test-coverage.yaml`. Addresses [#118](https://github.com/fishR-Core-Team/FSA/issues/118).
 * Removed `DescTools`, `plyr`, `psych` from Suggests (and all their uses in tests and linked code in documentation). Removed `ggplot2`, `marked`, `rcapture`, and `tibble` from Suggests (and use in examples was put in a `\dontrun()`).
@@ -122,11 +134,11 @@
 * `fitPlot()`: **REMOVED** (to `FSAmisc`).
 * `fsaNews()` and `FSANews()`: **Removed**.
 * `psdAdd()`: Modified. Changed the way `PSDlit` was loaded into the function environment so that `FSA::psdAdd()` will work. Addresses [#85](https://github.com/fishR-Core-Team/FSA/issues/85).
-* `PSDLit`: Modified. Added info for Utah Chub (from [here](https://webpages.uidaho.edu/quistlab/publications/NAJFM_2021_Black_et_al_UTC_Ws_length_categories.pdf); address [#84](https://github.com/fishR-Core-Team/FSA/issues/84)).
+* `PSDLit`: Modified. Added info for Utah Chub (from [here](https://www.usgs.gov/publications/proposed-standard-weight-ws-equation-and-length-categories-utah-chub); address [#84](https://github.com/fishR-Core-Team/FSA/issues/84)).
 * `psdVal()`: Modified. Changed the way `PSDlit` was loaded into the function environment so that `FSA::psdVal()` will work. Addresses [#85](https://github.com/fishR-Core-Team/FSA/issues/85).
 * `residPlot()`: **REMOVED** (to `FSAmisc`).
 * `wrAdd()`: Modified. Changed the way `WSlit` was loaded into the function environment so that `FSA::wrAdd()` will work. Addresses [#85](https://github.com/fishR-Core-Team/FSA/issues/85).
-* `WSLit`: Modified. Added info for Utah Chub (from [here](https://webpages.uidaho.edu/quistlab/publications/NAJFM_2021_Black_et_al_UTC_Ws_length_categories.pdf); address [#84](https://github.com/fishR-Core-Team/FSA/issues/84)).
+* `WSLit`: Modified. Added info for Utah Chub (from [here](https://www.usgs.gov/publications/proposed-standard-weight-ws-equation-and-length-categories-utah-chub); address [#84](https://github.com/fishR-Core-Team/FSA/issues/84)).
 * `wsVal()`: Modified. Changed the way `WSlit` was loaded into the function environment so that `FSA::wsVal()` will work. Addresses [#85](https://github.com/fishR-Core-Team/FSA/issues/85).
 
 # FSA 0.9.1

R/PSDWRtest.R

@@ -0,0 +1,44 @@
+#' @title Hypothetical weight-length data for testing PSD and relative weight functions
+#'
+#' @description Hypothetical weight-length and associated data. These data are useful for testing PSD and relative weight functions (e.g., \code{\link{psdAdd}} and \code{\link{wrAdd}}).
+#'
+#' @name PSDWRtest
+#'
+#' @docType data
+#'
+#' @format A data frame of many observations on the following 5 variables:
+#'  \describe{
+#'    \item{species}{Species name}
+#'    \item{location}{Broad location of capture}
+#'    \item{len}{Length in mm}
+#'    \item{wt}{Weight in g}
+#'    \item{sex}{Sex as \code{F} for female, \code{M} for male, or \code{U} or \code{NA} for unknown or unrecorded}
+#'  }
+#'
+#' @section Topic(s):
+#'  \itemize{
+#'    \item Size structure
+#'    \item Proportional size structure
+#'    \item Relative stock density
+#'    \item Proportional stock density
+#'    \item Relative weight
+#'    \item Standard weight
+#'    \item Condition
+#'  }
+#'
+#' @concept Size Structure
+#' @concept PSD
+#' @concept Condition
+#' @concept Relative Weight
+#' @concept Standard Weight
+#'
+#' @seealso \code{\link{psdAdd}}, \code{\link{psdCalc}}, and \code{\link{wrAdd}}
+#'
+#' @keywords datasets
+#'
+#' @examples
+#' str(PSDWRtest)
+#' peek(PSDWRtest,n=20)
+#' unique(PSDWRtest$species)
+#'
+NULL

R/PSDlit.R

@@ -1,6 +1,9 @@
 #' @title Gabelhouse five-cell length categories for various species.
 #'
 #' @description Cutoffs for the Gabelhouse five-cell length categories for a variety of species.
+#' 
+#' @details Entries for some species (e.g., \dQuote{Muskellunge} and \dQuote{Walleye}) have been duplicated for sub-groups to facilitate use with relative weight calculations. For example, entries for \dQuote{Muskellunge (overall)}, \dQuote{Muskellunge (female)}, and \dQuote{Muskellunge (male)} are duplicates of the entry for \dQuote{Muskellunge}; i.e., these entries in \code{PSDlit} are not necessarily just for those sub-groups but this allows for seamless similar computations of relative weights for these sub-groups.
+#' 
 #'
 #' @name PSDlit
 #'

R/WSlit.R

@@ -3,6 +3,8 @@
 #' @description Parameters for all known standard weight equations.
 #'
 #' @details The minimum TL for the English units were derived by rounding the converted minimum TL for the metric units to what seemed like common units (inches, half inches, or quarter inches).
+#' 
+#' Entries for \dQuote{Chinook Salmon (landlocked)} and \dQuote{Striped Bass (landlocked)} are the same as for \dQuote{Chinook Salmon} and \dQuote{Striped Bass} but were added to facilitate use with PSD calculations as Gabelhouse lengths are only published for the landlocked sub-group; i.e., these entries in \code{WSlit} are not necessarily just for landlocked populations.
 #'
 #' @name WSlit
 #'

R/chapmanRobson.R

@@ -164,7 +164,17 @@ chapmanRobson.default <- function(x,catch,ages2use=age,
   n <- sum(catch.e,na.rm=TRUE)
   T <- sum(age.r*catch.e,na.rm=TRUE)
   ## Estimate S and SE (eqns 6.4 & 6.5 from Miranda & Bettoli (2007))
+  if (n+T<1) STOP("The sum of 'catch' (n) and the product of 'age' and 'catch'",
+                  " (T) for 'ages2use' is less than 1, so survival (S) cannot",
+                  " be computed. This usually occurs when 'catch' is actually",
+                  " 'CPE' and the 'CPE' values are very small. If this is the",
+                  " case, consider rescaling your 'CPE' values.")
   S.est <- T/(n+T-1)
+  if (n+T<2) STOP("The sum of 'catch' (n) and the product of 'age' and 'catch'",
+                  " (T) for 'ages2use' is less than 2, so the SE of survival (S)",
+                  " cannot be computed. This usually occurs when 'catch' is",
+                  " actually 'CPE' and the 'CPE' values are very small. If this",
+                  " is the case, consider rescaling your 'CPE' values.")
   S.SE <- sqrt(S.est*(S.est-((T-1)/(n+T-2))))
   ## Estimate Z and SE
   switch(zmethod,

R/metaM.R

@@ -13,6 +13,7 @@
 #'    \item \code{method="HoenigLM"}: The \dQuote{modified Hoenig equation derived with a linear model} as described in Then \emph{et al.} (2015) on the second line of Table 3. Requires only \code{tmax}.
 #'    \item \code{method="HewittHoenig"}: The \dQuote{Hewitt and Hoenig (2005) equation} from their equation 8. Requires only \code{tmax}.
 #'    \item \code{method="tmax1"}: The \dQuote{one-parameter tmax equation} from the first line of Table 3 in Then \emph{et al.} (2015). Requires only \code{tmax}.
+#'    \item \code{method="HamelCope"}: The equation 7 from Hamel and Cope (2022). Requires only \code{tmax}.
 #'    \item \code{method="K1"}:  The \dQuote{one-parameter K equation} from the fourth line of Table 3 in Then \emph{et al.} (2015). Requires only \code{K}.
 #'    \item \code{method="K2"}: The \dQuote{two-parameter K equation} from the fifth line of Table 3 in Then \emph{et al.} (2015). Requires only \code{K}.
 #'    \item \code{method="JensenK1"}: The \dQuote{Jensen (1996) one-parameter K equation}. Requires only \code{K}.
@@ -54,15 +55,15 @@
 #'    \item \code{givens}: A string that contains the input values required by the method to estimate M.
 #'  }
 #' 
-#' @section Testing: Kenchington (2014) provided life history parameters for several stocks and used many models to estimate M. I checked the calculations for the \code{PaulyL}, \code{PaulyW}, \code{HoenigO}, \code{HoenigOF}, \code{HoenigO2}, \code{HoenigO2F}, \code{"JensenK1"}, \code{"Gislason"}, \code{"AlversonCarney"}, \code{"Charnov"}, \code{"ZhangMegrey"}, \code{"RikhterEfanov1"}, and \code{"RikhterEfanov2"} methods for three stocks. All results perfectly matched Kenchington's results for Chesapeake Bay Anchovy and Rio Formosa Seahorse. For the Norwegian Fjord Lanternfish, all results perfectly matched Kenchington's results except for \code{HoenigOF} and \code{HoenigO2F}.
+#' @section Testing: Kenchington (2014) provided life history parameters for several stocks and used many models to estimate M. I checked the calculations for the \code{"PaulyL"}, \code{"PaulyW"}, \code{"HoenigO"}, \code{"HoenigOF"}, \code{"HoenigO2"}, \code{"HoenigO2F"}, \code{"JensenK1"}, \code{"Gislason"}, \code{"AlversonCarney"}, \code{"Charnov"}, \code{"ZhangMegrey"}, \code{"RikhterEfanov1"}, and \code{"RikhterEfanov2"} methods for three stocks. All results perfectly matched Kenchington's results for Chesapeake Bay Anchovy and Rio Formosa Seahorse. For the Norwegian Fjord Lanternfish, all results perfectly matched Kenchington's results except for \code{"HoenigOF"} and \code{"HoenigO2F"}.
 #' 
-#' Results for the Rio Formosa Seahorse data were also tested against results from \code{\link[fishmethods]{M.empirical}} from \pkg{fishmethods} for the \code{PaulyL}, \code{PaulyW}, \code{HoenigO}, \code{HoenigOF}, \code{"Gislason"}, and \code{"AlversonCarney"} methods (the only methods in common between the two packages). All results matched perfectly.
+#' Results for the Rio Formosa Seahorse data were also tested against results from \code{\link[fishmethods]{M.empirical}} from \pkg{fishmethods} for the \code{"PaulyL"}, \code{"PaulyW"}, \code{"HoenigO"}, \code{"HoenigOF"}, \code{"Gislason"}, and \code{"AlversonCarney"} methods (the only methods in common between the two packages). All results matched perfectly.
 #' 
 #' @author Derek H. Ogle, \email{DerekOgle51@gmail.com}
 #' 
 #' @section IFAR Chapter: 11-Mortality.
 #' 
-#' @seealso See \code{\link[fishmethods]{M.empirical}} in \pkg{fishmethods} for similar functionality.
+#' @seealso See \code{\link[fishmethods]{M.empirical}} in \pkg{fishmethods} for similar functionality and the "Natural Mortality Tool" Shiny app on-line.
 #' 
 #' @references Ogle, D.H. 2016. \href{https://fishr-core-team.github.io/fishR/pages/books.html#introductory-fisheries-analyses-with-r}{Introductory Fisheries Analyses with R}. Chapman & Hall/CRC, Boca Raton, FL.
 #' 
@@ -74,6 +75,8 @@
 #' 
 #' Gislason, H., N. Daan, J.C. Rice, and J.G. Pope. 2010. Size, growth, temperature and the natural mortality of marine fish. Fish and Fisheries 11:149-158.
 #' 
+#' Hamel, O. and J. M. Cope. 2022. Development and considerations for application of a longevity-based prior for the natural mortality rate. Fisheries Research 256:106477 [Was (is? from https://www.researchgate.net/publication/363595336_Development_and_considerations_for_application_of_a_longevity-based_prior_for_the_natural_mortality_rate).]
+#' 
 #' Hewitt, D.A. and J.M. Hoenig. 2005. Comparison of two approaches for estimating natural mortality based on longevity. Fishery Bulletin. 103:433-437. [Was (is?) from http://fishbull.noaa.gov/1032/hewitt.pdf.]
 #' 
 #' Hoenig, J.M. 1983. Empirical use of longevity data to estimate mortality rates. Fishery Bulletin. 82:898-903. [Was (is?) from http://www.afsc.noaa.gov/REFM/age/Docs/Hoenig_EmpiricalUseOfLongevityData.pdf.]
@@ -108,7 +111,7 @@
 #' Mmethods("tmax")
 #' 
 #' ## Simple Examples
-#' metaM("tmax",tmax=20)
+#' metaM("HamelCope",tmax=20)
 #' metaM("HoenigNLS",tmax=20)
 #' metaM("HoenigNLS",tmax=20,verbose=FALSE)
 #'  
@@ -133,7 +136,7 @@
 #'
 #' ## Example of multiple methods using Mmethods
 #' # select some methods
-#' metaM(Mmethods()[-c(15,20,22:24,26:29)],K=K,Linf=Linf,Temp=Temp,tmax=tmax,t50=t50)
+#' metaM(Mmethods()[-c(16,21,23:25,27:30)],K=K,Linf=Linf,Temp=Temp,tmax=tmax,t50=t50)
 #' # select just the Hoenig methods
 #' metaM(Mmethods("Hoenig"),K=K,Linf=Linf,Temp=Temp,tmax=tmax,t50=t50)
 #'  
@@ -150,7 +153,7 @@ Mmethods <- function(method=c("all","tmax","K","Hoenig","Pauly","FAMS")) {
   method <- match.arg(method)
   all_meth <- c("HoenigNLS","HoenigO","HoenigOF","HoenigOM","HoenigOC",
                 "HoenigO2","HoenigO2F","HoenigO2M","HoenigO2C",
-                "HoenigLM","HewittHoenig","tmax1",
+                "HoenigLM","HewittHoenig","tmax1","HamelCope",
                 "PaulyLNoT","PaulyL","PaulyW",
                 "K1","K2","JensenK1","JensenK2","Gislason",
                 "AlversonCarney","Charnov",
@@ -161,7 +164,7 @@ Mmethods <- function(method=c("all","tmax","K","Hoenig","Pauly","FAMS")) {
   P_meth <- 
   switch(method,
          all    = { meths <- all_meth },
-         tmax   = { meths <- c("tmax1",H_meth)},
+         tmax   = { meths <- c("HamelCope","tmax1",H_meth)},
          K      = { meths <- c("K1","K2","JensenK1","JensenK2")},
          Hoenig = { meths <- H_meth},
          Pauly  = { meths <- all_meth[grep("Pauly",all_meth)] },
@@ -191,6 +194,11 @@ metaM <- function(method=Mmethods(),
 
 metaM1 <- function(method,tmax,K,Linf,t0,b,L,Temp,t50,Winf,PS,...) {
   switch(method,
+         HamelCope = { ## from Hamel & Cope (2022), Equation 7
+           name <- "Hamel and Cope (2022) tmax equation"
+           iCheck_tmax(tmax)
+           givens <- c(tmax=tmax)
+           M <- 5.40/tmax },
          tmax1 = { ## from Then et al. (2015), Table 3, 1st line
            name <- "Then et al. (2015) tmax equation"
            iCheck_tmax(tmax)