update function names

NAMESPACE

@@ -5,10 +5,10 @@ export(broken_stick)
 export(broken_stick_stevens)
 export(fake_crustaceans)
 export(infl_pt)
-export(regrans_fun)
-export(somerton_fun)
+export(regrans)
+export(somerton)
+export(two_line)
 export(two_line_logistic)
-export(two_line_stevens)
 import(ggplot2)
 import(rlang)
 importFrom(ggplot2,aes)

R/broken_stick.R

@@ -91,7 +91,7 @@ broken_stick <- function(dat,
     out <- append(out, c(segmented=seg_lm))
   }
   if ("regrans" %in% method | "all" %in% method) {
-    temp  <- regrans_fun(dat, xvar, yvar, verbose = FALSE)
+    temp  <- regrans(dat, xvar, yvar, verbose = FALSE)
     if (!("all" %in% method) & length(method)==1) {
       out <- temp
     }

R/broken_stick_stevens.R

@@ -55,6 +55,7 @@ broken_stick_stevens <- function(dat,
   stevens$xvar <- xraw
   stevens$yvar <- yraw
 
+  # null model - single line to describe both maturity stages
   lm0 <- stats::lm(yvar ~ xvar, data = stevens)
   rss0 <- stats::anova(lm0)[[2, 2]] # residual sum of squares
   ms0 <- stats::anova(lm0)[[3]] # mean squared error
@@ -64,7 +65,7 @@ broken_stick_stevens <- function(dat,
   mse0 <- mean(lm0$residuals ^ 2)
 
   # assign group membership
-  # 1 = left line, 2= right line
+  # 1 = left line, 2 = right line
   memb <- rep(1, nrow(stevens))
   memb_low <- (xraw <= min_x) # T/F list if less than low range
   memb_high <- (yraw > min_y) # T/F list if GT than high range
@@ -113,7 +114,7 @@ broken_stick_stevens <- function(dat,
 
     if (run == 1 |
         (rss_pool < rss_min)) {
-      # Run 1 OR pooled RSS
+      # Run 1 OR pooled RSS < minimum RSS so far
       rss_min <- rss_pool
       joint_x <- min_x
       joint_y <- min_y

R/regrans.R

@@ -23,9 +23,9 @@
 #' @examples
 #' set.seed(12)
 #' fc <- fake_crustaceans(n = 100, L50 = 100, allo_params = c(1, 0.2, 1.1, 0.2))
-#' regrans_fun(fc, "x", "y", verbose = FALSE)
-#' head(regrans_fun(fc, "x", "y", verbose = TRUE), n = 30)
-regrans_fun <- function(dat,
+#' regrans(fc, "x", "y", verbose = FALSE)
+#' head(regrans(fc, "x", "y", verbose = TRUE), n = 30)
+regrans <- function(dat,
                         xvar,
                         yvar,
                         lower = NULL,

R/somerton.R

@@ -26,10 +26,10 @@
 #' @examples
 #' set.seed(12)
 #' fc <- fake_crustaceans(n = 100, L50 = 100, allo_params = c(1, 0.2, 1.1, 0.2))
-#' out_df <- somerton_fun(fc, xvar = "x", yvar = "y")[[1]]
+#' out_df <- somerton(fc, xvar = "x", yvar = "y")[[1]]
 #' mod <- glm(data = out_df, pred_mat_num ~ x, family = binomial(link = "logit"))
 #' unname(-coef(mod)[1] / coef(mod)[2])
-somerton_fun <- function(
+somerton <- function(
     dat, # data.frame with columns corresponding to xvar, yvar
     xvar, # X variable
     yvar, # Y variable

R/two_line_stevens.R → R/two_line.R

@@ -1,4 +1,13 @@
-#' Two-line methods from Bradley Stevens
+#' Two-line regression method for estimating size at maturity
+#'
+#' @description Fits separate linear models for the allometric growth of
+#'   immature and mature individuals. Code adapted from Dr. Bradley Stevens at
+#'   the University of Maryland Eastern Shore.
+#'
+#' @details The optimal breakpoint between lines is found by minimizing the
+#'   residual sum of squares when iterating over (1) num_bps evenly-spaced
+#'   values within the possible range or (2) all values of the x-axis variable
+#'   present in the unknown range.
 #'
 #' @param dat data frame or matrix containing the data
 #' @param xvar Name of column (integer or double) of measurements for the x-axis
@@ -23,19 +32,24 @@
 #' @returns If verbose is FALSE (the default), two possible estimates of SM50:
 #'   the breakpoint x-value marking the transition between immature and mature
 #'   points/lines, and the intersection point where the two lines cross. The
-#'   intersection value will typically be extremely unrealistic unless
-#'   the slopes of the lines are drastically different. If verbose is TRUE,
-#'   output is a list that also includes the original data with a column
-#'   representing which line (immature or mature) the point was assigned to, the
-#'   immature amd mature slope and intercept parameters, and the intersection
-#'   point of the two lines.
+#'   intersection value will typically be extremely unrealistic unless the
+#'   slopes of the lines are drastically different. If verbose is TRUE, output
+#'   is a list that also includes the original data with a column representing
+#'   which line (immature or mature) the point was assigned to, the immature and
+#'   mature slope and intercept parameters, and the intersection point of the
+#'   two lines.
 #' @export
 #'
 #' @examples
 #' #' set.seed(12)
 #' fc <- fake_crustaceans(n = 100, L50 = 100, allo_params = c(1, 0.2, 1.1, 0.2))
-#' two_line_stevens(fc, xvar = "x", yvar = "y", verbose = FALSE)
-two_line_stevens <- function(dat,
+#' two_line(fc, xvar = "x", yvar = "y", verbose = FALSE)
+#'
+#' @seealso [two_line_logistic()] for an alternative two-line model with a
+#'   logistic transition between the left and right segments and
+#'   [broken_stick()] for segmented/piecewise regression methods.
+#'
+two_line <- function(dat,
                              xvar,
                              yvar,
                              lower = NULL,

README.Rmd

@@ -33,7 +33,7 @@ A compilation of methods used to estimate size at (sexual) maturity based on mor
 `morphmat` will include versions of the methods implemented in these existing GitHub repositories:
 
 |  |  |  |  |
-|----|----|----|----|
+|-----------------|-----------------|-----------------|----------------------|
 | **Type** | **Authors** | **GitHub repository** | **Description/notes** |
 | Package | Josymar Torrejon-Magallanes | [ejosymart/sizeMat](https://github.com/ejosymart/sizeMat) | [sizeMat: An R Package to Estimate Size at Sexual Maturity](https://cran.r-project.org/web/packages/sizeMat/vignettes/sizeMat.html) |
 | Package | Rodrigo Sant'Ana, Fernando Mayer | [rodrigosantana/Regrans: Fits Segmented Linear Regression Models](https://github.com/rodrigosantana/Regrans) | Older repository: [fernandomayer/Regrans](https://github.com/fernandomayer/Regrans/blob/master/change.point.R) |
@@ -46,7 +46,7 @@ A compilation of methods used to estimate size at (sexual) maturity based on mor
 The following scripts do not use morphometric data and require individuals to already be classified as mature or immature. They provide various examples of how to fit maturity\~length binomial models to estimate SM50 and obtain confidence intervals. These tools can also be used to calculate size at maturity for non-crustacean fisheries. For a comprehensive examination of this type of model, see [@mainguy2024].
 
 |  |  |  |  |
-|----|----|----|----|
+|----------------|----------------|-----------------|-----------------------|
 | **Type** | **Authors** | **GitHub repository** | **Description/notes** |
 | R scripts | Lucas Rodrigues | [lvcasrodrigues/maturity_at_size](https://github.com/lvcasrodrigues/maturity_at_size) | Does not use morphometric data; takes size classes with known numbers of mature individuals per size class and fits a binomial model (frequentist or Bayesian). Finds SM50 by generating new data from the model rather than from ratio of parameters |
 | R scripts | Mainguy et al. | [rafamoral/L50](https://github.com/rafamoral/L50): Monitoring reproduction in fish: Assessing the adequacy of ogives and the predicted uncertainty of their *L*~50~ estimates for more reliable biological inferences | Over a dozen methods for estimating L50 values and obtaining confidence intervals from (frequentist or Bayesian) binomial models (Delta, Fieller, bootstrap resampling, profile-likelihood, etc.). See accompanying manuscript by Mainguy et al. [-@mainguy2024]. |
@@ -77,7 +77,7 @@ fc <- fake_crustaceans(n = 100, L50 = 100, allo_params = c(1, 0.2, 1.1, 0.2))
 REGRANS:
 
 ```{r}
-regrans_fun(fc, "x", "y", verbose = FALSE)
+regrans(fc, "x", "y", verbose = FALSE)
 ```
 
 Two-line logistic:
@@ -86,10 +86,10 @@ Two-line logistic:
 two_line_logistic(fc, xvar = "x", yvar = "y", verbose = FALSE)
 ```
 
-Two-line Stevens:
+Two-line model (lines are fit separately; no forced intersection):
 
 ```{r}
-two_line_stevens(fc, xvar = "x", yvar = "y", verbose = FALSE)
+two_line(fc, xvar = "x", yvar = "y", verbose = FALSE)
 ```
 
 Broken-stick Stevens:
@@ -116,7 +116,7 @@ broken_stick(fc, xvar = "x", yvar = "y", method = "all")
 Somerton method:
 
 ```{r}
-out_df <- somerton_fun(fc, xvar = "x", yvar = "y")[[1]]
+out_df <- somerton(fc, xvar = "x", yvar = "y")[[1]]
 mod <- glm(data = out_df, pred_mat_num ~ x, family = binomial(link = "logit"))
 unname(-coef(mod)[1] / coef(mod)[2])
 ```

README.md

@@ -94,7 +94,7 @@ fc <- fake_crustaceans(n = 100, L50 = 100, allo_params = c(1, 0.2, 1.1, 0.2))
 REGRANS:
 
 ``` r
-regrans_fun(fc, "x", "y", verbose = FALSE)
+regrans(fc, "x", "y", verbose = FALSE)
 #> [1] 89.43822
 ```
 
@@ -106,10 +106,10 @@ two_line_logistic(fc, xvar = "x", yvar = "y", verbose = FALSE)
 #> 104.7633
 ```
 
-Two-line Stevens:
+Two-line model (lines are fit separately; no forced intersection):
 
 ``` r
-two_line_stevens(fc, xvar = "x", yvar = "y", verbose = FALSE)
+two_line(fc, xvar = "x", yvar = "y", verbose = FALSE)
 #>   breakpoint intersection 
 #>     106.0655    1383.9744
 ```
@@ -141,7 +141,7 @@ broken_stick(fc, xvar = "x", yvar = "y", method = "all")
 Somerton method:
 
 ``` r
-out_df <- somerton_fun(fc, xvar = "x", yvar = "y")[[1]]
+out_df <- somerton(fc, xvar = "x", yvar = "y")[[1]]
 mod <- glm(data = out_df, pred_mat_num ~ x, family = binomial(link = "logit"))
 unname(-coef(mod)[1] / coef(mod)[2])
 #> [1] 102.37

tests/testthat/test-broken_stick.R

@@ -1,8 +1,12 @@
 test_that("Stevens wrapper works", {
   set.seed(123)
-  fc <- fake_crustaceans(n=100, L50=100, allo_params=c(1, 0.2, 1.1, 0.2))
-  expect_equal(
-    round(broken_stick(fc, xvar="x", yvar="y", method="stevens"),4),
-    121.4316
-  )
+  fc <- fake_crustaceans(n = 100,
+                         L50 = 100,
+                         allo_params = c(1, 0.2, 1.1, 0.2))
+  expect_equal(round(broken_stick(
+    fc,
+    xvar = "x",
+    yvar = "y",
+    method = "stevens"
+  ), 4), 121.4316)
 })

tests/testthat/test-regrans.R

@@ -1,17 +1,23 @@
 test_that("function returns expected value", {
   set.seed(123)
-  fc <- fake_crustaceans(n=100, L50=100, allo_params=c(1, 0.2, 1.1, 0.2))
-  expect_equal(
-    round(regrans_fun(fc, xvar="x", yvar="y", verbose = FALSE),4),
-    122.0217
-  )
+  fc <- fake_crustaceans(n = 100,
+                         L50 = 100,
+                         allo_params = c(1, 0.2, 1.1, 0.2))
+  expect_equal(round(regrans(
+    fc,
+    xvar = "x",
+    yvar = "y",
+    verbose = FALSE
+  ), 4), 122.0217)
 
   x1 <- c(1:100)
-  y1 <- c(1:75)*2+rnorm(75, 0, 10)
-  y2 <- c(76:100)*4+rnorm(25, 3, 10)
-  testdat <- data.frame(x=x1, y=c(y1, y2))
-  expect_equal(
-    regrans_fun(testdat, xvar="x", yvar="y", verbose = FALSE),
-    64.6
-  )
+  y1 <- c(1:75) * 2 + rnorm(75, 0, 10)
+  y2 <- c(76:100) * 4 + rnorm(25, 3, 10)
+  testdat <- data.frame(x = x1, y = c(y1, y2))
+  expect_equal(regrans(
+    testdat,
+    xvar = "x",
+    yvar = "y",
+    verbose = FALSE
+  ), 64.6)
 })