run.particle.filter: Run Particle Filter

In FLightR: Reconstruct Animal Paths from Solar Geolocation Loggers Data

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
)

Arguments

all.out	An object created by make.prerun.object.
cpus	another way to specify threads
threads	An amount of threads to use while running in parallel. default is -1. if value 1 submitted package will run sequentially
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

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

Author(s)

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)

FLightR documentation built on Sept. 11, 2024, 5:14 p.m.