SSpace : A toolbox for State Space modelling

SSpace is a MATLAB toolbox for State Space modelling. State Space is in itself a powerful and ﬂexible framework for dynamic system modelling, and SSpace is conceived in a way that try to enhance such ﬂexibility to its maximum. One of the most salient features is that users implement their models by coding a MATLAB function. In this way, users have complete ﬂexibility when specifying the systems, having absolute control on parameterisations, constraints among parameters, etc. Besides, the toolbox allows for some ways to implement either non-standard models or standard models with non-standard extensions, like heteroskedasticity, time varying parameters, arbitrary non-linear relations with inputs, transfer functions without the need of using explicitly the State Space form, etc. The toolbox may be used on the basis of scratch State Space systems, but is supplied with a number of templates for standard widespread models. A full help system and documentation is provided. The way the toolbox is built allows for extensions in many ways. In order to fuel such extensions and discussions an on-line forum has been launched.


Introduction
SSpace is a MATLAB toolbox (The MathWorks Inc 2017) that provides a number of routines designed for a general analysis of State Space systems.It combines both flexibility and simplicity, and at the same time it enhances the power and versatility of State Space modelling in a friendly environment.The toolbox possess very distinct properties to other State Space pieces of software, but at the same time takes advantage of methods and algorithms from other sources, mainly Taylor, Pedregal, Young, and Tych (2007) and Durbin and Koopman (2012).The combination of all these factors give SSpace a particular flavour.
Popularity of high level programming languages like MATLAB has brought the availability of many free packages with an incredibly wide range of applications in many research areas.State Space (SS) routines are not an exception, and therefore good packages are so widespread nowadays, either as open source or paid versions, that it is impossible to quote even a portion of them.Without any intention of being exhaustive, we offer here a list of the most popular packages within the academic community.A partial review is available in volume 41, 2011 of the Journal of Statistical Software (Commandeur, Koopman, and Ooms 2011).There are several toolboxes written in MATLAB, like toolboxes supplied with the core program, but also CAPTAIN (Taylor et al. 2007), SSM (Peng and Aston 2011), SSMMATLAB (Gómez 2015) and E4 (Casals, Garcia-Hiernaux, Jerez, Sotoca, and Trindade 2016).One piece of software widely known is SSfPack (Koopman, Shephard, and Doornik 2008).Some others are written either in R (Petris and Petrone 2011), RATS (Doan 2011), gretl (Lucchetti 2011), etc.Also, some other, menu-driven programs that incorporate SS routines with less flexible programming capabilities are STAMP (Koopman, Harvey, Doornik, and Shephard 2009), Eviews (Bossche 2011), SAS (Selukar 2011), Stata (Drukker and Gates 2011), etc. ECOTOOL is a complementary MATLAB toolbox written by the same authors for the identification and estimation of dynamical systems (Pedregal and Trapero 2012).
In a broad sense, SSpace provides the user with the most advanced and up-to-date features available in the State Space framework, sharing some of these properties with some packages mentioned above and competing with them.However, some other features are specific of this toolbox and will not be found in any of the alternatives.
Regarding statistical issues, the main features of SSpace are: 1. Full multivariate linear and non-linear Gaussian models, and univariate non-Gaussian models are implementable.In any of these possibilities non-linear, time varying or transfer function relations with inputs are possible.
2. The framework is very general in the equations formulation and in the sense that all system matrices are potentially time-varying or state-dependent.
3. Kalman filter, fixed interval smoothing and disturbance smoothing are implemented with exact, diffuse or ad-hoc initialisation.Exact initialisation in non-linear models is also possible following Koopman and Lee (2009).
4. Steady state detection of linear invariant systems.
5. Use of exact score in Maximum Likelihood estimation, when possible.Use of numerical gradient is always possible, sometimes compulsory.
6. Other estimation procedures apart from Maximum Likelihood are implemented.At the moment the toolbox offers Concentrated Likelihood and minimization of combinations of several steps ahead forecast errors.More cost functions may be added in the future.
7. Kalman filtering and smoothing of multivariate systems are based on univariate treatment of multivariate systems, see Durbin and Koopman (2012), pages 155-160.
8. A family of models not used in any of the alternative packages is included, namely the Dynamic Harmonic Regression.To the best knowledge of the authors, this is the first time that a multivariate Seemingly Unrelated Dynamic Harmonic Regression is used and implemented.Such model is an extension of the univariate Dynamic Harmonic Regression counterpart, see Young, Pedregal, and Tych (1999) and worked example 3 below.
On the operative side, SSpace is rather flexible and user friendly because: • The toolbox is user-oriented in the sense that a big effort has been done on the developer side with the aim of simplifying usage to the final users.As a consequence, a comprehensive time series analysis may be performed with full control over models, parameters and specifications, by using just a few number of functions that follow a simple and fixed calling-standard that is easy to remember (see section of worked examples below).One example of this simplicity is that just one function (namely SSfilter) is used for filtering any kind of model, regardless of whether it is linear, non-gaussian or non-linear, i.e., the toolbox detects the type of model and apply the appropriate algorithms in each case automatically without any specific intervention of the user.
• The toolbox is composed of less than thirty functions with names that have been carefully selected following nemotechnic rules, so that the user may remember them or easily look for their names.There are three groups of functions: -Core functions (named SS*) which set up the models and perform the basic operations of filtering, smoothing, forecasting, validating, etc. -Template functions (Sample*) which help the user to set up the model either in terms of the crude State Space system matrices or in terms of its specific nature.-Other helpful functions for easy handling of models, matrices, etc.The main ones are for constraining parameters, building semi-definite covariance matrices, differencing time series, building forecast confidence bands, etc.
• Another key point is that models are directly specified by the user in a user-coded function written in plain MATLAB syntax.This approach has at least the following advantages: -Once the model is specified in the user-coded function, the same syntax applies to all sort of models, regardless of linearity, gaussianity, estimation method, etc. i.e., the same functions with the same syntax are used for estimation, filtering, smoothing, etc. Internally the operation of the toolbox may be rather different in each case, but such complexity does not require any intervention of the user.-The user-coded function is written following a particular template, that is basically a list of empty values for all the system matrices.The toolbox offers particular templates for a wide range of standard models.These templates may be extended or substituted by users.Such functions and templates may be extended in many ways.Typically, for complex models the model function has to be extended with the aid of additional inputs to the MATLAB function in order to define the model in SS form.
-The user has full control over his models in a fairly straightforward manner, e.g., different specific parameterizations of the same model are possible, parameter constraints of any kind may be imposed, non-standard features of the models may be added (like adding heteroskedasticity, time varying parameters, non linear eXogenous relations, ...), etc.
• Parameter estimation is carried out by the standard fminunc function from the optimization toolbox in MATLAB.By editing the script optimizer.m the user may tune the optimisation settings and/or change even the optimizer itself.
As a summary, the toolbox is highly configurable and could be extended in several ways, a reason for which users are encouraged to push their own contributions to the repository https://bitbucket.org/predilab/sspace-matlab/.Usually default options for modelling are in place in such a way that a few commands with a few options would produce sensible results, but advanced users may take advantage of the possibility to configure the toolbox at their own convenience.For example, they could select different sets of initial parameter values to start estimation in order to find the global optimum, build alternative cost functions to log-likelihood for parameter estimation based on the output of the Kalman filter, try out different optimisation algorithms to search for optimal parameters, add templates for models not yet implemented or suggest different versions to the existing ones, build canned functions for standard model estimation, etc.
The rest of the paper is organized as follows: the next section shows the models implemented in analytical form; Section 3 provides a broad vision of the functions included in the toolbox and its main usage on implementing a full time series analysis through a simple example; Section 4 illustrates the usage of SSpace with several examples for different scenarios and complexity levels; and Section 5 extracts the main conclusions.Code listings and examples are considerably compressed for space reasons, but may be consulted in extended form in the SSpace demos.

Models implemented in SSpace
SSpace supports linear Gaussian models, non-Gaussian models and non-linear models.
The linear Gaussian version is shown in Equation 1.
In this equations α t is the state vector of length n; y t are the m × 1 vector of output data; η t and t are the state and observational vectors of zero mean Gaussian noises, with dimensions r × 1 and h × 1, respectively; both noises are allowed to be correlated by a system matrix S t = Cov(η t , t ) of dimension r × h; α 1 is the initial state with mean a 1 and covariance P 1 and independent of all disturbances and observations involved.The remaining elements in (1) are the rest of system matrices with appropriate dimensions, i.e., One interesting feature (see Section 4.1.2for an example) is that the toolbox is flexible enough to allow the terms Γ t and D t be defined in such a way that k exogenous input variables appear explicitly, i.e., Γ t = f (γ t , u t ) and D t = g(d t , u t ), with u t of dimensions k × 1. Beware that general functions f (•) and g(•) include as particular cases time varying linear functions Γ t = γ t u t and D t = d t u t , with γ t and d t of dimensions n × k and m × k, respectively.
Apart from this, the formulation in ( 1) is also rather general.In particular, data sets may be multivariate, all system matrices are time varying and noises in state and observation equations may be correlated.The system is actually so general that some readers would immediately detect some redundancies and some terms that are not strictly necessary in most applications.However, we have preferred to set up the model in the most general possible way, such that any potential user acquainted with SS methodology does not have to change his particular mindset, so that the effort to translate the system into SSpace is kept to a minimum.
The non-Gaussian SS set up is shown in Equation 2: Here θ t is known as the signal.With this representation it is possible to deal with three types of models (see Durbin and Koopman, 2012): 1. Exponential family distribution, where p( 2. Stochastic Volatility models, i.e., y t = exp( 1 2 θ t ) t + D t .

Observations generated by the relation y
bution of the exponential family.
Finally, the non-linear models are of the type shown in Equation 3.
Functions T t (α t ) and Z t (α t ) with first derivatives provide non-linear transformations of the state vector into vectors of size n × 1 and m × 1, respectively.The rest of system matrices may also depend on the state vector and S t = 0.
Given this general framework, (extended) Kalman filtering, state and disturbance smoothing provide the basis for optimal state estimation, parameter estimation, signal extraction, forecasting, etc.For all the algorithmic issues not explicitly commented in this paper refer to Young et al. (1999), Taylor et al. (2007) and Durbin and Koopman (2012).
Table 2 shows some of the main features of most common software packages.The top block corresponds to toolboxes written in MATLAB, the rest are developed in other environments.
The table highlights several facts: i) exact initialization is present in most packages, ii) nonlinear and non-gaussian models are less common than expected and iii) most packages use Maximum Likelihood estimation as the only estimation method.
Moreover, there are some unique properties of SSpace, as far as the authors are concerned, like the implementation of multivariate Dynamic Harmonic Regression models, the implementation of systems by direct specification of the system matrices in a MATLAB function, system estimation via the minimization of forecast errors several steps ahead, the possibility of systems implementing arbitrary non-linear (and possibly multivariate) relations among inputs and outputs, the possibility of multiple-input-multiple-output transfer functions, and the chance to select an arbitrary minimizer algorithm to estimate the models (fminunc as a default).The flexibility of SSpace is so big that, being this its most powerful feature, at the same time it may be a problem for some users.Specifying a model from scratch in SSpace takes some time and a bit of familiarization with the toolbox.To solve these problems two solutions are implemented: i) when specifying the model, SSpace performs internally a full set of coherency tests to ensure that the model is correctly specified and issue error or warning messages with the specific problems that guide the user towards the solution, and ii) templates for most common models are provided so that the user do not have to bear in mind the State Space form of any of them.This is actually a part of SSpace that will grow as more templates appear in the future.

SSpace overview
Table 3 shows the core functions necessary to carry out a comprehensive time series analysis.From all this the most important to understand is SSmodel.It creates a structure with the user inputs and all the outputs, that will be empty at the time of creation (for a full description of inputs and outputs type help SSmodel at the MATLAB prompt).This structure will be the input to the rest of functions that have to handle the system, like estimation, filtering, etc., and it also may be the output to such functions, in a way that it is completed little by little with each additional operation.With SSmodel the user specifies the input and output data, the model to use, additional inputs to the user-coded function necessary to implement the model, either exact or diffuse or ad-hoc initialization of recursive algorithms, initial parameters for parameter estimation, fixed parameters that would be frozen in estimation, the cost function to optimize, exact or numerical score (if possible) in Maximum Likelihood estimation, etc.To sum up, it sets up the models up to the smallest detail, controlling the posterior performance of the rest of functions.
Once the model is created, SSestim performs parameter estimation by the method previously selected in SSmodel.SSvalidate produces a table with the estimation results and diagnostics.All the functions in Table 3 run on the model previously coded by the user in MATLAB language.In order to make the communication between the user and SSpace efficient and easy, a number of templates have been created and listed in Table 3. SampleSS sets up any linear and gaussian models with or without inputs and any sort of non-standard feature.The rest of linear models are self-explanatory and are intended for the creation of well-known models.
There are also some templates for non-Gaussian models and for general non-linear models (SamplenNL).Additional templates help the user to build models with time aggregation, concatenate systems o nest systems in inputs.In all cases, time varying system matrices are three dimensional, being time the third dimension.
Linear and Gaussian models SampleSS: General SS template SampleARIMA: ARIMA models with eXogenous variables SampleBSM: Basic Structural Model SampleDHR: Dynamic Harmonic Regression SampleDLR: Dynamic Linear Regression SampleES: Exponential Smoothing with eXogenous variables Non-Gaussian models SampleNONGAUSS: General non-Gaussian models SampleEXP: Non-Gaussian exponential family models SampleSV: Sochastic volatility models Non-linear models SampleNL: General non-linear models Other templates SampleAGG: Models with time aggregation SampleCAT: Concatenation of State Space systems SampleNEST: Nesting in inputs State Space systems The analysis with SSpace consists of following the next steps, that mimics closely the steps any researcher ought to follow in any SS analysis.
1. Write the model on paper or specify the model in SS form.
2. Translate model to MATLAB code using the templates supplied.
3. Set up model with SSmodel.

Check appropriateness of model with SSvalidate.
6. Determine optimal estimates of states, their covariance matrices, innovations, etc.Any or several of SSfilter, SSsmooth or SSdisturb may be used.
In the next subsections, a local level (or random walk plus noise) model is used to illustrate how to implement all these steps applied to the Nile river data used in Durbin and Koopman (2012), specifically demo1 of SSpace.The data consists of the flow volume of the Nile river at Aswan from 1871 to 1970.The local level model is given in Equation 4, being B the back-shift operator.

Specify model (step 1)
One SS representation of ( 4) is (5): State Equation: It may be seen immediately that the local level is one of the simplest models that can be specified in SS form.Comparing it with the general form (1) we see that for this case all system variables are scalar and time invariant, i.e., and Γ t and D t do not exist because the model has no inputs.

Code the model (step 2)
The best way to deal with the previous model is to edit the SampleSS template, rename it to, say, example1, and fill in all the matrices values accordingly.The aspect of SampleSS is shown below, with the system matrix names easily identifiable.The template is offered in this way, nothing should be removed, but anything could be added in order to define the system matrices.The following is the adaptation of such template to the local level model.Beware that the input argument p to both functions is a vector of parameters, in this case just the scalars Q and H.By default, both state and observation noises are considered independent.Furthermore, the first element in the vector p has been assigned to the matrix Q, while the second is assigned to H. Since both must be positive values, the system matrices are defined as powers of 10.An alternative and equivalent definition is model.Q=varmatrix(p(1)).

Setting up the model (step 3)
Now the user has to communicate with SSpace and build a model to use later on.This is done with the SSmodel function.In this case the MATLAB code is simply sys = SSmodel('y', nile, 'model', @example1).It is assumed that nile is a vector variable with the Nile data in and basically with this line code the user is telling that he wants to apply the local level model written in example1 to the data in the MATLAB variable nile.This is the most important step because at this stage is where the user defines the posterior performance of the toolbox.In essence, if the validation of the model is not correct, then the user has to come back to SSmodel and change either the model, options, etc.There are many options available to set up the model, that are passed on to SSmodel using duplets (see all possibilities in the SSpace documentation).

Estimate parameters (step 4)
Having defined the model in the previous step, the rest is straightforward.In particular, the estimation is done by sys = SSestim(sys).
No additional inputs to this functions are necessary, since everything has been set up in the previous step via the SSmodel function, in particular the estimation method that will be Exact Maximum Likelihood by default.Parameters are stored in the sys output structure.If estimation converges to well defined optimum, then estimation results, with standard errors of parameters, information criteria, etc. may be shown by means of the SSvalidate function with the syntax sys = SSvalidate(sys).

Use the model (step 5)
A final step consists of estimating the filtered and/or smoothed output together with the disturbances of the model, further validation tests.These operations constitute the basis for forecasting, signal extraction, interpolation, etc.When only the filtered output is required the call should be sys = SSfilter(sys); if smoothed estimates without disturbances is preferred then the call should be sys = SSsmooth(sys); whereas the full computation and output is produced by the call sys = SSdisturb(sys).
Results in all these brief examples are stored always in sys output structure, though at any point different structures may be used.It stores parameters with covariance matrix, optimal states and covariances, fitted output values and covariances, forecasted values and covariances, innovations, disturbances estimates with covariances.Further statistical diagnostics are advisable.

Worked examples
The examples shown in this section are presented as illustrations of the flexibility and power of the toolbox, with no pretension of showing any scientific result or improvement over other researcher's analysis.Code listings are truncated in order to save space.This is especially important in the case of the templates shown, for which the extended versions are also included in the software provided with an abundant help.Identification and validation issues are not treated in the examples to keep them short.
One of the challenges for this time series, is to evaluate whether the construction of the Aswan dam in 1899 (observation 29) led to a significant decline in the river flow.This may be tested in several ways by changing the user function, either by including a D t in Equation 1 directly (Case 1 below), or by using a dummy variable as input to the SS system (Cases 2 and 3).It is worthy passing through these three cases to realize the flexibility of SSpace when specifying models.

Case 1
In this case the user function for concentrated maximum likelihood would be: Keep in mind that matrix D t is time varying, but it is not defined as a three dimensional matrix, as it is the general convention in SSpace.This is an exception that affects also Γ t and has been considered very convenient from the user point of view, since handling three dimensional matrices in MATLAB is much more cumbersome than two dimensional.Nevertheless, orthodox three dimensional matrices would work exactly in the same way.The call for estimating the model by Concentrated Maximum Likelihood is sys = SSmodel('y', y, 'model', @example2, 'OBJ_FUNCTION_NAME', @llikc, 'p0', [-1; 1000]).An interesting point of this example is that a D t matrix is used, but not input data is supplied and there is no need to specify a Γ t matrix.Here, initial parameters for the numerical search are added via the duplet {'p0', [-1; 1000]}.The rest of the code is identical to the previous example.
The results are shown in Figure 2.
It is important to note that the estimation is such that there is no additional information in the series apart from the jump in the volume due to the Aswan dam.By comparison with Figure 1, it is easy to check this, since the innovations and output are essentially the same.

Case 2
An alternative way to do the same, which is more formal from a statistical point of view, consists on defining one dummy variable as a step, taking zeros up to observation 28 and ones afterwards, i.e., u = [zeros(28, 1); ones(82, 1)].In this case, the user function is: The difference with the previous option is that matrix model.D is just the second element of the parameter vector p, i.e., a coefficient that will multiply the input dummy variable u t .Now the call to SSmodel should be: sys = SSmodel('y', y, 'u', u, 'model', @example3, 'OBJ', @llikc); Here, the duplet {'u', u} tells SSpace which is the input variable to use.The estimation of the coefficient measuring the jump is negative and significant.

Case 3
A final case, still worth mentioning, consists of including the dummy input variable into the user function as an additional input argument, but now the SS system is considered as a system without inputs: The call now should be: sys = SSmodel('y', y, 'model', @example4, 'OBJ', @llikc, 'user_inputs', {u}); Additional inputs to the user function may be passed on to the model definition with the help of duplets {'user_inputs', {u}}.Though it does not make sense in this case, it is worth noting that the dependence to the inputs may be modelled by a non-linear function, e.g., just by defining model.D = p(2)*(u(2, :).^(p(3))) or any other specification.This is the main advantages of specifying models by writing a function.More examples may be checked in demo5.

Example 2: Univariate models
In this second example the air-passenger data taken from Box, Jenkins, Reinsel, and Ljung (2015) is analysed with a number of different univariate possibilities.
Case 1: Basic Structural Model (BSM) A BSM a la Harvey (Harvey 1989) may be used with the template SampleBSM (it is also possible to use SampleSS and test the SS-form from scratch).In such template, separate definitions are in place for the trend and the harmonics and input variables, if any.Have a look on the function demo_airpasbsm.mthat is one of the cases implemented in demo2.
The part of the template related to the trends is: where the variable m is the number of output variables (1 for univariate) and matrices I and O are pre-defined as a unity matrix and a block of zeros.The model is specified directly by the State Space form of the Local Linear Trend type (LLT), i.e., Case 2: ARIMA The ARIMA model is easily implemented by using the SampleARIMA template used as an example in demo3, check demo_airpasarima.Assuming that an ARIM A(0, 1, 1) × (0, 1, 1) 12 is to be estimated, the relevant part of this template is where Diffy is the differencing polynomial in the backshift operator B such that B j y t = y t−j , ARpoly is the AR polynomial and MApoly is the MA polynomial.Check that the differencing order is the convolution (i.e., multiplication) of a regular and seasonal difference operators, i.e., ∆∆ 12 = (1−B)(1−B 12 ).The MA polynomial of the model is (1+θ 1 B)(1+Θ 1 B 12 ), with p(1)= θ 1 and p(2)= Θ 1 .All polynomials are coded as column vectors of the corresponding coefficients in ascending order of powers of the backshift operator, as it is common in other MATLAB toolboxes.Though it does not make sense in this example, constraints among parameters would be very simple to impose, e.g., if the constraint θ 1 = Θ 1 is needed, the MA polynomial may be coded as MApoly = conv([1 p(1)], [1 zeros(1, 11) p(1)])' .

Case 3: Exponential Smoothing
A final illustration for this data is an Exponential Smoothing model a la Hyndman, Koehler, Ord, and Snyder (2008), which template is SampleES, check demo_airpasES used in demo3.
The template filled in for this example is: The argument ModelType deals with the type of model, the first letter stands for the type of level ('N' for none, 'A' for additive and 'D' for damped with damping factor Phi), the second letter is the slope type ('N' for none or 'A' for additive), and the third letter stands for the type of seasonal (again either 'N' or 'A'), and the numbers after those letters is the period of the seasonal component.The rest of the code sets up the α, β and γ parameters affecting the level, slope and seasonal components, that are suppose to be estimated within certain values, see Hyndman et al. (2008).Sigma stands for the variance of the unique noise present in the model.Input variables may be included by introducing a D matrix as a function of the p vector of parameters.

Example 3: Multivariate dynamic harmonic regression (DHR)
The models presented so far are univariate and may be easily extended to multivariate versions.In this example we present a new model that has not yet been used in its multivariate It is important to initialise the searching algorithm with appropriate diagonal covariance matrices, this is achieved by the setting of p0 above.The call to SSmodel is done with the required initial parameters and the number of time samples.
Figure 3 shows some output of this DHR model.

Example 4: Non-gaussian
The number of van drivers casualties in the UK, see Durbin and Koopman (2012) and Figure 4, is a case where a Poisson distribution is justified, because numbers are small and the units are integers.Neither the Gaussian assumption is strictly correct nor the logarithmic transformation manage to produce sensible results.The model used is a BSM with a trend, dummy seasonal, irregular and an exogenous effect due to the enforcement of the seat belt law, but the distribution of the observations is a Poisson, see Equation 7.

Example 5: Non-linear
This example illustrates the use of the Extended Kalman Filter with exact initialisation applied to the monthly visits abroad by UK residents from January 1980 to December 2006 following Koopman and Lee (2009) and Durbin and Koopman (2012).This example was used to test for the convenience of the log transform so widely use in Econometrics.As a matter of fact, it is shown that the log transform does not fix the heteroscedasticity problem, and, consequently a model with an interaction between the trend and the seasonal component is proposed instead with the rest of hypothesis applying, see Equation 8.

Concluding remarks
This paper has presented SSpace, a new toolbox for the exploitation of State Space models.It is intended for a wide audience, including professional practitioners, researchers and students, indeed anyone involved in the analysis of time series, forecasting or signal processing.
The library incorporates most of modern algorithms and advances in the field of State Space modelling, following mainly Taylor et al. (2007) and Durbin and Koopman (2012).The system is very general because it is possible to implement linear, non-gaussian and non-linear systems, all system matrices may vary over time and may be multivariate, several estimation methods are implemented, inputs to the system may be introduced explicitly, etc.
Other advantages of the library are that a few functions are necessary to carry out a comprehensive analysis of time series.Such functions are used systematically following a fixed pattern that simplifies the usage of the toolbox.However, one of the main feature that makes SSpace really flexible, powerful and transparent is that the user implements models directly as a function written in MATLAB.This approach makes some cumbersome tasks truly simple and transparent, this is the case, say of trying different parameterizations of the same model or imposing parameter constraints.
The toolbox is supplied with templates for building general SS models from scratch in a completely free way, but is also accompanied by a number of templates useful for the implementation of a variety of common models.
In this paper, the capabilities of the toolbox have been demonstrated in action on several worked examples.These properties should make the toolbox particularly interesting for those in need of non-standard models, for which even many commercial alternatives may not provide the required flexibility.
Figure4shows the trend with the jump due to the seatbelt law effect and twice the standard error confidence bands.

Figure 4 :
Figure 4: Data and trend of non-gaussian example.

Table 1 :
Options available in most common state space software packages.The options are exact initialization (EI), other estimation methods apart from ML (+ML), univariate treatment of multivariate models (UTMM), non linear and non gaussian models (NLNG) and availability of state disturbance algorithms (DA).

Table 2 :
SSfilter produce the innovations and filtered estimates of states and covariance matrices with additional output.If smoothed output is prefered, it is produced by the SSsmooth function.Disturbance errors (and smoothed output) may be computed by SSdisturb.Finally, there are eight step-by-step demos ready, that may be run with the SSdemo function.Main functions of the SSpace library.

Table 3 :
Available templates for the SSpace toolbox.The rest of functions in Table3are very useful to set up models in SS form: i) confband builds confidence bands of filtered or smoothed outputs in a comfortable way, ii) constrain settles constraints among parameters in the models, iii) varmatrix is a function useful to constrain covariance matrices to be semi positive definite in multivariate models or just positive in scalar cases, iv) normalize standardizes any set of time series with a time varying covariance structure, vi) vdiff produces differencing of vector time series, and vii) optimizer is an editable script that allows tuning the optimizer tolerances and even to change the optimizer itself.

Table 4 :
Auxiliary functions for the SSpace library.
Trend t + Cycle t + exp{bTrend t }Seasonal t + t (8)Comparing this equation with the general non-linear system (3) we see that there is only one non-linear term, namely T t (α t ) that is the Equation 3 without the noise.Setting up the model now is much more difficult because the partial derivatives of T t (α t ) with respect to the vector state α t ought to be calculated explicitly.For convenience a linear BSM model is implemented in a separate model using the SampleBSM template (check demo_uk in demo8): Some of the most relevant are linear, non-linear and time varying regressions (see SampleDLR and demo5), concatenation of State Space systems with the SampleCAT template (a typical case would be a BSM model with time varying parameters), estimating parameters of any model by minimizing functions of squared of several-steps-ahead forecast errors (see e.g., demo2), time aggregation problems (see SampleAGG and demo6), and nesting in inputs models (see SampleNEST and demo5).