pf_access_particles_unique.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pf_access.R
\name{pf_access_particles_unique}
\alias{pf_access_particles_unique}
\title{Access the cells sampled by PF}
\usage{
pf_access_particles_unique(
  history,
  use_memory_safe = FALSE,
  cl = NULL,
  varlist = NULL
)
}
\arguments{
\item{history}{A \code{\link[flapper]{pf_archive-class}} class object from \code{\link[flapper]{pf}}, the list of particle histories (the `history' element of a \code{\link[flapper]{pf_archive-class}} object) from \code{\link[flapper]{pf}} or a list of file paths to particle histories.}

\item{use_memory_safe}{If \code{history} is a record of file paths, \code{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 \code{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.}

\item{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 \code{use_memory_safe = FALSE}. \code{cl} is (a) a cluster object from \code{\link[parallel]{makeCluster}} or (b) an integer that defines the number of child processes. \code{varlist} is a character vector of variables for export (see \code{\link[flapper]{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 \code{\link[flapper]{cl_stop}}). For further information, see \code{\link[flapper]{cl_lapply}} and \code{\link[flapper]{flapper-tips-parallel}}.}
}
\value{
The function returns a vector of the unique particles sampled by the PF algorithm.
}
\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 (\code{\link[flapper]{pf}}).
}
\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
)

}
\seealso{
\code{\link[flapper]{pf}} implements particle filtering.
}
\author{
Edward Lavender
}