pf_setup_optimisers: Optimisation settings for 'pf'

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

Optimisation settings for pf

Description

This function defines optimisation settings for pf. These settings control under-the-hood implementation routines in pf that may improve computation time if adjusted.

Usage

pf_setup_optimisers(
  use_raster_operations = TRUE,
  use_calc_distance_euclid_backend_grass = FALSE,
  use_grass_dir = NULL
)

Arguments

use_raster_operations	(experimental) A logical input that defines whether or not to use raster operations, where applicable (e.g., calc), which are memory-safe, or to extract raster values into a data.table and perform arithmetic operations on the data.table. This option is only implemented for the ‘fast Euclidean distances’ method in pf. Trials suggest that use_raster_operations = FALSE does not improve computation time.
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 pf. The default is FALSE, in which case distanceFromPoints is used for these calculations. If TRUE, the fasterRaster package is required and fasterVectToRastDistance is used instead.
use_grass_dir	If use_calc_distance_euclid_backend_grass = TRUE, use_grass_dir is a character that defines the directory where GRASS is installed on your system and should be supplied.

Details

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 mobility parameter; for large numbers of particles, it is probably faster to set mobility = NULL. Adjusting raster{rasterOptions} such as chunksize and/or maxmemory may help in some circumstances too. Following optimisation of these settings, pf_setup_optimisers facilitates the adjustment of under-the-hood implementation routines which may further reduce computation time in some settings.

Value

The function returns pf_optimiser S3 class object, which is simply a named list of optimisation options that can be passed to pf via the optimisers argument.

Author(s)

Edward Lavender

See Also

pf

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().

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