Satellite Geolocation for Animal Tracking

essieThresholdModel

R Documentation

Threshold Model Structures (Essie)

Description

Threshold Model Structures for Essie

Usage

essieThresholdModel(
  twilight,
  rise,
  twilight.model = c("LogNormal", "Gamma", "Normal"),
  alpha,
  beta,
  logp0 = function(k, x) 0,
  x0,
  fixed = FALSE,
  missing = 0,
  dt = NULL,
  zenith = 96
)

Arguments

`twilight`	the observed times of twilight as POSIXct.
`rise`	logical vector indicating which twilights are sunrise.
`twilight.model`	the model for the errors in twilight times.
`alpha`	parameters of the twilight model.
`beta`	parameters of the behavioural model.
`logp0`	function to evaluate any additional contribution to the log posterior from the twilight locations.
`x0`	suggested starting points for twilight locations.
`fixed`	logical vector indicating which twilight locations to hold fixed.
`missing`	integer vector indicating which twilights are missing.
`dt`	time intervals for speed calculation in hours.
`zenith`	the solar zenith angle that defines twilight.

Details

Essie requires a model structure that describes the model being fitted. This function generates basic model structures for threshold twilight data that should provide a suitable starting point for most analyses.

The essieThresholdModel function constructs a model structure assuming that each twilight time is associated with a single location.

One of several models models may be selected for the errors in twilight times. The errors in twilight time are defined as the difference in the observed and true times of twilight, with sign selected so that a positive error always corresponds to a sunrise observed after the true time of sunrise, and sunset observed before the true time of sunset. That is, a positive error corresponds to the observed light level being lower than expected.

The properties of the twilight model are determined by alpha, which must be a vector of parameters that are to be applied to each twilight.

The twilight.model argument selects the distribution of the twilight errors

'Normal': Normally distributed with mean alpha[,1] and standard deviation alpha[,2],
'LogNormal': Log Normally distributed so the log errors have mean alpha[,1] and standard deviation alpha[,2], or
'Gamma': Gamma distributed with shape alpha[,1] and rate alpha[,2].

The initialization locations x0 are only required when specifying fixed locations.

Essie assumes that the average speed of travel between successive locations is Gamma distributed. By default, the speed of travel is calculated based on the time intervals between the twilights (in hours), but the intervals of time actually available for travel can be specified directly with the dt argument. The parameters beta[1] and beta[2] specify the shape and rate of the Gamma distribution of speeds.

Twilights can be missing because either the light record was too noisy at that time to estimate twilight reliably, or because the tag was at very high latitude and no twilight was observed. Missing twilights should be replaced with an approximate time of twilight, and the vector missing used to indicate which twilights are approximate and which are true. This should be a vector of integers, one for each twilight where the integer codes signify

0:: The twilight is not missing.
1:: The twilight is missing, but a twilight did occur.
2:: The twilight is missing because twilight did not occur.
3:: The twilight is missing and it is not known if a twilight occurred.

Value

a list with components

`logpk`	function to evaluate the contributions to the log posterior from the k-th twilight
`logpbk`	function to evaluate contribution to the log posterior from the behavioural model for the k-th track segment.
`fixed`	a logical vector indicating which locations should remain fixed.
`x0`	an array of initial twilight locations.
`time`	the twilight times.
`rise`	the sunrise indicators.
`alpha`	the twilight model parameters.
`beta`	the behavioural model parameters.