Type: Package
Title: Mark-Recapture Growth Models
Version: 0.1.2
Date: 2026-04-06
Maintainer: Donald T. McKnight <donald.mcknight@my.jcu.edu.au>
Description: Researchers often need to calculate body-size growth rates for individuals that do not have associated age data. These growth rates are based on mark-recapture data where an individual was captured and measured at time 1 then recaptured and measured at time 2. The sizes at each time and amount of time between captures can be used to calculate growth rates. 'MRgrowth' follows the approach in Edmonds et al. (2021) <doi:10.1371/journal.pone.0259978> and provides functions to calculate growth using three formulas, the Faben's reformulation of the von Bertalanffy formula, the Gompertz formula, and a logistic formula.
License: GPL (≥ 3)
Encoding: UTF-8
LazyData: true
RoxygenNote: 7.3.3
Suggests: knitr,rmarkdown
Depends: R (≥ 3.5)
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-04-06 23:11:29 UTC; Donald McKnight
Author: Donald T. McKnight [aut, cre] (affiliation: Savanna Field Station)
Repository: CRAN
Date/Publication: 2026-04-10 14:20:07 UTC

Example mark-recapture data set

Description

Example mark-recapture data set of male and female turtles from two populations

Usage

data(MRdata)

Format

A data frame with 43 rows and 3 variables:

id

Unique ID for each individual

size

Individual body size at each capture

date

Date of each measrement in Date format

Source

Hypothetical data over 2-3 capture events

Age at size

Description

Calculate expected age at a given size

Usage

age.at.size(A, k, size, size0, model)

Arguments

A

(numeric) Asymptotic body size (can be calculated in calc.growth())

k

(numeric) Growth rate (can be calculated in calc.growth())

size

(numeric vector) The size(s) for which you want to know the age (should be in the same units used to calculate A and k)

size0

(numeric) Initial body size at birth/hatching (should be in the same units used to calculate A and k). This will generally be a species average, rather than being specific per individual, but it can be a vector of specific birth/hatching sizes per individual if known.

model

(character) The model used to calculate A and k. One of "vb", "gompertz","logistic".

Details

It takes a vector of sizes, initial size for the species, and A and k from calc.growth() and returns the expected age at a given size based on the specified model.

Note: Age cannot be calculated for sizes >A, resulting in NaN.

Value

Vector of expected age(s)

Examples

#For this example, assume size is in mm and time is in years
#Use the gompertz formula to calculate the expected age of a 350 mm
#turtle for a species that hatches at an average size of 50 mm
age.at.size(A = 396.6738,
 k = 0.2029850,
 size = 350,
 size0 = 50,
 model="gompertz")

Calculate growth curves

Description

Calculate, compare, and plot growth curves based on different models

Usage

calc.growth(
  x,
  size0 = NULL,
  age.vect = NULL,
  models = c("vb", "gompertz", "logistic"),
  fixed.A = NULL,
  initial.A = NULL,
  initial.k = 0.5,
  size1.col = "size1",
  size2.col = "size2",
  times.col = "td",
  type = "ML",
  runs = 5000,
  seed = 1701,
  return.plot = TRUE,
  optimizer = "L-BFGS-B"
)

Arguments

x

(data frame) Output from MRgrowth::format.data() Data frame with columns of size at capture, size at recapture, and amount of time between captures.

size0

(numeric) Initial body size at birth/hatching (should be in the same units used to calculate A and k). This will generally be a species average, rather than being specific per individual, but it can be a vector of specific birth/hatching sizes per individual if known. Note that this will not affect the final values of A, k, or their confidence intervals, but it will affect the estimated sizes at ages.

age.vect

(numeric vector) Vector of ages for which you would like expected sizes and confidence intervals around the size (used for plotting growth curves). If age.vect is not supplied, a vector from 1 to 4x the largest time interval will be used (default = NULL)

models

(character vector) The model(s) used to calculate A and k. Can be any combination of "vb", "gompertz","logistic". Fitted parameters, model diagnostics, and sizes at expected ages will be returned for all included models (default = c("vb", "gompertz","logistic"))

fixed.A

(numeric) This fixes the asymptotic size (A) at the specified value, meaning that only the growth rate (k) will be estimated. Use with caution (see vignette; default = NULL)

initial.A

(numeric) Starting value for the search algorithm for the asymptotic size (A). This has no impact on the results, but an initial.A that is close to the final A will result in a faster run time (default = max size in your data set).

initial.k

(numeric) Starting value for the search algorithm for the growth rate (k). This has no impact on the results, but an initial.k that is close to the final k will result in a faster run time (default = 0.5).

size1.col

(character) Name of column containing size data at capture (default = "size1"; the output from MRgrowth::format.data())

size2.col

(character) Name of column containing size data at recapture (default = "size2"; the output from MRgrowth::format.data())

times.col

(character) Name of column containing time interval between captures (default = "td"; the output from MRgrowth::format.data())

type

(character) Method used of fitting the model. One of "ML" (Maximum Likelihood) or "OLS" (Ordinary Least Squares; default = "ML")

runs

(integer) The number of bootstraps to use for calculating confidence intervals. Large values result in long run times (see Vignette; default = 5000)

seed

(integer) Seed to use for random selections when calculating bootstrapped confidence intervals (default = 1701).

return.plot

(logical) Determines whether a plot of growth curves should be printed (default = TRUE)

optimizer

(character) One of the optimization methods available in optim (default = "L-BFGS-B")

Details

This is the primary function for MRgrowth. It takes the output from format.data(), calculates growth curves the selected model(s), and returns the model parameters and the data for plotting curves. The output includes model diagnostics like AIC values that can be used to evaluate model fit and compare models.

Value

A list of two objects:

parameters

A data frame with one row per model containing the following columns:

model

The growth model fitted

A

Estimated asymptotic size

A.lower

Lower 95% bootstrap confidence interval for A

A.upper

Upper 95% bootstrap confidence interval for A

k

Estimated growth coefficient

k.lower

Lower 95% bootstrap confidence interval for k

k.upper

Upper 95% bootstrap confidence interval for k

convergence

Convergence code from optim; 0 indicates successful convergence

NLL

Negative log-likelihood of the fitted model (only returned when type="ML")

SS

Sum of squares (only returned when type="OLS")

AIC

Akaike Information Criterion (only returned when type="ML")

AICc

Sample size corrected AIC (only returned when type="ML")

fixed.AIC

Akaike Information Criterion calculated with 2 parameters when A is fixed (only returned when type="ML" and a value is entered for fixed.A)

fixed.AICc

Sample size corrected AIC calculated with 2 parameters when A is fixed (only returned when type="ML" and a value is entered for fixed.A)

sizes.at.ages

A data frame with one row per age per model containing the following columns:

model

The growth model fitted

age

Age from age.vect

size

Predicted size at a given age

upper

Upper 95% bootstrap confidence interval for predicted size

lower

Lower 95% bootstrap confidence interval for predicted size

References

von Bertalanffy, L. (1957). Quantitative laws in metabolism and growth. The Quarterly Review of Biology, 32, 217-231.

Fabens, A.J. (1965). Properties and fitting of the Von Bertalanffy growth curve. Growth, 29, 265-289.

Gompertz, B. (1833). On the nature of the function expressive of the law of human mortality, and on a new mode of determining the value of life contingencies. Philosophical Transactions of the Royal Society of London, 123, 252-253.

Schoener, T.W. and Schoener, A. (1978). Estimating and interpreting body-size growth in some Anolis lizards. Copeia, 1978, 390-405.

Examples


data(MRdata)

#format the data
formatted.data <- format.data(
 x = MRdata,
 id.col = "id",
 date.col = "date",
 size.col = "size",
 units = "years",
 retain = "max")

#get growth curves for the gompertz and logistic methods.
#runs are set to 10 to keep the run time low.
#For actual CI estimates, much higher values are needed
#likewise, the plot function has been turned off
g.result <- calc.growth(formatted.data,
   size0=50,
   age.vect=c(1:40),
   models=c("gompertz","logistic"),
   runs=10,
   return.plot=FALSE)

Format data

Description

Format data for other MRgrowth functions

Usage

## S3 method for class 'data'
format(
  x,
  id.col = "id",
  date.col = "date",
  size.col = "size",
  units = "years",
  retain = "max",
  seed = 1701
)

Arguments

x

(data frame) Input data containing one row per capture event and columns for individual ID, date/time (formatted as a Date or POSIX), and body size measurement.

id.col

(character) Name of column containing unique individual IDs (default = "id")

date.col

(character) Name of column containing dates/times (default = "date")

size.col

(character) Name of column containing body size measurements (default = "size")

units

(character) Units to be returned for time intervals between measurements. One of "hours", "days", "weeks", "years" (default = "years")

retain

(character) Determines how the function should handle more than two measurements per individual. "max" returns the first and last measurement (after removing NAs), "random" = randomly selects two measurements (after removing NAs), "all" = keeps all measurements with growth intervals between measurements 1 and 2, 2 and 3, 3 and 4, etc. Note that "all" results in pseudoreplication. (default = "max")

seed

(integer) Seed to use for random selections if retain="random" (default = 1701).

Details

It takes a long-format data frame of capture events and measurements (one row per individual per capture) and converts it into the wide-format (one row per pair of capture events per individual) needed for MRgrowth

If retain is set to "random", only 1 pair of capture events will be retained per individual. The seed argument ensures repeatability of the code.

Note: Any NA data are removed as part of the function before applying the retain argument. Thus, if an individual was captured 3 times and only measured the 2nd and 3rd time, the data for the 2nd and 3rd capture events will be returned even if retain="max"

Note: Only individuals with at least 2 capture events (with no NAs) are returned. Any individuals that were never recaptured or did not have all data recorded for at least two recaptures are removed.

Value

Data frame of measurements and capture intervals formatted for MRgrowth functions. Each row is a pair of capture events and associated measurements for an individual.

Column id = IDs as entered in the input data

Column size1 = size at capture

Column size2 = size at recapture

Column date1 = date at capture

Column date2 = date at recapture

Column td = time difference between date1 and date2 in the units specified by the units argument.

Examples


data(MRdata)

#format data with years as the time units and the first and last
#measurement when more than 2 captures are present for an individual.
formatted.data <- format.data(
  x = MRdata,
  id.col = "id",
  date.col = "date",
  size.col = "size",
  units = "years",
  retain = "max"
)

Gompertz growth

Description

Calculate size after a given time interval using Gompertz formula

Usage

gompertz(A, k, size1, td)

Arguments

A

(numeric) Asymptotic body size (can be calculated in calc.growth())

k

(numeric) Growth rate (can be calculated in calc.growth())

size1

(numeric vector) Initial body size (should be in the same units used to calculate A and k)

td

(numeric vector) Time since size1 (should be in the same units used to calculate A and k)

Details

It takes a vector of initial sizes, vector of amounts of time since those sizes were measured, and A and k from calc.growth(model="gompertz") and returns the expected body sizes after the specified time intervals.

Note: If size1 > A, the resulting size estimate will be less than size1

Value

Vector of expected size(s) after the time interval(s) specified in td

References

Gompertz, B. (1833). On the nature of the function expressive of the law of human mortality, and on a new mode of determining the value of life contingencies. Philosophical Transactions of the Royal Society of London, 123, 252-253.

Examples

#For this example, assume size is in mm and time is in years
#calculate expected sizes of individuals that are 200 and 300 mm after 2 and 1.5 years, respectively
gompertz(A = 396.6738,
 k = 0.2029850,
 size1 = c(200,300),
 td = c(2,1.5))

Logistic growth

Description

Calculate size after a given time interval using the logistic formula

Usage

logistic(A, k, size1, td)

Arguments

A

(numeric) Asymptotic body size (can be calculated in calc.growth())

k

(numeric) Growth rate (can be calculated in calc.growth())

size1

(numeric vector) Initial body size (should be in the same units used to calculate A and k)

td

(numeric vector) Time since size1 (should be in the same units used to calculate A and k)

Details

It takes a vector of initial sizes, vector of amounts of time since those sizes were measured, and A and k from calc.growth(model="logistic") and returns the expected body sizes after the specified time intervals.

Note: If size1 > A, the resulting size estimate will be less than size1

Value

Vector of expected size(s) after the time interval(s) specified in td

References

Schoener, T.W. and Schoener, A. (1978). Estimating and interpreting body-size growth in some Anolis lizards. Copeia, 1978, 390-405.

Examples

#For this example, assume size is in mm and time is in years
#calculate expected sizes of individuals that are 200 and 300 mm after 2 and 1.5 years, respectively
logistic(A = 393.0270,
 k = 0.2835795,
 size1 = c(200,300),
 td = c(2,1.5))

Size at age

Description

Calculate expected size at a given age

Usage

size.at.age(A, k, age, size0, model)

Arguments

A

(numeric) Asymptotic body size (can be calculated in calc.growth())

k

(numeric) Growth rate (can be calculated in calc.growth())

age

(numeric vector) The age(s) for which you want to know the size (should be in the same units used to calculate A and k)

size0

(numeric) Initial body size at birth/hatching (should be in the same units used to calculate A and k). This will generally be a species average, rather than being specific per individual, but it can be a vector of specific birth/hatching sizes per individual if known.

model

(character) The model used to calculate A and k. One of "vb", "gompertz","logistic".

Details

It takes a vector of ages, initial size for the species, and A and k from calc.growth() and returns the expected body sizes at a given age based on the specified model.

Value

Vector of expected size(s)

Examples

#For this example, assume size is in mm and time is in years
#Use the gompertz formula to calculate the expected size of a 5-year old
#turtle for a species that hatches at an average size of 50 mm
size.at.age(A = 396.6738,
 k = 0.2029850,
 age = 5,
 size0 = 50,
 model="gompertz")

von Bertalanffy growth

Description

Calculate size after a given time interval using the Faben's reformulation of the von Bertalanffy formula

Usage

vb(A, k, size1, td)

Arguments

A

(numeric) Asymptotic body size (can be calculated in calc.growth())

k

(numeric) Growth rate (can be calculated in calc.growth())

size1

(numeric vector) Initial body size (should be in the same units used to calculate A and k)

td

(numeric vector) Time since size1 (should be in the same units used to calculate A and k)

Details

It takes a vector of initial sizes, vector of amounts of time since those sizes were measured, and A and k from calc.growth(model="vb") and returns the expected body sizes after the specified time intervals.

Note: If size1 > A, the resulting size estimate will be less than size1

Value

Vector of expected size(s) after the time interval(s) specified in td

References

von Bertalanffy, L. (1957). Quantitative laws in metabolism and growth. The Quarterly Review of Biology, 32, 217-231.

Fabens, A.J. (1965). Properties and fitting of the von Bertalanffy growth curve. Growth, 29, 265-289.

Examples

#For this example, assume size is in mm and time is in years
#calculate expected sizes of individuals that are 200 and 300 mm after 2 and 1.5 years, respectively
vb(A = 403.7077,
 k = 0.1365507,
 size1 = c(200,300),
 td = c(2,1.5))