update vignettes

README.Rmd

@@ -43,7 +43,7 @@ A compilation of methods used to estimate size at (sexual) maturity based on mor
 | Package | Tobie Surette | [TobieSurette/gulf.stats](https://github.com/TobieSurette/gulf.stats) | See files [morphometric.maturity.R](https://github.com/TobieSurette/gulf.stats/blob/master/R/morphometric.maturity.R) and [morphometry.R](https://github.com/TobieSurette/gulf.stats/blob/master/R/morphometry.R) |
 | R scripts | Bradley Stevens | [Crabman52/Crustacean_Sensation](https://github.com/Crabman52/Crustacean_Sensation) | Include three different methods for separating mature from immature crabs based on allometric growth of body parts, with code based on Somerton's (1980) program MATURE |
 
-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].
+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 Mainguy et al [-@mainguy2024].
 
 |  |  |  |  |
 |----------------|----------------|-----------------|-----------------------|
@@ -92,7 +92,7 @@ Two-line model (lines are fit separately; no forced intersection):
 two_line(fc, xvar = "x", yvar = "y", verbose = FALSE)
 ```
 
-Broken-stick Stevens:
+Broken-stick Stevens (only iterates over values of the x-axis variable present in the data):
 
 ```{r}
 broken_stick_stevens(fc, xvar = "x", yvar = "y", verbose = FALSE)

README.md

@@ -58,8 +58,8 @@ 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 ([Mainguy et al.
-2024](#ref-mainguy2024)).
+comprehensive examination of this type of model, see Mainguy et al
+([2024](#ref-mainguy2024)).
 
 |  |  |  |  |
 |----|----|----|----|
@@ -114,7 +114,8 @@ two_line(fc, xvar = "x", yvar = "y", verbose = FALSE)
 #>     106.0655    1383.9744
 ```
 
-Broken-stick Stevens:
+Broken-stick Stevens (only iterates over values of the x-axis variable
+present in the data):
 
 ``` r
 broken_stick_stevens(fc, xvar = "x", yvar = "y", verbose = FALSE)

vignettes/broken-stick.Rmd

@@ -61,7 +61,7 @@ We will start by simulating a data set with a known SM50 value of 75 mm to demon
 ```{r}
 #| label: generate-crabs
 
-set.seed(123) # set seed for reproducibility
+set.seed(12) # set seed for reproducibility
 
 fc <- fake_crustaceans(
   error_scale = 17,

vignettes/simulations.Rmd

@@ -56,9 +56,10 @@ mytheme <- theme_classic()+ #define custom theme for ggplots
 
 The parameterization of the logistic equation we will use is: $$f(x)=\frac{1}{1+e^{-(x-a)/b}} $$ where $a$ is a location parameter and $b$ is the shape parameter.
 
-The allometric growth equation is \\begin{equation}\label{eqn:allometry}Y=\\beta X\^{\\alpha},\\end{equation}
+The allometric growth equation is
+$$Y=\beta X^{\alpha}$$
 
-which results in a linear plot when log-transformed: $\log{(Y)}= \tilde\beta+\alpha \log{(X)}$. Here, $\alpha$ is the slope of the allometric line and $\beta$ is the intercept, with $\tilde{\beta}=\log{(\beta)}$. Differences in the intercept of the allometry indicate differences in the proportionate size of the chela, irrespective of carapace width. In contrast, differences in the slope parameter represent differences in how the relative size of the chela changes with body size.
+which results in a linear plot when log-transformed: $\log{(Y)}= \tilde{\beta}+\alpha\log{(X)}$. Here, $\alpha$ is the slope of the allometric line and $\beta$ is the intercept, with $\tilde{\beta}=\log{(\beta)}$. Differences in the intercept of the allometry indicate differences in the proportionate size of the chela, irrespective of carapace width. In contrast, differences in the slope parameter represent differences in how the relative size of the chela changes with body size.
 
 ## A note on the error distribution
 

vignettes/two-line.Rmd

@@ -40,15 +40,15 @@ mytheme <- theme_classic()+ #define custom theme for ggplots
 
 <!-- Here I will write a vignette explaining all of the two-line regression methods. This will be useful for referring readers to more complex options available in packages like `chngpt` that are not available within `morphmat`. -->
 
-## Standard {#sec-twoA}
+## Description {#sec-twoA}
 
 Two-line models differ from broken-stick models because the intersection point of the line representing the immature individuals and the line representing mature individuals is not necessarily the same as the optimal breakpoint value (the value on the x-axis where the y-values switch from being predicted by the immature line to being predicted by the mature line).
 
-We will test two slightly different versions of this approach using code from Crab_Maturity (Stevens, 2020). The first version uses a piecewise regression model to find the x-value/breakpoint that gives the lowest mean square error (MSE) by iteratively testing each observed x-value within the range of unknown maturity. In the second version, the tested x-values are evenly spaced points within the unknown range, and may not equal actual observed values (like REGRANS). The number and interval between points can be user-defined, but we will follow the convention of REGRANS and simply test every integer value in the unknown range.
+We will test two slightly different versions of this approach using code from Crab_Maturity (Stevens, 2020). The first version uses a piecewise regression model to find the x-value/breakpoint that gives the lowest mean square error (MSE) by iteratively testing each observed x-value within the range of unknown maturity. In the second version, the tested x-values are evenly spaced points within the unknown range, and may not equal actual observed values (like REGRANS). The number of (and therefore interval between) points can be user-defined.
 
-The SM50 could be defined as the optimal breakpoint OR as the point at which the two lines actually intersect; i.e. where the regression equations predict the same y-value. The intersection point may be lower than the previously determined breakpoint and can even be negative, so it is often more reasonable to use the breakpoint as our estimate of SM50.
+The SM50 could be defined as the optimal breakpoint OR as the point at which the two lines actually intersect; i.e. where the regression equations predict the same y-value. The intersection point may be much lower or higher than the previously determined breakpoint and can even be negative, so it is often more reasonable to use the breakpoint as our estimate of SM50.
 
-# Two-line Stevens
+# Two-line: standard
 
 ```{r}
 #| label: generate-crabs
@@ -74,12 +74,24 @@ ggplot() +
   mytheme
 ```
 
+The default function call iterates over 100 evenly-spaced points between the default upper and lower bounds (0.2 and 0.8 quantiles of the x-axis variable) of the region to search for possible SM50 values.
 ```{r}
-stevens_est <- two_line(fc, "x", "y", verbose = FALSE)
-stevens_est
+two_line_est <- two_line(fc, "x", "y", verbose = FALSE)
+two_line_est
 ```
 
-# Two-line with logistic transition
+The result can be influenced by the number of breakpoints tested:
+```{r}
+two_line(fc, "x", "y", verbose = FALSE, num_bps = 200)
+two_line(fc, "x", "y", verbose = FALSE, num_bps = 400)
+```
+
+Alternatively, possible breakpoints can be restricted to values of the x-axis variable present in the data:
+```{r}
+two_line(fc, "x", "y", verbose = FALSE, bps = "obs")
+```
+
+# Two-line: logistic transition
 
 ```{r}
 tll_est <- two_line_logistic(fc, "x", "y", verbose = FALSE)