R/12_calc_z.R

In mcsiple/mmrefpoints: Project Marine Mammal Populations and Calculate Reference Points

#' Degree of compensation
#'
#' @description Calculate the parameter z, the degree of compensation
#' @param MNPL_in User-specified value for MNPL as a proportion of K (between 0 and 1)
#' @param lh.params_in a list of life history parameters. Must contain S0, S1plus, nages, AgeMat, lambdaMax and z.
#' @details Helper function for calculating z when user specifies MNPL
#'
#' @return the value of z corresponding to the user-defined value of MNPL.
#' @export
#'
#' @examples
#' calc_z(MNPL_in = 0.5,
#' lh.params_in = list(S0 = 0.944, S1plus = 0.99, AgeMat = 17, nages = 19,
#' fmax = 0.29, lambdaMax = 1.04, K1plus = 9000))
#' 
calc_z <- function(MNPL_in, lh.params_in) {
  # Checks
  if(MNPL_in < 0 | MNPL_in > 1){
    stop("Check inputs; MNPL_in must be between 0 and 1.")}
  
  lims <- c(0.107, 7) # z limits from AEP meeting were 0 and 7; I increased the lower bound because z cannot be too low.
  # Solve for z value that gives MNPL = MNPL_in
  zero.cross <- tryCatch(
    stats::uniroot(f = get_dz, interval = lims, tol = 1e-7, MNPL = MNPL_in, lh.params = lh.params_in),
    error = function(e) {
      "x"
    }
  )
  if (is.character(zero.cross)) {
    stop(safeError("Error in solving for z. Try a smaller value of MNPL."))
  }
  z.out <- zero.cross$root
  return(z.out)
}