Skip to contents

Applies parameter modifications to an `Rpath` scene, runs the simulation, and either returns the full simulation output or evaluates the fit against observation data using a penalized negative log-likelihood.

Usage

rsim.fit.run(
  values,
  species,
  vartype,
  Rsim.scenario,
  run_method,
  run_years,
  verbose = F,
  penalty_weight = 0,
  nll_details = FALSE,
  ...
)

Arguments

values

A numeric vector of parameter values or modifiers. For a parameter of vartype `"mzero"`, the unit of the value is a mortality rate. Values for `"predvul"`, `"preyvul"`, and `"ppvul"` are log-scaled vulnerabilities.

species

A character vector indicating the species/groups to modify (or string representations of numeric link indices for `"ppvul"`).

vartype

A character vector indicating the types of parameters to modify. Currently supported parmaters are `"mzero"`, `"predvul"`, `"preyvul"`, and `"ppvul"`.

Rsim.scenario

An `Rsim` scenario object containing the fitting data.

run_method

Numerical integration method for rsim.run. Either 'AB' for Adams-Bashforth or 'RK4' for 4th order Runge-Kutta.

run_years

A numeric vector of years over which to run the simulation.

verbose

Logical; if `FALSE`, returns the NLL fit score. If `TRUE`, returns the complete simulation run object. Defaults to `F`.

penalty_weight

Numeric value to scale the L2 penalty term for parameter regularization. Defaults to `0`.

nll_details

Logical; if `TRUE` and `verbose = FALSE`, returns a list breaking down the total NLL into base error and penalty components.

...

Additional arguments (currently swallowed and unused by the function).

Value

* If `verbose = TRUE`: Returns an `Rsim` simulation run output object. * If `verbose = FALSE` and `nll_details = FALSE`: Returns a single numeric value representing the total penalized negative log-likelihood. * If `verbose = FALSE` and `nll_details = TRUE`: Returns a named list containing `total_nll`, `base_error`, and `penalty_term`.

Details

This function translates the defined fitting variables into the appropriate variables of an Rsim.scenario object and runs an rsim simulation with the resulting scenario. Applying an `"mzero"` parameter to a species replaces the Rsim.scenario$params$MzeroMort paramter for that species. `"predvul"`, `"preyvul"`, and `"ppvul"` are applied using the formula for each predator/prey link Rsim.scenario$params$VV(predator, prey) = (1 + exp(log(Rsim.scenario$params$VV(predator, prey)-1) + preddiff + preydiff + ppdiff))