Package 'ggFishPlots'

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

---

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.

---