R/exploitation.R

In jasondubois/sportfish: Methods and Function for CDFW Sportfish Unit Data

# ******************************************************************************
# Created: 20-Ju1-2018
# Author:  J. DuBois
# Contact: jason.dubois@wildlife.ca.gov
# Purpose: This file contains functions or methods to calculate exploitation
#          rate using mark-recapture data (i.e., tags released, tags returned)
# Source:  functions herein adapted from "Use of a Statewide Angler Tag
#          Reporting System to Estimate Rates of Exploitation and Total
#          Mortality for Idaho Sport Fisheries" --- Meyer & Schill (2014)
# ******************************************************************************

#' Calculates angler reporting rate of non-reward tags.
#'
#' @description In mark-recapture studies, anglers are encouraged to return
#'    tags to the issuing entity. A mixture of non-reward tags and high-value
#'    reward tags typically are released to ensure returns. Not all anglers
#'    return tags (non-reporting), and the reporting rate adjusts
#'    for non-reporting.
#'
#' @param rr Number of non-reward tags reported (positive integer).
#' @param rt Number of non-reward tags released (positive integer).
#' @param nr Number of high-reward tags reported (positive integer).
#' @param nt Number of high-reward tags released (positive integer).
#'
#' @return List containing reporting rate and reporting rate variance.
#' @export
#'
#' @note In the case of CDFW sturgeon mark-recapture, all tags released
#'    are reward tags. We assume, then, a reporting rate of 100% for
#'    the highest value reward.
#'
#' @references Kevin A. Meyer & Daniel J. Schill (2014) Use of a Statewide
#'    Angler Tag Reporting System to Estimate Rates of Exploitation
#'    and Total Mortality for Idaho Sport Fisheries, North American
#'    Journal of Fisheries Management, 34:6, 1145-1158,
#'    DOI: 10.1080/02755947.2014.951803
#'
#' @examples
#' # numbers for example only
#' ReportingRate(rr = 5, rt = 175, nr = 10, nt = 175)
ReportingRate <- function(rr, rt, nr, nt) {

  lambda <- (rr / rt) / (nr / nt)

  var_lambda <- lambda^2 * ((1/ rr) + (lambda / rr)^2 * (rt / nt)^2 * nr)

  list(
    RepRate = lambda,
    VarRepRate = var_lambda
  )
}
# end ReportingRate

#' Calculcates adjusted exploitation rate \eqn{\mu\prime}.
#'
#' @description Adjusted exploitation compensates for lack of angler-
#'    reporting (i.e., via reporting rate), tag loss, and mortality
#'    due to tagging. If tag loss or tagging mortality are unknown,
#'    values from literature can be used.
#'
#'    \deqn{\mu\prime=\frac{\mu}{(repRate \times (1-tagL) \times (1-tagM))}}
#'
#' @param rr Number of non-reward tags reported (positive integer).
#' @param rt Number of non-reward tags released (positive integer).
#' @param repRate Reporting rate \code{RepRate} from \code{ReportingRate}.
#' @param tagL Fraction of tags lost (default ??).
#' @param tagM Mortality (as a fraction) from tagging (default ??).
#'
#' @return List containing number returned, number released (tagged),
#'    reporting rate, raw exploitation rate mu, and adjusted exploitation
#'    rate \eqn{\mu\prime}.
#' @export
#'
#' @references Kevin A. Meyer & Daniel J. Schill (2014) Use of a Statewide
#'    Angler Tag Reporting System to Estimate Rates of Exploitation
#'    and Total Mortality for Idaho Sport Fisheries, North American
#'    Journal of Fisheries Management, 34:6, 1145-1158,
#'    DOI: 10.1080/02755947.2014.951803
#'
#' @examples
#' # numbers for example only
#' Exploitation(rr = 5, rt = 175, repRate = 0.5, tagL = 0.05, tagM = 0.05)
Exploitation <- function(rr, rt, repRate, tagL, tagM) {

  # (25-Jan-2019) causing issues with inputs will re-tool at a later date
  # if (!is.numeric(sapply(ls(), FUN = get, environment())))
  #   stop("All arguments must be numeric.", call. = FALSE)

  # if (!is.numeric())

  mu <- rr / rt
  mu_prime <- mu / (repRate * (1 - tagL) * (1 - tagM))

  # variance algorithm?

  list(
    NumRet = rr,
    NumRel = rt,
    RepRate = repRate,
    Mu = mu,
    MuPrime = mu_prime
  )
}
# end Exploitation