Type: Package
Title: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2'
Version: 0.3.0
Date: 2024-06-26
URL: https://deepwaterimr.github.io/ggFishPlots/
BugReports: https://github.com/DeepWaterIMR/ggFishPlots/issues
Description: Contains functions to create life history parameter plots from raw data. The plots are created using 'ggplot2', and calculations done using the 'tidyverse' collection of packages. The package contains references to FishBase (Froese R., Pauly D., 2023) https://www.fishbase.se/.
Depends: R (≥ 3.5.0), ggplot2
Imports: dplyr, tibble, tidyr, ggridges, fishmethods, broom, rlang, tidyselect, magrittr, ggrepel, scales, purrr
Suggests: knitr, rmarkdown
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.3.1
NeedsCompilation: no
Packaged: 2024-06-26 09:48:30 UTC; a22357
Author: Mikko Vihtakari ORCID iD [aut, cre] (affiliation: Institute of Marine Research)
Maintainer: Mikko Vihtakari <mikko.vihtakari@hi.no>
Repository: CRAN
Date/Publication: 2024-06-26 10:20:02 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

lhs

A value or the magrittr placeholder.

rhs

A function call using the magrittr semantics.

Value

The result of calling 'rhs(lhs)'.

Plot catch curve

Description

Plot a catch curve to estimate instantaneous total mortality (Z) using age data

Usage

plot_catchcurve(
  dt,
  age = "age",
  sex = "sex",
  time = NULL,
  age.range = NULL,
  female.sex = "F",
  male.sex = "M",
  split.by.sex = FALSE,
  base_size = 8,
  legend.position = "bottom"
)

Arguments

dt

A data.frame, tibble or data.table

age

Character argument giving the name of the age column in dt

sex

Character argument giving the name of the sex column in dt. Ignored if split.by.sex == FALSE.

time

Split analysis by time? If NULL, all data are assumed to stem from one time point. Using a character argument giving the name of a time column splits the analysis by unique values in that column and produces a faceted plot.

age.range

Defines the age range to be used for Z estimation. If NULL, all ages are used. If a numeric vector of length 2, the first number defines the minimum age to include and the last number the maximum age. It is also possible to use differing ranges by sex when split.by.sex = TRUE: use a named list of length two with names referring to female.sex and male.sex. Provide a numeric vector of length 2 to each element (first number defining the minimum age to include and the last number the maximum age). See Examples.

female.sex, male.sex

A character or integer denoting female and male sex in the sex column of dt, respectively.

split.by.sex

Logical indicating whether the result should be split by sex.

base_size

Base size parameter for ggplot. See ggtheme.

legend.position

Position of the ggplot legend as a character. See ggtheme.

Details

Calculates and plots the basic log-linearized catch curve to estimate instantaneous mortality. See e.g. Ogle (2013).

Author(s)

Mikko Vihtakari // Institute of Marine Research.

Examples

# Catch curve including all ages
data(survey_ghl)
plot_catchcurve(survey_ghl)

# Specific ages
plot_catchcurve(survey_ghl, age.range = c(10,26))
# Split by sex
plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE)
# Split by sex, separate age.range
plot_catchcurve(survey_ghl,
age.range = list("F" = c(13,26), "M" = c(10,26)),
split.by.sex = TRUE)

Plot age-length relationships and growth curves

Description

Plot age-length relationships and growth curves

Usage

plot_growth(
  dt,
  length = "length",
  age = "age",
  sex = "sex",
  female.sex = "F",
  male.sex = "M",
  length.unit = "cm",
  split.by.sex = FALSE,
  growth.model = 1,
  force.zero.group.length = NA,
  force.zero.group.strength = 10,
  force.zero.group.cv = 0,
  show.Linf = TRUE,
  boxplot = TRUE,
  base_size = 8,
  legend.position = "bottom"
)

Arguments

dt

A data.frame, tibble or data.table

length

Character argument giving the name of the length column in dt

age

Character argument giving the name of the age column in dt

sex

Character argument giving the name of the sex column in dt. Ignored if split.by.sex == FALSE.

female.sex, male.sex

A character or integer denoting female and male sex in the sex column of dt, respectively.

length.unit

A character argument giving the unit of length. Will be used in the labels of the figure.

split.by.sex

Logical indicating whether the result should be split by sex.

growth.model

Integer defining the growth model. 1 = von Bertalanffy, 2 = Gompertz, 3 = Logistic.

force.zero.group.length

Numeric indicating the length to which 0-group should be forced. Use NA ignore the forcing.

force.zero.group.strength

Numeric indicating how many percent of total fish should be added to the specified force.zero.group.length.

force.zero.group.cv

Numeric indicating the coefficient of variation for the forced 0-group length. Resulting lengths will be randomly generated from a normal distribution.

show.Linf

Logical indicating whether Linf values should be shown as dashed vertical lines.

boxplot

Logical indicating whether boxplots (TRUE) should be used to show data over points (FALSE)

base_size

Base size parameter for ggplot. See ggtheme.

legend.position

Position of the ggplot legend as a character. See ggtheme.

Details

Uses the fishmethods::growth function to calculate the growth curves. Zero group length can be forced to the growth functions using the force.zero.group.* parameters.

Value

A list containing the plot, text for Rmarkdown and Shiny applications, and estimated parameters (params).

Author(s)

Mikko Vihtakari // Institute of Marine Research.

Examples

# Simple plot. Note that a list is returned.
data(survey_ghl)
plot_growth(survey_ghl, length = "length", age = "age")

# Split by sex
plot_growth(survey_ghl, split.by.sex = TRUE)$plot
# Data as points. Forcing zero group to 10 cm
plot_growth(survey_ghl, force.zero.group.length = 10, boxplot = FALSE)$plot

Plot length-weight relationships

Description

Plots length-weight relationship for a species and calculates the a and b coefficients used in length-weight conversions.

Usage

plot_lw(
  dt,
  length = "length",
  weight = "weight",
  sex = "sex",
  female.sex = "F",
  male.sex = "M",
  length.unit = "cm",
  weight.unit = "kg",
  split.by.sex = FALSE,
  xlab = "Total length",
  ylab = "Weight",
  use.nls = FALSE,
  init.a = NULL,
  init.b = NULL,
  log.axes = FALSE,
  outlier.percentile = NULL,
  annotate.coefficients = FALSE,
  correct.units = FALSE,
  base_size = 8,
  legend.position = "bottom",
  point.size = 0.5,
  verbose = TRUE
)

Arguments

dt

A data.frame, tibble or data.table

length

Character argument giving the name of the length column in dt

weight

Character argument giving the name of the age column in dt

sex

Character argument giving the name of the sex column in dt. Ignored if split.by.sex == FALSE.

female.sex, male.sex

A character or integer denoting female and male sex in the sex column of dt, respectively.

length.unit

Character argument giving the unit of length. Will be used in the labels of the figure and for conversion of the a coefficient. Allowed values for the conversion: "mm" (millimeters), "cm" (centimeters), and "m" (meters).

weight.unit

Character argument giving the unit of weight. Will be used in the labels of the figure and for conversion of the a coefficient. Allowed values: "g" (grams), "kg" (kilograms), and "t" (metric tons).

split.by.sex

Logical indicating whether the result should be split by sex.

xlab

Character giving the x-axis label without unit

ylab

Character giving the x-axis label without unit.

use.nls

Logical indicating whether the parameters should be estimated using the nonlinear least squares (nls; TRUE) method over the log-log transformed linear model (lm; FALSE) method. See details.

init.a, init.b

Numeric values giving the starting value for a and b coefficients respectively for non-linear least-squares estimation (i.e. when use.nls = TRUE). If NULL (default) starting values are guessed.

log.axes

Logical indicating whether logarithmic axes should be used instead of Cartesian ones.

outlier.percentile

Numeric argument giving the probability as a percent value which should be used to calculate residual quantiles for outlier removal. See details. Values > 99 are recommended. If NULL (default), no outlier removal is conducted.

annotate.coefficients

Logical indicating whether the a and b coefficients should be annotated into the plot.

correct.units

Logical indicating whether the a and b coefficients should be converted for centimeters and grams as in FishBase.

base_size

Base size parameter for ggplot. See ggtheme.

legend.position

Position of the ggplot legend as a character. See ggtheme.

point.size

Numeric defining the size for data points in the plot. See the size argument in geom_point.

verbose

Logical indicating whether to return warnings and messages.

Details

The function estimates the a and b coefficients of the length weight relationship, weight = a \times length^b, and plots the data. The model can be fitted either using the standard log(weight) ~ log(length) regression (lm; default) or nonlinear least squares (nls) method. The nls method often manages to fit steeper slopes making the b parameter higher and the a parameter lower than the linear lm method. This tends to lead to visually more pleasing fits at high lengths and weights.

The a and b coefficients are dependent on the units of length and weight. In models, the length and weight units should often match those of the data going into the model, while in comparisons with FishBase, the units of length and weight should be centimeters and grams, respectively. If the units are wrong, the intercept, a, will be off the FishBase scale by orders of magnitude (see FishBase). The correct.units can be used to correct the data units to the FishBase standard (cm and g). The function also returns a warning when the returned parameters are not within expected bounds for cm and g estimation. It is recommended to compare the a and b coefficients with those in FishBase for the species as a quality assurance.

The outlier.percentile argument enables quick removal of troublesome outliers from the model estimation. The argument is defined as percentile probabilities and used to calculate quantile for absolute residual values from logarithmic regression to identify outliers (outlier = |r| > Pr[|r| > outlier.percentile/100]). These outliers are then removed from model dataset but plotted using crosses in the ggplot output. See Examples.

Value

A list with three elements: a ggplot object containing the plot, text giving the central statistics that can be pasted to Markdown, and the model parameters (params).

Author(s)

Mikko Vihtakari // Institute of Marine Research.

Examples

data(survey_ghl)

# Simple plot
plot_lw(survey_ghl, length = "length", weight = "weight")

# nls
plot_lw(survey_ghl, use.nls = TRUE)

# Split by sex, annotate coefficients
plot_lw(survey_ghl, split.by.sex = TRUE, annotate.coefficients = TRUE)$plot

# Outlier removal
plot_lw(survey_ghl, outlier.percentile = 99)

Plot maturity ogive

Description

Plots an estimate of length or age at 50% mature for a dataset

Usage

plot_maturity(
  dt,
  length = "length",
  maturity = "maturity",
  sex = "sex",
  split.by.sex = FALSE,
  female.sex = "F",
  male.sex = "M",
  length.unit = "cm",
  length.bin.width = 2,
  bootstrap.n = NA,
  force.zero.group.length = NA,
  force.zero.group.strength = NA,
  force.zero.group.n = NA,
  force.zero.group.cv = 0,
  xlab = "Total length",
  base_size = 8,
  legend.position = "bottom",
  ...
)

Arguments

dt

A data.frame, tibble or data.table

length

Character argument giving the name of the length (or age) column in dt

maturity

Character argument giving the name of the maturity column in dt. Should be either logical (TRUE == mature, FALSE == immature) or integer (1 == mature, 0 == immature).

sex

Character argument giving the name of the sex column in dt. Ignored if split.by.sex == FALSE.

split.by.sex

Logical indicating whether the result should be split by sex.

female.sex, male.sex

A character or integer denoting female and male sex in the sex column of dt, respectively.

length.unit

A character argument giving the unit of length. Will be used in the labels of the figure.

length.bin.width

Numeric specifying the increment (delta length) by which length data should be binned to calculate maturity proportions. Use NULL to remove from the plot.

bootstrap.n

Integer defining the number of bootstrap replicates to be used to calculate 95% confidence intervals for the mean 50% mature estimate. If NA (default), the confidence intervals are calculated from the glm object without boostrapping. See Details.

force.zero.group.length

Numeric indicating the length to which 0-group (all immatures) should be forced. Use NA ignore the forcing.

force.zero.group.strength

Numeric indicating how many percent of total fish should be added to the specified force.zero.group.length. Cannot be used simultaneously with force.zero.group.n

force.zero.group.n

Numeric indicating how many observations should be added to the specified force.zero.group.length. If split.by.sex = TRUE, use a named vector of length two with names referring to female.sex and male.sex. Cannot be used simultaneously with force.zero.group.strength

force.zero.group.cv

Numeric indicating the coefficient of variation for the forced 0-group (all immature) length. Resulting lengths will be randomly generated from a normal distribution.

xlab

Character giving the x-axis label without unit

base_size

Base size parameter for ggplot. See ggtheme.

legend.position

Position of the ggplot legend as a character. See ggtheme.

...

Additional arguments passed to geom_density_ridges.

Details

The 95% confidence intervals for the mean 50% mature estimate are calculated using the glm function by default. This routine might not be optimal when zero group fish are added. Hence, the function contains an option to bootstrap confidence intervals using the same number of data than observations (i.e. excluding the added data from the number of randomly resampled rows). Adding an integer to the bootstrap.n argument turns on this feature. Note that the confidence intervals calculated this way tend to be narrower than the glm() confidence intervals.

Value

Returns a ggplot2 or tibble depending on the plot argument showing the maturity ogives.

Author(s)

Mikko Vihtakari // Institute of Marine Research.

Examples

# Simple L50 plot
data(survey_ghl)
plot_maturity(survey_ghl, length = "length", maturity = "maturity")

# Bootstrapped CIs are narrower than the glm ones
plot_maturity(survey_ghl, bootstrap.n = 10)

# A50 plot, split by sex
plot_maturity(survey_ghl, length = "age", length.unit = "years",
xlab = "Age", length.bin.width = 1, split.by.sex = TRUE)$plot

# Add juveniles
plot_maturity(survey_ghl, length = "age", length.unit = "years",
xlab = "Age", length.bin.width = 1, split.by.sex = TRUE,
force.zero.group.length = 0,
force.zero.group.strength = 100)$plot

Round to multiple of any number

Description

Round to multiple of any number

Usage

round_any(x, accuracy, f = round)

Arguments

x

numeric vector to round

accuracy

number to round to; for POSIXct objects, a number of seconds

f

rounding function: floor, ceiling or round

Value

Rounded numeric vector

Author(s)

Hadley Wickham

Greenland halibut measurements from IMR surveys

Description

Greenland halibut measurements from IMR surveys

Usage

data(survey_ghl)

Format

A dataframe

Details

Contains length, weight, age, sex and maturity measurements of Greenland halibut acquired on various surveys.

Source

Institute of Marine Research (https://www.hi.no/hi)

A ggplot2 theme for the ggFishPlots package

Description

A ggplot2 theme for the ggFishPlots package

Usage

theme_fishplots(..., grid.col, grid.size)

Arguments

...

additional arguments passed to ggtheme.

grid.col

Character code specifying the color of grid lines. Use NA to remove the grid lines.

grid.size

Numeric value specifying the width of grid lines.

Value

A ggplot2 theme layer.

Back-transform predictor variables from a logit model

Description

Back-transform predictor variables from a logit model

Usage

unlogit(p, model)

Arguments

p

probability threshold to unlog from model

model

a glm model object

Value

A data frame

mirror server hosted at Truenetwork, Russian Federation.