Type:	Package
Title:	Linear Innovations State Space Unobserved Components Model
Version:	1.0.2
Maintainer:	Alexios Galanos <alexios@4dscape.com>
Description:	Unobserved components time series model using the linear innovations state space representation (single source of error) with choice of error distributions and option for dynamic variance. Methods for estimation using automatic differentiation, automatic model selection and ensembling, prediction, filtering, simulation and backtesting. Based on the model described in Hyndman et al (2012) <doi:10.1198/jasa.2011.tm09771>.
Depends:	R (≥ 4.1.0), Rcpp (≥ 0.12.9), tsmethods (≥ 1.0.0)
LinkingTo:	Rcpp (≥ 0.12.9), TMB, RcppEigen
Imports:	TMB (≥ 1.7.20), methods, tsaux, tsdistributions, zoo, xts, copula, flextable, data.table, sandwich, nloptr, RTMB, viridisLite, future, future.apply, progressr
Suggests:	rmarkdown, tstests, knitr, testthat (≥ 3.0.0)
License:	GPL-2
Encoding:	UTF-8
RoxygenNote:	7.3.2
VignetteBuilder:	knitr
LazyData:	true
URL:	https://github.com/tsmodels/tsissm, https://www.nopredict.com/packages/tsissm
Config/testthat/edition:	3
NeedsCompilation:	yes
Packaged:	2025-07-12 19:48:00 UTC; alexios
Author:	Alexios Galanos [aut, cre]
Repository:	CRAN
Date/Publication:	2025-07-12 20:20:02 UTC

tsissm: Linear Innovations State Space Unobserved Components Model

Description

Unobserved components time series model using the linear innovations state space representation (single source of error) with choice of error distributions and option for dynamic variance. Methods for estimation using automatic differentiation, automatic model selection and ensembling, prediction, filtering, simulation and backtesting. Based on the model described in Hyndman et al (2012) doi:10.1198/jasa.2011.tm09771.

Author(s)

Maintainer: Alexios Galanos alexios@4dscape.com (ORCID)

See Also

Useful links:

• https://github.com/tsmodels/tsissm

• https://www.nopredict.com/packages/tsissm

Akaike's An Information Criterion

Description

Extract the AIC from an estimated model.

Usage

## S3 method for class 'tsissm.estimate'
AIC(object, ..., k = 2)

## S3 method for class 'tsissm.selection'
AIC(object, ..., k = 2)

Arguments

Value

a numeric value.

Bayesian Information Criterion

Description

Extract the BIC from an estimated model.

Usage

## S3 method for class 'tsissm.estimate'
BIC(object, ...)

## S3 method for class 'tsissm.selection'
BIC(object, ...)

Arguments

Value

A numeric value.

Transform a summary object into flextable

Description

Transforms a “summary.tsissm.estimate” object into a flextable with options on symbolic representation and model equation.

Usage

## S3 method for class 'summary.tsissm.estimate'
as_flextable(
  x,
  digits = max(3L, getOption("digits") - 3L),
  signif.stars = getOption("show.signif.stars"),
  include.symbols = TRUE,
  include.equation = TRUE,
  include.statistics = TRUE,
  table.caption = paste0("ISSM Model: ", x$model),
  ...
)

Arguments

Value

A flextable object.

Bread Method

Description

Bread Method

Usage

## S3 method for class 'tsissm.estimate'
bread(x, ...)

Arguments

Value

The analytic hessian of the model.

Author(s)

Alexios Galanos

Extract Model Coefficients

Description

Extract the estimated coefficients of a model.

Usage

## S3 method for class 'tsissm.estimate'
coef(object, ...)

Arguments

Value

a numeric named vector.

Score Method

Description

Score Method

Usage

## S3 method for class 'tsissm.estimate'
estfun(x, ...)

Arguments

Details

The function returns the scores of the negative of the log likelihood at the optimal solution.

Value

The score matrix

Author(s)

Alexios Galanos

Model Estimation

Description

Estimates a model given a specification object using maximum likelihood.

Usage

## S3 method for class 'tsissm.spec'
estimate(
  object,
  solver = "nloptr",
  control = NULL,
  scores = TRUE,
  debug_mode = FALSE,
  ...
)

## S3 method for class 'tsissm.autospec'
estimate(object, solver = "nloptr", control = NULL, trace = FALSE, ...)

Arguments

Details

The maximum likelihood estimation for this model is described in the vignette.

Value

An object of class “tsissm.estimate” or “tsissm.selection”. In the case of automatic model selection an object of class “tsissm.estimate” will be returned based on AIC (minimum) if “top_n” is 1, else an object of class “tsissm.selection” with a list of length “top_n”. This object can then be used for filtering, prediction and simulation and then ensembled (based on user specified weights).

Note

When calculating the scores, a future promise is created so it is fastest if a future plan is pre-created with at least 2 workers so that the function can run in the background without having to wait for the estimation object to be returned.
If the control argument is NULL, then a hybrid strategy is adopted whereby the SLSQP algorithm is initially used and if it fails (status less than 0 or errors due to NaNs in sampled parameters) then the Augmented Lagrange with MMA local solver is used which is slower but may be more reliable.
For the automatic selection estimation, this will benefit from the use of multiple processes which can be set up with a plan. For progress tracing, use handlers. The function will check for number of parallel workers initialized (using ‘nbrOfWorkers’), and if it finds only 1 then will revert to non-parallel execution of the code.

Model Fitted Values

Description

Extract the fitted values from an estimated model.

Usage

## S3 method for class 'tsissm.estimate'
fitted(object, ...)

Arguments

Value

an xts object of the fitted values.

Multi-Step Ahead In-Sample Residuals

Description

Extract the multi-step ahead in-sample residual values from an estimated model.

Usage

## S3 method for class 'tsissm.estimate'
hresiduals(
  object,
  h = 12,
  transformed = TRUE,
  index_start = 0,
  simplify = TRUE,
  ...
)

hresiduals(object, ...)

Arguments

Details

For each time point t (t>=index_start), in the data sample, an h-steps ahead forecast (predicting the observation at time t + h) is made, using the full sample estimated parameters and observed data up to t. These h-step-ahead fitted residuals, in either transformed or untransformed space, can sometimes be used for diagnosing the multi-step ahead in-sample performance of the model. This is not a substitute for a proper rolling out of sample forecast, but a quick method which may still be useful.

Value

A data.table in either long or wide format.

ISSM solver control parameters

Description

ISSM solver control parameters

Usage

issm_control(
  solver = "nloptr",
  algorithm = c("SLSQP", "AUGLAG/MMA", "AUGLAG/CCSAQ"),
  trace = 0,
  xtol_rel = 1e-14,
  maxeval = 1000,
  xtol_abs = 1e-12
)

Arguments

Details

The function provides defaults for use, but additional control parameters may be appended to the list if the user so wishes (‘nloptr’ has many more options).

Value

a list with the options which is then passed to the solver.

Model Specification

Description

Specifies an ISSM model prior to estimation with option for automatic model selection.

Usage

issm_modelspec(
  y,
  auto = FALSE,
  slope = TRUE,
  slope_damped = FALSE,
  seasonal = FALSE,
  seasonal_frequency = 1,
  seasonal_harmonics = NULL,
  ar = 0,
  ma = 0,
  xreg = NULL,
  variance = "constant",
  garch_order = c(1, 1),
  lambda = NULL,
  lower = 0,
  upper = 1,
  distribution = "norm",
  sampling = NULL,
  init_garch = "unconditional",
  sample_n = 10,
  top_n = 1,
  ...
)

Arguments

Details

The specification object holds the information and data which is then passed to the maximum likelihood estimation routines. Depending on whether automatic selection is chosen, it will dispatch to the appropriate estimation routine.

The specification performs some sanity checks on the arguments provided and sets up the required state space matrices and parameters which are used in the estimation stage.

Value

An object of class “tsissm.spec” or “tsissm.autospec”.

References

De Livera, Alysha M and Hyndman, Rob J and Snyder, Ralph D, 2011, Forecasting time series with complex seasonal patterns using exponential smoothing, Journal of the American Statistical Association, 106(496), 1513–1527.

Model Log-Likelihood

Description

Extract the log-likelihood from an estimated model.

Usage

## S3 method for class 'tsissm.estimate'
logLik(object, ...)

## S3 method for class 'tsissm.selection'
logLik(object, ...)

Arguments

Value

Returns an object of class logLik. This is a number with at least one attribute, "df" (degrees of freedom), giving the number of (estimated) parameters in the model.

Mauna Loa CO2 Daily Measurements

Description

The dataset represents the daily average of the number of carbon dioxide molecules in a given number of molecules of air, after removal of water vapor (molefrac) from the Mauna Loa observatory, spanning the period 1974-05-19 to 2025-02-25.

Usage

maunaloa

Format

## 'maunaloa' A data.frame containing 15571 observations

date

The YYYY-MM-DD date

co2

The CO2 measurements

Source

https://gml.noaa.gov/ccgg/trends/data.html

Extract the Number of Observations

Description

Extract the number of observations from an estimated model. This is principally intended to be used in computing BIC and used in other tidy methods

Usage

## S3 method for class 'tsissm.estimate'
nobs(object, ...)

Arguments

Value

A numeric value.

Object Plots

Description

Plots for objects generated from the tsissm functions.

Usage

## S3 method for class 'tsissm.estimate'
plot(x, y = NULL, ...)

## S3 method for class 'tsissm.simulate'
plot(x, y = NULL, ...)

## S3 method for class 'tsissm.profile'
plot(x, y = NULL, type = c("coef", "mape", "mase", "crps"), ...)

Arguments

Value

different plots depending on the input class.

Model Prediction

Description

Prediction function for class “tsissm.estimate” or “tsissm.selection”.

Usage

## S3 method for class 'tsissm.estimate'
predict(
  object,
  h = 12,
  seed = NULL,
  newxreg = NULL,
  nsim = 1000,
  forc_dates = NULL,
  innov = NULL,
  innov_type = "q",
  init_states = NULL,
  ...
)

## S3 method for class 'tsissm.selection'
predict(
  object,
  h = 12,
  newxreg = NULL,
  nsim = 1000,
  forc_dates = NULL,
  init_states = NULL,
  ...
)

Arguments

Details

Like all models in the tsmodels framework, prediction is done by simulating h-steps ahead in order to build a predictive distribution.

Value

An object of class “tsissm.predict” which also inherits “tsmodel.predict”, with slots for the simulated prediction distribution, the original series (as a zoo object), the original specification object and the mean forecast. The predictive distribution is back transformed if lambda was not set to NULL in the specification. If the input class is “tsissm.selection” then the returned class with be “tsissm.selection_predict” which hold the list of predicted objects. For this dispatch method, custom innovations are not allowed since correlated innovations are passed to each model predicted (using a Normal Copula) in order to enable ensembling of the simulated predictive distributions.

Model Estimation Summary Print method

Description

Print method for class “summary.tsissm.estimate”

Usage

## S3 method for class 'summary.tsissm.estimate'
print(
  x,
  digits = max(3L, getOption("digits") - 3L),
  signif.stars = getOption("show.signif.stars"),
  ...
)

Arguments

Value

Invisibly returns the original summary object.

Model Diagnostics Print method

Description

Print method for class “tsissm.diagnose”

Usage

## S3 method for class 'tsissm.diagnose'
print(x, ...)

Arguments

Value

Invisibly returns the original object and prints the output to console.

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

flextable

as_flextable

sandwich

bread, estfun

Model Residuals

Description

Extract the residual values from an estimated model.

Usage

## S3 method for class 'tsissm.estimate'
residuals(object, standardize = FALSE, transformed = TRUE, ...)

Arguments

Details

For h>1, this is like performing an in-sample backtest starting at time 1 with fixed coefficients. The purpose of having the matrix of h-step ahead residuals is in order to calculate the 1:h covariance matrix as well as the cross 1:h covariance matrix when ensembling series at multiple horizons.

Value

An xts vector of the model residuals for h = 1, else a data.table with rows representing the first prediction date and columns the h-ahead forecast residuals.

Note

The function can use parallel functionality (for h>1) as long as the user has set up a plan using the future package.

The Standard Deviation of the model

Description

The Standard Deviation of the model

Usage

## S3 method for class 'tsissm.estimate'
sigma(object, ...)

Arguments

Value

If the model was estimated using dynamic variance (GARCH model), then an xts matrix is returned with the estimated GARCH volatility else the estimated standard deviation of the residuals in the case of constant variance.

Model Simulation

Description

Simulation function for class “tsissm.estimate”.

Usage

## S3 method for class 'tsissm.estimate'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  h = 1,
  newxreg = NULL,
  sim_dates = NULL,
  bootstrap = FALSE,
  innov = NULL,
  innov_type = "q",
  pars = coef(object),
  init_states = tail(object$model$states, 1),
  init_res = NULL,
  init_sigma = NULL,
  ...
)

## S3 method for class 'tsissm.selection'
simulate(
  object,
  nsim = 1,
  seed = NULL,
  h = 1,
  newxreg = NULL,
  sim_dates = NULL,
  bootstrap = FALSE,
  pars = coef(object),
  init_states = tail(object$model$states, 1),
  init_res = NULL,
  init_sigma = NULL,
  ...
)

Arguments

Value

An object of class “tsissm.simulate” with slots for the simulated series and states.

SPY ETF Adjusted Close

Description

The adjusted daily closing price of the SPY ETF.

Usage

spy

Format

## 'spy' A data.frame containing 7597 observations

date

The YYYY-MM-DD date

spy

The adjusted stock closing price.

Source

From Yahoo Finance.

Model Estimation Summary

Description

Summary method for class “tsissm.estimate”

Usage

## S3 method for class 'tsissm.estimate'
summary(object, vcov_type = "H", digits = 4, ...)

Arguments

Value

A printout of the parameter summary, model type and some model metrics.

Walk Forward Model Backtest

Description

Generates an expanding window walk forward backtest.

Usage

## S3 method for class 'tsissm.autospec'
tsbacktest(
  object,
  start = floor(length(object$y)/2),
  end = length(object$y),
  h = 1,
  estimate_every = 1,
  rolling = FALSE,
  weights_scheme = c("AIC", "BIC", "U"),
  weights = NULL,
  seed = NULL,
  solver = "nloptr",
  control = NULL,
  trace = FALSE,
  ...
)

## S3 method for class 'tsissm.spec'
tsbacktest(
  object,
  start = floor(length(object$target$y_orig)/2),
  end = length(object$target$y_orig),
  h = 1,
  estimate_every = 1,
  rolling = FALSE,
  seed = NULL,
  solver = "nloptr",
  control = NULL,
  trace = FALSE,
  ...
)

Arguments

Value

A list with the following data.tables:

• prediction : the backtest table with forecasts and actuals

• metrics: a summary performance table showing metrics by forecast horizon (MAPE, MSLRE, BIAS and MIS if alpha was not NULL).

Note

The function can use parallel functionality as long as the user has set up a plan using the future package. Model ensembling is used when the input object is of class “tsissm.autospec” and top_n is greeter than 1. The following weighting schemes are available:

U:

User supplied fixed weights.

AIC:

Models are weighted based on their Akaike Information Criterion (AIC), favoring models with lower AIC values. The weights are computed as:

w_i = \frac{\exp(-0.5 \times \Delta_i)}{\sum_{j} \exp(-0.5 \times \Delta_j)}

where

\Delta_i = AIC_i - \min(AIC)

BIC:

Similar to AIC-based weighting but uses the Bayesian Information Criterion (BIC) instead, which penalizes model complexity more strongly.

The final ensemble prediction is computed as:

\hat{y}_{\text{ensemble}} = \sum_{i} w_i \hat{y}_i

where w_i are the model weights and \hat{y}_i are the individual model predictions. AIC-based weighting is preferred when models have different complexities but are estimated on the same dataset, while BIC-based weighting may be better suited for large sample sizes due to its stronger penalty on complexity.

See Also

[tsensemble()]

Model Decomposition

Description

Decomposes the estimated model or prediction into its component parts (states).

Usage

## S3 method for class 'tsissm.estimate'
tsdecompose(object, simplify = FALSE, start = 1, ...)

## S3 method for class 'tsissm.predict'
tsdecompose(object, simplify = FALSE, start = 1, ...)

## S3 method for class 'tsissm.simulate'
tsdecompose(object, simplify = FALSE, start = 1, ...)

Arguments

Details

The 1-step ahead prediction is given by the following equation:

y_{t} = x_{t-1} w + \varepsilon_{t}

Because the decomposition pre lags the states so that the seed state is aligned with the error term, then summing the state distribution of each component with the returned error distribution will ensure that the exact same predicted value matched to the correct date is returned.

Value

For the estimated object, returns an xts matrix of the state components (including Irregular term). For the predicted object, a list with the simulated state components of class “tsmodel.predict” which includes the predictive distribution and original (estimated) series components.

Model Diagnostics

Description

Creates a short summary of model based diagnostics.

Usage

## S3 method for class 'tsissm.estimate'
tsdiagnose(object, plot = FALSE, ...)

Arguments

Value

A list of tests including the weighted Ljung-Box test for residual autocorrelation, system forecastability test, and outlier dates using the Rosner test (rosnerTest). Optionally generates a plot of relevant diagnostics.

Ensembling of Models and Predictions

Description

Ensembles estimated, predicted and simulated objects arising from the automatic selection method.

Usage

## S3 method for class 'tsissm.selection'
tsensemble(object, weights = NULL, start = 1, ...)

## S3 method for class 'tsissm.selection_predict'
tsensemble(object, weights = NULL, start = 1, ...)

## S3 method for class 'tsissm.selection_simulate'
tsensemble(object, weights = NULL, start = 1, ...)

Arguments

Value

For the estimated object, a list with the weighted fit and errors, whilst for the predicted and simulated objects a list with the ensemble predictions as a “tsmodel.predict” object. If the models were all estimated with the same Box Cox lambda, then the weighted state decomposition is also returned inside the “tsmodel.predict” object. Additionally, for the predicted object, the ensemble analytic mean is also returned.

Note

Only the size of the weights is checked (should be equal to number of selected models), but not checks are performed on the values of the weights or whether they sum to 1. This is left to the user. When lambda is 1, the sum of component will be off by 1 versus the weighted distribution since the Box Cox transform contains an offset (so it is to be expected). To replicate the value of the predicted distribution by summing the decomposed components, the argument “start” should be set to 0 to return the lagged predicted components.

Model Equation (LaTeX)

Description

Generates a list of model equations in LaTeX.

Usage

## S3 method for class 'tsissm.estimate'
tsequation(object, ...)

Arguments

Details

This method is called in the summary when the format output option chosen is “flextable”.

Value

A list of equations in LaTeX which can be used in documents. This is a list with 3 slots for the observation, state and variance equations,

Online Model Filtering

Description

Online filter which updates the states and fitted values using new data.

Usage

## S3 method for class 'tsissm.estimate'
tsfilter(object, y = NULL, newxreg = NULL, ...)

## S3 method for class 'tsissm.selection'
tsfilter(object, y = NULL, newxreg = NULL, ...)

Arguments

Details

The new data is filtered (1 step ahead) using the last state of the object. Once this is complete, the object is updated with the new states and information so that the process can be continued on the same object as new information arrives.

Value

An object of class “tsissm.estimate” or “tsissm.selection”.

Performance Metrics

Description

Performance metrics from an estimated or predicted tsissm model.

Usage

## S3 method for class 'tsissm.predict'
tsmetrics(object, actual, alpha = 0.1, ...)

## S3 method for class 'tsissm.estimate'
tsmetrics(object, ...)

Arguments

Value

a data.frame of performance metrics including MAPE, MSLRE, BIAS and AIC for the estimate object and MAPE, MSLRE, BIAS, MASE, MIS and CRPS for predict object.

Analytic Forecast Moments

Description

Prediction function for class “tsissm.estimate”.

Usage

## S3 method for class 'tsissm.estimate'
tsmoments(
  object,
  h = 1,
  newxreg = NULL,
  init_states = NULL,
  transform = FALSE,
  ...
)

Arguments

Details

For the constant variance model the conditional moments are given by:

E\left(y_{n+h|n}^{(\omega)}\right) = \mathbf{w}' \mathbf{F}^{h-1}\mathbf{x}_n

V\left(y_{n+h|n}^{(\omega)}\right) = \begin{cases} \sigma^2, & \text{if } h = 1, \\[6pt] \sigma^2 \left[1 + \sum_{j=1}^{h-1} c_j^2 \right], & \text{if } h \geq 2. \end{cases}

The backtransformed variance should be used with caution as it uses a higher-order expansion correction which is known to be inaccurate for h > 5. Instead, use the simulated distribution to extract this information.

Value

a list with a slot for the analytic mean and one for the process variance. In the case of dynamic variance, it returns an additional slot for the GARCH variance.

Model Simulation Based Profiling

Description

Profiling of model dynamics using simulation/estimation/prediction.

Usage

## S3 method for class 'tsissm.estimate'
tsprofile(
  object,
  h = 1,
  nsim = 100,
  seed = NULL,
  solver = "nloptr",
  control = NULL,
  trace = FALSE,
  ...
)

Arguments

Details

The function profiles an estimated model by simulating and then estimating multiple paths from the assumed DGP while leaving h values out for prediction evaluation. Each simulated path is equal to the size of the original dataset plus h additional values, and initialized with the initial state vector from the model. The resulting output contains the distribution of the MAPE, percent bias (BIAS) and mean squared log relative error (MSLRE) per horizon h. Since these matrices are of class “tsmodel.distribution” they can be readily plotted with the special purpose “plot” function for this class from the “tsmethods” package. Additionally, a data.table matrix is also returned with the distribution of the coefficients from each path estimation.

Value

An object of class “tsissm.profile”.

Note

The function can use parallel functionality as long as the user has set up a plan using the future package. The simulated states are checked for positivity and any paths which have negative values are excluded. If more than half of the paths have negative values then an error is raised and the function will stop.

Model Specification Extractor

Description

Extracts a model specification (class “tsissm.spec”) from an object of class “tsissm.estimate”.

Usage

## S3 method for class 'tsissm.estimate'
tsspec(
  object,
  y = NULL,
  lambda = NULL,
  xreg = NULL,
  parameters = "initial",
  ...
)

Arguments

Value

An object of class “tsissm.spec”.

Note

This function is used by other functions in the package such as the backtest which requires rebuilding the specification for each re-estimation step with updated data but keeping all else equal.

Advance Retail Sales: Retail Trade (US)

Description

The dataset represents the monthly, non-seasonally adjusted advance estimate of sales from the retail trade based on data from a subsample of firms from the larger Monthly Retail Trade Survey.

Usage

us_retail_sales

Format

## 'us_retail_sales' A data.frame containing 398 observations

date

The YYYY-MM-DD date

co2

The sales value in millions of dollars.

Source

U.S. Census Bureau, Advance Retail Sales: Retail Trade [RSXFSN]. Retrieved from FRED, Federal Reserve Bank of St. Louis: https://fred.stlouisfed.org/series/RSXFSN on March 27, 2025.

The Covariance Matrix of the Estimated Parameters

Description

The Covariance Matrix of the Estimated Parameters

Usage

## S3 method for class 'tsissm.estimate'
vcov(object, adjust = FALSE, type = c("H", "OP", "QMLE", "NW"), ...)

Arguments

Value

The variance-covariance matrix of the estimated parameters.