Package 'mustelus'

Common blacktip shark data

Description

A dataset containing life history information for 475 common blacktip sharks, Carcharhinus limbatus, collected from south-east Queensland and northern New South Wales, Australia, between 2004 and 2013. These are the data analysed by Harry et al. (2019), including the corrections made in that study.

Usage

blacktip

Format

A data frame with 475 rows and 24 variables:

source

Data source: "QLD 2004-2007", Moreton Bay survey; "QLD 2007", neonates purchased from a Moreton Bay commercial fisher; "NSW 2008-2010" and "NSW 2013", observer surveys of the New South Wales Ocean Trap and Line Fishery

date

Date collected

month

Month, integer form

year

Calendar year

tag

Identification number

FL

Fork length (cm)

STL

Stretched total length (cm), measured with the upper caudal lobe depressed in line with the body axis

PCL

Pre-caudal length (cm)

wgt

Weight (kg)

sex

2 level factor

umb_scar

Umbilical scar open? Yes, no or partially

neonate

Known age-zero individual, TRUE where the umbilical scar was open or partially healed

clasp_length

Outer length of male claspers (mm)

clasp_calc

Were claspers calcified? Yes, no or partially

uter_stage

Macroscopic staging of female uterus, 1 to 6 (recorded as A to F in the original data)

maturity_stage

Binary maturity stage: 0, immature; 1, mature

maternity_stage

Binary female maternity stage: 0, non-maternal; 1, maternal

emb

Number of embryos

embTL

Mean total length of embryos (mm)

male_emb

Number of male embryos

female_emb

Number of female embryos

reader1

Age from the first reader, adjusted for date of birth

reader2

Age from the second reader, adjusted for date of birth

age_agree

Consensus age estimate, adjusted for date of birth

Details

The data combine four sources that used different fishing gears and sampled different parts of the population. Sharks from Moreton Bay, Queensland, were mostly neonates and small juveniles, sampled by fishery-independent methods and by a commercial gillnet fisher. Sharks from New South Wales were mostly larger than 150 cm and were caught on demersal setlines by the Ocean Trap and Line Fishery. Vertebrae were collected only from the 2008 to 2010 New South Wales survey, and umbilical scars were recorded only in Queensland. Species identity in the 2008 to 2010 survey was determined genetically, and individuals of hybrid ancestry with C. tilstoni are included, as in the original study.

Ages are counts of growth zone pairs on sectioned vertebrae, read independently by two readers, plus the fraction of a year between an assumed birth date of 1 November and the start of the month of capture. The same fraction is added to both readings and the consensus age, so they can be passed directly to growth().

Source

https://github.com/alharry/limbatus

References

Harry, A.V., Butcher, P.A., Macbeth, W.G., Morgan, J.A.T., Taylor, S.M. and Geraghty, P.T. (2019) Life history of the common blacktip shark, Carcharhinus limbatus, from central eastern Australia and comparative demography of a cryptic shark complex. Marine and Freshwater Research 70(6), 834-848. doi:10.1071/MF18141

---

Analyse clasper length as a function of length or age

Description

Fits a nonlinear (logistic) model of clasper length against a continuous predictor such as body length or age, describing the rapid elongation of claspers that accompanies maturation in male chondrichthyans. The model is

Usage

clasp_length(clasp, x, calc = NULL, data, times = 1000, start = NULL)

Arguments

clasp	Numeric vector of clasper lengths
x	Continuous predictor variable (e.g. length, age)
calc	Optional clasper calcification stage, conventionally coded "n" (not calcified), "p" (partially calcified) and "y" (calcified). Used only for plotting, where points are shaded white, grey and black respectively; it does not enter the model.
data	A data frame containing the above variables
times	Number of bootstrap replicates (default 1000)
start	Optional named list of starting values for a, b, L50 and L95. If NULL (the default) these are derived from the data.

Details

$CL = b + (a - b)\left(1 + e^{-\log(19)(x - L_{50})/(L_{95} - L_{50})}\right)^{-1}$

where b and a are the juvenile and adult asymptotes, and L50 and L95 are the values of the predictor at which clasper length reaches 50 and 95 percent of the way between them. It is fitted on the log scale via nls(), giving multiplicative error, so the fitted curve describes median rather than mean clasper length.

Confidence intervals on the parameters and on the fitted curve are obtained by bootstrap resampling with rsample. Prediction intervals combine the bootstrap variance of the curve with the residual variance of the fit.

Records with missing or non-positive clasper length are dropped, so passing a data frame containing both sexes is safe provided females are recorded as NA.

Value

A one row tibble of class "clasp_length" containing the list columns data, coefs, preds, mods and boot_coefs.

Examples

library(ggplot2)
data(spottail)

cl <- clasp_length(clasp_length, length, clasp_calc, data = spottail, times = 200)

summary(cl)

plot(cl) + xlab("Total length (mm)") + ylab("Clasper length (mm)")

---

Analyse fecundity as a function of length or age

Description

Fits a linear regression of fecundity (e.g. number of in utero embryos) against a continuous predictor such as length or age. Essentially a wrapper for lm() and predict.lm() that tabulates useful summary statistics and returns the predicted mean with 95 percent confidence and prediction intervals, in the style of Walker (2005).

Usage

fecundity(fec, x, data)

Arguments

fec	Numeric vector of fecundity counts (e.g. number of embryos)
x	Continuous predictor variable (e.g. length, age)
data	A data frame containing the above variables

Details

Records with zero or negative fecundity are dropped before fitting, since a count of zero indicates a non-gravid animal rather than a fecundity of zero. The number dropped is reported as a message. Predictions therefore span the length or age range of gravid animals only.

Value

A one row tibble of class "fecundity" containing the list columns data, coefs, preds, and mods.

References

Walker, T.I. (2005) Reproduction in fisheries science. In: Hamlett, W.C. (ed) Reproductive Biology and Phylogeny of Chondrichthyes.

Examples

library(ggplot2)
data(spottail)

fec <- fecundity(emb, length, data = spottail)

summary(fec)

plot(fec) + xlab("Total length (mm)") + ylab("Number of embryos")

---

Analyse growth from length at age data

Description

Fits a von Bertalanffy growth model to length at age data, following Harry et al. (2019), which builds on Cope and Punt (2007). The curve is parameterised by length at birth rather than $t_0$:

Usage

growth(
  len,
  age,
  grouping_var = NULL,
  data,
  neonate = NULL,
  reads = NULL,
  cv_age = NULL,
  start = NULL
)

Arguments

len	Numeric vector of lengths
age	Numeric vector of ages. Used directly when ageing error is off, and as the starting value for true age when it is on.
grouping_var	Optional grouping variable (typically sex). Separate Linf and K are estimated per group; L0 and CV_L are shared.
data	A data frame containing the above variables
neonate	Optional indicator for individuals of known age zero. Anything coercible to logical, e.g. umb_scar %in% c("y", "p").
reads	Optional replicate age reading columns, e.g. c(reader1, reader2). Switches on ageing error. Readings must be on the same scale as age: where ages include an adjustment for birth date, the same adjustment should be added to each reading. Readings must be greater than zero.
cv_age	Optional ageing CV supplied directly. An alternative to reads when only a consensus age is available.
start	Optional named list of starting values for Linf, K, L0 and CV_L. Derived from the data if NULL.

Details

$L_{i,g}(a) = L_0 + (L_{\infty,g} - L_0)(1 - e^{-K_g a_{i,g}})$

where $L_{\infty,g}$ and $K_g$ may differ between groups (typically sexes) while $L_0$ is shared. Observed length is normally distributed about the curve with a standard deviation proportional to expected length, $\sigma_{L} = CV_L L_{i,g}$, so variability in length at age grows with size.

Two optional extensions from the paper can each be switched on independently.

Ageing error. Supplying reads, two or more columns of replicate age readings, treats true age as a random effect. Observed readings are linked to true age by $A_{i,j} = a_i + \epsilon$, with $\epsilon \sim N(0, (CV_a a_i)^2)$. The ageing CV is computed from the replicate readings outside the likelihood and held fixed. Alternatively cv_age supplies that CV directly, which is useful where only a consensus age is available but the ageing CV is known from elsewhere. With neither argument, age is treated as measured without error.

Neonates. Supplying neonate, an indicator for individuals of known age zero such as those with an unhealed umbilical scar, adds their lengths as direct information on $L_0$ through $L_{0,i} \sim N(L_0, (CV_L L_{0,i})^2)$. Flagged individuals are used only for this term: any that also carry an age are removed from the length at age data, since an age-zero observation and a length at birth observation carry the same information and including both would count it twice.

Estimation is by maximum likelihood using RTMB, with the random effects integrated out by the Laplace approximation. Confidence intervals on the fitted curve come from the delta method via sdreport; prediction intervals add the individual variability $CV_L$.

Value

A one row tibble of class "growth" containing the list columns data, coefs, preds, mods and neonates. coefs has one row per group, with L0 and CV_L repeated since they are shared. mods holds the RTMB objective, the nlminb result and the sdreport.

References

Cope, J.M. and Punt, A.E. (2007) Admitting ageing error when fitting growth curves: an example using the von Bertalanffy growth function with random effects. Canadian Journal of Fisheries and Aquatic Sciences 64(2), 205-218. doi:10.1139/f06-179

Harry, A.V., Butcher, P.A., Macbeth, W.G., Morgan, J.A.T., Taylor, S.M. and Geraghty, P.T. (2019) Life history of the common blacktip shark, Carcharhinus limbatus, from central eastern Australia and comparative demography of a cryptic shark complex. Marine and Freshwater Research 70(6), 834-848. doi:10.1071/MF18141

Examples

library(ggplot2)
data(spottail)

# Sex-specific growth, with neonates informing length at birth
g <- growth(length, age_agree, sex, data = spottail,
            neonate = umb_scar %in% c("y", "p"))

summary(g)

plot(g) + xlab("Age (years)") + ylab("Total length (mm)")

# Ageing error from two readers, as in Harry et al. (2019)
data(blacktip)
g2 <- growth(STL, age_agree, sex, data = blacktip, neonate = neonate,
             reads = c(reader1, reader2))

summary(g2)

---

Likelihood confidence regions for growth parameters

Description

Constructs approximate joint confidence regions for $L_\infty$ and $K$ from a growth fit, following Kimura (1980). Unlike an ellipse drawn from the covariance matrix of the estimates, the region follows a contour of equal likelihood and need not be symmetrical about the estimates.

Usage

growth_region(x, level = 0.95, profile_L0 = FALSE, n_steps = 50)

Arguments

x	An object returned by growth
level	Confidence level
profile_L0	Re-estimate $L_0$ at each point rather than holding it at its estimate
n_steps	Number of values of $K$ at which the boundary is found

Details

Kimura (1980) defined the region by the residual sum of squares,

$S(L_\infty, K, t_0) \le \hat{S}\left(1 + \frac{p}{N - p} F_{p, N-p}(1 - \alpha)\right)$

with $p = 3$ parameters and $N$ observations, and displayed it as the two-dimensional cross-section for $L_\infty$ and $K$ with $t_0$ held at its estimate. growth() maximises a likelihood with a standard deviation that changes with length, so the same criterion is applied to the log-likelihood $\ell$:

$2\left[\hat{\ell} - \ell(L_\infty, K)\right] \le N \log\left(1 + \frac{p}{N - p} F_{p, N-p}(1 - \alpha)\right)$

For a single group with constant variance this is identical to Kimura's criterion. $N$ is the number of aged individuals in the group.

$L_0$ takes the place of $t_0$ and is held at its estimate, as are the parameters of the other groups. $CV_L$ is re-estimated at each point, as $\sigma$ effectively is in the ratio of sums of squares. As Kimura noted, holding the third parameter fixed gives a cross-section of the region rather than a true confidence region, since more extreme values of $L_\infty$ and $K$ may occur at a different value of it. Setting profile_L0 = TRUE re-estimates $L_0$ at each point as well, giving the projection of the full three-parameter region onto $L_\infty$ and $K$. The two are close when $L_0$ is well determined, for example by neonates. When it is not, the projection can be noticeably wider, mainly in $K$.

As in Kimura (1980), the boundary is found by stepping through values of $K$ and solving for the two values of $L_\infty$ at which the likelihood reaches the critical value. This follows regions that are strongly curved, as they often are when few old animals have been aged. For models with ageing error each evaluation of the likelihood includes the Laplace approximation, and the calculation takes longer.

Value

A tibble of class "growth_region" with one row per group, holding the estimates, the number of aged individuals n, the critical value crit, and the boundary of the region in the list column region. summary() gives the range of $L_\infty$ and $K$ within each region.

References

Kimura, D.K. (1980) Likelihood methods for the von Bertalanffy growth curve. Fishery Bulletin 77(4), 765-776.

Examples

library(ggplot2)
data(blacktip)

g <- growth(STL, age_agree, sex, data = blacktip, neonate = neonate)
r <- growth_region(g)

summary(r)

plot(r) + labs(x = "Linf (cm)", y = "K (per year)", linetype = "Sex")

---

Analyse weight-length relationship

Description

Function for running a log-linear regression model to analyse body mass as a function of length. Essentially just a wrapper for lm() and predict.lm() that tabulates some useful summary statistics. Also returns the predicted mean, 95 percent confidence intervals and prediction intervals, corrected for bias due to log transformation, and the fitted lm() objects.

Usage

len_weight(weight, length, grouping_var = NULL, data)

Arguments

weight	Numeric vector of weights
length	Numeric vector of lengths
grouping_var	Categorical variable containing two or more unique variables (e.g. sex). Will be converted into a factor.
data	A data frame containing, minimally, variables for length and weight, and optionally sex or another grouping variable

Value

results A list containing the lm model, coefficients and other useful info, predicted mean and raw data

Examples

library(ggplot2)
data(spottail)

lw <- len_weight(wgt, length, sex, data = spottail)

summary(lw)

p <- plot(lw)

p$f + xlab("Total Length (mm)") + ylab("Weight (kg)")

---

Analyse length or age at maternity

Description

Fits the three-parameter logistic maternity function of Walker (2005) to binary data on female maternal condition, as described in Harry et al. (2024):

Usage

maternity(matern, x, data, pmax = NULL, times = 1000, start = NULL)

Arguments

matern	Binary maternal condition variable (0 = not maternal, 1 = maternal), defined following Walker (2005) as whether a female would give birth or lay eggs in the current year.
x	Continuous predictor variable (e.g. length, age)
data	A data frame containing the above variables
pmax	Upper asymptote. NULL (the default) estimates it from the data; a value in (0, 1] fixes it.
times	Number of bootstrap replicates (default 1000)
start	Optional named list of starting values for m50, m95 and pmax. Derived from the data if NULL.

Details

$E[Y_i] = P_{Max}\left(1 + e^{-\ln(19)(x_i - x_{50})/(x_{95} - x_{50})}\right)^{-1}$

where $Y_i$ is a Bernoulli random variable indicating whether female $i$ is in maternal condition, $x_{50}$ and $x_{95}$ are the lengths (or ages) at which 50 and 95 percent of the maximum proportion $P_{Max}$ are in maternal condition, and $P_{Max}$ itself is the proportion of females contributing to recruitment in a given year. The model reduces to the familiar two-parameter maturity ogive when $P_{Max} = 1$.

Two methods from Harry et al. (2024) are available. With pmax = NULL the asymptote is estimated from the data (3PLF-estimated). Supplying a value fixes it and estimates only m50 and m95 (3PLF-fixed), the approach of Walker (2005) where the asymptote is chosen from knowledge of the ovarian and uterine cycles, e.g. 0.5 for a biennial cycle or 1/3 for a triennial one. Fitting both and comparing AIC provides a formal test of reproductive periodicity.

The model is implemented in RTMB and estimated by maximum likelihood. Confidence intervals on the parameters and on the fitted curve are obtained by bootstrap resampling with rsample, refitting the model to each resample; replicates that fail to converge or contain no maternal females are dropped and the number reported.

Harry et al. (2024) found that sample sizes of roughly 100-200 maternal females were typically required to estimate $P_{Max}$ accurately. With fewer, fixing pmax from independent information is likely to be the better choice.

Value

A one row tibble of class "maternity" containing the list columns data, coefs, preds, mods and boot_coefs. mods holds the RTMB objective function, the nlminb result and the sdreport. coefs reports asymptotic standard errors alongside the bootstrap intervals, and convergence is FALSE if any parameter is poorly identified.

References

Harry, A.V., Baremore, I.E. and Piercy, A.N. (2024) Quantifying maternal reproductive output of chondrichthyan fishes. Canadian Journal of Fisheries and Aquatic Sciences 81(10), 1481-1494. doi:10.1139/cjfas-2024-0031

Walker, T.I. (2005) Reproduction in fisheries science. In: Hamlett, W.C. (ed) Reproductive Biology and Phylogeny of Chondrichthyes. Science Publishers, Enfield, NH, pp. 81-127.

Examples

library(ggplot2)
data(sandbar)

# Estimate the asymptote
mt <- maternity(maternity_stage, FL, data = sandbar, times = 200)
summary(mt)

# Fix it at 0.5, as for a biennial cycle, and compare by AIC
mt_biennial <- maternity(maternity_stage, FL, data = sandbar,
                         pmax = 0.5, times = 200)
summary(mt_biennial)

plot(mt) + xlab("Fork length (cm)") + ylab("Proportion in maternal condition")

---

Analyse length or age at maturity

Description

Fits a logistic regression model (binomial GLM) of maturity stage as a function of length, age, or another continuous predictor. Bootstrap confidence intervals are computed via rsample.

Usage

maturity(mat, x, grouping_var = NULL, data, times = 1000)

Arguments

mat	Binary maturity variable (0 = immature, 1 = mature)
x	Continuous predictor variable (e.g. length, age)
grouping_var	Optional categorical grouping variable (e.g. sex). Will be converted to a factor.
data	A data frame containing the above variables
times	Number of bootstrap replicates (default 1000)

Value

A nested tibble of class "maturity" with one row per group, containing list columns data, coefs, preds, and mods, each named by the grouping variable level.

Examples

library(ggplot2)
data(spottail)

lm50 <- maturity(maturity_stage, length, sex, data = spottail, times = 100)

summary(lm50)

plot(lm50)

---

Sandbar shark data

Description

A dataset containing maturity and maternity data from 1087 female sandbar sharks, Carcharhinus plumbeus, collected from the Gulf of Mexico and western north Atlantic Ocean. Data from two studies were combined and maternal condition assigned to each individual for the empirical case study of Harry et al. (2024).

Usage

sandbar

Format

A data frame with 1087 rows and 4 variables:

FL

Fork length (cm)

maturity_stage

Binary maturity stage: 0, immature; 1, mature

maternity_stage

Binary maternity stage: 0, non-maternal; 1, maternal

source

Originating study: "Baremore" or "Piercy"

Source

https://doi.org/10.1139/cjfas-2024-0031

References

Baremore, I.E. and Hale, L.F. (2012) Reproduction of the sandbar shark in the western North Atlantic Ocean and Gulf of Mexico. Marine and Coastal Fisheries 4(1), 560-572. doi:10.1080/19425120.2012.700904

Harry, A.V., Baremore, I.E. and Piercy, A.N. (2024) Quantifying maternal reproductive output of chondrichthyan fishes. Canadian Journal of Fisheries and Aquatic Sciences 81(10), 1481-1494. doi:10.1139/cjfas-2024-0031

Piercy, A.N., Murie, D.J. and Gelsleichter, J.J. (2016) Histological and morphological aspects of reproduction in the sandbar shark Carcharhinus plumbeus in the U.S. south-eastern Atlantic Ocean and Gulf of Mexico. Journal of Fish Biology 88(5), 1708-1730. doi:10.1111/jfb.12945

---

Spot-tail shark data

Description

A dataset containing life history information for 659 spot-tail sharks, Carcharhinus sorrah, collected from north-eastern Australia.

Usage

spottail

Format

A data frame with 659 rows and 27 variables:

month

Month, integer form

year

Calendar year

date

Date collected

jday

Day of year

tag

Identification number

FL

Fork length (mm)

TL

Total length (mm)

PCL

Pre-caudal length (mm)

length

Preferred length measurement (STL)

wgt

Weight (mm)

sex

2 level factor, NA if unavailable

umb_scar

Umbilical scar open? Yes, no or partially

clasp_length

Outer length of male claspers (mm)

clasp_calc

Were claspers calcified? Yes, no or partially

gonad_stage

Macroscopic staging of male testes (Not used)

run_sperm

Running sperm present? Yes, no or partially (Not used)

MOD

Maximum diameter of the largest ovarian follicle

yolky_ova

Number of yolky ovarian follices (Not used)

uter_stage

Macroscopic staging of female uterus

maturity_stage

Binary maturity stage: 0, immature; 1, mature

maternity_stage

Binary female maternity stage: 0, non-maternal; 1, maternal

emb

Number of embryos

embTL

Mean total length of embryos

embryo

Is individual an embryo? TRUE/FALSE

male_emb

Number of male embryos

female_emb

Number of female embryos

vertebrae

Vertebrae collected? TRUE/FALSE

age_agree

Consensus age estimate, adjusted for date of birth

Source

http://dx.doi.org/10.1071/MF12142

---