Package ‘KFAS’ · Title Kalman Filter and Smoother for Exponential Family State Space ... State Space Models Description Package KFAS contains ... diffuse initialization

Package ‘KFAS’February 15, 2013

Version 0.9.11

Date 2012-07-09

Title Kalman Filter and Smoother for Exponential Family State Space Models.

Author Jouni Helske <[email protected]>

Maintainer Jouni Helske <[email protected]>

Depends R (>= 2.15.0)

Description Package KFAS provides functions for Kalman filtering,smoothing, forecasting and simu-lation of Gaussian, Poisson and Binomial state space models with exact diffuse initializationwhen distributions of some or all elements of initial state vector are unknown.

License GPL (>= 2)

Repository CRAN

Date/Publication 2012-07-09 09:29:46

NeedsCompilation yes

R topics documented:+.SSModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2approxSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2arimaSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3boat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5fitSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5GlobalTemp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6importanceSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7KFAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8KFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12ldl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15logLik.SSModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15plot.approxSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16plot.KFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

1

2 approxSSM

predict.KFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17print.KFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18print.SSModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18regSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19residuals.KFS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21simulateSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21SSModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22structSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24transformSSM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Index 28

+.SSModel Combine State Space Model Objects of class SSModel

Description

Second model needs to have either only duplicate time series with first model, or no identical seriesat all.

Usage

## S3 method for class ’SSModel’e1 + e2

Arguments

e1 ,

e2 Models to be combined.

Value

model Combined model.

approxSSM Linear Gaussian Approximation for Non-Gaussian State Space Model

Description

Function approxSMM computes the linear Gaussian approximation of a state space model wherethe observations have a non-Gaussian exponential family distribution. Currently only Poisson andBinomial distributions are supported.

Usage

approxSSM(object, theta = NULL, maxiter = 100)

arimaSSM 3

Arguments

object Non-Gaussian state space model object of class SSModel.

theta Initial values for conditional mode theta. Default is log(mean(y/u)) for Pois-son and log(mean(y/(u-y))) for Binomial distribution (or log(mean(y)) incase of ut − yt = 0 for some t).

maxiter Maximum number of iterations used in linearisation. Default is 100.

Details

The linear Gaussian approximating model is a model defined by

yt = Ztαt + εt, εt ∼ N(0, Ht),

αt+1 = Ttαt +Rtηt, ηt ∼ N(0, Qt),

and α1 ∼ N(a1, P1), where y and H is chosen in a way that the linear Gaussian approximatingmodel has the same conditional mode of θ = Zα given the observations y as the original non-Gaussian model. Models also have same curvature at the mode.

The linearization of the exponential family state space model is based on the first two derivatives ofthe observational logdensity.

The approximating Gaussian model is used in computation of the log-likelihood of the non-Gaussianmodel and in importance sampling of non-Gaussian model.

Value

An object which contains the approximating Gaussian state space model with additional compo-nents original.distribution, original.y, thetahat, and iterations (the number of itera-tions used).

See Also

Importance sampling of non-Gaussian state space models importanceSSM, construct a SSModelobject SSModel.

arimaSSM Create a State Space Representation of ARIMA Model

Description

Function arimaSSM creates a state space representation of ARIMA model.

Usage

arimaSSM(y, arima, H = NULL, Q = NULL, u = NULL,distribution = c("Gaussian", "Poisson", "Binomial"),transform = c("none", "ldl", "augment"),tolF = .Machine$double.eps^0.5,tol0 = .Machine$double.eps^0.5)

4 arimaSSM

Arguments

arima A list or a list of lists with components ar, ma and d, giving the autoregres-sion and moving average coefficients, and the degree of differencing for eachseries. If arima is a single list, it is assumed that all p series have same ARIMAstructure. Otherwise first sublist gives the ARIMA structure of the first seriesetc.

H A p × p covariance matrix (or p × p × n array in of time-varying case) of thedisturbance terms εt of the observation equation. Default gives p×p zero matrixie. ordinary ARIMA model without additional noise. Omitted in case of non-Gaussian distributions. Augment the state vector if you to add want additionalnoise.

Q A p × p covariance matrix of the disturbance terms ηt of the system equation.Default is p × p identity matrix ie. ordinary ARIMA model with disturbanceterms having unit variance.

y A time series object of class ts, or a object that can be coerced to such.u Only used with non-Gaussian distribution. See details.distribution Specify the distribution of the observations. Default is "Gaussian".transform The functions of KFAS require diagonal covariance matrix Ht. If Ht is not di-

agonal, model can be transformed using one of the two options. Option "ldl"performs LDL decomposition for covariance matrix Ht, and multiplies the ob-servation equation with the L−1t , so εt ∼ N(0, Dt). Option "augment" addsεt to the state vector, when Qt becomes block diagonal with blocks Qt and Ht.In case of univariate series, option "ldl" only changes the H_type argument ofthe model to "Diagonal". Default is "none" which does no transformation butchecks if H is diagonal. If not, H_type is set to "Untransformed".

tolF Tolerance parameter for Finf. Smallest value not counted for zero.tol0 Tolerance parameter for LDL decomposition, determines which diagonal values

are counted as zero.

Details

The linear Gaussian state space model is given by

yt = Ztαt + εt,

αt+1 = Ttαt +Rtηt,

where εtÑ(0, Ht), ηtÑ(0, Qt) and α1Ñ(a1, P1) independently of each other. In case of non-Gaussian observations, the observation equation is of form p(yt|θt) = p(yt|Ztαt), with p(yt|θt)being one of the following:

If observations are Poisson distributed, parameter of Poisson distribution is utλt and θt = log(λt).

If observations are from binomial distribution, u is a vector specifying number the of trials at times1, . . . , n, and θt = log[πt/(1− πt)], where πt is the probability of success at time t.

For non-Gaussian models ut = 1 as a default. For Gaussian models, parameter is omitted.

Only univariate observations are supported when observation equation is non-Gaussian.

boat 5

See Also

regSSM for state space representation of a regression model, structSSM for structural time seriesmodel, and SSModel for custom SSModel object.

boat Oxford-Cambridge boat race results 1829-2000

Description

Results of the annual boat race between universities of Oxford (0) and Cambridge (1).

Format

An time series object containing 172 observations.

Source

http://www.ssfpack.com/DKbook.html

References

Koopman, S.J. and Durbin J. (2001). Time Series Analysis by State Space Methods. Oxford:Oxford University Press.

fitSSM Maximum Likelihood Estimation of a State Space Model

Description

Function fitSSM finds the maximum likelihood estimates for unknown parameters of an arbitarystate space model if an user defined model building function is defined. As a default, fitSSMestimates the non-zero elements, which are marked as NA, of the time-invariant covariance matricesH and Q of the given model.

Usage

fitSSM(inits, model = NULL, modFun = NULL,method = "BFGS", nsim = 0, antithetics = TRUE,taylor = TRUE, theta = NULL, maxiter = 500, ...)

6 GlobalTemp

Arguments

inits Initial values for optim

model Model object of class SSModel. if ModFun is defined, this argument is ignored.

modFun User defined function which builds the model of class SSModel given the pa-rameters. If NULL, default estimation procedure is used (See details).

method The method to be used in optim. Default is "BFGS".

nsim Number of independent samples used in estimating the log-likelihood of thenon-gaussian state space object. Default is 0, which gives good starting valuefor optimisation. Only used in case of non-Gaussian state space model.

antithetics Logical. If TRUE, two antithetic variables are used in simulations, one for loca-tion and another for scale. Default is TRUE. Only used in case of non-Gaussianstate space model.

taylor Logical. If TRUE, control variable based on Taylor approximation is used. De-fault is TRUE. Only used in case of non-Gaussian state space model.

theta Initial values for conditional mode theta. Default is object$y. Only used incase of non-Gaussian state space model.

maxiter Maximum number of iterations used in linearisation. Only used in case of non-Gaussian state space model.

... Optional arguments for functions optim and modFun.

Value

A list with elements

optim.out Output from function optim.

model Model with estimated parameters.

GlobalTemp Two series of average global temperature deviations for years 1880-1987

Description

This data set contains two series of average global temperature deviations for years 1880-1987.These series are same as used in Shumway and Stoffer (2006), where they are known as HL andFolland series. For more details, see Shumway and Stoffer (2006, p. 327).

Format

An time series object containing 108 times 2 observations.

Source

http://lib.stat.cmu.edu/general/stoffer/tsa2/

importanceSSM 7

References

Shumway, Robert H. and Stoffer, David S. (2006). Time Series Analysis and Its Applications: WithR examples.

importanceSSM Importance Sampling of Non-Gaussian State Space Model

Description

Importance Sampling of Non-Gaussian State Space Model.

Usage

importanceSSM(model, nsim = 1000, save.model = FALSE,theta = NULL, antithetics = TRUE, maxiter = 100)

Arguments

model Non-Gaussian state space model object of class SSModel.

nsim Number of independent samples. Default is 1000.

save.model Return the original model with the samples. Default is FALSE.

theta Initial values for conditional mode theta. Default is log(mean(y/u)) for Pois-son and log(mean(y/(u-y))) for Binomial distribution (or log(mean(y)) incase of ut − yt = 0 for some t).

antithetics Logical. If TRUE, two antithetic variables are used in simulations, one for loca-tion and another for scale. Default is TRUE.


Details

Function importanceSSM simulates states of the non-Gaussian state space model conditioned withthe observations, returning the simulated samples of the states with the importance weights.

8 KFAS

KFAS KFAS: Functions for Gaussian and Non-Gaussian State Space Models

Description

Package KFAS contains functions for Kalman filtering, smoothing and simulation of linear statespace models with exact diffuse initialization.

Details


yt = Ztαt + εt,


where εt ∼ N(0, Ht), ηt ∼ N(0, Qt) and α1 ∼ N(a1, P1) independently of each other.

All system and covariance matrices Z, H, T, R and Q can be time-varying, and partially or totallymissing observations yt are allowed.

Covariance matrices H and Q has to be positive semidefinite.

Dimensions of system matrices are

Z p×m× 1 or p×m× n in time varying caseH p× p× 1 or p× p× n in time varying caseT m×m× 1 or m×m× n in time varying caseR m× k × 1 or m× k × n in time varying caseQ k × k × 1 or k × k × n in time varying case

In case of non-Gaussian observations, the observation equation is of form

p(yt|θt) = p(yt|Ztαt)

with p(yt|θt) being one of the following:

If observations yt are Poisson distributed, parameter of Poisson distribution is utλt and θt =log(λt), where ut is so called offset term.

If observations eqny_ty[t] are from binomial distribution, u is a vector specifying number the oftrials at times 1, . . . , n, and θt = log[πt/(1− πt)], where πt is the probability of success at time t.



For the unknown elements of initial state vector a1, KFS uses exact diffuse initialization by Koop-man and Durbin (2000, 2001, 2003), where the unknown initial states are set to have a zero mean

KFAS 9

and infinite variance, soP1 = P∗,1 + κP∞,1,

with κ going to infinity and P∞,1 being diagonal matrix with ones on diagonal elements corre-sponding to unknown initial states.

Diffuse phase is continued until rank of P∞,t becomes zero. Rank of P∞ decreases by 1, if F∞ >tolF > 0. Usually the number of diffuse time points equals the number unknown elements of initialstate vector, but missing observations or time-varying Z can affect this. See Koopman and Durbin(2000, 2001, 2003) for details for exact diffuse and non-diffuse filtering.

To lessen the notation and storage space, KFAS uses letters P, F and K for non-diffuse part of thecorresponding matrices, omitting the asterisk in diffuse phase.

All functions of KFAS use the univariate approach (also known as sequential processing, see Ander-son and Moore (1979)) which is from Koopman and Durbin (2000, 2001). In univariate approachthe observations are introduced one element at the time. Therefore the prediction error variancematrices F and Finf does not need to be non-singular, as there is no matrix inversions in univariateapproach algorithm. This provides more stable and possibly more faster filtering and smoothingthan normal multivariate Kalman filter algorithm. If covariance matrix H is not diagonal, it is possi-ble to transform the model by either using LDL decomposition on H, or augmenting the state vectorwith ε disturbances. See transformSSM for more details.

References

Koopman, S.J. and Durbin J. (2000). Fast filtering and smoothing for non-stationary time seriesmodels, Journal of American Statistical Assosiation, 92, 1630-38.

Koopman, S.J. and Durbin J. (2001). Time Series Analysis by State Space Methods. Oxford:Oxford University Press.

Koopman, S.J. and Durbin J. (2003). Filtering and smoothing of state vector for diffuse state spacemodels, Journal of Time Series Analysis, Vol. 24, No. 1. #’ Shumway, Robert H. and Stoffer, DavidS. (2006). Time Series Analysis and Its Applications: With R examples.

Examples

library(KFAS)

# Example of local level model for Nile series

y<-NilemodelNile<-structSSM(y=y)

fit<-fitSSM(inits=c(0.5*log(var(Nile)),0.5*log(var(Nile))),model=modelNile)# Filtering and state smoothingkfsNile<-KFS(fit$model,smoothing="state")# Simple plot of series and the smoothed signal = Z*alphahatplot(kfsNile,col=1:2)

# Confidence intervals for the statelows<-c(kfsNile$alphahat-qnorm(0.95)*sqrt(c(kfsNile$V)))

10 KFAS

ups<-c(kfsNile$alphahat+qnorm(0.95)*sqrt(c(kfsNile$V)))plot.ts(cbind(y,c(kfsNile$alphahat),lows,ups), plot.type="single", col=c(1:2,3,3),

ylab="Predicted Annual flow", main="River Nile")

# Missing observations, using same parameter estimates

y<-Niley[c(21:40,61:80)]<-NAmodelNile<-structSSM(y=y,H=fit$model$H,Q.level=fit$model$Q)

kfsNile<-KFS(modelNile,smoothing="state")

# Filtered stateplot.ts(cbind(y,c(NA,kfsNile$a[,-c(1,101)])), plot.type="single", col=c(1:2,3,3),


# Smoothed stateplot.ts(cbind(y,c(kfsNile$alp)), plot.type="single", col=c(1:2,3,3),


# Prediction of missing observationspredictNile<-predict(kfsNile)lows<-predictNile$y-qnorm(0.95)*sqrt(c(predictNile$F))ups<-predictNile$y+qnorm(0.95)*sqrt(c(predictNile$F))

plot.ts(cbind(y,predictNile$y,lows,ups), plot.type="single", col=c(1:2,4,4),ylab="Predicted Annual flow", main="River Nile")

# Example of multivariate local level model with only one state# Two series of average global temperature deviations for years 1880-1987# See Shumway and Stoffer (2006), p. 327 for details

data(GlobalTemp)

modelTemp<-SSModel(y=GlobalTemp, Z = matrix(1,nrow=2), T=1, R=1, H=matrix(NA,2,2),Q=NA, a1=0, P1=0, P1inf=1)

# Estimating the variance parameters

fit<-fitSSM(inits=c(0.5*log(.1),0.5*log(.1),0.5*log(.1),0),model=modelTemp)

outTemp<-KFS(fit$model,smooth="both")

ts.plot(cbind(modelTemp$y,t(outTemp$alphahat)),col=1:3)legend("bottomright",legend=c(colnames(GlobalTemp), "Smoothed signal"), col=1:3, lty=1)

# Example of multivariate series where first series follows stationary ARMA(1,1)

KFAS 11

# process and second stationary AR(1) process.

y1<-arima.sim(model=list(ar=0.8,ma=0.3), n=100, sd=0.5)

model1<-arimaSSM(y=y1,arima=list(ar=0.8,ma=0.3),Q=0.5^2)

y2<-arima.sim(model=list(ar=-0.5), n=100)

model2<-arimaSSM(y=y2,arima=list(ar=-0.5))

model<-model1+model2

# Another way:

modelb<-arimaSSM(y=ts.union(y1,y2),arima=list(list(ar=0.8,ma=0.3),list(ar=-0.5)),Q=diag(c(0.5^2,1)))

f.out<-KFS(model)

# Driversmodel<-structSSM(y=log(Seatbelts[,"drivers"]),trend="level",seasonal="time",

X=cbind(log(Seatbelts[,"kms"]),log(Seatbelts[,"PetrolPrice"]),Seatbelts[,c("law")]))fit<-fitSSM(inits=rep(-1,3),model=model)out<-KFS(fit$model,smoothing="state")

plot(out,lty=1:2,col=1:2,main="Observations and smoothed signal with and without seasonal component")lines(signal(out,states=c(1,13:15))$s,col=4,lty=1)legend("bottomleft",legend=c("Observations", "Smoothed signal","Smoothed level"), col=c(1,2,4), lty=c(1,2,1))

# Multivariate model with constant seasonal pattern in frequency domain

model<-structSSM(y=log(Seatbelts[,c("front","rear")]),trend="level",seasonal="freq",X=cbind(log(Seatbelts[,c("kms")]),log(Seatbelts[,"PetrolPrice"]),Seatbelts[,"law"]),H=NA,Q.level=NA,Q.seasonal=0)

sbFit<-fitSSM(inits=rep(-1,6),model=model)

out<-KFS(sbFit$model,smoothing="state")

ts.plot(signal(out,states=c(1:2,25:30))$s,model$y,col=1:4)

# Poisson modelmodel<-structSSM(y=Seatbelts[,"VanKilled"],trend="level",seasonal="time",X=Seatbelts[,"law"],

distribution="Poisson")

# Estimate variance parametersfit<-fitSSM(inits=rep(0.5*log(0.005),2), model=model)

model<-fit$model# Approximating model, gives also the conditional mode of thetaamod<-approxSSM(model)

12 KFS

out.amod<-KFS(amod,smoothing="state")

# State smoothing via importance samplingout<-KFS(model,nsim=1000)

# Observations with exp(smoothed signal) computed by# importance sampling in KFS, and by approximating modelts.plot(cbind(model$y,out$yhat,exp(amod$theta)),col=1:3) # Almost identical

# It is more interesting to look at the smoothed values of exp(level + intervention)lev1<-exp(signal(out,states=c(1,13))$s)lev2<-exp(signal(out.amod,states=c(1,13))$s)# These are slightly biased as E[exp(x)] > exp(E[x]), better to use importance sampling:vansample<-importanceSSM(model,save.model=FALSE,nsim=250)# nsim is number of independent samples, as default two antithetic variables are used,# so total number of samples is 1000.

w<-vansample$weights/sum(vansample$weights)level<-colSums(t(exp(vansample$states[1,,]+model$Z[1,13,]*vansample$states[13,,]))*w)ts.plot(cbind(model$y,lev1,lev2,level),col=1:4) #’ Almost identical results

# Confidence intervals (no seasonal component)

varlevel<-colSums(t(exp(vansample$states[1,,]+model$Z[1,13,]*vansample$states[13,,])^2)*w)-level^2intv<-level + qnorm(0.975)*varlevel%o%c(-1,1)ts.plot(cbind(model$y,level,intv),col=c(1,2,3,3))

# Simulation error

# Mean estimation error of the single draw with 2 antitheticslevel2<-t(exp(vansample$states[1,,1:250]+model$Z[1,13,]*vansample$states[13,,1:250])-level)*w[1:250]+

t(exp(vansample$states[1,,251:500]+model$Z[1,13,]*vansample$states[13,,251:500])-level)*w[251:500]+t(exp(vansample$states[1,,501:750]+model$Z[1,13,]*vansample$states[13,,501:750])-level)*w[501:750]+t(exp(vansample$states[1,,751:1000]+model$Z[1,13,]*vansample$states[13,,751:1000])-level)*w[751:1000]

varsim<-colSums(level2^2)ts.plot(sqrt(varsim/varlevel)*100)

# Same without antithetic variablesvansamplenat<-importanceSSM(model,save.model=FALSE,nsim=1000,antithetics=FALSE)w<-vansamplenat$weights/sum(vansamplenat$weights)levelnat<-colSums(t(exp(vansamplenat$states[1,,]+

model$Z[1,13,]*vansamplenat$states[13,,]))*w)varsimnat<-colSums((t(exp(vansamplenat$states[1,,]+

model$Z[1,13,]*vansamplenat$states[13,,])-levelnat)*w)^2)varlevelnat<-colSums(t(exp(vansamplenat$states[1,,]+

model$Z[1,13,]*vansamplenat$states[13,,])^2)*w)-levelnat^2ts.plot(sqrt(varsimnat/varlevelnat)*100)ts.plot((sqrt(varsimnat)-sqrt(varsim))/sqrt(varsimnat)*100)

KFS 13

KFS Kalman Filter and Smoother with Exact Diffuse Initialization for Ex-ponential Family State Space Models

Description

Performs Kalman filtering and smoothing with exact diffuse initialization using univariate approachfor exponential family state space models. For non-Gaussian models, state smoothing is providedwith additional smoothed mean and variance of observations.

Usage

KFS(object,smoothing = c("state", "disturbance", "both", "none"),simplify = TRUE, transform = c("ldl", "augment"),nsim = 100, theta = NULL, maxiter = 100)

Arguments

object Object of class SSModel or KFS (in which case only smoothing is performed).

smoothing Perform state or disturbance smoothing or both. Default is "state" for Gaus-sian models. For non-Gaussian models, state smoothing is always performed.

simplify If FALSE, KFS returns some generally not so interesting variables from filteringand smoothing. Default is TRUE.

transform How to transform the model in case of non-diagonal covariance matrix H . De-faults to "ldl". See function transformSSM for details.

nsim Number of independent samples. Default is 100. Only used for non-Gaussianmodel.

theta Initial values for conditional mode theta. Default is log(mean(y/u)) for Pois-son and log(mean(y/(u-y))) for Binomial distribution (or log(mean(y)) incase of ut − yt = 0 for some t). Only used for non-Gaussian model.

maxiter Maximum number of iterations used in linearisation. Default is 100. Only usedfor non-Gaussian model.

Details

Notice that in case of multivariate observations, v, F, Finf, K and Kinf are usually not the same asthose calculated in usual multivariate Kalman filter. As filtering is done one observation element atthe time, the elements of prediction error vt are uncorrelated, and F, Finf, K and Kinf contain onlythe diagonal elemens of the corresponding covariance matrices.

In rare cases of a very long diffuse initialization phase with highly correlated states, cumulativerounding errors in computing Finf and Pinf can sometimes cause the diffuse phase end too early.Changing the tolerance parameter tolF to smaller (or larger) should help.

14 KFS

Value

For Gaussian model, a list with the following components:

model Original state space model.KFS.transform Type of H after possible transformation.logLik Value of the log-likelihood function.a One step predictions of states, at = E(αt|yt−1, . . . , y1).P Covariance matrices of predicted states, Pt = Cov(αt|yt−1, . . . , y1).Pinf Diffuse part of Pt.v Prediction errors vi,t = yi,t − Zi,tai,t, i = 1, . . . , p,

where ai,t = E(αt|yi−1,t, . . . , y1,t, . . . , y1,1).F Prediction error variances V ar(vt).Finf Diffuse part of Ft.d The last index of diffuse phase, i.e. the non-diffuse phase began from time d+1.j The index of last yi,t of diffuse phase.alphahat Smoothed estimates of states,E(αt|y1, . . . , yn). Only computed if smoothing="state"

or smoothing="both".V Covariances V ar(αt|y1, . . . , yn).Only computed if smoothing="state" or smoothing="both".etahat Smoothed disturbance termsE(ηt|y1, . . . , yn).Only computed if smoothing="disturbance"

or smoothing="both".V_eta Covariances V ar(ηt|y1, . . . , yn). Only computed if smoothing="disturbance"

or smooth="both".epshat Smoothed disturbance termsE(εt|y1, . . . , yn). Only computed if smoothing="disturbance"

or smoothing="both".V_eps Diagonal elements of V ar(εt|y1, . . . , yn). Note that due to the diagonalization,

off-diagonal elements are zero. Only computed if smoothing="disturbance"or smoothing="both".

In addition, if argument simplify=FALSE, list contains following components:

K Covariances Cov(αt,i, yt,i|yi−1,t, . . . , y1,t, yt−1, . . . , y1), i = 1, . . . , p.Kinf Diffuse part of Kt.r Weighted sums of innovations vt+1, . . . , vn. Notice that in literature t in rt goes

from 0, . . . , n. Here t = 1, . . . , n+ 1. Same applies to all r and N variables.r0, r1 Diffuse phase decomposition of rt.N Covariances V ar(rt) .N0, N1, N2 Diffuse phase decomposition of Nt.

For non-Gaussian model, a list with the following components:

model Original state space model with additional elements from function approxSSM.alphahat Smoothed estimates of states E(αt|y1, . . . , yn).V Covariances V ar(αt|y1, . . . , yn).yhat A time series object containing smoothed means of observation distributions,

with parameter utexp(θt) for Poisson and utexp(θt)/(1 + exp(θt)).V.yhat a vector of length containing smoothed variances of observation distributions.

ldl 15

References

Koopman, S.J. and Durbin J. (2000). Fast filtering and smoothing for non-stationary time seriesmodels, Journal of American Statistical Assosiation, 92, 1630-38.

Koopman, S.J. and Durbin J. (2001). Time Series Analysis by State Space Methods. Oxford: Ox-ford University Press.

Koopman, S.J. and Durbin J. (2003). Filtering and smoothing of state vector for diffuse state spacemodels, Journal of Time Series Analysis, Vol. 24, No. 1.

ldl LDL Decomposition of a Matrix

Description

Function ldl computes the LDL decomposition of a symmetric matrix.

Usage

ldl(x, tol = .Machine$double.eps^0.5)

Arguments

x Symmetrix matrix.

tol Tolerance parameter for LDL decomposition, determines which diagonal valuesare counted as zero.

logLik.SSModel Log-likelihood of the State Space Model.

Description

Function logLik.SSmodel computes the log-likelihood value of a state-space model.

Usage

## S3 method for class ’SSModel’logLik(object, nsim = 0,

antithetics = TRUE, taylor = TRUE, theta = NULL,maxiter = 100, fix.seed = TRUE, ...)

16 plot.approxSSM

Arguments

object State space model of class SSModel.

nsim Number of independent samples used in estimating the log-likelihood of thenon-gaussian state space model. Default is 0, which gives good starting valuefor optimization. Only used for non-Gaussian model.

antithetics Logical. If TRUE, two antithetic variables are used in simulations, one for loca-tion and another for scale. Default is TRUE. Only used for non-Gaussian model.

taylor Logical. If TRUE, control variable based on Taylor series is used. Default isTRUE. Only used for non-Gaussian model.

theta Initial values for conditional mode theta. Default is log(mean(y/u)) for Pois-son and log(mean(y/(u-y))) for Binomial distribution (or log(mean(y)) incase of ut − yt = 0 for some t). Only used for non-Gaussian model.

fix.seed Use fixed seed. If FALSE, no fixed seed is used. If fix.seed is positive value,the value is used as a seed via set.seed function. Default is TRUE, so that thevariation in random number generation does not affect numerical optimizationalgorithms. Only used for non-Gaussian model.

... Ignored.


Value

log-likelihood of the state space model.

plot.approxSSM Plot Approximating Gaussian State Space Model

Description

Plot Approximating Gaussian State Space Model

Usage

## S3 method for class ’approxSSM’plot(x, y = NULL,

legend.position = "bottomright", ...)

Arguments

x approxSSM object

y Ignored.legend.position

Position of the legend as a keyword. See function legend for details.

... Graphical parameters for function plot.ts.

plot.KFS 17

plot.KFS Plot Ouput of Kalman Filter and Smoother

Description

Plot Ouput of Kalman Filter and Smoother

Usage

## S3 method for class ’KFS’plot(x, y = NULL, type = "signal", ...)

Arguments

x object of class KFS

y Ignored.

type Draw "signals" together with observations, or figures of "state" components.Default is "signal". If smoothed values of states are available, those are used.Otherwise filtered values are used.

... Graphical parameters for function plot.ts.

predict.KFS Estimate the Missing Observations of a State Space Model

Description

Function predict.KFS computes the expected values of missing observations given the observeddata.

Usage

## S3 method for class ’KFS’predict(object, fill = FALSE, ...)

Arguments

object object of class KFS ie. the output from function KFS.

fill If FALSE, only predictions of missing observations are returned, and other timepoints are markes as NA. This is convinient for plotting purposes. If TRUE,original time series is filled with predicted values for missing observations, andFt = 0 if observation is not missing. Default is FALSE.

... Ignored.

18 print.SSModel

Value

A list with the following components:

y Time series object with missing observations replaced by E(yt|y).F Covariances Cov(yt|y). Note that this is the usual multivariate version of Ft

given by ZtPtZ ′t +Ht, not the univariate version given by KFS.

print.KFS Print Ouput of Kalman Filter and Smoother

Description

Print Ouput of Kalman Filter and Smoother

Usage

## S3 method for class ’KFS’print(x, ...)

Arguments

x output object from function KFS.

... Ignored.

print.SSModel Print SSModel Object

Description

Print SSModel Object

Usage

## S3 method for class ’SSModel’print(x, ...)

Arguments

x SSModel object

... Ignored.

regSSM 19

regSSM Create a State Space Model Representation of Linear RegressionModel

Description

Function regSSM creates a state space representation of linear regression model.

Usage

regSSM(y, X, H = NULL, Q = NULL, u = NULL,distribution = c("Gaussian", "Poisson", "Binomial"),transform = c("none", "ldl", "augment"),tolF = .Machine$double.eps^0.5,tol0 = .Machine$double.eps^0.5)

Arguments

X A n × k matrix of explanatory variables, with each column containing one ex-planatory variable, or a list of length p containing X matrices for each series. IfX is matrix, it is assumed that all p series use same explanatory variables.

H A p × p covariance matrix (or p × p × n array in of time-varying case) of thedisturbance terms εt of the observation equation. Default gives p×p zero matrix.Omitted in case of non-Gaussian distributions. Augment the state vector if youwant to add additional noise.

Q A r × r (or r × r × n array in of time-varying case) covariance matrix of thedisturbance terms ηt of the system equation. Default is m ×m zero matrix ie.ordinary time-invariant regression.

y A time series object of class ts, or a object that can be coerced to such.

u Only used with non-Gaussian distribution. See details.

distribution Specify the distribution of the observations. Default is "Gaussian".

transform The functions of KFAS require diagonal covariance matrix Ht. If Ht is not di-agonal, model can be transformed using one of the two options. Option "ldl"performs LDL decomposition for covariance matrix Ht, and multiplies the ob-servation equation with the L−1t , so εt ∼ N(0, Dt). Option "augment" addsεt to the state vector, when Qt becomes block diagonal with blocks Qt and Ht.In case of univariate series, option "ldl" only changes the H_type argument ofthe model to "Diagonal". Default is "none" which does no transformation butchecks if H is diagonal. If not, H_type is set to "Untransformed".

tolF Tolerance parameter for Finf. Smallest value not counted for zero.

tol0 Tolerance parameter for LDL decomposition, determines which diagonal valuesare counted as zero.

20 residuals.KFS

Details


yt = Xtβt + εt,


where εtÑ(0, Ht), ηtÑ(0, Qt) and α1Ñ(a1, P1) independently of each other. In case of non-Gaussian observations, the observation equation is of form p(yt|θt) = p(yt|Ztαt), with p(yt|θt)being one of the following:

See Also

arimaSSM for state space representation of ARIMA model, structSSM for structural time seriesmodel, and SSModel for custom SSModel object.

residuals.KFS Extract Standardized Residuals of Kalman Filter and Smoother output

Description

Extract Standardized Residuals of Kalman Filter and Smoother output

Usage

## S3 method for class ’KFS’residuals(object, ...)

Arguments

object KFS object... Ignored.

Details

For object of class KFS, three types of residuals can be computed: Standardized one-step aheadprediction residuals are defined as

vi,t/√Fi,t, i = 1, . . . , p, t = d+ 1, . . . , n,

with residuals being undefined in diffuse phase.

Residuals based on the smoothed disturbance terms are defined as

εi,t/√V ar(εi,t), i = 1, . . . , p, t = 1, . . . , n,

andL−1t ηt, t = 1, . . . , n,

where Lt is the lower triangular matrix from Cholesky decomposition of Vη,t

signal 21

signal Extract the filtered or smoothed signal of a State Space Model

Description

Function signal extracts the filtered or smoothed signal of a State Space model depending on theinput object.

Usage

signal(object, states = NULL)

Arguments

object Object of class KFS.

states Which states are combined? Default is NULL which combines all states accord-ing to Zt.

Value

signal Time series object of filtered signal Ztat or smoothed signal Ztαt using onlythe defined states. Filtered signal is computed only for non-diffuse phase.

variance Cov(Ztat) or Cov(Ztαt) using only the defined states. Covariances of filteredsignal is computed only for non-diffuse phase.

simulateSSM Simulation of a Gaussian State Space Model

Description

Function simulateSMM simulates states, disturbances or missing observations of the Gaussian statespace object conditionally on the data.

Usage

simulateSSM(object,sim = c("states", "disturbances", "observations"),nsim = 1, antithetics = FALSE, conditional = TRUE)

22 SSModel

Arguments

object Gaussian state space object.

sim What to simulate. Note that all the simulations are done independently.

nsim Number of independent samples. Default is 1.

antithetics Use antithetic variables in simulation. Default is FALSE.

conditional Simulations are conditional to data. If FALSE, the initial state α1 is set to α1

computed by KFS, and all the observations are removed from the model. Defaultis TRUE.

Details

Simulation smoother algorithm is from article by J. Durbin and S.J. Koopman (2002).

Function can use two antithetic variables, one for location and other for scale, so output containsfour blocks of simulated values which correlate which each other (ith block correlates negativelywith (i+1)th block, and positively with (i+2)th block etc.).

References

Durbin J. and Koopman, S.J. (2002). A simple and efficient simulation smoother for state spacetime series analysis, Biometrika, Volume 89, Issue 3

SSModel Create a State Space Model Object of class SSModel

Description

Function SSModel creates a state space object object of class SSModel which can be used as an inputobject for various functions of KFAS package.

Usage

SSModel(y, Z = NULL, H = NULL, T = NULL, R = NULL,Q = NULL, a1 = NULL, P1 = NULL, P1inf = NULL, u = NULL,distribution = c("Gaussian", "Poisson", "Binomial"),transform = c("none", "ldl", "augment"),tolF = .Machine$double.eps^0.5,tol0 = .Machine$double.eps^0.5)

Arguments


Z System matrix or array of observation equation.

H Covariance matrix or array of disturbance terms εt of observation equation.Omitted in case of non-Gaussian distributions. Augment the state vector if youwant to add additional noise.

SSModel 23

T System matrix or array of transition equation.

R System matrix or array of transition equation.

Q Covariance matrix or array of disturbance terms ηt.

a1 Expected value of the initial state vector α1.

P1 Covariance matrix of α1. In the diffuse case the non-diffuse part of P1.

P1inf Diffuse part of P1. Diagonal matrix with ones on diagonal elements whichcorrespond to the unknown initial states.






Details

The custom state space model is constructed by using the given system matrices Z, H, T, R, Q, a1,P1 and P1inf. Matrix or scalar Z (array in case of time-varying Z) is used to determine the numberof states m. If some of the other elements of the object are missing, SSModel uses default valueswhich are identity matrix for T, R (or k first columns of identity matrix) and P1inf, and zero matrixfor H, Q, P1 and , a1. If P1 is given and P1inf is not, the it is assumed to be zero matrix. If Q isgiven, it is used to define r, the dimensions of Q, which can be smaller than m (defaults to m).


yt = Ztαt + εt,


where εt ∼ N(0, Ht), ηt ∼ N(0, Qt) and α1 ∼ N(a1, P1) independently of each other. In caseof non-Gaussian observations, the observation equation is of form p(yt|θt) = p(yt|Ztαt), withp(yt|θt) being one of the following:

If observations are Poisson distributed, parameter of Poisson distribution is utλt and θt = log(λt).

If observations are from binomial distribution, u is a vector specifying number the of trials at times1, . . . , n, and θt = log[πt/(1− πt)], where πt is the probability of success at time t.



24 structSSM

Value

object of class SSModel with elements

See Also

arimaSSM for state space representation of ARIMA model, regSSM for state space representation ofa regression model, and structSSM for structural time series model.

structSSM Create a Structural Time Series State Space Model

Description

Function structSSM creates a state space representation of structural time series.

Usage

structSSM(y, trend = "level", seasonal = "none",X = NULL, H = NULL, Q.level = NULL, Q.slope = NULL,Q.seasonal = NULL, Q.regression = NULL, u = NULL,distribution = c("Gaussian", "Poisson", "Binomial"),transform = c("none", "ldl", "augment"),tolF = .Machine$double.eps^0.5,tol0 = .Machine$double.eps^0.5)

Arguments

trend A character vector defining the type of the level component of the model. Formultivariate series, either one type, it is assumed that all p series have sametype of trend components. Possible values are "level" (local level model) and"slope" (local linear trend model). Default is "level".

seasonal A character vector defining the type of the seasonal component of the model.For multivariate series, it is assumed that all p series have same type of seasonalcomponents. Possible values are "none" (no seasonal), "time" (time domainform) and "time" (frequency domain form). The length of the seasonal patternis taken as the frequency attribute of the time series object y. Default is "none".

X A n × k matrix of explanatory variables, with each column containing one ex-planatory variable. It is assumed that all p series use same explanatory variables.

H A p × p covariance matrix (or p × p × n array in time-varying case) of thedisturbance terms εt of the observation equation. Default gives p×p zero matrix.Omitted in case of non-Gaussian distributions. Augment the state vector if youwant to add additional noise.

Q.level A scalar or p × p covariance matrix (or p × p × n array in time-varying case)of the disturbance terms ξt corresponding to the level process µt. Default givesdiagonal matrix with NA’s on diagonal.

structSSM 25

Q.slope A scalar or p × p covariance matrix (or p × p × n array in time-varying case)of the disturbance terms ζt corresponding to the slope process νt. Default givesdiagonal matrix with NA’s on diagonal. Omitted if trend="level".

Q.seasonal scalar or A p × p covariance matrix (or p × p × n array in time-varying case)of the disturbance terms ωt corresponding to the seasonal process γt. Defaultgives diagonal matrix with NA’s on diagonal. Omitted if seasonal="none".There are several ωt processes in the frequency domain case, but they are allidentically distributed, so only the (co)variance structure of one of them need tobe defined.

Q.regression A scalar or xn×xn covariance matrix (or xn×xn×n array in time-varying case)of the disturbance terms corresponding to the regression coefficient processes.Default gives zero matrix i.e. ordinary time-invariant regression.







Details

The structural time series model has form

yt = µt + γt + εt, εt ∼ N(0, Ht)

µt+1 = µt + νt + ξt, ξt ∼ N(0, Qlevel,t)

νt+1 = νt + ζt, ζt ∼ N(0, Qslope,t)

with seasonal component being either time domain form

γt+1 = −s−1∑j=1

γt+1−j + ωt, ωt ∼ N(0, Qseasonal,t),

or frequency domain form where

26 transformSSM

γt =

bs/2c∑j=1

γj,t

γj,t+1 = γj,tcosλj + γ∗j,tsinλj + ωj,t,

γ∗j,t+1 = −γj,tsinλj + γ∗j,tcosλj + ω∗j,t, j = 1, . . . , bs/2c,with ωj,t and ω∗j,t being independently distributed variables with N(0, Qseasonal,t) distribution andλj = 2πj/s.

Explanatory variables can also be added to the model; in structSSM function it is assumed thatsame explanatory variables are used for all series. See regSSM and + for more complicated settings.

See Also

arimaSSM for state space representation of ARIMA model, regSSM for state space representation ofa regression model, SSModel for custom SSModel object and KFAS for general information regardingthe package and examples of its usage.

transformSSM Transform the SSModel object with multivariate observations

Description

Function transform.SSModel transforms original model by LDL decomposition or state vector aug-mentation,

Usage

transformSSM(object, type = c("ldl", "augment"))

Arguments

object State space model object from function SSModel.type Option "ldl" performs LDL decomposition for covariance matrixHt, and mul-

tiplies the observation equation with the L−1t , so ε∗t ∼ N(0, Dt). Option"augment" adds εt to the state vector, when Qt becomes block diagonal withblocks Qt and Ht. In case of univariate series, option "ldl" only changes theH_type argument of the model to "Diagonal".

Details

As all the functions in KFAS use univariate approach, Ht, a covariance matrix of an observationequation needs to be either diagonal or zero matrix. Function transformSSM performs either theLDL decomposition of the covariance matrix of the observation equation, or augments the statevector with the disturbances of the observation equation.

In case of a LDL decomposition, the new Ht contains the diagonal part of the decomposition,whereas observations yt and system matrices Zt are multiplied with the inverse of Lt.

transformSSM 27

Value

model Transformed model.

Index

∗Topic datasetsboat, 5GlobalTemp, 6

+, 26+.SSModel, 2

approxSSM, 2arimaSSM, 3, 20, 24, 26

boat, 5

fitSSM, 5

GlobalTemp, 6

importanceSSM, 3, 7

KFAS, 8, 26KFAS-package (KFAS), 8KFS, 12

ldl, 15logLik (logLik.SSModel), 15logLik.SSModel, 15

plot.approxSSM, 16plot.KFS, 17predict (predict.KFS), 17predict.KFS, 17print.KFS, 18print.SSModel, 18

regSSM, 5, 19, 24, 26residuals.KFS, 20

signal, 21simulateSSM, 21SSModel, 3, 5, 20, 22, 26structSSM, 5, 20, 24, 24

transformSSM, 9, 13, 26

28

Documents

Package ‘KFAS’ · Title Kalman Filter and Smoother for Exponential Family State Space ... State Space Models Description Package KFAS contains ... diffuse initialization