plot_lw {ggFishPlots}

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)