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.
Note: parm_sens
assumes that the reward function does not depend explicitly on the parameters of interest, so any parameter perturbation will only affect the reward indirectly through its effects on the state variables. If this assumption is not true, then there is an additional 'direct' contribution that needs to be added to the results; we will show how this can be done in a future vignette.
Usage
parm_sens(
state_sens_out,
numDeriv_arglist = list(),
verbose = TRUE
)
Arguments
state_sens_out |
Output returned by To make this help page easier to read, from now on, any time we mention |
numDeriv_arglist |
Optional list of arguments passed to the function |
verbose |
Whether to display progress messages in the console. Either |
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 |
tdps |
Time-dependent parameter sensitivities. An object whose structure depends on the structure of
As a concrete example, say |
Warning
The function parm_sens
will calculate the sensitivities for every parameter in the argument parms
used by dynamic_fn
. Hence, parms
should not contain discrete parameters such as the length of the vector or the dimensions of a matrix; otherwise jacobian
(from the numDeriv package) will attempt to numerically evaluate the derivative of dynamic_fn
with respect to such a discrete parameter and will hence almost invariably return an error message or nonsensical results. The solution is instead to make use the fact that we allow dynamic_fn
to take additional arguments ...
; for example, we can define dynamic_fn
to take an additional argument parms2
that will then be used to hold these discrete parameters instead of parms
.
References
Ng, W. H., Myers, C. R., McArt, S., & Ellner, S. P. (2023). A time for every purpose: using time-dependent sensitivity analysis to help understand and manage dynamic ecological systems. American Naturalist, 202, 630-654. doi: 10.1086/726143. eprint doi: 10.1101/2023.04.13.536769.
Ng, W. H., Myers, C. R., McArt, S., & Ellner, S. P. (2023). tdsa: An R package to perform time-dependent sensitivity analysis. Methods in Ecology and Evolution, 14, 2758-2765. doi: 10.1111/2041-210X.14216.
See Also
state_sens
for time-dependent state sensitivities.