PF: pf_particles objects

An S3-class that defines the named list returned by pf_filter() and pf_smoother_two_filter().

Structure

pf_particles is a label used to denote outputs from selected functions in patter. The structure of this class is not strictly defined and primarily exists to streamline documentation. At the time of writing, pf_particles objects may comprise the following elements:

• states—NULL or a data.table::data.table of simulated states;

• diagnostics—A data.table::data.table of diagnostic statistics;

• callstats—A data.table::data.table of call statistics;

states

Unless, .batch is specified in pf_filter() and pf_smoother_two_filter(), states is a data.table::data.table that defines simulated particle states, with the following columns:

• path_id—An integer vector that defines the particle index;

• timestep—An integer vector that defines the time step;

• timestamp—A POSIXct vector of time stamps;

• Additional columns with the values of each state dimension (e.g., map_value, x, y);

Particles are equally weighted, as the .n_record particles recorded at each time step are selected by resampling (see pf_filter()).

If the .batch is specified, states is NULL.

diagnostics

diagnostics is a data.table::data.table that stores diagnostic statistics for each time step. This includes timestep, timestamp and the following columns:

• ess—A numeric vector that defines the effective sample size;

• maxlp—A numeric vector that defines the maximum log posterior;

callstats

callstats is a one-row data.table::data.table that stores call statistics for the function call. This includes the following columns:

• timestamp—A POSIXct value that defines the start time of the function call;

• routine—A character vector that defines the routine:

  • "filter: forward";

  • "filter: backward";

  • "smoother: two-filter";

• n_particle—An integer that defines the number of particles;

• n_iter—An integer that defines the number of iterations (trials);

• error—A character vector of error message(s);

• loglik—A double that defines the log likelihood of the observations given the parameters:

  • For pf_filter(), loglik is computed (if convergence = FALSE, loglik = -Inf);

  • For pf_smoother_two_filter(), loglik is NA_real_;

• convergence—A logical variable that defines whether or not the algorithm converged

  • For pf_filter(), convergence is TRUE if the filter reaches the end of the time series;

  • For pf_smoother_two_filter(), convergence is set to TRUE if proper smoothing is possible on at least 95 % of time steps; i.e., if 95 % of diagnostics$ess values are not NaN (see Patter.particle_smoother_two_filter());

• time—A numeric value that defines the duration (s) of the function call;

See also

Particle filters and smoothers sample states (particles) that represent the possible locations of an individual through time, accounting for all data and the individual's movement.

• To simulate artificial datasets, see sim_*() functions (especially sim_path_walk(), sim_array() and sim_observations()).

• To assemble real-world datasets for the filter, see assemble_*() functions.

• pf_filter() runs the filter:

  • For state types, see State;

  • For observation models, see ModelObs;

  • For movement models, see ModelMove;

• To run particle smoothing, use pf_smoother_two_filter().

• To map emergent patterns of space use, use a map_*() function (such as map_pou(), map_dens() and map_hr()).

Author

Edward Lavender