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