EKF_1d_interp_joint {animalEKF} | R Documentation |
Extended Kalman Filter (EKF) for 1-D movement with interpolation
Description
Extended Kalman Filter (EKF) for 1-D movement with interpolation
Usage
EKF_1d_interp_joint(d, npart=100, sigma_pars,
alpha0_pars=list(mu0=c(5, 9), V0=c(0.25, 0.25)),
Errvar0=rep(list(5), 2), Errvar_df=c(20, 20),
Particle_errvar0, Particle_err_df=20, delaysample=1,
dirichlet_init=c(10,3,3,8), maxStep=NULL,
state_favor=c(1,1), nstates=2,
lowvarsample=FALSE, time_radius=60*30, spat_radius=300,
min_num_neibs=10, interact=TRUE,
interact_pars=list(mu0=0, precision0=2,
known_precision=2),
neff_sample=1, time_dep_trans=FALSE,
time_dep_trans_init=dirichlet_init, smoothing=FALSE,
fix_smoothed_behaviors=TRUE, smooth_parameters=TRUE,
reg_dt=120, max_int_wo_obs=NULL,
resamp_full_hist=TRUE, compare_with_known=FALSE,
known_trans_prob=NULL, known_foraging_prob=NULL,
known_regular_step_ds=NULL, update_eachstep=FALSE,
update_params_for_obs_only=FALSE,
output_plot=TRUE, loc_pred_plot_conf=0.5,
output_dir=getwd(), pdf_prefix="EKF_1D", verbose=3)
Arguments
d |
Dataset of observations, with required variable columns: tag, X, velocity, date_as_sec, time_to_next, state.guess2, prev.guess2. |
npart |
Number of particles to be used in simulation. |
sigma_pars |
Vector of inverse-gamma parameters for sigma^2 (logV variance). Two elements for each state. The inverse gamma parameters are specified in pairs. |
alpha0_pars |
List of initial values of mean velocity (mu) and degrees of freedom (V), one for each behavioral state. |
Errvar0 |
List of prior 1x1 covariance matrices for predicting y from x, one for each behavioral state. |
Errvar_df |
Vector of degrees of freedom of |
Particle_errvar0 |
Prior 1x1 covariance matrix for predicting x_t from x_t-1. |
Particle_err_df |
Degree of freedom of |
dirichlet_init |
List of 4-element vectors specifying Dirichlet parameters for transition matrices for each region. Will be replicated to equal number of regions. |
maxStep |
Maximum number of regular steps to simulate. Default is NULL, meaning that the number of regular steps simulated will be the minimum number required to cover the range of observed data. If not NULL, maxStep will be the minimum of the submitted value or the the above. |
delaysample |
Number of regular steps at which resampling will begin. The default =1 means resampling will begin immediately. |
state_favor |
Vector of weights to favor states when resampling (but not propagating). For instance c(1,3) will favor state 2 weight 3 times as much as state 1 weights for particles. By default, they are equally weighted. |
nstates |
Number of behavioral states. For now restricted to a maximum of 2. |
lowvarsample |
Logical. If TRUE, use low-variance sampling when resampling particles to ensure particles are resampled proportionately to weight. Otherwise there is some sampling variance when drawing random samples. The setting applies to smoothing as well. |
time_radius |
Time in seconds to consider for spatial neighbors (1-D interval on either side). |
spat_radius |
Radius (half of interval length) in meters of spatial neighborhood. |
min_num_neibs |
Minimum number of time and spatial radius observations that need to exist to constitute a neighborhood. |
interact |
Logical. If TRUE, simulate interaction parameters of neighborhood. If |
interact_pars |
List of interaction priors: |
neff_sample |
Number between 0 and 1. If effective sample size < |
time_dep_trans |
Logical. If TRUE, state transition matrices are time-dependent meaning that probability depends on the number of steps a shark has remained in the current state. |
time_dep_trans_init |
4-element numeric vector of Dirichlet parameters for |
smoothing |
Logical. If TRUE, perform smoothing at the end. |
fix_smoothed_behaviors |
Logical. If TRUE, when performing smoothing, keep behavior modes fixed for each particle history from what was originally predicted duruing filtering,
before smoothing. This means the particles will be smoothed backwards with each particle weight at each time point being conditioned on the
behavior predicted in filtering. Thus, the behavioral agreement with, say, the observed or true behaviors is the same for smoothing as for
filtering, since behaviors are not allowed to change. If |
smooth_parameters |
Logical. If TRUE, when performing smoothing, resample the parameters theta as well. |
reg_dt |
Length in seconds of each regular interval. |
max_int_wo_obs |
When simulating, the maximum number of intervals of length |
resamp_full_hist |
Logical. If TRUE, resample the full particle history, not just all particle times since the last observation, each time resampling occurs. |
compare_with_known |
Logical. If TRUE, provide a known regular-step dataset from which |
known_trans_prob |
If |
known_foraging_prob |
If |
known_regular_step_ds |
If |
update_eachstep |
Logical. If TRUE, for regular steps without observations, update the movement parameters based on the simulated movements. If FALSE, parameters are only updated based on the simulated movements when a new observation occurs; this means the simulated movements are drawn using the parameter values learned since the last observation. |
update_params_for_obs_only |
Logical. If TRUE, the particle movement parameters are updated based on simulated movement only at intervals with observed locations.
If FALSE, particle movement in intermediate steps that are simulated will be used to update as well.
If TRUE, then |
output_plot |
Logical. If TRUE, a set of diagnostic plots will be printed to a file in |
loc_pred_plot_conf |
Numeric. Confidence level of confidence interval for location prediction error to plot in step-wise diagnostics. |
pdf_prefix |
String prefix for output PDF filename, if |
output_dir |
Directory for output PDF of diagnostic plots. |
verbose |
Integer, one of 0,1,2,3. Control of verbosity of printouts during simulation. 3 means show both printouts and plots; 2 means show plots only; 1 means show printouts only; 0 means show no plots or prinouts. Final plotting will be done regardless. |
Value
d |
Input dataset as |
N |
Number of regular steps of length |
t_reg |
Vector of times of regular step |
nsharks |
Number of sharks in output data. |
shark_names |
Names of sharks in output data. |
shark_valid_steps |
List of regular-step intervals that each shark has simulated particle movement for. |
shark_intervals |
List of regular-step intervals that each shark has observations for. |
first_intervals |
List of regular-step intervals that begin each shark's segments of simulated particle movement.
If observed gaps are larger than |
included_intervals |
Unique list of regular-step intervals with simulated movement for any shark. |
mu |
Array of estimated values of mean log-velocity for normal inverse-gamma conjugate distribution |
XY_errvar |
Estimated matrix and degrees of freedom of estimated location error covariance, for each behavior. |
sigma_pars |
Posterior inverse gamma distribution parameters for the velocity (or, for 2-D, log-velocity) variance. |
Xpart_history |
Overall history of estimated movement values. |
param_draws |
Posterior sampled values of mean of velocity (or, for 2-D, log-velocity). |
variance_draws |
Posterior sampled value of variance of velocity (or, for 2-D, log-velocity). |
eff_size_hist |
History of effective sample sizes in simulations. |
agree_table |
Table of observed agreement between particle predictions of behavior and those observed, overall and by behavior, if |
states |
Observed vector of behavioral states. |
state_counts |
Array of total number of simulated regular-step intervals in each behavioral state. |
lambda_matrix |
History of particle predicted values of lambda, the behavior variable. |
lambda_matrix_beforesamp |
Same as |
resample_history |
Fraction of unique particles that are resampled at each regular step over the history. |
transition_mat |
Estimated transition probability matrix parameters for Dirichlet distribution. If |
error_beforesamp |
For each regular step |
error_beforesamp_quantiles |
Quantiles of |
error_final_allpart |
For each regular step |
error_final_quantiles |
Quantiles of |
error_true_allpart |
If |
error_true_quantiles |
If |
The following inputted parameters are returned :
npart |
|
nstates |
|
state_favor |
|
known_regular_step_ds |
|
known_foraging_prob |
|
neff_sample |
|
resamp_full_hist |
|
time_dep_trans |
|
interact |
|
spat_radius |
|
time_radius |
|
lowvarsample |
|
update_eachstep |
|
update_params_for_obs_only |
The following are returned if nstates > 1
:
trans_counts |
Array of total number of simulated regular-step intervals with transitions between each possible pair of behaviors. |
trans_mean |
Posterior estimates of mean behavior switching probabilities from |
region_foraging_draws |
Posterior estimate of probability of foraging (lambda=0) from behavior switching probabilities. |
region_trans_draws |
Posterior draws of behavior switching probabilities from |
In addition, the following are returned if compare_with_known = TRUE
:
error_final_true_allpart |
Errors from estimating true locations from particle locations (at the same times). |
error_final_true_quantiles |
Quantiles of |
euclidean_estimate_true_from_obs |
Estimates of true locations by Euclidean interpolation from observations |
error_euclidean_estimate_true_from_obs |
Euclidean error from |
In addition, the following are returned if interact = TRUE
:
spatial_interact_pars |
Estimated parameters for sharks' tendency to be influenced by other neighboring sharks in determining behavior. |
interact_mu_draws |
Posterior sampled values of interaction mu parameter. |
interact_intensity_draw |
Posterior sampled values of interaction tendency multiplier, at different proportions of neighboring sharks with second behavior type. |
spatial_interact_mu_history |
History of simulated values of interaction mu. |
spatial_interact_intensity_history |
History of simulated values of interaction tendency multiplier. |
The following are returned if smoothing = TRUE
:
Xpart_history_smoothed |
Resampled values of |
error_smoothed_allpart |
For each regular step |
error_smoothed_quantiles |
Quantiles of |
In addition, if smooth_parameters = TRUE
:
param_draws_smoothed |
Posterior sampled values of mean of velocity (or, for 2-D, log-velocity) after resampling by smoothing. |
variance_draws_smoothed |
Posterior sampled values of variance of velocity (or, for 2-D, log-velocity) after resampling by smoothing. |
transition_mat_smoothed |
Estimated transition probability matrix parameters for Dirichlet distribution after resampling by smoothing. |
In addition, if smooth_parameters = TRUE
and interact = TRUE
:
spatial_interact_pars_smoothed |
Estimated parameters for sharks' tendency to be influenced by other neighboring sharks in determining behavior, after resampling by smoothing. |
interact_mu_draws_smoothed |
Posterior sampled values of interaction mu parameter, after resampling by smoothing. |
interact_intensity_draw_smoothed |
Posterior sampled values of interaction tendency multiplier, at different proportions of neighboring sharks with second behavior type, after resampling by smoothing. |
In addition to smoothing, if compare_with_known = TRUE
:
error_smoothed_true_allpart |
For each regular step |
error_smoothed_true_quantiles |
Quantiles of |
In addition to smoothing, if smoothing = TRUE
but fix_smoothed_behaviors = FALSE
(smoothed behaviors allowed to change from filtering):
mu_smoothed |
Corresponding version of |
sigma_pars_smoothed |
Corresponding version of |
agree_table_smoothed |
Corresponding version of |
Note
See sim_trajectory_joint
for a full example of usage.
Video explanation of EKF state-space model by author: https://youtu.be/SgyhRVUn77k
Author(s)
Samuel Ackerman
References
Ackerman, Samuel. "A Probabilistic Characterization of Shark Movement Using Location Tracking Data." Temple University doctoral thesis, 2018. https://digital.library.temple.edu/digital/collection/p245801coll10/id/499150
Carvalho, Carlos M., Johannes, Michael S., Lopes, Hedibert F., and Nicholas G. Polson. "Particle learning and smoothing." Statistical Science, 2010.