EKF_1d_interp_joint {animalEKF}  R Documentation 
Extended Kalman Filter (EKF) for 1D movement with interpolation
Description
Extended Kalman Filter (EKF) for 1D 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 inversegamma 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_t1. 
Particle_err_df 
Degree of freedom of 
dirichlet_init 
List of 4element 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 lowvariance 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 (1D 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 timedependent meaning that probability depends on the number of steps a shark has remained in the current state. 
time_dep_trans_init 
4element 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 regularstep 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 stepwise 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 regularstep intervals that each shark has simulated particle movement for. 
shark_intervals 
List of regularstep intervals that each shark has observations for. 
first_intervals 
List of regularstep intervals that begin each shark's segments of simulated particle movement.
If observed gaps are larger than 
included_intervals 
Unique list of regularstep intervals with simulated movement for any shark. 
mu 
Array of estimated values of mean logvelocity for normal inversegamma 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 2D, logvelocity) variance. 
Xpart_history 
Overall history of estimated movement values. 
param_draws 
Posterior sampled values of mean of velocity (or, for 2D, logvelocity). 
variance_draws 
Posterior sampled value of variance of velocity (or, for 2D, logvelocity). 
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 regularstep 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 regularstep 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 2D, logvelocity) after resampling by smoothing. 
variance_draws_smoothed 
Posterior sampled values of variance of velocity (or, for 2D, logvelocity) 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 statespace 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.