R: Time-Dependent Parameter Sensitivities

parm_sens {tdsa}

R Documentation

Time-Dependent Parameter Sensitivities

Description

Function to calculate time-dependent parameter sensitivities.

Assume the same model and reward as described in state_sens. Unlike perturbations of the state variables, since the model parameters are not treated as dynamic quantities (even if they may be time-varying), an explicit perturbation of a parameter will only temporarily change the parameter while the perturbation lasts. Now consider a very brief perturbation (i.e., a sharp spike or dip) of the parameter \(b_i\), centered at time \(t\). We define the time-dependent parameter sensitivity \(\kappa_i(t)\) as the sensitivity of the reward to such a perturbation. See Ng et al. (in press, submitted) for a more precise definition.

This function uses the output returned by state_sens (which contain elements parms and times) to calculate the sensitivity for every parameter in parms at every time step in times.

See state_sens for examples.

Usage

parm_sens(
  state_sens_out,
  numDeriv_arglist = list(),
  verbose = TRUE
)

Arguments

state_sens_out

Output returned by state_sens. List containing the elements model_type, dynamic_fn, parms, dynamic_fn_arglist, times, state and tdss.

To make this help page easier to read, from now on, any time we mention dynamic_fn, parms, etc., we refer to the corresponding elements in state_sens_out.

numDeriv_arglist

Optional list of arguments passed to the function jacobian from the numDeriv package, when calculating derivatives. Can be used to specify the method, and arguments controlling the method. For example, if the parameter sensitivities take too long to calculate, try setting numDeriv_arglist = list(method="simple") to replace Richardson's extrapolation by a simple one-sided epsilon difference.

verbose

Whether to display progress messages in the console. Either TRUE (the default) or FALSE.

Details

Parameter sensitivities can be obtained from the state sensitivities using the following formulae.

Continuous-time models: \[ \kappa_i(t) = \sum_{j=1}^{n_y} \left. \frac{\partial g_j(t,\mathbf{y}(t), \mathbf{b})}{\partial b_i}\right\vert_{\mathbf{b}=\mathbf{b}(t)} \lambda_j(t), \] where \(\lambda_j(t)\) is the state sensitivity of \(y_j\) at time \(t\).
Discrete-time models: \[ \kappa_i(t) = \sum_{j=1}^{n_y} \left. \frac{\partial g_j(t,\mathbf{y}(t), \mathbf{b})}{\partial b_i}\right\vert_{\mathbf{b}=\mathbf{b}(t)} \lambda_j(t+1), \] where \(\lambda_j(t+1)\) is the state sensitivity of \(y_j\) at time step \(t+1\). This also means that the parameter sensitivities are always zero at the final time step \(t_1\), because \(\lambda_j(t_1+1)=0\) for all \(j\).

To apply these formulae, we need to calculate derivatives of dynamic_fn with respect to parms, using the function jacobian from numDeriv. The main coding challenge that we have addressed is to make this work even when the structure of parms is only under the relatively mild restrictions imposed in state_sens.

Value

A list with the following elements:

times

Time steps at which the parameter sensitivities are evaluated, a numeric vector. Same as times from state_sens_out.

tdps

Time-dependent parameter sensitivities. An object whose structure depends on the structure of parms.

If parms is a numeric object, then tdps is an array with one more index than the object, so a vector becomes a matrix, a matrix becomes a 3-index array, etc. The first index is new and is associated with the time step.
If parms is a function of the form function(t) that returns a numeric object (i.e., time-varying parameters), then tdps is an array with one more index than the returned object. Again, the first index is new and is associated with the time step.
If parms is a list containing any combination of numeric objects and functions, then tdps is a list of the same length, with the previous "rules" applied element-wise.

As a concrete example, say parms is a matrix of dimension c(3,2), and times a vector of length 50. Then tdps is a 3-index array of dimension c(50,3,2), and the array element tdps[20,1,2] gives the sensitivity for the parameter parms[1,2] at time step times[20].

References

Ng, W. H., Myers, C. R., McArt, S., & Ellner, S. P. (in press). A time for every purpose: using time-dependent sensitivity analysis to help understand and manage dynamic ecological systems. American Naturalist. eprint doi: 10.1101/2023.04.13.536769.

Ng, W. H., Myers, C. R., McArt, S., & Ellner, S. P. (submitted). tdsa: An R package to perform time-dependent sensitivity analysis. Methods in Ecology and Evolution.