diff --git a/DESCRIPTION b/DESCRIPTION index b585f4d..15fa8a3 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,8 @@ Package: ggFishPlots Type: Package Title: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2' -Version: 0.2.6 -Date: 2024-01-31 +Version: 0.2.7 +Date: 2024-06-26 Authors@R: c(person("Mikko", "Vihtakari", email = "mikko.vihtakari@hi.no", role = c("aut", "cre"), comment = c(affiliation = "Institute of Marine Research", @@ -16,8 +16,8 @@ Description: Contains functions to create life history parameter plots from raw (Froese R., Pauly D., 2023) . Depends: R (>= 3.5.0), ggplot2 Imports: dplyr, tibble, tidyr, ggridges, fishmethods, broom, rlang, tidyselect, - magrittr, ggrepel, scales + magrittr, ggrepel, scales, purrr Suggests: knitr, rmarkdown License: GPL-3 Encoding: UTF-8 -RoxygenNote: 7.3.0 +RoxygenNote: 7.3.1 diff --git a/NAMESPACE b/NAMESPACE index e12668e..84164ae 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -24,4 +24,5 @@ importFrom(stats,na.omit) importFrom(stats,nls) importFrom(stats,predict) importFrom(stats,quantile) +importFrom(stats,residuals) importFrom(stats,rnorm) diff --git a/R/plot_lw.R b/R/plot_lw.R index 05bd9a4..851a0ba 100644 --- a/R/plot_lw.R +++ b/R/plot_lw.R @@ -1,36 +1,57 @@ #' @title Plot length-weight relationships +#' @description +#' Plots length-weight relationship for a species and calculates the a and b coefficients used in length-weight conversions. #' @param length Character argument giving the name of the length column in \code{dt} #' @param weight Character argument giving the name of the age column in \code{dt} #' @param ylab Character giving the x-axis label without unit. -#' @param length.unit Character argument giving the unit of \code{length}. Will be used in the labels of the figure and for conversion of the a parameter. Allowed values for the conversion: "mm" (millimmeters), "cm" (centimeters), and "m" (meters). -#' @param weight.unit Character argument giving the unit of \code{weight}. Will be used in the labels of the figure and for conversion of the a parameter. Allowed values: "g" (grams), "kg" (kilograms), and "t" (metric tons). -#' @param use.nls Logical indicating whether the parameters should be calculated using the nonlinear least squares (\code{nls; TRUE}) method over the log-log transformed linear model (\code{lm; FALSE}) method. -#' @param init.a,init.b Numeric values giving the starting value for a and b parameters respecitively for non-linear least-squares estimation (i.e. when \code{use.nls = TRUE}). If \code{NULL}, default values are guessed. -#' @param log.axes Logical indicating whether logarithmic axes should be used instead of cartesian ones. -#' @param correct.units Logical indicating whether a and b parameters should be converted for centimeters and grams as in FishBase. +#' @param length.unit Character argument giving the unit of \code{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). +#' @param weight.unit Character argument giving the unit of \code{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). +#' @param use.nls Logical indicating whether the parameters should be estimated using the nonlinear least squares (\code{nls; TRUE}) method over the log-log transformed linear model (\code{lm; FALSE}) method. See details. +#' @param 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 \code{use.nls = TRUE}). If \code{NULL} (default) starting values are guessed. +#' @param log.axes Logical indicating whether logarithmic axes should be used instead of Cartesian ones. +#' @param 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 \code{NULL} (default), no outlier removal is conducted. +#' @param annotate.coefficients Logical indicating whether the a and b coefficients should be annotated into the plot. +#' @param correct.units Logical indicating whether the a and b coefficients should be converted for centimeters and grams as in FishBase. +#' @param point.size Numeric defining the size for data points in the plot. See the \code{size} argument in \link[ggplot2]{geom_point}. #' @param verbose Logical indicating whether to return warnings and messages. #' @inheritParams plot_maturity -#' @details It is crucial to get the units right when calculating length-weight relationships. 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 centimetres and grams, respectively. If the units are wrong, the intercept, a, will be off the FishBase scale by orders of magnitude (see \href{https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm}{FishBase}). If \code{correct.units = TRUE}, \code{plot_lw()} attempts to correct for the 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. You can ignore this warning if you want to estimate values. Comparing your a and b with those in FishBase for the species is a good idea. This function may contain bugs. -#' @return A ggplot together with the a and b parameters. +#' @details The function estimates the a and b coefficients of the length weight relationship, \eqn{weight = a \times length^b}{weight = a*length^b}, and plots the data. The model can be fitted either using the standard log(weight) ~ log(length) regression (\link[stats]{lm}; default) or nonlinear least squares (\link[stats]{nls}) method. The nls method often manages to fit steeper slopes making the b parameter higher and the a parameter lower than the linear \link[stats]{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 \href{https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm}{FishBase}). The \code{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 \code{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 (\eqn{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. +#' @return 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 Mikko Vihtakari // Institute of Marine Research. #' @import dplyr ggplot2 -#' @importFrom stats lm nls +#' @importFrom stats lm nls quantile residuals #' @examples #' data(survey_ghl) #' #' # Simple plot #' plot_lw(survey_ghl, length = "length", weight = "weight") #' \donttest{ -#' # Split by sex -#' plot_lw(survey_ghl, split.by.sex = TRUE)$plot +#' # 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) #' } #' @export # Debug parameters: # dt = survey_ghl; -# 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; log.axes = FALSE; base_size = 8; legend.position = "bottom"; correct.units = FALSE; verbose = TRUE +# 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 = 99.5; annotate.coefficients = TRUE; base_size = 8; legend.position = "bottom"; correct.units = FALSE; verbose = TRUE -plot_lw <- function(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, base_size = 8, legend.position = "bottom", correct.units = FALSE, verbose = TRUE) { +plot_lw <- function( + 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) { # Add row number #### @@ -44,7 +65,17 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal stop(female.sex, " or ", male.sex, " not found from the ", sex, " column. Check the female.sex and male.sex parameters.") } - if(dt %>% dplyr::pull(!!rlang::enquo(sex)) %>% na.omit() %>% length() < 10) stop("Either invalid sex column or not enough sex data") + + if(!inherits(dt$sex, class(female.sex))) { + class(female.sex) <- class(dt$sex) + } + + if(!inherits(dt$sex, class(male.sex))) { + class(male.sex) <- class(dt$sex) + } + + if(dt %>% dplyr::pull(!!rlang::enquo(sex)) %>% na.omit() %>% length() < 10) + stop("Either invalid sex column or not enough sex data") orig.nrow <- nrow(dt) @@ -112,47 +143,193 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal } } + # Outlier removal + + if(!is.null(outlier.percentile)) { + if(!is.numeric(outlier.percentile)) + stop("The outlier.percentile argument has to be numeric between 0 and 100. + Values > 99 are recommended.") + + if(split.by.sex) { + dt <- lapply(unique(dt$sex), function(k) { + tmp <- dt %>% filter(sex == k) + mod <- lm(log(weight) ~ log(length), data = tmp) + res <- abs(stats::residuals(mod)) + tmp$outlier <- res > stats::quantile(res, outlier.percentile/100) + tmp + }) %>% + dplyr::bind_rows() %>% + dplyr::arrange(id) + + } else { + mod <- lm(log(weight) ~ log(length), data = dt) + res <- abs(stats::residuals(mod)) + dt$outlier <- res > stats::quantile(res, outlier.percentile/100) + } + } else { + dt$outlier <- FALSE + } + # Calculate a and b #### if(use.nls) { if(split.by.sex) { + lwModPars <- dt %>% - dplyr::group_by(sex) %>% - dplyr::do(mod = broom::tidy(nls(I(weight)~a*length^b,., - start = list(a = init.a, b = init.b)), - conf.int = TRUE)) %>% - tidyr::unnest(mod) + dplyr::filter(!.data$outlier) %>% + dplyr::group_by(.data$sex) %>% + tidyr::nest() %>% + dplyr::mutate( + mod = purrr::map(data, ~nls(I(weight)~a*length^b,., + start = list(a = init.a, b = init.b))), + coeff = purrr::map(mod, broom::tidy, conf.int = TRUE), + fit = purrr::map(mod, broom::glance) + ) %>% + dplyr::select(-.data$data, -.data$mod) %>% + tidyr::unnest(.data$coeff) %>% + dplyr::mutate(term = dplyr::recode(.data$term, "(Intercept)" = "a", "log(length)" = "b")) + + lwModPars <- + lwModPars %>% dplyr::select(-.data$fit) %>% + dplyr::bind_cols( + lwModPars$fit %>% + dplyr::bind_rows() %>% + dplyr::select(.data$AIC, .data$nobs) + ) %>% + dplyr::left_join( + lapply(unique(lwModPars$sex), function(k) { + tmp <- dt %>% dplyr::filter(.data$sex == k) + + tibble( + sex = k, + length = paste( + round(min(tmp$length, na.rm = TRUE), 3), + round(max(tmp$length, na.rm = TRUE), 3), sep = " - "), + length.unit = length.unit, + weight = paste( + round(min(tmp$weight, na.rm = TRUE), 4), + round(max(tmp$weight, na.rm = TRUE), 2), sep = " - "), + weight.unit = weight.unit + ) + }) %>% + dplyr::bind_rows(), + by = dplyr::join_by(sex) + ) + } else { + lwModPars <- dt %>% - dplyr::do(mod = broom::tidy(nls(I(weight)~a*length^b,., - start = list(a = init.a, b = init.b)), - conf.int = TRUE)) %>% - tidyr::unnest(mod) - } + dplyr::filter(!.data$outlier) %>% + tidyr::nest() %>% + dplyr::mutate( + mod = purrr::map(data, ~nls(I(weight)~a*length^b,., + start = list(a = init.a, b = init.b))), + coeff = purrr::map(mod, broom::tidy, conf.int = TRUE), + fit = purrr::map(mod, broom::glance) + ) %>% + dplyr::select(-.data$data, -.data$mod) %>% + tidyr::unnest(.data$coeff) %>% + dplyr::mutate(term = dplyr::recode(term, "(Intercept)" = "a", "log(length)" = "b")) + + lwModPars <- + lwModPars %>% dplyr::select(-.data$fit) %>% + dplyr::bind_cols( + lwModPars$fit %>% + dplyr::bind_rows() %>% + dplyr::select(.data$AIC, .data$nobs) + ) %>% + dplyr::mutate( + length = paste(min(dt$length, na.rm = TRUE), max(dt$length, na.rm = TRUE), sep = " - "), + length.unit = length.unit, + weight = paste( + round(min(dt$weight, na.rm = TRUE), 4), + round(max(dt$weight, na.rm = TRUE), 2), sep = " - "), + weight.unit = weight.unit + ) + } } else { if(split.by.sex) { lwModPars <- - dt %>% - dplyr::group_by(sex) %>% - dplyr::do(mod = broom::tidy(lm(log(weight) ~ log(length), data = .), conf.int = TRUE)) %>% - tidyr::unnest(mod) %>% - dplyr::mutate(term = dplyr::recode(term, "(Intercept)" = "a", "log(length)" = "b")) + dt %>% + dplyr::filter(!.data$outlier) %>% + dplyr::group_by(.data$sex) %>% + tidyr::nest() %>% + dplyr::mutate( + mod = purrr::map(data, ~lm(log(weight) ~ log(length), data = .)), + coeff = purrr::map(mod, broom::tidy, conf.int = TRUE), + fit = purrr::map(mod, broom::glance) + ) %>% + dplyr::select(-.data$data, -.data$mod) %>% + tidyr::unnest(.data$coeff) %>% + dplyr::mutate(term = dplyr::recode(.data$term, "(Intercept)" = "a", "log(length)" = "b")) + + lwModPars <- + lwModPars %>% dplyr::select(-.data$fit) %>% + dplyr::bind_cols( + lwModPars$fit %>% + dplyr::bind_rows() %>% + dplyr::select(.data$r.squared, .data$AIC, .data$nobs) + ) %>% + dplyr::left_join( + lapply(unique(lwModPars$sex), function(k) { + tmp <- dt %>% dplyr::filter(.data$sex == k) + + tibble( + sex = k, + length = paste( + round(min(tmp$length, na.rm = TRUE), 3), + round(max(tmp$length, na.rm = TRUE), 3), sep = " - "), + length.unit = length.unit, + weight = paste( + round(min(tmp$weight, na.rm = TRUE), 4), + round(max(tmp$weight, na.rm = TRUE), 2), sep = " - "), + weight.unit = weight.unit + ) + }) %>% + dplyr::bind_rows(), + by = dplyr::join_by(sex) + ) lwModPars[lwModPars$term == "a", c("estimate", "conf.low", "conf.high")] <- # Transform back to normal space exp(lwModPars[lwModPars$term == "a", c("estimate", "conf.low", "conf.high")]) + } else { + lwModPars <- dt %>% - dplyr::do(mod = broom::tidy(lm(log(weight) ~ log(length), data = .), conf.int = TRUE)) %>% - tidyr::unnest(mod) %>% - dplyr::mutate(term = dplyr::recode(term, "(Intercept)" = "a", "log(length)" = "b")) + dplyr::filter(!.data$outlier) %>% + tidyr::nest() %>% + dplyr::mutate( + mod = purrr::map(data, ~lm(log(weight) ~ log(length), data = .)), + coeff = purrr::map(mod, broom::tidy, conf.int = TRUE), + fit = purrr::map(mod, broom::glance) + ) %>% + dplyr::select(-.data$data, -.data$mod) %>% + tidyr::unnest(.data$coeff) %>% + dplyr::mutate(term = dplyr::recode(.data$term, "(Intercept)" = "a", "log(length)" = "b")) - lwModPars[lwModPars$term == "a", c("estimate", "conf.low", "conf.high")] <- # Transform back to normal space + lwModPars <- + lwModPars %>% dplyr::select(-.data$fit) %>% + dplyr::bind_cols( + lwModPars$fit %>% + dplyr::bind_rows() %>% + dplyr::select(.data$r.squared, .data$AIC, .data$nobs) + ) %>% + dplyr::mutate( + length = paste(min(dt$length, na.rm = TRUE), max(dt$length, na.rm = TRUE), sep = " - "), + length.unit = length.unit, + weight = paste( + round(min(dt$weight, na.rm = TRUE), 4), + round(max(dt$weight, na.rm = TRUE), 2), sep = " - "), + weight.unit = weight.unit + ) + + lwModPars[lwModPars$term == "a", c("estimate", "conf.low", "conf.high")] <- # Transform back to normal space exp(lwModPars[lwModPars$term == "a", c("estimate", "conf.low", "conf.high")]) } } @@ -170,14 +347,21 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal if(split.by.sex) { tmp <- bind_rows( - tibble(length = 0:max(dt[dt$sex == female.sex, "length"]), - weight = (lwModPars %>% filter(sex == female.sex, term == "a") %>% pull(estimate))*length^ - (lwModPars %>% filter(sex == female.sex, term == "b") %>% pull(estimate)), - weight.low = (lwModPars %>% filter(sex == female.sex, term == "a") %>% pull(conf.low))*length^ - (lwModPars %>% filter(sex == female.sex, term == "b") %>% pull(conf.low)), - weight.high = (lwModPars %>% filter(sex == female.sex, term == "a") %>% pull(conf.high))*length^ - (lwModPars %>% filter(sex == female.sex, term == "b") %>% pull(conf.high)), - sex = female.sex), + tibble( + length = 0:max(dt[dt$sex == female.sex, "length"]), + weight = (lwModPars %>% filter(sex == female.sex, term == "a") %>% + pull(estimate)) * + length^(lwModPars %>% filter(sex == female.sex, term == "b") %>% + pull(estimate)), + weight.low = (lwModPars %>% filter(sex == female.sex, term == "a") %>% + pull(conf.low)) * + length^(lwModPars %>% filter(sex == female.sex, term == "b") %>% + pull(conf.low)), + weight.high = (lwModPars %>% filter(sex == female.sex, term == "a") %>% + pull(conf.high)) * + length^(lwModPars %>% filter(sex == female.sex, term == "b") %>% + pull(conf.high)), + sex = female.sex), tibble(length = 0:max(dt[dt$sex == male.sex, "length"]), weight = (lwModPars %>% filter(sex == male.sex, term == "a") %>% pull(estimate))*length^ (lwModPars %>% filter(sex == male.sex, term == "b") %>% pull(estimate)), @@ -190,15 +374,38 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal Plot <- suppressWarnings({ ggplot() + - geom_point(data = dt, aes(x = length, y = weight, color = sex, text = paste0("row number: ", id)), shape = 21, alpha = 0.8, size = 0.5) + + geom_point( + data = dt, + aes(x = length, y = weight, color = sex, + text = paste0("row number: ", id), shape = outlier), alpha = 0.8, + size = point.size, show.legend = !is.null(outlier.percentile)) + + scale_shape_manual(values = c(`FALSE` = 21, `TRUE` = 4)) + geom_line(data = tmp, aes(x = length, y = weight.low, color = sex), linetype = 2) + geom_line(data = tmp, aes(x = length, y = weight.high, color = sex), linetype = 2) + facet_wrap(~sex) + - annotate("line", x = tmp[tmp$sex == female.sex,]$length, y = tmp[tmp$sex == female.sex,]$weight, color = "tomato4") + - annotate("line", x = tmp[tmp$sex == male.sex,]$length, y = tmp[tmp$sex == male.sex,]$weight, color = "dodgerblue4") + + annotate("line", x = tmp[tmp$sex == female.sex,]$length, + y = tmp[tmp$sex == female.sex,]$weight, color = "tomato4") + + annotate("line", x = tmp[tmp$sex == male.sex,]$length, + y = tmp[tmp$sex == male.sex,]$weight, color = "dodgerblue4") + + {if(annotate.coefficients) + geom_text( + data = lwModPars %>% + dplyr::select(sex, term, estimate) %>% + tidyr::pivot_wider(names_from = "term", values_from = "estimate"), + aes(x = - Inf, y = Inf, + label = paste( + "a = ", + round(a, 10), + "\nb = ", + round(b, 4)), + vjust = 1, hjust = -0.1) + ) + } + scale_color_manual("Sex", values = c("#FF5F68", "#449BCF")) + scale_y_continuous(n.breaks = 8) + - labs(x = paste0("Total length (", length.unit, ")"), y = paste0("Weight (", weight.unit, ")")) + + labs(x = paste0("Total length (", length.unit, ")"), + y = paste0("Weight (", weight.unit, ")"), + shape = "Removed") + coord_cartesian(expand = FALSE, clip = "off") + theme_fishplots(base_size = base_size) + theme(legend.position = legend.position, @@ -208,12 +415,18 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal Text <- paste0( if(use.nls) {paste0("Nonlinear least squares length-weight model")} else {paste0("Logarithm transformed linear length-weight model")}, " for females and males, respectively:", - " \n a = ", lwModPars %>% filter(term == "a", sex == female.sex) %>% pull(estimate) %>% round(.,4), - " +/- ", lwModPars %>% filter(term == "a", sex == female.sex) %>% pull(conf.low) %>% round(.,3), " - ", - lwModPars %>% filter(term == "a", sex == female.sex) %>% pull(conf.high) %>% round(.,3), " (95% CIs) and ", - lwModPars %>% filter(term == "a", sex == male.sex) %>% pull(estimate) %>% round(.,4), - " +/- ", lwModPars %>% filter(term == "a", sex == male.sex) %>% pull(conf.low) %>% round(.,3), " - ", - lwModPars %>% filter(term == "a", sex == male.sex) %>% pull(conf.high) %>% round(.,3), " (95% CIs).", + " \n a = ", lwModPars %>% filter(term == "a", sex == female.sex) %>% + pull(estimate) %>% round(., ifelse(weight.unit == "kg", 10, 5)), + " +/- ", lwModPars %>% filter(term == "a", sex == female.sex) %>% + pull(conf.low) %>% round(., ifelse(weight.unit == "kg", 10, 5)), " - ", + lwModPars %>% filter(term == "a", sex == female.sex) %>% + pull(conf.high) %>% round(., ifelse(weight.unit == "kg", 10, 5)), " (95% CIs) and ", + lwModPars %>% filter(term == "a", sex == male.sex) %>% + pull(estimate) %>% round(., ifelse(weight.unit == "kg", 10, 5)), + " +/- ", lwModPars %>% filter(term == "a", sex == male.sex) %>% + pull(conf.low) %>% round(., ifelse(weight.unit == "kg", 10, 5)), " - ", + lwModPars %>% filter(term == "a", sex == male.sex) %>% pull(conf.high) %>% + round(., ifelse(weight.unit == "kg", 10, 5)), " (95% CIs).", " \n b = ", lwModPars %>% filter(term == "b", sex == female.sex) %>% pull(estimate) %>% round(.,3), " +/- ", lwModPars %>% filter(term == "b", sex == female.sex) %>% pull(conf.low) %>% round(.,2), " - ", @@ -222,30 +435,53 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal " +/- ", lwModPars %>% filter(term == "b", sex == male.sex) %>% pull(conf.low) %>% round(.,2), " - ", lwModPars %>% filter(term == "b", sex == male.sex) %>% pull(conf.high) %>% round(.,2), " (95% CIs).", + " \n Length in ", length.unit, " and weight in ", weight.unit, " \n Number of included specimens = ", nrow(dt[dt$sex == female.sex,]), " and ", nrow(dt[dt$sex == male.sex,]), " \n Total number of measured = ", orig.nrow, - " \n Excluded (data missing): \n Length = ", length.missing, "; weight = ", weight.missing, "; sex = ", sex.missing + " \n Excluded (data missing): \n Length = ", length.missing, "; weight = ", + weight.missing, "; sex = ", sex.missing, "; outlier = ", sum(dt$outlier) ) } else { - tmp <- tibble(length = 0:max(dt$length), - weight = (lwModPars %>% filter(term == "a") %>% pull(estimate))*length^ - (lwModPars %>% filter(term == "b") %>% pull(estimate)), - weight.low = (lwModPars %>% filter(term == "a") %>% pull(conf.low))*length^ - (lwModPars %>% filter(term == "b") %>% pull(conf.low)), - weight.high = (lwModPars %>% filter(term == "a") %>% pull(conf.high))*length^ - (lwModPars %>% filter(term == "b") %>% pull(conf.high)) + tmp <- tibble( + length = 0:max(dt$length), + weight = (lwModPars %>% filter(term == "a") %>% pull(estimate)) * + length^(lwModPars %>% filter(term == "b") %>% pull(estimate)), + weight.low = (lwModPars %>% filter(term == "a") %>% pull(conf.low)) * + length^(lwModPars %>% filter(term == "b") %>% pull(conf.low)), + weight.high = (lwModPars %>% filter(term == "a") %>% pull(conf.high)) * + length^(lwModPars %>% filter(term == "b") %>% pull(conf.high)) ) Plot <- suppressWarnings({ ggplot() + - geom_point(data = dt, aes(x = length, y = weight, text = paste0("row number: ", id)), shape = 21, alpha = 0.8, size = 0.5) + - geom_line(data = tmp, aes(x = length, y = weight.low), linetype = 2, color = "blue") + - geom_line(data = tmp, aes(x = length, y = weight.high), linetype = 2, color = "blue") + + geom_point( + data = dt, + aes(x = length, y = weight, text = paste0("row number: ", id), + color = outlier, shape = outlier), alpha = 0.8, size = point.size, + show.legend = !is.null(outlier.percentile)) + + scale_shape_manual(values = c(`FALSE` = 21, `TRUE` = 4)) + + scale_color_manual(values = c(`FALSE` = "black", `TRUE` = "darkred")) + + geom_line(data = tmp, aes(x = length, y = weight.low), linetype = 2, + color = "blue") + + geom_line(data = tmp, aes(x = length, y = weight.high), linetype = 2, + color = "blue") + annotate("line", x = tmp$length, y = tmp$weight, color = "blue") + + {if(annotate.coefficients) + annotate( + "text", x = - Inf, y = Inf, + label = paste( + "a = ", + lwModPars %>% filter(term == "a") %>% pull(estimate) %>% round(10), + "\nb = ", + lwModPars %>% filter(term == "b") %>% pull(estimate) %>% round(4)), + vjust = 1, hjust = -0.1) + } + scale_y_continuous(n.breaks = 8) + - labs(x = paste0("Total length (", length.unit, ")"), y = paste0("Weight (", weight.unit, ")")) + + labs(x = paste0("Total length (", length.unit, ")"), + y = paste0("Weight (", weight.unit, ")"), + color = "Removed", shape = "Removed") + coord_cartesian(expand = FALSE, clip = "off") + theme_fishplots(base_size = base_size) + theme(legend.position = legend.position, @@ -255,17 +491,22 @@ plot_lw <- function(dt, length = "length", weight = "weight", sex = "sex", femal Text <- paste0( if(use.nls) {paste0("Nonlinear least squares length-weight model")} else {paste0("Logarithm transformed linear length-weight model")}, ". Not splitted by sex:", - " \n a = ", lwModPars %>% filter(term == "a") %>% pull(estimate) %>% round(.,4), - " +/- ", lwModPars %>% filter(term == "a") %>% pull(conf.low) %>% round(.,3), " - ", - lwModPars %>% filter(term == "a") %>% pull(conf.high) %>% round(.,3), " (95% CIs).", + " \n a = ", lwModPars %>% filter(term == "a") %>% + pull(estimate) %>% round(., ifelse(weight.unit == "kg", 10, 5)), + " +/- ", lwModPars %>% filter(term == "a") %>% + pull(conf.low) %>% round(., ifelse(weight.unit == "kg", 10, 5)), " - ", + lwModPars %>% filter(term == "a") %>% + pull(conf.high) %>% round(., ifelse(weight.unit == "kg", 10, 5)), " (95% CIs).", " \n b = ", lwModPars %>% filter(term == "b") %>% pull(estimate) %>% round(.,3), " +/- ", lwModPars %>% filter(term == "b") %>% pull(conf.low) %>% round(.,2), " - ", lwModPars %>% filter(term == "b") %>% pull(conf.high) %>% round(.,2), " (95% CIs).", + " \n Length in ", length.unit, " and weight in ", weight.unit, " \n Number of included specimens = ", nrow(dt), " \n Total number of measured = ", orig.nrow, - " \n Excluded (data missing): \n Length = ", length.missing, "; weight = ", weight.missing + " \n Excluded (data missing): \n Length = ", length.missing, "; weight = ", + weight.missing, "; outlier = ", sum(dt$outlier) ) } diff --git a/R/plot_maturity.R b/R/plot_maturity.R index 4ff10a7..3f3771e 100644 --- a/R/plot_maturity.R +++ b/R/plot_maturity.R @@ -7,8 +7,7 @@ #' @param length.unit A character argument giving the unit of \code{length}. Will be used in the labels of the figure. #' @param length.bin.width Numeric specifying the increment (delta length) by which length data should be binned to calculate maturity proportions. Use \code{NULL} to remove from the plot. #' @param split.by.sex Logical indicating whether the result should be split by sex. -#' @param female.sex A character denoting female sex in the \code{sex} column of \code{dt} -#' @param male.sex A character denoting male sex in the \code{sex} column of \code{dt} +#' @param female.sex,male.sex A character or integer denoting female and male sex in the \code{sex} column of \code{dt}, respectively. #' @param bootstrap.n Integer defining the number of bootstrap replicates to be used to calculate 95\% confidence intervals for the mean 50\% mature estimate. If \code{NA} (default), the confidence intervals are calculated from the glm object without boostrapping. See Details. #' @param force.zero.group.length Numeric indicating the length to which 0-group (all immatures) should be forced. Use \code{NA} ignore the forcing. #' @param 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. diff --git a/R/zzz.R b/R/zzz.R index 78bec44..f33855c 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -1,4 +1,4 @@ # Define global variables -utils::globalVariables(c("bin1", "mat.pr", "ci.min", "ci.max", "bin", "conf.high", "conf.low", "estimate", "mod", "term", "weight.high", "weight.low", ".")) +utils::globalVariables(c("bin1", "mat.pr", "ci.min", "ci.max", "bin", "conf.high", "conf.low", "estimate", "mod", "term", "weight.high", "weight.low", ".", "a", "b", "outlier", "data")) diff --git a/README.Rmd b/README.Rmd index e84fdf6..d7fb669 100644 --- a/README.Rmd +++ b/README.Rmd @@ -19,7 +19,7 @@ knitr::opts_chunk$set( **Visualise and calculate life history parameters for fisheries science using ggplot2. R package version `r packageVersion("ggFishPlots")`** - +[![DOI](https://zenodo.org/badge/DOI/10.32614/CRAN.package.ggFishPlots.svg)](https://doi.org/10.32614/CRAN.package.ggFishPlots) [![R-CMD-check](https://github.com/DeepWaterIMR/ggFishPlots/workflows/R-CMD-check/badge.svg)](https://github.com/DeepWaterIMR/ggFishPlots/actions) [![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/ggFishPlots)](https://CRAN.R-project.org/package=ggFishPlots) @@ -173,13 +173,18 @@ You can also transform the parameters according to the formulas given in the Fis plot_lw(survey_ghl %>% dplyr::mutate(weight = weight*1000), weight.unit = "g")$params ``` - #### Log-log axes to see differences ```{r} plot_lw(survey_ghl, split.by.sex = TRUE, log.axes = TRUE)$plot ``` +#### Outlier removal + +```{r} +plot_lw(survey_ghl, outlier.percentile = 99.5, annotate.coefficients = TRUE)$plot +``` + ### Catch curves to estimate instantaneous total mortality (Z) Catch curves were added to the version 0.2.3 and may not be available in the CRAN version. [A FishR tutorial written by Ogle (2013)](https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm) contains a nice explanation of catch curves. At the time of writing ggFishPlots calculates only the simple log-linearised regression. diff --git a/README.md b/README.md index 1da0dc2..4e5b862 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ # ggFishPlots **Visualise and calculate life history parameters for fisheries science -using ggplot2. R package version 0.2.4** +using ggplot2. R package version 0.2.7** - +[![DOI](https://zenodo.org/badge/DOI/10.32614/CRAN.package.ggFishPlots.svg)](https://doi.org/10.32614/CRAN.package.ggFishPlots) [![R-CMD-check](https://github.com/DeepWaterIMR/ggFishPlots/workflows/R-CMD-check/badge.svg)](https://github.com/DeepWaterIMR/ggFishPlots/actions) [![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/ggFishPlots)](https://CRAN.R-project.org/package=ggFishPlots) @@ -83,6 +83,9 @@ head(survey_ghl) #> 4 NA 31 NA 0 #> 5 NA 32 NA 0 #> 6 NA 32 NA 0 +``` + +``` r plot_growth(survey_ghl, length = "length", age = "age") #> $plot @@ -194,11 +197,11 @@ plot_maturity(survey_ghl, bootstrap.n = 10) #> #> $text - #> [1] "50% maturity at length (L50) based on logit regressions:\n54.777 cm. 95% confidence intervals: 54.638 - 54.923\n Number of specimens: 64265\n\n Confidence intervals estimated using 10 bootstrap replicates." + #> [1] "50% maturity at length (L50) based on logit regressions:\n54.783 cm. 95% confidence intervals: 54.604 - 54.932\n Number of specimens: 64265\n\n Confidence intervals estimated using 10 bootstrap replicates." #> #> $params - #> mean ci.min ci.max sex intercept slope n - #> 1 54.77727 54.6383 54.92337 both -5.755492 0.1050587 64265 + #> mean ci.min ci.max sex intercept slope n + #> 1 54.78312 54.60357 54.93155 both -5.755492 0.1050587 64265 #### Split by sex @@ -270,14 +273,16 @@ plot_lw(survey_ghl, length = "length", weight = "weight") #> #> $text - #> [1] "Logarithm transformed linear length-weight model. Not splitted by sex: \n a = 0 +/- 0 - 0 (95% CIs). \n b = 3.221 +/- 3.22 - 3.22 (95% CIs). \n Number of included specimens = 67457 \n Total number of measured = 618779 \n Excluded (data missing): \n Length = 0; weight = 551322" + #> [1] "Logarithm transformed linear length-weight model. Not splitted by sex: \n a = 3.8236e-06 +/- 3.7869e-06 - 3.8606e-06 (95% CIs). \n b = 3.221 +/- 3.22 - 3.22 (95% CIs). \n Length in cm and weight in kg \n Number of included specimens = 67457 \n Total number of measured = 618779 \n Excluded (data missing): \n Length = 0; weight = 551322; outlier = 0" #> #> $params - #> # A tibble: 2 × 7 - #> term estimate std.error statistic p.value conf.low conf.high - #> - #> 1 a 0.00000382 0.00491 -2540. 0 0.00000379 0.00000386 - #> 2 b 3.22 0.00128 2519. 0 3.22 3.22 + #> # A tibble: 2 × 14 + #> term estimate std.error statistic p.value conf.low conf.high r.squared + #> + #> 1 a 0.00000382 0.00491 -2540. 0 0.00000379 0.00000386 0.989 + #> 2 b 3.22 0.00128 2519. 0 3.22 3.22 0.989 + #> # ℹ 6 more variables: AIC , nobs , length , length.unit , + #> # weight , weight.unit The dashed lines represent 95% confidence intervals. @@ -294,14 +299,16 @@ plot_lw(survey_ghl, use.nls = TRUE) #> #> $text - #> [1] "Nonlinear least squares length-weight model. Not splitted by sex: \n a = 0 +/- 0 - 0 (95% CIs). \n b = 3.419 +/- 3.42 - 3.42 (95% CIs). \n Number of included specimens = 67457 \n Total number of measured = 618779 \n Excluded (data missing): \n Length = 0; weight = 551322" + #> [1] "Nonlinear least squares length-weight model. Not splitted by sex: \n a = 1.7268e-06 +/- 1.6962e-06 - 1.758e-06 (95% CIs). \n b = 3.419 +/- 3.42 - 3.42 (95% CIs). \n Length in cm and weight in kg \n Number of included specimens = 67457 \n Total number of measured = 618779 \n Excluded (data missing): \n Length = 0; weight = 551322; outlier = 0" #> #> $params - #> # A tibble: 2 × 7 - #> term estimate std.error statistic p.value conf.low conf.high - #> - #> 1 a 0.00000173 0.0000000156 110. 0 0.00000170 0.00000176 - #> 2 b 3.42 0.00215 1590. 0 3.42 3.42 + #> # A tibble: 2 × 13 + #> term estimate std.error statistic p.value conf.low conf.high AIC nobs + #> + #> 1 a 0.00000173 1.56e-8 110. 0 1.70e-6 1.76e-6 -27925. 67457 + #> 2 b 3.42 2.15e-3 1590. 0 3.42e+0 3.42e+0 -27925. 67457 + #> # ℹ 4 more variables: length , length.unit , weight , + #> # weight.unit #### Split by sex @@ -321,27 +328,32 @@ plot_lw(survey_ghl, split.by.sex = TRUE, correct.units = TRUE) #> #> $text - #> [1] "Logarithm transformed linear length-weight model for females and males, respectively: \n a = 0.0035 +/- 0.003 - 0.004 (95% CIs) and 0.0051 +/- 0.005 - 0.005 (95% CIs). \n b = 3.247 +/- 3.24 - 3.25 (95% CIs) and 3.143 +/- 3.14 - 3.15 (95% CIs). \n Number of included specimens = 34889 and 30354 \n Total number of measured = 618779 \n Excluded (data missing): \n Length = 0; weight = 456891; sex = 96645" + #> [1] "Logarithm transformed linear length-weight model for females and males, respectively: \n a = 0.0035 +/- 0.00344 - 0.00355 (95% CIs) and 0.00507 +/- 0.00497 - 0.00517 (95% CIs). \n b = 3.247 +/- 3.24 - 3.25 (95% CIs) and 3.143 +/- 3.14 - 3.15 (95% CIs). \n Length in cm and weight in g \n Number of included specimens = 34889 and 30354 \n Total number of measured = 618779 \n Excluded (data missing): \n Length = 0; weight = 456891; sex = 96645; outlier = 0" #> #> $params - #> # A tibble: 4 × 8 - #> sex term estimate std.error statistic p.value conf.low conf.high - #> - #> 1 F a 0.00350 0.00765 -739. 0 0.00344 0.00355 - #> 2 F b 3.25 0.00195 1666. 0 3.24 3.25 - #> 3 M a 0.00507 0.0101 -525. 0 0.00497 0.00517 - #> 4 M b 3.14 0.00265 1188. 0 3.14 3.15 + #> # A tibble: 4 × 15 + #> # Groups: sex [2] + #> sex term estimate std.error statistic p.value conf.low conf.high r.squared + #> + #> 1 F a 0.00350 0.00765 -739. 0 0.00344 0.00355 0.988 + #> 2 F b 3.25 0.00195 1666. 0 3.24 3.25 0.988 + #> 3 M a 0.00507 0.0101 -525. 0 0.00497 0.00517 0.979 + #> 4 M b 3.14 0.00265 1188. 0 3.14 3.15 0.979 + #> # ℹ 6 more variables: AIC , nobs , length , length.unit , + #> # weight , weight.unit You can also transform the parameters according to the formulas given in the FishBase. ``` r plot_lw(survey_ghl %>% dplyr::mutate(weight = weight*1000), weight.unit = "g")$params -#> # A tibble: 2 × 7 -#> term estimate std.error statistic p.value conf.low conf.high -#> -#> 1 a 0.00382 0.00491 -1133. 0 0.00379 0.00386 -#> 2 b 3.22 0.00128 2519. 0 3.22 3.22 +#> # A tibble: 2 × 14 +#> term estimate std.error statistic p.value conf.low conf.high r.squared +#> +#> 1 a 0.00382 0.00491 -1133. 0 0.00379 0.00386 0.989 +#> 2 b 3.22 0.00128 2519. 0 3.22 3.22 0.989 +#> # ℹ 6 more variables: AIC , nobs , length , length.unit , +#> # weight , weight.unit ``` #### Log-log axes to see differences @@ -352,6 +364,14 @@ plot_lw(survey_ghl, split.by.sex = TRUE, log.axes = TRUE)$plot ![](man/figures/README-unnamed-chunk-17-1.png) +#### Outlier removal + +``` r +plot_lw(survey_ghl, outlier.percentile = 99.5, annotate.coefficients = TRUE)$plot +``` + +![](man/figures/README-unnamed-chunk-18-1.png) + ### Catch curves to estimate instantaneous total mortality (Z) Catch curves were added to the version 0.2.3 and may not be available in @@ -365,7 +385,7 @@ plot_catchcurve(survey_ghl) #> $plot ``` -![](man/figures/README-unnamed-chunk-18-1.png) +![](man/figures/README-unnamed-chunk-19-1.png) #> #> $text @@ -385,7 +405,7 @@ The ages to be included to the Z estimation can be adjusted using the plot_catchcurve(survey_ghl, age.range = c(10,26))$plot ``` -![](man/figures/README-unnamed-chunk-19-1.png) +![](man/figures/README-unnamed-chunk-20-1.png) In the plot above, -b is Z (i.e. Z = 0.356) and exp(a) (i.e. 68391) is the number of 0 age fish assuming constant mortality. @@ -396,7 +416,7 @@ the number of 0 age fish assuming constant mortality. plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE)$plot ``` -![](man/figures/README-unnamed-chunk-20-1.png) +![](man/figures/README-unnamed-chunk-21-1.png) Use a named list to use separate age ranges for females and males. @@ -408,7 +428,7 @@ split.by.sex = TRUE) tmp$plot ``` -![](man/figures/README-unnamed-chunk-21-1.png) +![](man/figures/README-unnamed-chunk-22-1.png) Parameter estimates for the catch curve above: @@ -441,20 +461,19 @@ articles. For up-to-date citation information, please use: ``` r citation("ggFishPlots") -#> #> To cite package 'ggFishPlots' in publications use: #> -#> Vihtakari M (2023). _ggFishPlots: Visualise and Calculate Life +#> Vihtakari M (2024). _ggFishPlots: Visualise and Calculate Life #> History Parameters for Fisheries Science using 'ggplot2'_. R package -#> version 0.2.4, . +#> version 0.2.7, . #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, #> title = {ggFishPlots: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2'}, #> author = {Mikko Vihtakari}, -#> year = {2023}, -#> note = {R package version 0.2.4}, +#> year = {2024}, +#> note = {R package version 0.2.7}, #> url = {https://deepwaterimr.github.io/ggFishPlots/}, #> } ``` diff --git a/docs/404.html b/docs/404.html index e61027f..c4b9b4e 100644 --- a/docs/404.html +++ b/docs/404.html @@ -7,10 +7,10 @@ Page not found (404) • ggFishPlots - - + + - + License • ggFishPlotsLicense • ggFishPlots Skip to contents -
+
+
+

Plot age-length relationships and growth curves

+ Source: R/plot_growth.R +
plot_growth.Rd
-
+

Plot age-length relationships and growth curves

-
+
+

Usage

plot_growth(
   dt,
   length = "length",
@@ -70,8 +68,8 @@ 
Plot age-length relationships and growth curves

 )
-
-

Arguments

+
+

Arguments

dt

A data.frame, tibble or data.table

@@ -88,12 +86,8 @@

Arguments

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

-
female.sex
-

A character denoting female sex in the sex column of dt

- - -
male.sex
-

A character denoting male sex in the sex column of dt

+
female.sex, male.sex
+

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

length.unit
@@ -136,23 +130,23 @@

Arguments

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

-
-

Value

+
+

Value

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

-
-

Details

+
+

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.

-
-

Author

+
+

Author

Mikko Vihtakari // Institute of Marine Research.

-
-

Examples

+
+

Examples

# Simple plot. Note that a list is returned.
 data(survey_ghl)
 plot_growth(survey_ghl, length = "length", age = "age")
@@ -180,26 +174,22 @@ 
Examples

 # }
-
- -
+
-
-

Developed by Mikko Vihtakari.

+
+

Developed by Mikko Vihtakari.

-
-

Site built with pkgdown 2.0.7.

+
+

Site built with pkgdown 2.0.9.

-
+
- diff --git a/docs/reference/plot_lw-1.png b/docs/reference/plot_lw-1.png index a9ce5b8..05832d5 100644 Binary files a/docs/reference/plot_lw-1.png and b/docs/reference/plot_lw-1.png differ diff --git a/docs/reference/plot_lw-2.png b/docs/reference/plot_lw-2.png index b0eb0cf..1aea823 100644 Binary files a/docs/reference/plot_lw-2.png and b/docs/reference/plot_lw-2.png differ diff --git a/docs/reference/plot_lw-3.png b/docs/reference/plot_lw-3.png new file mode 100644 index 0000000..309cdbc Binary files /dev/null and b/docs/reference/plot_lw-3.png differ diff --git a/docs/reference/plot_lw-4.png b/docs/reference/plot_lw-4.png new file mode 100644 index 0000000..183c8d0 Binary files /dev/null and b/docs/reference/plot_lw-4.png differ diff --git a/docs/reference/plot_lw.html b/docs/reference/plot_lw.html index 1bc33cf..4309997 100644 --- a/docs/reference/plot_lw.html +++ b/docs/reference/plot_lw.html @@ -1,55 +1,53 @@ -Plot length-weight relationships — plot_lw • ggFishPlotsPlot length-weight relationships — plot_lw • ggFishPlots + + Skip to contents -
-
-
-
-

Plot length-weight relationships

- Source: R/plot_lw.R - +
+ + +
+
+
+
+

Plot length-weight relationships

+ Source: R/plot_lw.R +
plot_lw.Rd
-
-

Plot length-weight relationships

+
+

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",
@@ -66,15 +64,18 @@ 
Plot length-weight relationships

   init.a = NULL,
   init.b = NULL,
   log.axes = FALSE,
+  outlier.percentile = NULL,
+  annotate.coefficients = FALSE,
+  correct.units = FALSE,
   base_size = 8,
   legend.position = "bottom",
-  correct.units = FALSE,
+  point.size = 0.5,
   verbose = TRUE
 )
-
-

Arguments

+
+

Arguments

dt

A data.frame, tibble or data.table

@@ -91,20 +92,16 @@

Arguments

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

-
female.sex
-

A character denoting female sex in the sex column of dt

- - -
male.sex
-

A character denoting male sex in the sex column of dt

+
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 parameter. Allowed values for the conversion: "mm" (millimmeters), "cm" (centimeters), and "m" (meters).

+

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 parameter. Allowed values: "g" (grams), "kg" (kilograms), and "t" (metric tons).

+

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
@@ -120,15 +117,27 @@

Arguments

use.nls
-

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

+

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 parameters respecitively for non-linear least-squares estimation (i.e. when use.nls = TRUE). If NULL, default values are guessed.

+

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.

+

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
@@ -139,31 +148,33 @@

Arguments

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

-
correct.units
-

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

+
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.

-
-

Value

+
+

Value

-

A ggplot together with the a and b parameters.

+

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).

-
-

Details

-

It is crucial to get the units right when calculating length-weight relationships. 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 centimetres and grams, respectively. If the units are wrong, the intercept, a, will be off the FishBase scale by orders of magnitude (see FishBase). If correct.units = TRUE, plot_lw() attempts to correct for the 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. You can ignore this warning if you want to estimate values. Comparing your a and b with those in FishBase for the species is a good idea. This function may contain bugs.

+
+

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.

-
-

Author

+
+

Author

Mikko Vihtakari // Institute of Marine Research.

-
-

Examples

+
+

Examples

data(survey_ghl)
 
 # Simple plot
@@ -172,42 +183,76 @@ 
Examples

 
 #> 
 #> $text
-#> [1] "Logarithm transformed linear length-weight model. Not splitted by sex:  \n a = 0 +/- 0 - 0 (95% CIs).  \n b = 3.221 +/- 3.22 - 3.22 (95% CIs).  \n Number of included specimens = 67457  \n Total number of measured = 618779  \n Excluded (data missing): \n Length = 0; weight = 551322"
+#> [1] "Logarithm transformed linear length-weight model. Not splitted by sex:  \n a = 3.8236e-06 +/- 3.7869e-06 - 3.8606e-06 (95% CIs).  \n b = 3.221 +/- 3.22 - 3.22 (95% CIs).  \n Length in cm and weight in kg  \n Number of included specimens = 67457  \n Total number of measured = 618779  \n Excluded (data missing): \n Length = 0; weight = 551322; outlier = 0"
 #> 
 #> $params
-#> # A tibble: 2 × 7
-#>   term    estimate std.error statistic p.value   conf.low  conf.high
-#>   <chr>      <dbl>     <dbl>     <dbl>   <dbl>      <dbl>      <dbl>
-#> 1 a     0.00000382   0.00491    -2540.       0 0.00000379 0.00000386
-#> 2 b     3.22         0.00128     2519.       0 3.22       3.22      
+#> # A tibble: 2 × 14
+#>   term    estimate std.error statistic p.value   conf.low  conf.high r.squared
+#>   <chr>      <dbl>     <dbl>     <dbl>   <dbl>      <dbl>      <dbl>     <dbl>
+#> 1 a     0.00000382   0.00491    -2540.       0 0.00000379 0.00000386     0.989
+#> 2 b     3.22         0.00128     2519.       0 3.22       3.22           0.989
+#> # ℹ 6 more variables: AIC <dbl>, nobs <int>, length <chr>, length.unit <chr>,
+#> #   weight <chr>, weight.unit <chr>
 #> 
 # \donttest{
-# Split by sex
-plot_lw(survey_ghl, split.by.sex = TRUE)$plot
+# nls
+plot_lw(survey_ghl, use.nls = TRUE)
+#> $plot
 
+#> 
+#> $text
+#> [1] "Nonlinear least squares length-weight model. Not splitted by sex:  \n a = 1.7268e-06 +/- 1.6962e-06 - 1.758e-06 (95% CIs).  \n b = 3.419 +/- 3.42 - 3.42 (95% CIs).  \n Length in cm and weight in kg  \n Number of included specimens = 67457  \n Total number of measured = 618779  \n Excluded (data missing): \n Length = 0; weight = 551322; outlier = 0"
+#> 
+#> $params
+#> # A tibble: 2 × 13
+#>   term    estimate  std.error statistic p.value conf.low conf.high     AIC  nobs
+#>   <chr>      <dbl>      <dbl>     <dbl>   <dbl>    <dbl>     <dbl>   <dbl> <int>
+#> 1 a     0.00000173    1.56e-8      110.       0  1.70e-6   1.76e-6 -27925. 67457
+#> 2 b     3.42          2.15e-3     1590.       0  3.42e+0   3.42e+0 -27925. 67457
+#> # ℹ 4 more variables: length <chr>, length.unit <chr>, weight <chr>,
+#> #   weight.unit <chr>
+#> 
+
+# 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
+
+#> 
+#> $text
+#> [1] "Logarithm transformed linear length-weight model. Not splitted by sex:  \n a = 3.74e-06 +/- 3.7064e-06 - 3.7738e-06 (95% CIs).  \n b = 3.227 +/- 3.22 - 3.23 (95% CIs).  \n Length in cm and weight in kg  \n Number of included specimens = 67457  \n Total number of measured = 618779  \n Excluded (data missing): \n Length = 0; weight = 551322; outlier = 675"
+#> 
+#> $params
+#> # A tibble: 2 × 14
+#>   term    estimate std.error statistic p.value   conf.low  conf.high r.squared
+#>   <chr>      <dbl>     <dbl>     <dbl>   <dbl>      <dbl>      <dbl>     <dbl>
+#> 1 a     0.00000374   0.00460    -2717.       0 0.00000371 0.00000377     0.991
+#> 2 b     3.23         0.00120     2697.       0 3.22       3.23           0.991
+#> # ℹ 6 more variables: AIC <dbl>, nobs <int>, length <chr>, length.unit <chr>,
+#> #   weight <chr>, weight.unit <chr>
+#> 
 # }
-
- -
+
-
-

Developed by Mikko Vihtakari.

+
+

Developed by Mikko Vihtakari.

-
-

Site built with pkgdown 2.0.7.

+
+

Site built with pkgdown 2.0.9.

-
+
- diff --git a/docs/reference/plot_maturity-1.png b/docs/reference/plot_maturity-1.png index b1215c8..5adeb2b 100644 Binary files a/docs/reference/plot_maturity-1.png and b/docs/reference/plot_maturity-1.png differ diff --git a/docs/reference/plot_maturity-2.png b/docs/reference/plot_maturity-2.png index 0d8eb4b..5d5d7c0 100644 Binary files a/docs/reference/plot_maturity-2.png and b/docs/reference/plot_maturity-2.png differ diff --git a/docs/reference/plot_maturity-3.png b/docs/reference/plot_maturity-3.png index 271017e..bc898d7 100644 Binary files a/docs/reference/plot_maturity-3.png and b/docs/reference/plot_maturity-3.png differ diff --git a/docs/reference/plot_maturity-4.png b/docs/reference/plot_maturity-4.png index 0c10a31..2aa4b02 100644 Binary files a/docs/reference/plot_maturity-4.png and b/docs/reference/plot_maturity-4.png differ diff --git a/docs/reference/plot_maturity.html b/docs/reference/plot_maturity.html index ff5eef1..1747907 100644 --- a/docs/reference/plot_maturity.html +++ b/docs/reference/plot_maturity.html @@ -1,55 +1,53 @@ -Plot maturity ogive — plot_maturity • ggFishPlotsPlot maturity ogive — plot_maturity • ggFishPlots + + Skip to contents -
-
-
-
-

Plot maturity ogive

- Source: R/plot_maturity.R - +
+ + +
+
+
+
+

Plot maturity ogive

+ Source: R/plot_maturity.R +
plot_maturity.Rd
-
+

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

-
+
+

Usage

plot_maturity(
   dt,
   length = "length",
@@ -72,8 +70,8 @@ 
Plot maturity ogive

 )
-
-

Arguments

+
+

Arguments

dt

A data.frame, tibble or data.table

@@ -94,12 +92,8 @@

Arguments

Logical indicating whether the result should be split by sex.

-
female.sex
-

A character denoting female sex in the sex column of dt

- - -
male.sex
-

A character denoting male sex in the sex column of dt

+
female.sex, male.sex
+

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

length.unit
@@ -146,26 +140,27 @@

Arguments

Additional arguments passed to geom_density_ridges.

-
-

Value

+
+

Value

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

-
-

Details

+
+

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.

-
-

Author

+
+

Author

Mikko Vihtakari // Institute of Marine Research.

-
-

Examples

+
+

Examples

# Simple L50 plot
 data(survey_ghl)
 plot_maturity(survey_ghl, length = "length", maturity = "maturity")
+#> Warning: Ignoring unknown parameters: `size`
 #> $plot
 #> Picking joint bandwidth of 1.21
 
@@ -180,16 +175,17 @@ 
Examples

 # \donttest{
 # Bootstrapped CIs are narrower than the glm ones
 plot_maturity(survey_ghl, bootstrap.n = 10)
+#> Warning: Ignoring unknown parameters: `size`
 #> $plot
 #> Picking joint bandwidth of 1.21
 
 #> 
 #> $text
-#> [1] "50% maturity at length (L50) based on logit regressions:\n54.766 cm. 95% confidence intervals: 54.68 - 54.963\n  Number of specimens: 64265\n\n Confidence intervals estimated using 10 bootstrap replicates."
+#> [1] "50% maturity at length (L50) based on logit regressions:\n54.793 cm. 95% confidence intervals: 54.706 - 54.884\n  Number of specimens: 64265\n\n Confidence intervals estimated using 10 bootstrap replicates."
 #> 
 #> $params
-#>       mean   ci.min   ci.max  sex intercept     slope     n
-#> 1 54.76594 54.67962 54.96343 both -5.755492 0.1050587 64265
+#>       mean   ci.min  ci.max  sex intercept     slope     n
+#> 1 54.79348 54.70635 54.8836 both -5.755492 0.1050587 64265
 #> 
 
 # A50 plot, split by sex
@@ -208,26 +204,22 @@ 
Examples

 # }
-
- -
+
-
-

Developed by Mikko Vihtakari.

+
+

Developed by Mikko Vihtakari.

-
-

Site built with pkgdown 2.0.7.

+
+

Site built with pkgdown 2.0.9.

-
+
- diff --git a/docs/search.json b/docs/search.json index faca4dc..196728a 100644 --- a/docs/search.json +++ b/docs/search.json @@ -1 +1 @@ -[{"path":"/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Mikko Vihtakari. Author, maintainer. Institute Marine Research","code":""},{"path":"/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Vihtakari M (2023). ggFishPlots: Visualise Calculate Life History Parameters Fisheries Science using 'ggplot2'. R package version 0.2.4, https://deepwaterimr.github.io/ggFishPlots/.","code":"@Manual{, title = {ggFishPlots: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2'}, author = {Mikko Vihtakari}, year = {2023}, note = {R package version 0.2.4}, url = {https://deepwaterimr.github.io/ggFishPlots/}, }"},{"path":"/index.html","id":"ggfishplots","dir":"","previous_headings":"","what":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Visualise calculate life history parameters fisheries science using ggplot2. R package version 0.2.4","code":""},{"path":"/index.html","id":"overview","dir":"","previous_headings":"","what":"Overview","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"ggFishPlots package R allows quickly plotting calculating life history parameters required stock assessment models. package uses ggplot2 plotting tidyverse packages calculations. ggOceanMaps package developed Institute Marine Research. Note package comes absolutely warranty. bug reports code fixes warmly welcomed. See Contributions details. looking similar packages, make sure check AquaticLifeHistory, FSA, fishmethods packages, well FishR webpage.","code":""},{"path":"/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"date version package can always found GitHub. CRAN version work shown examples website, try installing GitHub version. can using devtools remotes packages.","code":"remotes::install_github(\"DeepWaterIMR/ggFishPlots\")"},{"path":"/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"package website. time writing, package produces four kinds plots: growth curves, maturity plots, length-weight relationships, catch curves. function returns ggplot2 plot estimated parameters text string can used Rmarkdown Shiny applications well data frame use parameters. elements returned list. package contains example data illustrate functionality.","code":""},{"path":"/index.html","id":"growth-curves","dir":"","previous_headings":"Usage","what":"Growth curves","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Note text params returned list together plot. text object can rendered R markdown documents using results = 'asis' setting code chunk header (.e. {r, results = 'asis'}) cat() function replacing \"\\n\" \"\\ n\": von Bertalanffy growth function coefficients: Linf (asymptotic average length) = 91.2 cm +/- 88.3 - 94.6 (95% CIs) K (growth rate coefficient) = 0.0633 +/- 0.059 - 0.068 (95% CIs) t0 (age length 0) = -3.04 (years) +/- -3.337 - -2.769 (95% CIs) tmax (life span; t0 + 3/K) = 44.4 years Number included specimens = 10401 Total number measured = 618779 Excluded (length age missing): Length = 0; age = 608378","code":"library(ggFishPlots) data(survey_ghl) # example data head(survey_ghl) #> # A tibble: 6 × 5 #> age sex length weight maturity #> #> 1 NA 35 NA 0 #> 2 NA 43 NA 0 #> 3 NA 51 NA 0 #> 4 NA 31 NA 0 #> 5 NA 32 NA 0 #> 6 NA 32 NA 0 plot_growth(survey_ghl, length = \"length\", age = \"age\") #> $plot #> #> $text #> [1] \"von Bertalanffy growth function coefficients: \\n Linf (asymptotic average length) = 91.2 cm +/- 88.3 - 94.6 (95% CIs) \\n K (growth rate coefficient) = 0.0633 +/- 0.059 - 0.068 (95% CIs) \\n t0 (age at length 0) = -3.04 (years) +/- -3.337 - -2.769 (95% CIs) \\n tmax (life span; t0 + 3/K) = 44.4 years \\n Number of included specimens = 10401 \\n Total number of measured = 618779 \\n Excluded (length or age missing): \\n Length = 0; age = 608378\" #> #> $params #> # A tibble: 3 × 7 #> term estimate std.error statistic p.value conf.low conf.high #> #> 1 Sinf 91.2 1.51 60.3 0 88.3 94.6 #> 2 K 0.0633 0.00231 27.4 4.90e-160 0.0586 0.0680 #> 3 t0 -3.04 0.139 -21.8 1.71e-103 -3.34 -2.77 htmlcat <- function(text){ cat(gsub(pattern = \"\\n\", replacement = \" \\n\", x = text)) } htmlcat(plot_growth(survey_ghl)$text)"},{"path":"/index.html","id":"split-by-sex","dir":"","previous_headings":"Usage > Growth curves","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Specifying length, age sex arguments omitted since argument names default example data. plot element returned time. dashed lines Sinf. Data behind growth curves shown box plots default. possible plot data points defining boxplot = FALSE. can also force zero group curves know length . Assumed 14 cm . Zero group forcing strength 10 % number observations default can adjusted using force.zero.group.strength argument.","code":"plot_growth(survey_ghl, split.by.sex = TRUE)$plot plot_growth(survey_ghl, force.zero.group.length = 14, boxplot = FALSE)$plot"},{"path":[]},{"path":"/index.html","id":"l50-plots","dir":"","previous_headings":"Usage > Maturity plots","what":"L50 plots","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Maturity ogives estimated using logistic (family = binomial(link = \"logit\")) glm() error bars represent 95% confidence intervals calculated model object using confint() function back-transformed original scale. grey stepped line binned average defined using length.bin.width argument. function also contains option bootstrap confidence intervals (CIs) produce narrower CIs. Bootstrapping probably correct way estimating CIs application. Using 10 replicates save processing time. real application use least 1000.","code":"plot_maturity(survey_ghl, length = \"length\", maturity = \"maturity\") #> $plot #> #> $text #> [1] \"50% maturity at length (L50) based on logit regressions:\\n54.784 cm. 95% confidence intervals: 52.852 - 56.787\\n Number of specimens: 64265.\\n Confidence intervals estimated from the glm object.\" #> #> $params #> mean ci.min ci.max sex intercept slope n #> 1 54.78361 52.85249 56.787 both -5.755492 0.1050587 64265 plot_maturity(survey_ghl, bootstrap.n = 10) #> $plot #> #> $text #> [1] \"50% maturity at length (L50) based on logit regressions:\\n54.777 cm. 95% confidence intervals: 54.638 - 54.923\\n Number of specimens: 64265\\n\\n Confidence intervals estimated using 10 bootstrap replicates.\" #> #> $params #> mean ci.min ci.max sex intercept slope n #> 1 54.77727 54.6383 54.92337 both -5.755492 0.1050587 64265"},{"path":"/index.html","id":"split-by-sex-1","dir":"","previous_headings":"Usage > Maturity plots","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"","code":"plot_maturity(survey_ghl, split.by.sex = TRUE)$plot"},{"path":"/index.html","id":"a50-plots","dir":"","previous_headings":"Usage > Maturity plots","what":"A50 plots","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"principle can used produce A50 (50% maturity age) plots:","code":"plot_maturity(survey_ghl, length = \"age\", length.unit = \"years\", xlab = \"Age\", length.bin.width = 1, split.by.sex = TRUE)$plot"},{"path":"/index.html","id":"addition-of-juveniles","dir":"","previous_headings":"Usage > Maturity plots","what":"Addition of juveniles","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Also plot_maturity() function option add juveniles (zero group fish). addition juveniles can necessary make glm() converge small immature fish scarce dataset. Note addition increases estimate males dataset contain sufficient number young males number females seems sufficient females mature older species. One option can estimate number added juveniles using plot_catchcurve() function:","code":"plot_maturity(survey_ghl, length = \"age\", length.unit = \"years\", xlab = \"Age\", length.bin.width = 1, force.zero.group.length = 0, force.zero.group.strength = 100, split.by.sex = TRUE)$plot plot_maturity(survey_ghl, length = \"age\", length.unit = \"years\", xlab = \"Age\", length.bin.width = 1, force.zero.group.length = 0, force.zero.group.n = c(\"F\" = exp(11.363), \"M\" = exp(11.885)), split.by.sex = TRUE)$plot"},{"path":[]},{"path":"/index.html","id":"log-linearized-models","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Log-linearized models","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Simple plot using log-transformation linear models default. dashed lines represent 95% confidence intervals.","code":"plot_lw(survey_ghl, length = \"length\", weight = \"weight\") #> $plot #> #> $text #> [1] \"Logarithm transformed linear length-weight model. Not splitted by sex: \\n a = 0 +/- 0 - 0 (95% CIs). \\n b = 3.221 +/- 3.22 - 3.22 (95% CIs). \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322\" #> #> $params #> # A tibble: 2 × 7 #> term estimate std.error statistic p.value conf.low conf.high #> #> 1 a 0.00000382 0.00491 -2540. 0 0.00000379 0.00000386 #> 2 b 3.22 0.00128 2519. 0 3.22 3.22"},{"path":"/index.html","id":"non-linear-least-square-models","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Non-linear least square models","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Use non-linear least squares instead:","code":"plot_lw(survey_ghl, use.nls = TRUE) #> $plot #> #> $text #> [1] \"Nonlinear least squares length-weight model. Not splitted by sex: \\n a = 0 +/- 0 - 0 (95% CIs). \\n b = 3.419 +/- 3.42 - 3.42 (95% CIs). \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322\" #> #> $params #> # A tibble: 2 × 7 #> term estimate std.error statistic p.value conf.low conf.high #> #> 1 a 0.00000173 0.0000000156 110. 0 0.00000170 0.00000176 #> 2 b 3.42 0.00215 1590. 0 3.42 3.42"},{"path":"/index.html","id":"split-by-sex-2","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"decimal point b estimates depends length weight units. FishBase uses centimeters grams. function can correct units asked (length.unit weight.unit parameters defined correctly). can also transform parameters according formulas given FishBase.","code":"plot_lw(survey_ghl, split.by.sex = TRUE, correct.units = TRUE) #> $plot #> #> $text #> [1] \"Logarithm transformed linear length-weight model for females and males, respectively: \\n a = 0.0035 +/- 0.003 - 0.004 (95% CIs) and 0.0051 +/- 0.005 - 0.005 (95% CIs). \\n b = 3.247 +/- 3.24 - 3.25 (95% CIs) and 3.143 +/- 3.14 - 3.15 (95% CIs). \\n Number of included specimens = 34889 and 30354 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 456891; sex = 96645\" #> #> $params #> # A tibble: 4 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 F a 0.00350 0.00765 -739. 0 0.00344 0.00355 #> 2 F b 3.25 0.00195 1666. 0 3.24 3.25 #> 3 M a 0.00507 0.0101 -525. 0 0.00497 0.00517 #> 4 M b 3.14 0.00265 1188. 0 3.14 3.15 plot_lw(survey_ghl %>% dplyr::mutate(weight = weight*1000), weight.unit = \"g\")$params #> # A tibble: 2 × 7 #> term estimate std.error statistic p.value conf.low conf.high #> #> 1 a 0.00382 0.00491 -1133. 0 0.00379 0.00386 #> 2 b 3.22 0.00128 2519. 0 3.22 3.22"},{"path":"/index.html","id":"log-log-axes-to-see-differences","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Log-log axes to see differences","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"","code":"plot_lw(survey_ghl, split.by.sex = TRUE, log.axes = TRUE)$plot"},{"path":"/index.html","id":"catch-curves-to-estimate-instantaneous-total-mortality-z","dir":"","previous_headings":"Usage","what":"Catch curves to estimate instantaneous total mortality (Z)","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Catch curves added version 0.2.3 may available CRAN version. FishR tutorial written Ogle (2013) contains nice explanation catch curves. time writing ggFishPlots calculates simple log-linearised regression. ages included Z estimation can adjusted using age.range argument. plot , -b Z (.e. Z = 0.356) exp() (.e. 68391) number 0 age fish assuming constant mortality.","code":"plot_catchcurve(survey_ghl) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range .\\n\\nZ = 0.19 (0.123-0.257 95% CIs)\\nN at age 0 = 1448 (449-4674 95% CIs)\\nLongevity = 38.3 years (23.8 - 68.8 95% CIs)\\n\\n\" #> #> $params #> # A tibble: 2 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 both (Intercept) 7.28 0.573 12.7 2.25e-13 6.11 8.45 #> 2 both age -0.190 0.0328 -5.79 2.85e- 6 -0.257 -0.123 plot_catchcurve(survey_ghl, age.range = c(10,26))$plot"},{"path":"/index.html","id":"split-by-sex-3","dir":"","previous_headings":"Usage > Catch curves to estimate instantaneous total mortality (Z)","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Use named list use separate age ranges females males. Parameter estimates catch curve : Instantenous total mortality (Z) estimated using catch curve age range females males. Females: Z = 0.37 (0.31-0.431 95% CIs) N age 0 = 86119 (25990-285354 95% CIs) Longevity = 30.7 years (23.6 - 40.5 95% CIs) Males: Z = 0.511 (0.492-0.53 95% CIs) N age 0 = 145002 (105241-199785 95% CIs) Longevity = 23.3 years (21.8 - 24.8 95% CIs)","code":"plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE)$plot tmp <- plot_catchcurve(survey_ghl, age.range = list(\"F\" = c(13,26), \"M\" = c(10,26)), split.by.sex = TRUE) tmp$plot htmlcat(tmp$text)"},{"path":"/index.html","id":"citations-and-data-sources","dir":"","previous_headings":"","what":"Citations and data sources","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"data used package property Institute Marine Research Norwegian Government. distributed Creative Commons (CCBY NLOD) licenses allowing free use long source (IMR) cited. ask user refer package plots estimates used reports scientific articles. --date citation information, please use:","code":"citation(\"ggFishPlots\") #> #> To cite package 'ggFishPlots' in publications use: #> #> Vihtakari M (2023). _ggFishPlots: Visualise and Calculate Life #> History Parameters for Fisheries Science using 'ggplot2'_. R package #> version 0.2.4, . #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, #> title = {ggFishPlots: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2'}, #> author = {Mikko Vihtakari}, #> year = {2023}, #> note = {R package version 0.2.4}, #> url = {https://deepwaterimr.github.io/ggFishPlots/}, #> }"},{"path":"/index.html","id":"contributions","dir":"","previous_headings":"","what":"Contributions","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"contributions package welcome. Please contact package maintainer Mikko Vihtakari (mikko.vihtakari@hi.) discuss ideas improving package. Bug reports corrections submitted directly GitHub site. Please include minimal reproducible example. Considerable contributions package development credited authorship.","code":""},{"path":"/reference/plot_catchcurve.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot catch curve — plot_catchcurve","title":"Plot catch curve — plot_catchcurve","text":"Plot catch curve estimate instantaneous total mortality (Z) using age data","code":""},{"path":"/reference/plot_catchcurve.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot catch curve — plot_catchcurve","text":"","code":"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\" )"},{"path":"/reference/plot_catchcurve.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot catch curve — plot_catchcurve","text":"dt data.frame, tibble data.table age Character argument giving name age column dt sex Character argument giving name sex column dt. Ignored split..sex == FALSE. time Split analysis time? NULL, data assumed stem one time point. Using character argument giving name time column splits analysis unique values column produces faceted plot. age.range Defines age range used Z estimation. NULL, ages used. numeric vector length 2, first number defines minimum age include last number maximum age. also possible use differing ranges sex split..sex = TRUE: use named list length two names referring female.sex male.sex. Provide numeric vector length 2 element (first number defining minimum age include last number maximum age). See Examples. female.sex character denoting female sex sex column dt male.sex character denoting male sex sex column dt split..sex Logical indicating whether result split sex. base_size Base size parameter ggplot. See ggtheme. legend.position Position ggplot legend character. See ggtheme.","code":""},{"path":"/reference/plot_catchcurve.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Plot catch curve — plot_catchcurve","text":"Calculates plots basic log-linearized catch curve estimate instantaneous mortality. See e.g. Ogle (2013).","code":""},{"path":"/reference/plot_catchcurve.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot catch curve — plot_catchcurve","text":"Mikko Vihtakari // Institute Marine Research.","code":""},{"path":"/reference/plot_catchcurve.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot catch curve — plot_catchcurve","text":"","code":"# Catch curve including all ages data(survey_ghl) plot_catchcurve(survey_ghl) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range .\\n\\nZ = 0.19 (0.123-0.257 95% CIs)\\nN at age 0 = 1448 (449-4674 95% CIs)\\nLongevity = 38.3 years (23.8 - 68.8 95% CIs)\\n\\n\" #> #> $params #> # A tibble: 2 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 both (Intercept) 7.28 0.573 12.7 2.25e-13 6.11 8.45 #> 2 both age -0.190 0.0328 -5.79 2.85e- 6 -0.257 -0.123 #> # \\donttest{ # Specific ages plot_catchcurve(survey_ghl, age.range = c(10,26)) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range 10-26.\\n\\nZ = 0.356 (0.312-0.401 95% CIs)\\nN at age 0 = 68394 (29985-156005 95% CIs)\\nLongevity = 31.2 years (25.7 - 38.3 95% CIs)\\n\\n\" #> #> $params #> # A tibble: 2 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 both (Intercept) 11.1 0.387 28.8 1.54e-14 10.3 12.0 #> 2 both age -0.356 0.0207 -17.2 2.81e-11 -0.401 -0.312 #> # Split by sex plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range 10-26 for both sexes.\\n\\nFemales:\\nZ = 0.31 (0.256-0.365 95% CIs)\\nN at age 0 = 23925 (8625-66368 95% CIs)\\nLongevity = 32.5 years (24.8 - 43.4 95% CIs)\\n\\nMales:\\nZ = 0.511 (0.492-0.53 95% CIs)\\nN at age 0 = 145002 (105241-199785 95% CIs)\\nLongevity = 23.3 years (21.8 - 24.8 95% CIs)\" #> #> $params #> # A tibble: 4 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 F (Intercept) 10.1 0.479 21.1 1.49e-12 9.06 11.1 #> 2 F age -0.310 0.0257 -12.1 3.87e- 9 -0.365 -0.256 #> 3 M (Intercept) 11.9 0.147 80.8 8.62e-18 11.6 12.2 #> 4 M age -0.511 0.00866 -59.0 3.72e-16 -0.530 -0.492 #> # 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 #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range for females and for males.\\n\\nFemales:\\nZ = 0.37 (0.31-0.431 95% CIs)\\nN at age 0 = 86119 (25990-285354 95% CIs)\\nLongevity = 30.7 years (23.6 - 40.5 95% CIs)\\n\\nMales:\\nZ = 0.511 (0.492-0.53 95% CIs)\\nN at age 0 = 145002 (105241-199785 95% CIs)\\nLongevity = 23.3 years (21.8 - 24.8 95% CIs)\" #> #> $params #> # A tibble: 4 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 F (Intercept) 11.4 0.550 20.7 9.51e-11 10.2 12.6 #> 2 F age -0.370 0.0276 -13.4 1.38e- 8 -0.431 -0.310 #> 3 M (Intercept) 11.9 0.147 80.8 8.62e-18 11.6 12.2 #> 4 M age -0.511 0.00866 -59.0 3.72e-16 -0.530 -0.492 #> # }"}] +[{"path":"/authors.html","id":null,"dir":"","previous_headings":"","what":"Authors","title":"Authors and Citation","text":"Mikko Vihtakari. Author, maintainer. Institute Marine Research","code":""},{"path":"/authors.html","id":"citation","dir":"","previous_headings":"","what":"Citation","title":"Authors and Citation","text":"Vihtakari M (2024). ggFishPlots: Visualise Calculate Life History Parameters Fisheries Science using 'ggplot2'. R package version 0.2.7, https://deepwaterimr.github.io/ggFishPlots/.","code":"@Manual{, title = {ggFishPlots: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2'}, author = {Mikko Vihtakari}, year = {2024}, note = {R package version 0.2.7}, url = {https://deepwaterimr.github.io/ggFishPlots/}, }"},{"path":"/index.html","id":"ggfishplots","dir":"","previous_headings":"","what":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Visualise calculate life history parameters fisheries science using ggplot2. R package version 0.2.7","code":""},{"path":"/index.html","id":"overview","dir":"","previous_headings":"","what":"Overview","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"ggFishPlots package R allows quickly plotting calculating life history parameters required stock assessment models. package uses ggplot2 plotting tidyverse packages calculations. ggOceanMaps package developed Institute Marine Research. Note package comes absolutely warranty. bug reports code fixes warmly welcomed. See Contributions details. looking similar packages, make sure check AquaticLifeHistory, FSA, fishmethods packages, well FishR webpage.","code":""},{"path":"/index.html","id":"installation","dir":"","previous_headings":"","what":"Installation","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"date version package can always found GitHub. CRAN version work shown examples website, try installing GitHub version. can using devtools remotes packages.","code":"remotes::install_github(\"DeepWaterIMR/ggFishPlots\")"},{"path":"/index.html","id":"usage","dir":"","previous_headings":"","what":"Usage","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"package website. time writing, package produces four kinds plots: growth curves, maturity plots, length-weight relationships, catch curves. function returns ggplot2 plot estimated parameters text string can used Rmarkdown Shiny applications well data frame use parameters. elements returned list. package contains example data illustrate functionality.","code":""},{"path":"/index.html","id":"growth-curves","dir":"","previous_headings":"Usage","what":"Growth curves","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Note text params returned list together plot. text object can rendered R markdown documents using results = 'asis' setting code chunk header (.e. {r, results = 'asis'}) cat() function replacing \"\\n\" \"\\ n\": von Bertalanffy growth function coefficients: Linf (asymptotic average length) = 91.2 cm +/- 88.3 - 94.6 (95% CIs) K (growth rate coefficient) = 0.0633 +/- 0.059 - 0.068 (95% CIs) t0 (age length 0) = -3.04 (years) +/- -3.337 - -2.769 (95% CIs) tmax (life span; t0 + 3/K) = 44.4 years Number included specimens = 10401 Total number measured = 618779 Excluded (length age missing): Length = 0; age = 608378","code":"library(ggFishPlots) data(survey_ghl) # example data head(survey_ghl) #> # A tibble: 6 × 5 #> age sex length weight maturity #> #> 1 NA 35 NA 0 #> 2 NA 43 NA 0 #> 3 NA 51 NA 0 #> 4 NA 31 NA 0 #> 5 NA 32 NA 0 #> 6 NA 32 NA 0 plot_growth(survey_ghl, length = \"length\", age = \"age\") #> $plot #> #> $text #> [1] \"von Bertalanffy growth function coefficients: \\n Linf (asymptotic average length) = 91.2 cm +/- 88.3 - 94.6 (95% CIs) \\n K (growth rate coefficient) = 0.0633 +/- 0.059 - 0.068 (95% CIs) \\n t0 (age at length 0) = -3.04 (years) +/- -3.337 - -2.769 (95% CIs) \\n tmax (life span; t0 + 3/K) = 44.4 years \\n Number of included specimens = 10401 \\n Total number of measured = 618779 \\n Excluded (length or age missing): \\n Length = 0; age = 608378\" #> #> $params #> # A tibble: 3 × 7 #> term estimate std.error statistic p.value conf.low conf.high #> #> 1 Sinf 91.2 1.51 60.3 0 88.3 94.6 #> 2 K 0.0633 0.00231 27.4 4.90e-160 0.0586 0.0680 #> 3 t0 -3.04 0.139 -21.8 1.71e-103 -3.34 -2.77 htmlcat <- function(text){ cat(gsub(pattern = \"\\n\", replacement = \" \\n\", x = text)) } htmlcat(plot_growth(survey_ghl)$text)"},{"path":"/index.html","id":"split-by-sex","dir":"","previous_headings":"Usage > Growth curves","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Specifying length, age sex arguments omitted since argument names default example data. plot element returned time. dashed lines Sinf. Data behind growth curves shown box plots default. possible plot data points defining boxplot = FALSE. can also force zero group curves know length . Assumed 14 cm . Zero group forcing strength 10 % number observations default can adjusted using force.zero.group.strength argument.","code":"plot_growth(survey_ghl, split.by.sex = TRUE)$plot plot_growth(survey_ghl, force.zero.group.length = 14, boxplot = FALSE)$plot"},{"path":[]},{"path":"/index.html","id":"l50-plots","dir":"","previous_headings":"Usage > Maturity plots","what":"L50 plots","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Maturity ogives estimated using logistic (family = binomial(link = \"logit\")) glm() error bars represent 95% confidence intervals calculated model object using confint() function back-transformed original scale. grey stepped line binned average defined using length.bin.width argument. function also contains option bootstrap confidence intervals (CIs) produce narrower CIs. Bootstrapping probably correct way estimating CIs application. Using 10 replicates save processing time. real application use least 1000.","code":"plot_maturity(survey_ghl, length = \"length\", maturity = \"maturity\") #> $plot #> #> $text #> [1] \"50% maturity at length (L50) based on logit regressions:\\n54.784 cm. 95% confidence intervals: 52.852 - 56.787\\n Number of specimens: 64265.\\n Confidence intervals estimated from the glm object.\" #> #> $params #> mean ci.min ci.max sex intercept slope n #> 1 54.78361 52.85249 56.787 both -5.755492 0.1050587 64265 plot_maturity(survey_ghl, bootstrap.n = 10) #> $plot #> #> $text #> [1] \"50% maturity at length (L50) based on logit regressions:\\n54.783 cm. 95% confidence intervals: 54.604 - 54.932\\n Number of specimens: 64265\\n\\n Confidence intervals estimated using 10 bootstrap replicates.\" #> #> $params #> mean ci.min ci.max sex intercept slope n #> 1 54.78312 54.60357 54.93155 both -5.755492 0.1050587 64265"},{"path":"/index.html","id":"split-by-sex-1","dir":"","previous_headings":"Usage > Maturity plots","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"","code":"plot_maturity(survey_ghl, split.by.sex = TRUE)$plot"},{"path":"/index.html","id":"a50-plots","dir":"","previous_headings":"Usage > Maturity plots","what":"A50 plots","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"principle can used produce A50 (50% maturity age) plots:","code":"plot_maturity(survey_ghl, length = \"age\", length.unit = \"years\", xlab = \"Age\", length.bin.width = 1, split.by.sex = TRUE)$plot"},{"path":"/index.html","id":"addition-of-juveniles","dir":"","previous_headings":"Usage > Maturity plots","what":"Addition of juveniles","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Also plot_maturity() function option add juveniles (zero group fish). addition juveniles can necessary make glm() converge small immature fish scarce dataset. Note addition increases estimate males dataset contain sufficient number young males number females seems sufficient females mature older species. One option can estimate number added juveniles using plot_catchcurve() function:","code":"plot_maturity(survey_ghl, length = \"age\", length.unit = \"years\", xlab = \"Age\", length.bin.width = 1, force.zero.group.length = 0, force.zero.group.strength = 100, split.by.sex = TRUE)$plot plot_maturity(survey_ghl, length = \"age\", length.unit = \"years\", xlab = \"Age\", length.bin.width = 1, force.zero.group.length = 0, force.zero.group.n = c(\"F\" = exp(11.363), \"M\" = exp(11.885)), split.by.sex = TRUE)$plot"},{"path":[]},{"path":"/index.html","id":"log-linearized-models","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Log-linearized models","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Simple plot using log-transformation linear models default. dashed lines represent 95% confidence intervals.","code":"plot_lw(survey_ghl, length = \"length\", weight = \"weight\") #> $plot #> #> $text #> [1] \"Logarithm transformed linear length-weight model. Not splitted by sex: \\n a = 3.8236e-06 +/- 3.7869e-06 - 3.8606e-06 (95% CIs). \\n b = 3.221 +/- 3.22 - 3.22 (95% CIs). \\n Length in cm and weight in kg \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322; outlier = 0\" #> #> $params #> # A tibble: 2 × 14 #> term estimate std.error statistic p.value conf.low conf.high r.squared #> #> 1 a 0.00000382 0.00491 -2540. 0 0.00000379 0.00000386 0.989 #> 2 b 3.22 0.00128 2519. 0 3.22 3.22 0.989 #> # ℹ 6 more variables: AIC , nobs , length , length.unit , #> # weight , weight.unit "},{"path":"/index.html","id":"non-linear-least-square-models","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Non-linear least square models","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Use non-linear least squares instead:","code":"plot_lw(survey_ghl, use.nls = TRUE) #> $plot #> #> $text #> [1] \"Nonlinear least squares length-weight model. Not splitted by sex: \\n a = 1.7268e-06 +/- 1.6962e-06 - 1.758e-06 (95% CIs). \\n b = 3.419 +/- 3.42 - 3.42 (95% CIs). \\n Length in cm and weight in kg \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322; outlier = 0\" #> #> $params #> # A tibble: 2 × 13 #> term estimate std.error statistic p.value conf.low conf.high AIC nobs #> #> 1 a 0.00000173 1.56e-8 110. 0 1.70e-6 1.76e-6 -27925. 67457 #> 2 b 3.42 2.15e-3 1590. 0 3.42e+0 3.42e+0 -27925. 67457 #> # ℹ 4 more variables: length , length.unit , weight , #> # weight.unit "},{"path":"/index.html","id":"split-by-sex-2","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"decimal point b estimates depends length weight units. FishBase uses centimeters grams. function can correct units asked (length.unit weight.unit parameters defined correctly). can also transform parameters according formulas given FishBase.","code":"plot_lw(survey_ghl, split.by.sex = TRUE, correct.units = TRUE) #> $plot #> #> $text #> [1] \"Logarithm transformed linear length-weight model for females and males, respectively: \\n a = 0.0035 +/- 0.00344 - 0.00355 (95% CIs) and 0.00507 +/- 0.00497 - 0.00517 (95% CIs). \\n b = 3.247 +/- 3.24 - 3.25 (95% CIs) and 3.143 +/- 3.14 - 3.15 (95% CIs). \\n Length in cm and weight in g \\n Number of included specimens = 34889 and 30354 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 456891; sex = 96645; outlier = 0\" #> #> $params #> # A tibble: 4 × 15 #> # Groups: sex [2] #> sex term estimate std.error statistic p.value conf.low conf.high r.squared #> #> 1 F a 0.00350 0.00765 -739. 0 0.00344 0.00355 0.988 #> 2 F b 3.25 0.00195 1666. 0 3.24 3.25 0.988 #> 3 M a 0.00507 0.0101 -525. 0 0.00497 0.00517 0.979 #> 4 M b 3.14 0.00265 1188. 0 3.14 3.15 0.979 #> # ℹ 6 more variables: AIC , nobs , length , length.unit , #> # weight , weight.unit plot_lw(survey_ghl %>% dplyr::mutate(weight = weight*1000), weight.unit = \"g\")$params #> # A tibble: 2 × 14 #> term estimate std.error statistic p.value conf.low conf.high r.squared #> #> 1 a 0.00382 0.00491 -1133. 0 0.00379 0.00386 0.989 #> 2 b 3.22 0.00128 2519. 0 3.22 3.22 0.989 #> # ℹ 6 more variables: AIC , nobs , length , length.unit , #> # weight , weight.unit "},{"path":"/index.html","id":"log-log-axes-to-see-differences","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Log-log axes to see differences","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"","code":"plot_lw(survey_ghl, split.by.sex = TRUE, log.axes = TRUE)$plot"},{"path":"/index.html","id":"outlier-removal","dir":"","previous_headings":"Usage > Length-weight relationships","what":"Outlier removal","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"","code":"plot_lw(survey_ghl, outlier.percentile = 99.5, annotate.coefficients = TRUE)$plot"},{"path":"/index.html","id":"catch-curves-to-estimate-instantaneous-total-mortality-z","dir":"","previous_headings":"Usage","what":"Catch curves to estimate instantaneous total mortality (Z)","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Catch curves added version 0.2.3 may available CRAN version. FishR tutorial written Ogle (2013) contains nice explanation catch curves. time writing ggFishPlots calculates simple log-linearised regression. ages included Z estimation can adjusted using age.range argument. plot , -b Z (.e. Z = 0.356) exp() (.e. 68391) number 0 age fish assuming constant mortality.","code":"plot_catchcurve(survey_ghl) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range .\\n\\nZ = 0.19 (0.123-0.257 95% CIs)\\nN at age 0 = 1448 (449-4674 95% CIs)\\nLongevity = 38.3 years (23.8 - 68.8 95% CIs)\\n\\n\" #> #> $params #> # A tibble: 2 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 both (Intercept) 7.28 0.573 12.7 2.25e-13 6.11 8.45 #> 2 both age -0.190 0.0328 -5.79 2.85e- 6 -0.257 -0.123 plot_catchcurve(survey_ghl, age.range = c(10,26))$plot"},{"path":"/index.html","id":"split-by-sex-3","dir":"","previous_headings":"Usage > Catch curves to estimate instantaneous total mortality (Z)","what":"Split by sex","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"Use named list use separate age ranges females males. Parameter estimates catch curve : Instantenous total mortality (Z) estimated using catch curve age range females males. Females: Z = 0.37 (0.31-0.431 95% CIs) N age 0 = 86119 (25990-285354 95% CIs) Longevity = 30.7 years (23.6 - 40.5 95% CIs) Males: Z = 0.511 (0.492-0.53 95% CIs) N age 0 = 145002 (105241-199785 95% CIs) Longevity = 23.3 years (21.8 - 24.8 95% CIs)","code":"plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE)$plot tmp <- plot_catchcurve(survey_ghl, age.range = list(\"F\" = c(13,26), \"M\" = c(10,26)), split.by.sex = TRUE) tmp$plot htmlcat(tmp$text)"},{"path":"/index.html","id":"citations-and-data-sources","dir":"","previous_headings":"","what":"Citations and data sources","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"data used package property Institute Marine Research Norwegian Government. distributed Creative Commons (CCBY NLOD) licenses allowing free use long source (IMR) cited. ask user refer package plots estimates used reports scientific articles. --date citation information, please use:","code":"citation(\"ggFishPlots\") #> To cite package 'ggFishPlots' in publications use: #> #> Vihtakari M (2024). _ggFishPlots: Visualise and Calculate Life #> History Parameters for Fisheries Science using 'ggplot2'_. R package #> version 0.2.7, . #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, #> title = {ggFishPlots: Visualise and Calculate Life History Parameters for Fisheries Science using 'ggplot2'}, #> author = {Mikko Vihtakari}, #> year = {2024}, #> note = {R package version 0.2.7}, #> url = {https://deepwaterimr.github.io/ggFishPlots/}, #> }"},{"path":"/index.html","id":"contributions","dir":"","previous_headings":"","what":"Contributions","title":"Visualise and Calculate Life History Parameters for Fisheries Science using ggplot2","text":"contributions package welcome. Please contact package maintainer Mikko Vihtakari (mikko.vihtakari@hi.) discuss ideas improving package. Bug reports corrections submitted directly GitHub site. Please include minimal reproducible example. Considerable contributions package development credited authorship.","code":""},{"path":"/reference/plot_catchcurve.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot catch curve — plot_catchcurve","title":"Plot catch curve — plot_catchcurve","text":"Plot catch curve estimate instantaneous total mortality (Z) using age data","code":""},{"path":"/reference/plot_catchcurve.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot catch curve — plot_catchcurve","text":"","code":"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\" )"},{"path":"/reference/plot_catchcurve.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot catch curve — plot_catchcurve","text":"dt data.frame, tibble data.table age Character argument giving name age column dt sex Character argument giving name sex column dt. Ignored split..sex == FALSE. time Split analysis time? NULL, data assumed stem one time point. Using character argument giving name time column splits analysis unique values column produces faceted plot. age.range Defines age range used Z estimation. NULL, ages used. numeric vector length 2, first number defines minimum age include last number maximum age. also possible use differing ranges sex split..sex = TRUE: use named list length two names referring female.sex male.sex. Provide numeric vector length 2 element (first number defining minimum age include last number maximum age). See Examples. female.sex, male.sex character integer denoting female male sex sex column dt, respectively. split..sex Logical indicating whether result split sex. base_size Base size parameter ggplot. See ggtheme. legend.position Position ggplot legend character. See ggtheme.","code":""},{"path":"/reference/plot_catchcurve.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Plot catch curve — plot_catchcurve","text":"Calculates plots basic log-linearized catch curve estimate instantaneous mortality. See e.g. Ogle (2013).","code":""},{"path":"/reference/plot_catchcurve.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot catch curve — plot_catchcurve","text":"Mikko Vihtakari // Institute Marine Research.","code":""},{"path":"/reference/plot_catchcurve.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot catch curve — plot_catchcurve","text":"","code":"# Catch curve including all ages data(survey_ghl) plot_catchcurve(survey_ghl) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range .\\n\\nZ = 0.19 (0.123-0.257 95% CIs)\\nN at age 0 = 1448 (449-4674 95% CIs)\\nLongevity = 38.3 years (23.8 - 68.8 95% CIs)\\n\\n\" #> #> $params #> # A tibble: 2 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 both (Intercept) 7.28 0.573 12.7 2.25e-13 6.11 8.45 #> 2 both age -0.190 0.0328 -5.79 2.85e- 6 -0.257 -0.123 #> # \\donttest{ # Specific ages plot_catchcurve(survey_ghl, age.range = c(10,26)) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range 10-26.\\n\\nZ = 0.356 (0.312-0.401 95% CIs)\\nN at age 0 = 68394 (29985-156005 95% CIs)\\nLongevity = 31.2 years (25.7 - 38.3 95% CIs)\\n\\n\" #> #> $params #> # A tibble: 2 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 both (Intercept) 11.1 0.387 28.8 1.54e-14 10.3 12.0 #> 2 both age -0.356 0.0207 -17.2 2.81e-11 -0.401 -0.312 #> # Split by sex plot_catchcurve(survey_ghl, age.range = c(10,26), split.by.sex = TRUE) #> $plot #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range 10-26 for both sexes.\\n\\nFemales:\\nZ = 0.31 (0.256-0.365 95% CIs)\\nN at age 0 = 23925 (8625-66368 95% CIs)\\nLongevity = 32.5 years (24.8 - 43.4 95% CIs)\\n\\nMales:\\nZ = 0.511 (0.492-0.53 95% CIs)\\nN at age 0 = 145002 (105241-199785 95% CIs)\\nLongevity = 23.3 years (21.8 - 24.8 95% CIs)\" #> #> $params #> # A tibble: 4 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 F (Intercept) 10.1 0.479 21.1 1.49e-12 9.06 11.1 #> 2 F age -0.310 0.0257 -12.1 3.87e- 9 -0.365 -0.256 #> 3 M (Intercept) 11.9 0.147 80.8 8.62e-18 11.6 12.2 #> 4 M age -0.511 0.00866 -59.0 3.72e-16 -0.530 -0.492 #> # 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 #> #> $text #> [1] \"Instantenous total mortality (Z) estimated using a catch curve and\\nage range for females and for males.\\n\\nFemales:\\nZ = 0.37 (0.31-0.431 95% CIs)\\nN at age 0 = 86119 (25990-285354 95% CIs)\\nLongevity = 30.7 years (23.6 - 40.5 95% CIs)\\n\\nMales:\\nZ = 0.511 (0.492-0.53 95% CIs)\\nN at age 0 = 145002 (105241-199785 95% CIs)\\nLongevity = 23.3 years (21.8 - 24.8 95% CIs)\" #> #> $params #> # A tibble: 4 × 8 #> sex term estimate std.error statistic p.value conf.low conf.high #> #> 1 F (Intercept) 11.4 0.550 20.7 9.51e-11 10.2 12.6 #> 2 F age -0.370 0.0276 -13.4 1.38e- 8 -0.431 -0.310 #> 3 M (Intercept) 11.9 0.147 80.8 8.62e-18 11.6 12.2 #> 4 M age -0.511 0.00866 -59.0 3.72e-16 -0.530 -0.492 #> # }"},{"path":"/reference/plot_growth.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot age-length relationships and growth curves — plot_growth","title":"Plot age-length relationships and growth curves — plot_growth","text":"Plot age-length relationships growth curves","code":""},{"path":"/reference/plot_growth.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot age-length relationships and growth curves — plot_growth","text":"","code":"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\" )"},{"path":"/reference/plot_growth.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot age-length relationships and growth curves — plot_growth","text":"dt data.frame, tibble data.table length Character argument giving name length column dt age Character argument giving name age column dt sex Character argument giving name sex column dt. Ignored split..sex == FALSE. female.sex, male.sex character integer denoting female male sex sex column dt, respectively. length.unit character argument giving unit length. used labels figure. split..sex Logical indicating whether result split sex. growth.model Integer defining growth model. 1 = von Bertalanffy, 2 = Gompertz, 3 = Logistic. force.zero.group.length Numeric indicating length 0-group forced. Use NA ignore forcing. force.zero.group.strength Numeric indicating many percent total fish added specified force.zero.group.length. force.zero.group.cv Numeric indicating coefficient variation forced 0-group length. Resulting lengths randomly generated normal distribution. show.Linf Logical indicating whether Linf values shown dashed vertical lines. boxplot Logical indicating whether boxplots (TRUE) used show data points (FALSE) base_size Base size parameter ggplot. See ggtheme. legend.position Position ggplot legend character. See ggtheme.","code":""},{"path":"/reference/plot_growth.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot age-length relationships and growth curves — plot_growth","text":"list containing plot, text Rmarkdown Shiny applications, estimated parameters (params).","code":""},{"path":"/reference/plot_growth.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Plot age-length relationships and growth curves — plot_growth","text":"Uses fishmethods::growth function calculate growth curves. Zero group length can forced growth functions using force.zero.group.* parameters.","code":""},{"path":"/reference/plot_growth.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot age-length relationships and growth curves — plot_growth","text":"Mikko Vihtakari // Institute Marine Research.","code":""},{"path":"/reference/plot_growth.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot age-length relationships and growth curves — plot_growth","text":"","code":"# Simple plot. Note that a list is returned. data(survey_ghl) plot_growth(survey_ghl, length = \"length\", age = \"age\") #> $plot #> #> $text #> [1] \"von Bertalanffy growth function coefficients: \\n Linf (asymptotic average length) = 91.2 cm +/- 88.3 - 94.6 (95% CIs) \\n K (growth rate coefficient) = 0.0633 +/- 0.059 - 0.068 (95% CIs) \\n t0 (age at length 0) = -3.04 (years) +/- -3.337 - -2.769 (95% CIs) \\n tmax (life span; t0 + 3/K) = 44.4 years \\n Number of included specimens = 10401 \\n Total number of measured = 618779 \\n Excluded (length or age missing): \\n Length = 0; age = 608378\" #> #> $params #> # A tibble: 3 × 7 #> term estimate std.error statistic p.value conf.low conf.high #> #> 1 Sinf 91.2 1.51 60.3 0 88.3 94.6 #> 2 K 0.0633 0.00231 27.4 4.90e-160 0.0586 0.0680 #> 3 t0 -3.04 0.139 -21.8 1.71e-103 -3.34 -2.77 #> # \\donttest{ # 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 # }"},{"path":"/reference/plot_lw.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot length-weight relationships — plot_lw","title":"Plot length-weight relationships — plot_lw","text":"Plots length-weight relationship species calculates b coefficients used length-weight conversions.","code":""},{"path":"/reference/plot_lw.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot length-weight relationships — plot_lw","text":"","code":"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 )"},{"path":"/reference/plot_lw.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot length-weight relationships — plot_lw","text":"dt data.frame, tibble data.table length Character argument giving name length column dt weight Character argument giving name age column dt sex Character argument giving name sex column dt. Ignored split..sex == FALSE. female.sex, male.sex character integer denoting female male sex sex column dt, respectively. length.unit Character argument giving unit length. used labels figure conversion coefficient. Allowed values conversion: \"mm\" (millimeters), \"cm\" (centimeters), \"m\" (meters). weight.unit Character argument giving unit weight. used labels figure conversion coefficient. Allowed values: \"g\" (grams), \"kg\" (kilograms), \"t\" (metric tons). split..sex Logical indicating whether result split sex. xlab Character giving x-axis label without unit ylab Character giving x-axis label without unit. use.nls Logical indicating whether parameters estimated using nonlinear least squares (nls; TRUE) method log-log transformed linear model (lm; FALSE) method. See details. init., init.b Numeric values giving starting value b coefficients respectively non-linear least-squares estimation (.e. use.nls = TRUE). NULL (default) starting values guessed. log.axes Logical indicating whether logarithmic axes used instead Cartesian ones. outlier.percentile Numeric argument giving probability percent value used calculate residual quantiles outlier removal. See details. Values > 99 recommended. NULL (default), outlier removal conducted. annotate.coefficients Logical indicating whether b coefficients annotated plot. correct.units Logical indicating whether b coefficients converted centimeters grams FishBase. base_size Base size parameter ggplot. See ggtheme. legend.position Position ggplot legend character. See ggtheme. point.size Numeric defining size data points plot. See size argument geom_point. verbose Logical indicating whether return warnings messages.","code":""},{"path":"/reference/plot_lw.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot length-weight relationships — plot_lw","text":"list three elements: ggplot object containing plot, text giving central statistics can pasted Markdown, model parameters (params).","code":""},{"path":"/reference/plot_lw.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Plot length-weight relationships — plot_lw","text":"function estimates b coefficients length weight relationship, \\(weight = \\times length^b\\), plots data. model can fitted either using standard log(weight) ~ log(length) regression (lm; default) nonlinear least squares (nls) method. nls method often manages fit steeper slopes making b parameter higher parameter lower linear lm method. tends lead visually pleasing fits high lengths weights. b coefficients dependent units length weight. models, length weight units often match data going model, comparisons FishBase, units length weight centimeters grams, respectively. units wrong, intercept, , FishBase scale orders magnitude (see FishBase). correct.units can used correct data units FishBase standard (cm g). function also returns warning returned parameters within expected bounds cm g estimation. recommended compare b coefficients FishBase species quality assurance. outlier.percentile argument enables quick removal troublesome outliers model estimation. argument defined percentile probabilities used calculate quantile absolute residual values logarithmic regression identify outliers (\\(outlier = |r| > Pr[|r| > outlier.percentile/100]\\)). outliers removed model dataset plotted using crosses ggplot output. See Examples.","code":""},{"path":"/reference/plot_lw.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot length-weight relationships — plot_lw","text":"Mikko Vihtakari // Institute Marine Research.","code":""},{"path":"/reference/plot_lw.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot length-weight relationships — plot_lw","text":"","code":"data(survey_ghl) # Simple plot plot_lw(survey_ghl, length = \"length\", weight = \"weight\") #> $plot #> #> $text #> [1] \"Logarithm transformed linear length-weight model. Not splitted by sex: \\n a = 3.8236e-06 +/- 3.7869e-06 - 3.8606e-06 (95% CIs). \\n b = 3.221 +/- 3.22 - 3.22 (95% CIs). \\n Length in cm and weight in kg \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322; outlier = 0\" #> #> $params #> # A tibble: 2 × 14 #> term estimate std.error statistic p.value conf.low conf.high r.squared #> #> 1 a 0.00000382 0.00491 -2540. 0 0.00000379 0.00000386 0.989 #> 2 b 3.22 0.00128 2519. 0 3.22 3.22 0.989 #> # ℹ 6 more variables: AIC , nobs , length , length.unit , #> # weight , weight.unit #> # \\donttest{ # nls plot_lw(survey_ghl, use.nls = TRUE) #> $plot #> #> $text #> [1] \"Nonlinear least squares length-weight model. Not splitted by sex: \\n a = 1.7268e-06 +/- 1.6962e-06 - 1.758e-06 (95% CIs). \\n b = 3.419 +/- 3.42 - 3.42 (95% CIs). \\n Length in cm and weight in kg \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322; outlier = 0\" #> #> $params #> # A tibble: 2 × 13 #> term estimate std.error statistic p.value conf.low conf.high AIC nobs #> #> 1 a 0.00000173 1.56e-8 110. 0 1.70e-6 1.76e-6 -27925. 67457 #> 2 b 3.42 2.15e-3 1590. 0 3.42e+0 3.42e+0 -27925. 67457 #> # ℹ 4 more variables: length , length.unit , weight , #> # weight.unit #> # 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 #> #> $text #> [1] \"Logarithm transformed linear length-weight model. Not splitted by sex: \\n a = 3.74e-06 +/- 3.7064e-06 - 3.7738e-06 (95% CIs). \\n b = 3.227 +/- 3.22 - 3.23 (95% CIs). \\n Length in cm and weight in kg \\n Number of included specimens = 67457 \\n Total number of measured = 618779 \\n Excluded (data missing): \\n Length = 0; weight = 551322; outlier = 675\" #> #> $params #> # A tibble: 2 × 14 #> term estimate std.error statistic p.value conf.low conf.high r.squared #> #> 1 a 0.00000374 0.00460 -2717. 0 0.00000371 0.00000377 0.991 #> 2 b 3.23 0.00120 2697. 0 3.22 3.23 0.991 #> # ℹ 6 more variables: AIC , nobs , length , length.unit , #> # weight , weight.unit #> # }"},{"path":"/reference/plot_maturity.html","id":null,"dir":"Reference","previous_headings":"","what":"Plot maturity ogive — plot_maturity","title":"Plot maturity ogive — plot_maturity","text":"Plots estimate length age 50% mature dataset","code":""},{"path":"/reference/plot_maturity.html","id":"ref-usage","dir":"Reference","previous_headings":"","what":"Usage","title":"Plot maturity ogive — plot_maturity","text":"","code":"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\", ... )"},{"path":"/reference/plot_maturity.html","id":"arguments","dir":"Reference","previous_headings":"","what":"Arguments","title":"Plot maturity ogive — plot_maturity","text":"dt data.frame, tibble data.table length Character argument giving name length (age) column dt maturity Character argument giving name maturity column dt. either logical (TRUE == mature, FALSE == immature) integer (1 == mature, 0 == immature). sex Character argument giving name sex column dt. Ignored split..sex == FALSE. split..sex Logical indicating whether result split sex. female.sex, male.sex character integer denoting female male sex sex column dt, respectively. length.unit character argument giving unit length. used labels figure. length.bin.width Numeric specifying increment (delta length) length data binned calculate maturity proportions. Use NULL remove plot. bootstrap.n Integer defining number bootstrap replicates used calculate 95% confidence intervals mean 50% mature estimate. NA (default), confidence intervals calculated glm object without boostrapping. See Details. force.zero.group.length Numeric indicating length 0-group (immatures) forced. Use NA ignore forcing. force.zero.group.strength Numeric indicating many percent total fish added specified force.zero.group.length. used simultaneously force.zero.group.n force.zero.group.n Numeric indicating many observations added specified force.zero.group.length. split..sex = TRUE, use named vector length two names referring female.sex male.sex. used simultaneously force.zero.group.strength force.zero.group.cv Numeric indicating coefficient variation forced 0-group (immature) length. Resulting lengths randomly generated normal distribution. xlab Character giving x-axis label without unit base_size Base size parameter ggplot. See ggtheme. legend.position Position ggplot legend character. See ggtheme. ... Additional arguments passed geom_density_ridges.","code":""},{"path":"/reference/plot_maturity.html","id":"value","dir":"Reference","previous_headings":"","what":"Value","title":"Plot maturity ogive — plot_maturity","text":"Returns ggplot2 tibble depending plot argument showing maturity ogives.","code":""},{"path":"/reference/plot_maturity.html","id":"details","dir":"Reference","previous_headings":"","what":"Details","title":"Plot maturity ogive — plot_maturity","text":"95% confidence intervals mean 50% mature estimate calculated using glm function default. routine might optimal zero group fish added. Hence, function contains option bootstrap confidence intervals using number data observations (.e. excluding added data number randomly resampled rows). Adding integer bootstrap.n argument turns feature. Note confidence intervals calculated way tend narrower glm() confidence intervals.","code":""},{"path":"/reference/plot_maturity.html","id":"author","dir":"Reference","previous_headings":"","what":"Author","title":"Plot maturity ogive — plot_maturity","text":"Mikko Vihtakari // Institute Marine Research.","code":""},{"path":"/reference/plot_maturity.html","id":"ref-examples","dir":"Reference","previous_headings":"","what":"Examples","title":"Plot maturity ogive — plot_maturity","text":"","code":"# Simple L50 plot data(survey_ghl) plot_maturity(survey_ghl, length = \"length\", maturity = \"maturity\") #> Warning: Ignoring unknown parameters: `size` #> $plot #> Picking joint bandwidth of 1.21 #> #> $text #> [1] \"50% maturity at length (L50) based on logit regressions:\\n54.784 cm. 95% confidence intervals: 52.852 - 56.787\\n Number of specimens: 64265.\\n Confidence intervals estimated from the glm object.\" #> #> $params #> mean ci.min ci.max sex intercept slope n #> 1 54.78361 52.85249 56.787 both -5.755492 0.1050587 64265 #> # \\donttest{ # Bootstrapped CIs are narrower than the glm ones plot_maturity(survey_ghl, bootstrap.n = 10) #> Warning: Ignoring unknown parameters: `size` #> $plot #> Picking joint bandwidth of 1.21 #> #> $text #> [1] \"50% maturity at length (L50) based on logit regressions:\\n54.793 cm. 95% confidence intervals: 54.706 - 54.884\\n Number of specimens: 64265\\n\\n Confidence intervals estimated using 10 bootstrap replicates.\" #> #> $params #> mean ci.min ci.max sex intercept slope n #> 1 54.79348 54.70635 54.8836 both -5.755492 0.1050587 64265 #> # 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 #> Picking joint bandwidth of 0.602 # 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 #> Picking joint bandwidth of 0.638 # }"}] diff --git a/man/figures/README-unnamed-chunk-10-1.png b/man/figures/README-unnamed-chunk-10-1.png index 11738da..de1deeb 100644 Binary files a/man/figures/README-unnamed-chunk-10-1.png and b/man/figures/README-unnamed-chunk-10-1.png differ diff --git a/man/figures/README-unnamed-chunk-11-1.png b/man/figures/README-unnamed-chunk-11-1.png index c738442..38deb1a 100644 Binary files a/man/figures/README-unnamed-chunk-11-1.png and b/man/figures/README-unnamed-chunk-11-1.png differ diff --git a/man/figures/README-unnamed-chunk-12-1.png b/man/figures/README-unnamed-chunk-12-1.png index 6ae5b46..58eaf8c 100644 Binary files a/man/figures/README-unnamed-chunk-12-1.png and b/man/figures/README-unnamed-chunk-12-1.png differ diff --git a/man/figures/README-unnamed-chunk-15-1.png b/man/figures/README-unnamed-chunk-15-1.png index a90eaa9..82fa412 100644 Binary files a/man/figures/README-unnamed-chunk-15-1.png and b/man/figures/README-unnamed-chunk-15-1.png differ diff --git a/man/figures/README-unnamed-chunk-17-1.png b/man/figures/README-unnamed-chunk-17-1.png index 126dfe7..9aa86cd 100644 Binary files a/man/figures/README-unnamed-chunk-17-1.png and b/man/figures/README-unnamed-chunk-17-1.png differ diff --git a/man/figures/README-unnamed-chunk-18-1.png b/man/figures/README-unnamed-chunk-18-1.png index 3160178..afb18dc 100644 Binary files a/man/figures/README-unnamed-chunk-18-1.png and b/man/figures/README-unnamed-chunk-18-1.png differ diff --git a/man/figures/README-unnamed-chunk-19-1.png b/man/figures/README-unnamed-chunk-19-1.png index 272044e..3160178 100644 Binary files a/man/figures/README-unnamed-chunk-19-1.png and b/man/figures/README-unnamed-chunk-19-1.png differ diff --git a/man/figures/README-unnamed-chunk-20-1.png b/man/figures/README-unnamed-chunk-20-1.png index d8ee5aa..272044e 100644 Binary files a/man/figures/README-unnamed-chunk-20-1.png and b/man/figures/README-unnamed-chunk-20-1.png differ diff --git a/man/figures/README-unnamed-chunk-21-1.png b/man/figures/README-unnamed-chunk-21-1.png index 9fbf153..d8ee5aa 100644 Binary files a/man/figures/README-unnamed-chunk-21-1.png and b/man/figures/README-unnamed-chunk-21-1.png differ diff --git a/man/figures/README-unnamed-chunk-22-1.png b/man/figures/README-unnamed-chunk-22-1.png new file mode 100644 index 0000000..9fbf153 Binary files /dev/null and b/man/figures/README-unnamed-chunk-22-1.png differ diff --git a/man/figures/README-unnamed-chunk-5-1.png b/man/figures/README-unnamed-chunk-5-1.png index e76de10..8701907 100644 Binary files a/man/figures/README-unnamed-chunk-5-1.png and b/man/figures/README-unnamed-chunk-5-1.png differ diff --git a/man/figures/README-unnamed-chunk-7-1.png b/man/figures/README-unnamed-chunk-7-1.png index 9e24668..51a8fa8 100644 Binary files a/man/figures/README-unnamed-chunk-7-1.png and b/man/figures/README-unnamed-chunk-7-1.png differ diff --git a/man/figures/README-unnamed-chunk-8-1.png b/man/figures/README-unnamed-chunk-8-1.png index 261a6e5..9d1f4ba 100644 Binary files a/man/figures/README-unnamed-chunk-8-1.png and b/man/figures/README-unnamed-chunk-8-1.png differ diff --git a/man/figures/README-unnamed-chunk-9-1.png b/man/figures/README-unnamed-chunk-9-1.png index 6cf8468..dd2ae43 100644 Binary files a/man/figures/README-unnamed-chunk-9-1.png and b/man/figures/README-unnamed-chunk-9-1.png differ diff --git a/man/plot_catchcurve.Rd b/man/plot_catchcurve.Rd index a7df4f7..cf79970 100644 --- a/man/plot_catchcurve.Rd +++ b/man/plot_catchcurve.Rd @@ -28,9 +28,7 @@ plot_catchcurve( \item{age.range}{Defines the age range to be used for Z estimation. If \code{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 \code{split.by.sex = TRUE}: use a named list of length two with names referring to \code{female.sex} and \code{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.} -\item{female.sex}{A character denoting female sex in the \code{sex} column of \code{dt}} - -\item{male.sex}{A character denoting male sex in the \code{sex} column of \code{dt}} +\item{female.sex, male.sex}{A character or integer denoting female and male sex in the \code{sex} column of \code{dt}, respectively.} \item{split.by.sex}{Logical indicating whether the result should be split by sex.} diff --git a/man/plot_growth.Rd b/man/plot_growth.Rd index 2afc75c..7120822 100644 --- a/man/plot_growth.Rd +++ b/man/plot_growth.Rd @@ -32,9 +32,7 @@ plot_growth( \item{sex}{Character argument giving the name of the sex column in \code{dt}. Ignored if \code{split.by.sex == FALSE}.} -\item{female.sex}{A character denoting female sex in the \code{sex} column of \code{dt}} - -\item{male.sex}{A character denoting male sex in the \code{sex} column of \code{dt}} +\item{female.sex, male.sex}{A character or integer denoting female and male sex in the \code{sex} column of \code{dt}, respectively.} \item{length.unit}{A character argument giving the unit of \code{length}. Will be used in the labels of the figure.} diff --git a/man/plot_lw.Rd b/man/plot_lw.Rd index 9723e21..f0685a3 100644 --- a/man/plot_lw.Rd +++ b/man/plot_lw.Rd @@ -20,9 +20,12 @@ plot_lw( init.a = NULL, init.b = NULL, log.axes = FALSE, + outlier.percentile = NULL, + annotate.coefficients = FALSE, + correct.units = FALSE, base_size = 8, legend.position = "bottom", - correct.units = FALSE, + point.size = 0.5, verbose = TRUE ) } @@ -35,13 +38,11 @@ plot_lw( \item{sex}{Character argument giving the name of the sex column in \code{dt}. Ignored if \code{split.by.sex == FALSE}.} -\item{female.sex}{A character denoting female sex in the \code{sex} column of \code{dt}} - -\item{male.sex}{A character denoting male sex in the \code{sex} column of \code{dt}} +\item{female.sex, male.sex}{A character or integer denoting female and male sex in the \code{sex} column of \code{dt}, respectively.} -\item{length.unit}{Character argument giving the unit of \code{length}. Will be used in the labels of the figure and for conversion of the a parameter. Allowed values for the conversion: "mm" (millimmeters), "cm" (centimeters), and "m" (meters).} +\item{length.unit}{Character argument giving the unit of \code{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).} -\item{weight.unit}{Character argument giving the unit of \code{weight}. Will be used in the labels of the figure and for conversion of the a parameter. Allowed values: "g" (grams), "kg" (kilograms), and "t" (metric tons).} +\item{weight.unit}{Character argument giving the unit of \code{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).} \item{split.by.sex}{Logical indicating whether the result should be split by sex.} @@ -49,28 +50,38 @@ plot_lw( \item{ylab}{Character giving the x-axis label without unit.} -\item{use.nls}{Logical indicating whether the parameters should be calculated using the nonlinear least squares (\code{nls; TRUE}) method over the log-log transformed linear model (\code{lm; FALSE}) method.} +\item{use.nls}{Logical indicating whether the parameters should be estimated using the nonlinear least squares (\code{nls; TRUE}) method over the log-log transformed linear model (\code{lm; FALSE}) method. See details.} + +\item{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 \code{use.nls = TRUE}). If \code{NULL} (default) starting values are guessed.} + +\item{log.axes}{Logical indicating whether logarithmic axes should be used instead of Cartesian ones.} -\item{init.a, init.b}{Numeric values giving the starting value for a and b parameters respecitively for non-linear least-squares estimation (i.e. when \code{use.nls = TRUE}). If \code{NULL}, default values are guessed.} +\item{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 \code{NULL} (default), no outlier removal is conducted.} -\item{log.axes}{Logical indicating whether logarithmic axes should be used instead of cartesian ones.} +\item{annotate.coefficients}{Logical indicating whether the a and b coefficients should be annotated into the plot.} + +\item{correct.units}{Logical indicating whether the a and b coefficients should be converted for centimeters and grams as in FishBase.} \item{base_size}{Base size parameter for ggplot. See \link[ggplot2]{ggtheme}.} \item{legend.position}{Position of the ggplot legend as a character. See \link[ggplot2]{ggtheme}.} -\item{correct.units}{Logical indicating whether a and b parameters should be converted for centimeters and grams as in FishBase.} +\item{point.size}{Numeric defining the size for data points in the plot. See the \code{size} argument in \link[ggplot2]{geom_point}.} \item{verbose}{Logical indicating whether to return warnings and messages.} } \value{ -A ggplot together with the a and b parameters. +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). } \description{ -Plot length-weight relationships +Plots length-weight relationship for a species and calculates the a and b coefficients used in length-weight conversions. } \details{ -It is crucial to get the units right when calculating length-weight relationships. 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 centimetres and grams, respectively. If the units are wrong, the intercept, a, will be off the FishBase scale by orders of magnitude (see \href{https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm}{FishBase}). If \code{correct.units = TRUE}, \code{plot_lw()} attempts to correct for the 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. You can ignore this warning if you want to estimate values. Comparing your a and b with those in FishBase for the species is a good idea. This function may contain bugs. +The function estimates the a and b coefficients of the length weight relationship, \eqn{weight = a \times length^b}{weight = a*length^b}, and plots the data. The model can be fitted either using the standard log(weight) ~ log(length) regression (\link[stats]{lm}; default) or nonlinear least squares (\link[stats]{nls}) method. The nls method often manages to fit steeper slopes making the b parameter higher and the a parameter lower than the linear \link[stats]{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 \href{https://www.fishbase.se/manual/english/FishBaseThe_LENGTH_WEIGHT_Table.htm}{FishBase}). The \code{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 \code{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 (\eqn{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. } \examples{ data(survey_ghl) @@ -78,8 +89,14 @@ data(survey_ghl) # Simple plot plot_lw(survey_ghl, length = "length", weight = "weight") \donttest{ -# Split by sex -plot_lw(survey_ghl, split.by.sex = TRUE)$plot +# 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) } } \author{ diff --git a/man/plot_maturity.Rd b/man/plot_maturity.Rd index 9d21855..f07c9e1 100644 --- a/man/plot_maturity.Rd +++ b/man/plot_maturity.Rd @@ -36,9 +36,7 @@ plot_maturity( \item{split.by.sex}{Logical indicating whether the result should be split by sex.} -\item{female.sex}{A character denoting female sex in the \code{sex} column of \code{dt}} - -\item{male.sex}{A character denoting male sex in the \code{sex} column of \code{dt}} +\item{female.sex, male.sex}{A character or integer denoting female and male sex in the \code{sex} column of \code{dt}, respectively.} \item{length.unit}{A character argument giving the unit of \code{length}. Will be used in the labels of the figure.}