kftrack {kftrack}R Documentation

Kalman filter tracking (of tagged individuals)

Description

Fit a state space model to observed geo–locations via the extended Kalman filter. A few variations of the model is available.

Usage

kftrack(data, fix.first=TRUE, fix.last=TRUE, 
  theta.active=c(u.active, v.active, D.active, bx.active, by.active, 
                 sx.active, sy.active, a0.active, b0.active, vscale.active), 
  theta.init=c(u.init, v.init, D.init, bx.init, by.init, sx.init, sy.init, 
               a0.init, b0.init, vscale.init), 
  u.active=TRUE, v.active=TRUE, D.active=TRUE, bx.active=TRUE, 
  by.active=TRUE, sx.active=TRUE, sy.active=TRUE, a0.active=TRUE, 
  b0.active=TRUE, vscale.active=TRUE, u.init=0, v.init=0, D.init=100, 
  bx.init=0, by.init=0, sx.init=.5, sy.init=1.5, a0.init=0.001, b0.init=0, 
  vscale.init=1, var.struct="solstice", dev.pen=0.0, save.dir=NULL, admb.string="")

Arguments

data A data.frame consisting of five columns. The first three columns should contain day, month and year corresponding to valid dates. The dates must be sorted in ascending order. Column four and five should contain the longitude and latitude in degrees. A valid data set example is supplied as part of the package (see big.241).
fix.first TRUE (default) if the first position in the data set is the true release position (known without error), FALSE otherwise.
fix.last TRUE (default) if the last position in the data set is the true recapture/popoff position (known without error), FALSE otherwise.
theta.active A logical vector with nine elements, each corresponding to a model parameter. If an element is set to TRUE the value of corresponding parameter is optimized, otherwise it is kept at its initial value. The default value is TRUE for all parameters. The values 1/0 can be used instead of TRUE/FALSE. The order of the elements in this vector is c(u.active, v.active, D.active, bx.active, by.active, sx.active, sy.active, a0.active, b0.active), hence a value of c(0,0,1,1,1,1,1,1,1) would result in a model where u and v were fixed at there initial values.
theta.init A numeric vector with nine elements, each corresponding to a model parameter. The order of the elements in this vector is c(u.init, v.init, D.init, bx.init, by.init, sx.init, sy.init, a0.init, b0.init) and the default value is c(0, 0, 100, 0, 0, 0.5, 1.5, 0.001, 0). It is unwise to initialize elements D.init, sx.init and sy.init below zero, as they correspond to standard deviations.
u.active TRUE (default) if u should be optimized, FALSE if it should be fixed at its initial value.
v.active TRUE (default) if v should be optimized, FALSE if it should be fixed at its initial value.
D.active TRUE (default) if D should be optimized, FALSE if it should be fixed at its initial value.
bx.active TRUE (default) if b[x] should be optimized, FALSE if it should be fixed at its initial value.
by.active TRUE (default) if b[y] should be optimized, FALSE if it should be fixed at its initial value.
sx.active TRUE (default) if sigma[x] should be optimized, FALSE if it should be fixed at its initial value.
sy.active TRUE (default) if sigma[y] should be optimized, FALSE if it should be fixed at its initial value.
a0.active If the variance structure var.struct="solstice" is chosen this flag should be set to TRUE (default) if a[0] should be optimized, FALSE if it should be fixed at its initial value. If a different variance structure is selected this flag is ignored.
b0.active If the variance structure var.struct="solstice" is chosen this flag should be set to TRUE (default) if b[0] should be optimized, FALSE if it should be fixed at its initial value. If a different variance structure is selected this flag is ignored.
vscale.active If the variance structure var.struct="specified" and this is TRUE a common scaling parameter is estimated for the specified covariance matrices
u.init The initial value of u. Default is 0.
v.init The initial value of v. Default is 0.
D.init The initial value of D. Default is 100.
bx.init The initial value of b[x]. Default is 0.
by.init The initial value of b[y]. Default is 0.
sx.init The initial value of sigma[x]. Default is 0.5.
sy.init The initial value of sigma[y]. Default is 1.5.
a0.init If the variance structure var.struct="solstice" is chosen this sets the initial value of a[0]. Default is 0.001. If a different variance structure is selected this is ignored.
b0.init If the variance structure var.struct="solstice" is chosen this sets the initial value of b[0]. Default is 0. If a different variance structure is selected this is ignored.
vscale.init Initial value for the common scaling parameter for the specified covariance matrices
var.struct Four options are available: "uniform", "specified", "solstice"(default) and "daily". These are defined in the details section.
dev.pen If var.struct="daily" is set, this parameter sets the derivative penalty.
save.dir NULL (default) if the estimation should be done in a temporary directory, otherwise the quoted name of the directory where the estimation should be saved.
admb.string Additional command line arguments to the underlying AD Model Builder program can be passed as a string. For instance "-est". The available command line arguments can be found in the AD Model Builder documentation (see http://otter-rsch.com)

Details

The model is a state space model, where the state equation is describing the movements of a fish in an axis–parallel plane. A random walk model is assumed:

alpha[i] = alpha[i-1]+c[i]+eta[i], i=1,...,T

Here alpha[i] is a two dimensional vector containing the coordinates at time t[i], c[i] is the drift vector describing the deterministic part of the movement, and eta[i] is the noise vector a describing the random part of the movement. The deterministic part of the movement is assumed to be proportional to time:

c[i] = ( u(t[i]-t[i-1]), v(t[i]-t[i-1]) )'

The random part is assumed to be serially uncorrelated and follow a two dimensional Gaussian distribution with mean vector 0 and covariance matrix Q[i], where

Q[i] = 2D(t[i]-t[i-1])I, (here `I' is the 2x2 unit matrix)

The measurement equation of the state space model is a non–linear mapping of the coordinates on the axis–parallel plane on to the sphere. The original coordinates were in Nautical miles and the coordinates on the sphere are in degrees of longitude and latitude. The measurement equation describing the actual position y[i] is:

y[i]=z(alpha[i])+d[i]+epsilon[i], i=1,...,T

where z is the coordinate change function given by:

z(alpha[i]) = ( alpha[i,1]/(60cos(alpha[i,2]PI/180/60)) , alpha[i,2]/60 )'

d[i] is the observed bias:

d[i]=( b[x] , b[y] )'

and epsilon[i] is the measurement error which is assumed to follow a Gaussian distribution with mean vector 0 and covariance matrix H[i], where

H[i]=diag(sigma[x]^2, sigma[y[i]]^2)

The arguments u.active, v.active, D.active, bx.active, by.active, sx.active and sy.active offers an alternative way of specifying the argument vector theta.active. This is useful for two reasons. Firstly, if only a few of the elements of theta.active is changed from their defaults, it is convenient not having to specify the entire vector. Secondly, it is not required to remember the correct order of the arguments in theta.active, if they are specified individually. If theta.active is specified any individually specified arguments are ignored and the values of theta.active is used.

Similarly the arguments u.init, v.init, D.init, bx.init, by.init, sx.init and sy.init offers an alternative way of specifying the argument vector theta.init.

The argument var.struct sets the model for the latitude error sigma[y[i]]^2. Three options are available.

If "uniform" the same variance is assumed for all observations.

If "solstice" the variance is assumed to follow the model:

sigma[y[i]]^2 = sigma[y[0]]^2 / (cos^2(2pi(J[i]+(-1)^(s[i])b[0])/365.25)+a[0])

where J[i] is the number of days since last solstice prior to all observations, s[i] is the season number since the beginning of the track (one for the first 182.625 days, then two for the next 182.625, then three and so on). a[0], b[0] and sigma[y[0]]^2 are model parameters.

If "daily" the variance is assumed to have a different value at each time step, and psi[i] are normally distributed random variables with mean zero and variance sigma[psi]^2 representing transient deviations in the latitude error.

Value

An object of class kftrack is returned. This object contains information about the fit and estimated tracks.

Author(s)

John Sibert jsibert@soest.hawaii.edu, Anders Nielsen anielsen@dina.kvl.dk

References

Sibert, J., Musyl, M. K. and Brill, R.W. (2002) Horizontal movements of bigeye tuna near Hawaii determined by Kalman filter analysis of archival tagging data. Fish. Oceanogr. In press(?):??–??.

See Also

plot.kftrack

Examples

data(big.241)
fit<-kftrack(big.241, fix.last=FALSE)
plot(fit)

[Package kftrack version 0.70 Index]