FLightR (version 0.5.6)

run.particle.filter: Run Particle Filter

Description

Main function of FLightR, it takes fully prepared object created by make.prerun.object and produces a result object that can be used for plotting etc.

Usage

run.particle.filter(
  all.out,
  cpus = NULL,
  threads = -1,
  nParticles = 1e+06,
  known.last = TRUE,
  precision.sd = 25,
  behav.mask.low.value = 0,
  k = NA,
  plot = TRUE,
  cluster.type = "PSOCK",
  a = 45,
  b = 1500,
  L = 90,
  adaptive.resampling = 0.99,
  check.outliers = FALSE,
  sink2file = FALSE,
  add.jitter = FALSE,
  profile.phases = FALSE,
  profile.top.level = FALSE,
  propagation.backend = c("auto", "cached", "legacy", "partial_cached"),
  verbose = FALSE
)

Value

FLightR object, containing output and extracted results. It is a list with the following elements

Indices

List with prior information and indices

Spatial

Spatial data - Grid, Mask, spatial likelihood

Calibration

all calibration parameters

Data

original data

Results

The main results object. Main components of it are

Quantiles

dataframe containing results on locations. Each line corresponds to a twilight

Movement.results

dataframe containing all the movement results, Note - time at line n means time of the end of transition between n and n-1

outliers

id of twilights excluded by online outlier detection tool

LL

-Log likelihood

Points.rle

run length encoding object with posterior distribution for every twilight. Note that numbers of points correspond to line numbers in $Spatial$Grid

Transitions.rle

run length encoding object with all the transitions

Arguments

all.out

An object created by make.prerun.object.

cpus

another way to specify threads

threads

An amount of threads to use for the particle-filter step. Default is -1. Value 1 forces sequential evaluation. Note that parallelism in make.prerun.object can be useful, but recent validation benchmarks found the particle-filter PSOCK path slower than threads = 1 for the tested data/backend; benchmark your own data before using threads > 1 here.

nParticles

total amount of particles to be used with the run. 10 000 (1e4) is recommended for the preliminary run and 1 000 000 (1e6) for the final

known.last

Set to FALSE if your bird was not at a known place during last twilight in the data

precision.sd

if known.last then what is the precision of this information. Will be used to resample particles proportionally to their distance from the known last point with probability P = dnorm(0, precision.sd)

behav.mask.low.value

Probability value that will be used instead of 0 in the behavioural mask. If set to 1 behavioural mask will not be active anymore

k

Kappa parameter from vonMises distribution. Default is NA, otherwise will generate particles in a direction of a previous transitions with kappa = k

plot

Should function plot preliminary map in the end of the run?

cluster.type

see help to package parallel for details

a

minimum distance that is used in the movement model - left boundary for truncated normal distribution of distances moved between twilights. Default is 45 for as default grid has a minimum distance of 50 km.

b

Maximum distance allowed to fly between two consecutive twilights

L

how many consecutive particles to resample

adaptive.resampling

Above what level of ESS resampling should be skipped

check.outliers

switches ON the online outlier routine

sink2file

will write run details in a file instead of showing on the screen

add.jitter

will add spatial jitter inside a grid cell for the median estimates

profile.phases

logical; if TRUE, stores detailed particle-filter phase timings in the returned object. Intended for diagnostics.

profile.top.level

logical; if TRUE, stores top-level timing for particle-filter post-processing phases in the returned object.

propagation.backend

Movement proposal backend. "auto" currently uses the fast cached backend when possible and falls back to legacy on construction failure. "partial_cached" lazily caches reachable destinations only for visited grid cells and is recommended for larger spatial extents; local validation benchmarks observed about 20-25x faster particle-filter runtime for a full-length 1e6-particle run on one tested dataset and machine. Actual speedups depend on grid size, backend, particle count, hardware, and thread settings. "cached" eagerly builds candidate lists for all grid cells and can be fastest on moderate grids. "legacy" keeps the original per-proposal distance calculation for fallback/reproducibility.

verbose

Controls particle-filter console output. The default FALSE is quiet and suppresses normal progress messages while keeping warnings and errors visible. Use TRUE for normal progress messages, or "debug" for detailed loop diagnostics.

Author

Eldar Rakhimberdiev

Examples

File<-system.file("extdata", "Godwit_TAGS_format.csv", package = "FLightR")
# to run example fast we will cut the real data file by 2013 Aug 20
Proc.data<-get.tags.data(File, end.date=as.POSIXct('2013-07-02', tz='GMT'))
Calibration.periods<-data.frame(
       calibration.start=NA,
       calibration.stop=as.POSIXct("2013-08-20", tz='GMT'),
       lon=5.43, lat=52.93) 
       #use c() also for the geographic coordinates, if you have more than one calibration location
       # (e. g.,  lon=c(5.43, 6.00), lat=c(52.93,52.94))
print(Calibration.periods)

# NB Below likelihood.correction is set to FALSE for fast run! 
# Leave it as default TRUE for real examples
Calibration<-make.calibration(Proc.data, Calibration.periods, likelihood.correction=FALSE)

Grid<-make.grid(left=0, bottom=50, right=10, top=56,
  distance.from.land.allowed.to.use=c(-Inf, Inf),
  distance.from.land.allowed.to.stay=c(-Inf, Inf))

all.in<-make.prerun.object(Proc.data, Grid, start=c(5.43, 52.93),
                             Calibration=Calibration, threads=2)
# here we will run only 1e4 partilces for a very short track.
# One should use 1e6 particles for the full run.
Result<-run.particle.filter(all.in, threads=1,
           nParticles=1e3, known.last=TRUE,
           precision.sd=25, check.outliers=FALSE)