pf_setup_optimisers.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pf_setup.R
\name{pf_setup_optimisers}
\alias{pf_setup_optimisers}
\title{Optimisation settings for \code{\link[flapper]{pf}}}
\usage{
pf_setup_optimisers(
  use_raster_operations = TRUE,
  use_calc_distance_euclid_backend_grass = FALSE,
  use_grass_dir = NULL
)
}
\arguments{
\item{use_raster_operations}{(experimental) A logical input that defines whether or not to use \code{\link[raster]{raster}} operations, where applicable (e.g., \code{\link[raster]{calc}}), which are memory-safe, or to extract \code{\link[raster]{raster}} values into a \code{\link[data.table]{data.table}} and perform arithmetic operations on the \code{\link[data.table]{data.table}}. This option is only implemented for the `fast Euclidean distances' method in \code{\link[flapper]{pf}}. Trials suggest that \code{use_raster_operations = FALSE} does not improve computation time.}

\item{use_calc_distance_euclid_backend_grass}{A logical input that defines whether or not to use GRASS as the backend for Euclidean distances calculations in \code{\link[flapper]{pf}}. The default is \code{FALSE}, in which case \code{\link[raster]{distanceFromPoints}} is used for these calculations. If \code{TRUE}, the \code{\link[fasterRaster]{fasterRaster}} package is required and \code{\link[fasterRaster]{fasterVectToRastDistance}} is used instead.}

\item{use_grass_dir}{If \code{use_calc_distance_euclid_backend_grass = TRUE}, \code{use_grass_dir} is a character that defines the directory where GRASS is installed on your system and should be supplied.}
}
\value{
The function returns \code{pf_optimiser} S3 class object, which is simply a named list of optimisation options that can be passed to \code{\link[flapper]{pf}} via the \code{optimisers} argument.
}
\description{
This function defines optimisation settings for \code{\link[flapper]{pf}}. These settings control under-the-hood implementation routines in \code{\link[flapper]{pf}} that may improve computation time if adjusted.
}
\details{
\code{\link[flapper]{pf}} is a computationally intensive routine. To reduce computation time, the most effective approaches are to minimise data volume and reduce the size (dimensions and/or resolution) of the grid over which particle filtering is implemented; use the `fast Euclidean distances' method for distance calculations; and minimise the number of particles. For small numbers of particles, it may be faster to specify the \code{mobility} parameter; for large numbers of particles, it is probably faster to set \code{mobility = NULL}. Adjusting \code{\link{raster}{rasterOptions}} such as \code{chunksize} and/or \code{maxmemory} may help in some circumstances too. Following optimisation of these settings, \code{\link[flapper]{pf_setup_optimisers}} facilitates the adjustment of under-the-hood implementation routines which may further reduce computation time in some settings.
}
\examples{
#### Example (1): The default implementation
pf_setup_optimisers()

#### Example (2): Use GRASS for Euclidean distance calculations
# Specification for GRASS-7.4.4 on MacOS
pf_setup_optimisers(
  use_calc_distance_euclid_backend_grass = TRUE,
  use_grass_dir = "/Applications/GRASS-7.4.4.app/Contents/Resources"
)
# This list should be passed to the 'optimisers' argument in pf().

}
\seealso{
\code{\link[flapper]{pf}}
}
\author{
Edward Lavender
}