kftrack {kftrack} | R Documentation |
Fit a state space model to observed geo–locations via the extended Kalman filter. A few variations of the model is available.
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="")
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) |
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.
An object of class kftrack
is returned. This object contains
information about the fit and estimated tracks.
John Sibert jsibert@soest.hawaii.edu, Anders Nielsen anielsen@dina.kvl.dk
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(?):??–??.
data(big.241) fit<-kftrack(big.241, fix.last=FALSE) plot(fit)