pf_access_particles_unique: Access the cells sampled by PF

In edwardlavender/flapper: Routines for the Analysis of Passive Acoustic Telemetry Data

Access the cells sampled by PF

Description

Given a list of particle histories (or a list of file paths), this function accesses the unique particles (cells) sampled by a particle filtering (PF) algorithm (pf).

Usage

pf_access_particles_unique(
  history,
  use_memory_safe = FALSE,
  cl = NULL,
  varlist = NULL
)

Arguments

history	A pf_archive-class class object from pf, the list of particle histories (the ‘history’ element of a pf_archive-class object) from pf or a list of file paths to particle histories.
use_memory_safe	If history is a record of file paths, use_memory_safe is a logical variable that defines whether or not to use the ‘memory-safe(r)’ method to access unique cell samples. If specified, the function sequentially loads each file and re-defines the vector of unique particles at each time step as the unique combination of previous (unique) samples and the samples from the current time step. This may be slow. Alternatively, under the default use_memory_safe = FALSE option, the function loads each file (in parallel if specified), retaining all sampled particles, before selecting the unique particles (once) at the end of this process. This option should be faster.
cl, varlist	(optional) Parallelisation options implemented if (a) particle histories are contained in memory or (b) particle histories are supplied as a list of file paths with use_memory_safe = FALSE. cl is (a) a cluster object from makeCluster or (b) an integer that defines the number of child processes. varlist is a character vector of variables for export (see cl_export). Exported variables must be located in the global environment. If a cluster is supplied, the connection to the cluster is closed within the function (see cl_stop). For further information, see cl_lapply and flapper-tips-parallel.

Value

The function returns a vector of the unique particles sampled by the PF algorithm.

Author(s)

Edward Lavender

See Also

pf implements particle filtering.

Examples

#### Example (1): Access unique particles when 'history' exists in memory
# Access unique particles from a pf_archive object
pf_access_particles_unique(dat_dcpf_histories)
# Access unique particles from a list of particle histories
pf_access_particles_unique(dat_dcpf_histories$history)
# Supply a cluster to speed up the algorithm (for very large lists)
pf_access_particles_unique(dat_dcpf_histories$history,
  cl = parallel::makeCluster(2L)
)

#### Example (2): Access unique particles when 'history' is a list of file paths

## Write example particle histories to file (to load)
root <- paste0(tempdir(), "/pf/")
dir.create(root)
pf_args <- dat_dcpf_histories$args
pf_args$calc_distance_euclid_fast <- TRUE
pf_args$write_history <- list(file = root)
out_pf <- do.call(pf, pf_args)

## Access particle histories using default options (use_memory_safe = FALSE)
# Access particle histories via pf_access_history_files()
pf_access_particles_unique(pf_access_history_files(root, use_list = TRUE))
# Supply a cluster to speed up the algorithm (for very large lists)
pf_access_particles_unique(pf_access_history_files(root, use_list = TRUE),
  cl = parallel::makeCluster(2L)
)

## Access particle histories using the 'memory_safe' option
# For large lists, this is likely to be slower
# ... but it may be the only option in some cases.
pf_access_particles_unique(pf_access_history_files(root, use_list = TRUE),
  use_memory_safe = TRUE
)

edwardlavender/flapper documentation built on Jan. 22, 2025, 2:44 p.m.