Satellite Geolocation for Animal Tracking

thresholdModel

R Documentation

Threshold Model Structures

Description

Threshold Model Structures for Stella and Estelle

Usage

thresholdModel(
  twilight,
  rise,
  twilight.model = c("Gamma", "LogNormal", "Normal", "ModifiedGamma",
    "ModifiedLogNormal"),
  alpha,
  beta,
  logp.x = function(x) rep.int(0L, nrow(x)),
  logp.z = function(z) rep.int(0L, nrow(z)),
  x0,
  z0 = NULL,
  fixedx = FALSE,
  missing = 0,
  dt = NULL,
  zenith = 96
)

thresholdModel0(
  twilight,
  rise,
  twilight.model = c("Gamma", "LogNormal", "Normal", "ModifiedGamma",
    "ModifiedLogNormal"),
  alpha,
  logp.x = function(x) rep.int(0L, nrow(x)),
  logp.z = function(z) rep.int(0L, nrow(z)),
  fixedx = FALSE,
  missing = 0,
  zenith = 96
)

groupedThresholdModel(
  twilight,
  rise,
  group,
  twilight.model = c("Gamma", "LogNormal", "Normal", "ModifiedGamma",
    "ModifiedLogNormal"),
  alpha,
  beta,
  logp.x = function(x) rep.int(0L, nrow(x)),
  logp.z = function(z) rep.int(0L, nrow(z)),
  x0,
  z0 = NULL,
  fixedx = FALSE,
  missing = 0,
  dt = NULL,
  zenith = 96
)

groupedThresholdModel0(
  twilight,
  rise,
  group,
  twilight.model = c("Gamma", "LogNormal", "Normal", "ModifiedGamma",
    "ModifiedLogNormal"),
  alpha,
  logp.x = function(x) rep.int(0L, nrow(x)),
  logp.z = function(z) rep.int(0L, nrow(z)),
  fixedx = FALSE,
  missing = 0,
  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.
`logp.x`	function to evaluate any additional contribution to the log posterior from the twilight locations.
`logp.z`	function to evaluate any additional contribution to the log posterior from the intermediate locations.
`x0`	suggested starting points for twilight locations.
`z0`	suggested starting points for intermediate locations.
`fixedx`	logical vector indicating which twilight locations to hold fixed.
`missing`	integer vector indicating which twilights were unobserved and why.
`dt`	time intervals for speed calculation in hours.
`zenith`	the solar zenith angle that defines twilight.
`group`	integer vector that defines the twilight groups. If codegroup[k]==j then the k-th twilight occurs at location j.

Details

Stella and Estelle require a model structure that describes the model being fitted. These function generate basic model structures for threshold twilight data that should provide a suitable starting point for most analyses.

The thresholdModel function constructs a model structure assuming that each twilight time is associated with a single location, while the groupedThresholdModel function allows multiple twilight times to be 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 either a vector of parameters that are to be applied to each twilight, or a matrix of parameters with one row for 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 'LogNormal' and 'Gamma' models forbid negative errors, that is, the observed light cannot be brighter than expected. There are modified variants of these models for which negative errors are extremely unlikely, but not forbidden, and can be used to generate suitable initialization locations for their unmodified counterparts.

The initialization locations x0 and z0 must be consistent with the chosen twilight model. That is, if 'LogNormal' or 'Gamma' models are selected, the x0 cannot yield negative twilight errors.

Both Estelle and Stella variants of the model assume that the average speed of travel between successive locations is Gamma distributed, and for Estelle models, the change in bearing (degrees) along the dog-leg path segments can be assumed Normally distributed with mean zero. 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.

If beta is a vector, then beta[1] and beta[2] specify the shape and rate of the Gamma distribution of speeds. If beta has three elements, then beta[3] specifies the standard deviation of the change in bearing (in degrees) along dog leg paths.

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 approaximate 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.

The thresholdModel0 and groupedThresholdModel0 functions construct the non-movement elements of the model, and the movement elements of the model are constructed by the speedGammaModel function.

Value

a list with components

`logpx`	function to evaluate the contributions to the log posterior from the twilight model
`logpz`	function to evaluate the contributions to the log posterior from the prior for the z locations
`estelle.logpb`	function to evaluate contribution to the log posterior from the behavioural model for estelle.
`stella.logpb`	function to evaluate contribution to the log posterior from the behavioural model for stella.
`residuals`	function to evaluate the twilight model residuals.
`fixedx`	a logical vector indicating which locations should remain fixed.
`x0`	an array of initial twilight locations.
`z0`	an array of initial intermediate locations.
`time`	the twilight times.
`rise`	the sunrise indicators.
`group`	the grouping vector.