Transfer Function and ARIMA Models

Description

The tfarima package provides classes and methods to build customized transfer function and ARIMA models with multiple operators and parameter restrictions. It includes functions for model identification, estimation using exact or conditional maximum likelihood, diagnostic checking, automatic outlier detection, calendar effects, forecasting, and seasonal adjustment.

Details

The current version extends the functionality by incorporating the estimation of unobserved components in ARIMA models through the UCARIMA representation and structural time series models.

Author(s)

Jose Luis Gallego jose.gallego@unican.es

References

Bell, W. R. and Hillmer, S. C. (1983). Modeling Time Series with Calendar Variation. Journal of the American Statistical Association, 78(383), 526–534.

Box, G. E. P., Jenkins, G. M., Reinsel, G. C., and Ljung, G. M. (2015). Time Series Analysis: Forecasting and Control. John Wiley & Sons, Hoboken.

Box, G. E. P., Pierce, D. A., and Newbold, D. A. (1987). Estimating Trend and Growth Rates in Seasonal Time Series. Journal of the American Statistical Association, 82(397), 276–282.

Box, G. E. P. and Tiao, G. C. (1975). Intervention Analysis with Applications to Economic and Environmental Problems. Journal of the American Statistical Association, 70(349), 70–79.

Chen, C. and Liu, L. (1993). Joint Estimation of Model Parameters and Outlier Effects in Time Series. Journal of the American Statistical Association, 88(421), 284–297.

Thompson, H. E. and Tiao, G. C. (1971). Analysis of Telephone Data: A Case Study of Forecasting Seasonal Time Series. Bell Journal of Economics, 2(2), 515–541.

AIC for fitted state space models

Description

AIC for fitted state space models

Usage

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

Arguments

Value

The AIC value, or NULL if model is not fitted.

AIC and BIC for Transfer Function Models

Description

Computes Akaike's Information Criterion (AIC) and Bayesian Information Criterion (BIC) for transfer function models.

Usage

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

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

Arguments

Details

AIC = -2*logLik + k*npar, where npar is the number of parameters. Lower values indicate better fit penalized for complexity.

Value

If one model: numeric value of AIC/BIC. If multiple models: data frame with columns df (degrees of freedom) and AIC for each model.

See Also

logLik.tfm, BIC.tfm

Examples

## Not run: 
model1 <- tfm(output, inputs = tf1, noise = noise1)
model2 <- tfm(output, inputs = tf2, noise = noise2)

# Single model AIC
AIC(model1)

# Compare models
AIC(model1, model2)

# BIC
BIC(model1)

## End(Not run)

Monthly Retail Sales: Building Material and Supplies Dealers (NAICS 4441)

Description

Monthly U.S. retail sales for building material and supplies dealers (NAICS code 4441), in millions of dollars, seasonally adjusted. Source: U.S. Census Bureau, Monthly Retail Trade Survey (via FRED).

Usage

BuildingMat

Format

A time series object of class ts with frequency 12, starting in January 1992 and ending in December 2024.

References

U.S. Census Bureau, Monthly Retail Trade Survey. FRED series code: MRTSSM4441USS.

Calendar variables

Description

'CalendarVar()' creates a set of deterministic regressors to capture calendar effects (trading/working days, length-of-month, leap-year and Easter).

Usage

CalendarVar(
  x,
  form = c("dif", "td", "td7", "td6", "wd", "null"),
  ref = 0,
  lom = TRUE,
  lpyear = TRUE,
  easter = FALSE,
  len = 4,
  easter.mon = FALSE,
  n.ahead = 0
)

Arguments

Value

An object of class 'ts' or 'mts' with the requested regressors.

References

Bell, W.R. and Hillmer, S.C. (1983) “Modeling time series with calendar variation”, *Journal of the American Statistical Association*, 78, 526–534.

Examples

X <- CalendarVar(AirPassengers, form = "wd", easter = TRUE, len = 5)

Intervention variables

Description

'InterventionVar()' creates pulse, step, or ramp variables at a given date.

Usage

InterventionVar(Y, date, type = c("P", "S", "R"), n.ahead = 0)

Arguments

Value

A 'ts' intervention variable.

References

Box, G.E.P. and Tiao, G.C. (1975) “Intervention analysis with applications to economic and environmental problems”, *JASA*, 70(349), 70–79.

Examples

# Pulse at March 1958:
P <- InterventionVar(AirPassengers, date = c(1958, 3), type = "P")
# Or by index within the extended sample (here no extension):
P2 <- InterventionVar(AirPassengers, date = 123, type = "P")

Annual (rolling) sum

Description

Computes rolling sum over one year for monthly/quarterly data.

Usage

S(x, extend = TRUE)

Arguments

Value

Time series of annual sums with same frequency as input.

Wisconsin Telephone Company

Description

Monthly data from January 1951 to October 1966.

Usage

Wtelephone

Format

A object of class data.frame with 215 rows and 2 columns:

X

Monthly outward station movements.

Y

Montly inward station movements.

Source

https://drive.google.com/file/d/1LP8aMIQewMrxgOlrg9rN3eWHhZuUsY8K/view?usp=sharing

References

Thompson, H. E. and Tiao, G. C. (1971) "Analysis of Telephone Data: A Case Study of Forecasting Seasonal Time Series," Bell Journal of Economics, The RAND Corporation, vol. 2(2), pages 515-541, Autumn.

Addition or substraction of univariate (ARIMA) models

Description

add_um creates a univariate (ARIMA) model from the addition or substraction of two univariate (arima) models.

Usage

add_um(um1, um2, add = TRUE, tol = 1e-05)

Arguments

Value

A "um" S3 object.

Note

The + and - operators can also be used to add or substract ARIMA models.

Examples

um1 <- um(i = "(1 - B)", ma = "(1 - 0.8B)")
um2 <- um(i = "(1 - B12)", ma = "(1 - 0.8B^12)")
um3 <- add_um(um1, um2)
um4 <- um3 - um2

Airline Model (SARIMA(0,1,1)x(0,1,1)s)

Description

Creates a seasonal ARIMA model with the structure popularized by Box and Jenkins using airline passenger data: (0,1,1)x(0,1,1)s.

Usage

airline(z, bc = FALSE, sma = c("standard", "generalized", "factorized"), ...)

Arguments

Details

This is a convenience function equivalent to: um(z, bc = bc, i = list(1, c(1, s)), ma = list(1, c(1, s)), ...) where s = frequency(z).

Value

A um object with airline model specification.

See Also

um

Lag polynomial converter

Description

as.lagpol converts a numeric vector c(1, -a_1, ..., -a_d) into a lag polynomial (1 - a_1 B - ... - a_p B^p).

Usage

as.lagpol(pol, p = 1, coef.name = "a")

Arguments

Value

An object of class lagpol.

Examples

as.lagpol(c(1, -0.8))
as.lagpol(c(1, 0, 0, 0, -0.8))

Structural form for an ARIMA model

Description

as.ssm finds the structural form for an ARIMA model from its the eventual forecast function.

Usage

## S3 method for class 'ucarima'
as.ssm(object, ...)

as.ssm(object, ...)

## S3 method for class 'um'
as.ssm(
  object,
  z = NULL,
  msoe = TRUE,
  H = NULL,
  cform = TRUE,
  tol = 1.490116e-08,
  nonadm = c("quadprog", "nnls", "none"),
  envir = NULL,
  ...
)

Arguments

Value

An object of class ssm

Examples

airl <- um(i = list(1, c(1, 12)), ma = "(1 - 0.8B)(1 - 0.8B12)")
ssm1 <- as.ssm(airl, index = c(1, 0, rep(2, 11)))
ssm1

Generic function for coercion to class "ucarima"

Description

Coerce an object to class "ucarima"

Usage

as.ucarima(object, ...)

Arguments

Value

An object of class "ucarima".

Coerce a Univariate Model to UCARIMA form

Description

Converts an object of class "um" (univariate model) to its equivalent "ucarima" representation, i.e., the ARIMA-model-based decomposition of unobserved components (trend, seasonal, cycle, irregular, etc.) implied by the univariate ARIMA structure, following the approach of Hillmer and Tiao (1982).

Usage

## S3 method for class 'um'
as.ucarima(
  object,
  ar = NULL,
  i = NULL,
  single = FALSE,
  canonical = FALSE,
  cwfact = c("roots", "iter", "best"),
  pfrac = c("gcd", "solve"),
  tol = 1e-05,
  envir = parent.frame(),
  ...
)

Arguments

Details

The UCARIMA decomposition expresses a univariate ARIMA model as the sum of independent component ARIMA models (trend, seasonal, cycle, irregular, etc.) obtained through the factorization of its spectral density. This provides a model-based interpretation of signal extraction and seasonal adjustment.

References

Hillmer, S. C., & Tiao, G. C. (1982). An ARIMA-model-based approach to seasonal adjustment. Journal of the American Statistical Association, 77(377), 63–70.

Burman, J. P. (1980). Seasonal adjustment by signal extraction. Journal of the Royal Statistical Society: Series A, 143(3), 321–337.

Godolphin, E. J. (1976). On the Cramer–Wold factorization. Biometrika, 63(2), 367–372. doi:10.1093/biomet/63.2.367

Tunnicliffe Wilson, G. (1969). Factorization of the covariance generating function of a pure moving average process. SIAM Journal on Numerical Analysis, 6(1), 1–7. doi:10.1137/0706001

See Also

ucarima

Convert arima into um.

Description

as.um converts an object of class arima into an object of class um.

Usage

as.um(arima, ...)

Arguments

Value

An object of class um.

Examples

z <- AirPassengers
a <- arima(log(z), order = c(0,1,1), 
seasonal = list(order = c(0,1,1), frequency = 12))
um1 <- as.um(a)

Theoretical simple/partial autocorrelations of an ARMA model

Description

autocorr computes the simple/partial autocorrelations of an ARMA model.

Usage

## S3 method for class 'ucarima'
autocorr(x, ...)

autocorr(x, ...)

## S3 method for class 'um'
autocorr(x, lag.max = 10, par = FALSE, ...)

Arguments

Value

A numeric vector.

Note

The I polynomial is ignored.

Examples

ar1 <- um(ar = "1-0.8B")
autocorr(ar1, lag.max = 13)
autocorr(ar1, lag.max = 13, par = TRUE)

Theoretical autocovariances of an ARMA model

Description

autocov computes the autocovariances of an ARMA model.

Usage

## S3 method for class 'ssm'
autocov(mdl, lag.max = NULL, arma = TRUE, varphi = FALSE, tol = 1e-04, ...)

## S3 method for class 'ucarima'
autocov(mdl, ma = FALSE, ...)

autocov(mdl, ...)

## S3 method for class 'um'
autocov(mdl, lag.max = 10, ...)

Arguments

Value

A numeric vector.

Note

The I polynomial is ignored.

Examples

# Local level model
ssm1 <- ssm(b = 1, C = 1, S = diag(c(irr = 0.8, lvl = 0.04)))
autocov(ssm1)

ar1 <- um(ar = "1-0.8B")
autocov(ar1, lag.max = 13)

Convert autocovariances to MA parameters

Description

Computes MA polynomial coefficients and error variance from autocovariances.

Usage

autocov2MA(x, method = c("roots", "acov"), tol = 1e-05)

Arguments

Value

Named vector: c(s2, ma0=1, ma1=-theta1, ..., maq=-thetaq).

References

Godolphin, E. J. (1976). On the Cramer-Wold factorization. Biometrika, 63(2), 367-372. doi:10.1093/biomet/63.2.367

Tunnicliffe Wilson, G. (1969). Factorization of the covariance generating function of a pure moving average process. SIAM Journal on Numerical Analysis, 6(1), 1-7. doi:10.1137/0706001

Examples

ma1 <- um(ma = "1 - 0.8B", sig2 = 0.5)
autocov2MA(autocov(ma1, 1))
autocov2MA(autocov(ma1, 1), method = "acov")

Calendar effects

Description

calendar extends the ARIMA model um by including a set of deterministic variables to capture the calendar variation in a monthly time series. Two equivalent representations are available: (i) D0, D1, ..., D6, (ii) L, D1-D0, ..., D6-D0 where D0, D2, ..., D6 are deterministic variables representing the number of Sundays, Mondays, ..., Saturdays, L = D0 + D1 + ... + D6 is the of the month. Alternatively, the Leap Year indicator (LPY) can be included instead of L. The seven trading days can also be compacted into two variables: week days and weekends. Optionally, a deterministic variable to estimate the Easter effect can also be included, see "easter".

Usage

## S3 method for class 'ssm'
calendar(
  mdl,
  form = c("dif", "td", "td7", "td6", "wd"),
  ref = 0,
  lom = TRUE,
  lpyear = TRUE,
  easter = FALSE,
  len = 4,
  easter.mon = FALSE,
  n.ahead = 0,
  p.value = 1,
  envir = NULL,
  ...
)

## S3 method for class 'tfm'
calendar(
  mdl,
  y = NULL,
  form = c("dif", "td", "td7", "td6", "wd"),
  ref = 0,
  lom = TRUE,
  lpyear = TRUE,
  easter = FALSE,
  len = 4,
  easter.mon = FALSE,
  n.ahead = 0,
  p.value = 1,
  envir = parent.frame(),
  ...
)

calendar(mdl, ...)

## S3 method for class 'um'
calendar(
  mdl,
  y = NULL,
  form = c("dif", "td", "td7", "td6", "wd"),
  ref = 0,
  lom = TRUE,
  lpyear = TRUE,
  easter = FALSE,
  len = 4,
  easter.mon = FALSE,
  n.ahead = 0,
  p.value = 1,
  envir = parent.frame(),
  ...
)

Arguments

Value

An object of class "tfm".

References

W. R. Bell & S. C. Hillmer (1983) Modeling Time Series with Calendar Variation, Journal of the American Statistical Association, 78:383, 526-534, DOI: 10.1080/01621459.1983.10478005

Examples

data(rsales)
um1 <- um(rsales, i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
tfm1 <- calendar(um1)

Cross-correlation check

Description

ccf displays ccf between prewhitened inputs and residuals.

Usage

ccf.tfm(
  x,
  lag.max = NULL,
  method = c("exact", "cond"),
  envir = parent.frame(),
  ...
)

Arguments

Coefficients of a Transfer Function Model

Description

Extracts the estimated coefficients from a fitted transfer function model of class tfm. This is a method for the generic coef function.

Usage

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

Arguments

Value

A named numeric vector with the estimated coefficients of the model, including regression coefficients, transfer function parameters, and noise model parameters.

See Also

tfm

Examples

## Not run: 
mdl <- tfm(y, xreg = X, noise = um())
coef(mdl)

## End(Not run)

Extract coefficients from UCM objects

Description

Extract coefficients from UCM objects

Usage

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

Arguments

Value

A named numeric vector of model coefficients.

Coefficients of a univariate model

Description

coef extracts the "coefficients" from a um object.

Usage

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

Arguments

Value

A numeric vector.

Cramer-Wold Factorization

Description

cwfact performs the Cramer-Wold factorization of the generating autocovariance function of a pure moving average (MA) process, expressed as:

g(x) = \theta(x)\theta(x^{-1})

where

g(x) = g_0 + g_1(x + x^{-1}) + \dots + g_q(x^q + x^{-q})

and

\theta(x) = \theta_0 + \theta_1 x + \dots + \theta_q x^q

Usage

cwfact(
  g,
  th = NULL,
  method = c("roots", "wilson", "best"),
  tol = 1e-08,
  iter.max = 500
)

Arguments

Details

The factorization can be computed by finding the roots of the polynomial g(x), or using the iterative Wilson (1969) algorithm as implemented by Laurie (1981).

The implementation for method = "laurie" is a custom R adaptation of Algorithm AS 175 from Laurie (1981).

Value

A numeric vector containing the moving average coefficients c(theta_0, ..., theta_q).

References

Wilson, G. T. (1969). Factorization of the covariance generating function of a pure moving average process. SIAM Journal on Numerical Analysis, 6(1), 1–7.

Laurie, D. P. (1981). Cramer-Wold Factorization. Journal of the Royal Statistical Society Series C: Applied Statistics, 31(1), 86–93.

Examples

g <- autocov(um(ma = "1 - 0.8B"), lag.max = 1)
cwfact(g, method = "roots")
cwfact(g, method = "wilson")

Unobserved components decomposition

Description

Estimates the unobserved components of a time series (trend, seasonal, cycle, stationary, and irregular) based on the structure of an underlying model. The estimation can be carried out through the UCARIMA representation, the state-space model (SSM) form, or via forward/backward forecasts.

Usage

## S3 method for class 'ssm'
decomp(mdl, tol = 1e-05, ...)

## S3 method for class 'tfm'
decomp(
  mdl,
  y = NULL,
  method = c("mixed", "forecast", "backcast"),
  envir = NULL,
  ...
)

## S3 method for class 'ucarima'
decomp(mdl, ...)

decomp(mdl, ...)

## S3 method for class 'um'
decomp(
  mdl,
  z = NULL,
  method = c("ucarima", "ucarima0", "ssm", "ssm0", "mixed", "forecast", "backcast"),
  envir = parent.frame(),
  ...
)

## S3 method for class 'um'
decomp(
  mdl,
  z = NULL,
  method = c("ucarima", "ucarima0", "ssm", "ssm0", "mixed", "forecast", "backcast"),
  envir = parent.frame(),
  ...
)

Arguments

Details

The function applies the corresponding internal routines to estimate the components depending on the chosen method. For UCARIMA-based methods, the Wiener–Kolmogorov filter is used. For state-space approaches, a Kalman smoother is applied.

Value

A data.frame with the estimated unobserved components.

Examples

Z <- AirPassengers
um1 <- um(Z, i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
uc1 <- decomp(um1, method = "ucarima")

Diagnostic checking

Description

For objects of class ucarima, this method calls diagchk.um internally to perform diagnostic checking.

diagchk displays tools for diagnostic checking.

Usage

## S3 method for class 'ssm'
diagchk(mdl, lag.max = NULL, lags.at = NULL, freq.at = NULL, std = TRUE, ...)

## S3 method for class 'ucarima'
diagchk(mdl, ...)

diagchk(mdl, ...)

## S3 method for class 'um'
diagchk(
  mdl,
  z = NULL,
  method = c("exact", "cond"),
  lag.max = NULL,
  lags.at = NULL,
  freq.at = NULL,
  std = TRUE,
  envir = NULL,
  ...
)

Arguments

Examples

# Local level model
b <- 1
C <- as.matrix(1)
ssm1 <- ssm(Nile, b, C, S = diag(c(irr = 15127.7, lvl = 1453.2)))
diagchk(ssm1)
z <- AirPassengers
airl <- um(z, i = list(1, c(1,12)), ma = list(1, c(1,12)), bc = TRUE)
diagchk(airl)

Diagnostic Checking for Transfer Function Models

Description

Produces diagnostic plots for residuals of a fitted transfer function model.

Usage

## S3 method for class 'tfm'
diagchk(
  mdl,
  y = NULL,
  method = c("exact", "cond"),
  lag.max = NULL,
  lags.at = NULL,
  freq.at = NULL,
  std = TRUE,
  envir = NULL,
  ...
)

Arguments

Details

Generates five diagnostic plots: time series plot of residuals, histogram, ACF, PACF, and cumulative periodogram. Uses the ide function for plotting.

See Also

tfm, tsdiag.tfm

Graphs for ARMA models

Description

display shows graphs characterizing one or a list of ARMA models.

Usage

display(um, ...)

## S3 method for class 'um'
display(
  um,
  lag.max = 25,
  n.freq = 501,
  log.spec = FALSE,
  lags.at = NULL,
  graphs = c("acf", "pacf", "spec"),
  byrow = FALSE,
  eq = TRUE,
  cex = 1.25,
  ...
)

## Default S3 method:
display(um, ...)

Arguments

Examples

um1 <- um(ar = "(1 - 0.8B)(1 - 0.8B^12)")
um2 <- um(ma = "(1 - 0.8B)(1 - 0.8B^12)")
display(list(um1, um2))

Easter effect

Description

easter extends the ARIMA model um by including a regression variable to capture the Easter effect.

Usage

easter(um, ...)

## S3 method for class 'um'
easter(
  um,
  z = NULL,
  len = 4,
  easter.mon = FALSE,
  n.ahead = 0,
  envir = NULL,
  ...
)

Arguments

Value

An object of class "tfm".

Examples

data(rsales)
um1 <- um(rsales, i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
tfm1 <- easter(um1)

Equation of ucarima model

Description

equation prints the equation of an object of class um.

Usage

## S3 method for class 'ucarima'
equation(x, ...)

equation(x, ...)

## S3 method for class 'um'
equation(
  x,
  unscramble = FALSE,
  digits = 4,
  z = "z",
  a = "a",
  width = NULL,
  ...
)

Arguments

Examples

equation(um(ar = "(1 - 0.8B)"))

Factorized form of a univariate ARIMA model

Description

factorize .

Usage

factorize(um, ...)

## S3 method for class 'um'
factorize(um, full = TRUE, ...)

Arguments

Examples

factorize(um(ar = "(1 - 0.8B)"))

Lag polynomial factorization

Description

factors extracts the simplifying factors of a polynomial in the lag operator by replacing, if needed, its approximate unit or real roots to exact unit or real roots.

Usage

factors(lp, ...)

## S3 method for class 'lagpol'
factors(lp, full = TRUE, tol = 1e-05, expand = FALSE, ...)

Arguments

Value

factors returns a list with the simplifying factors of the lag polynomial or the expanded polynomial.

Examples

factors( as.lagpol(c(1, rep(0, 11), -1)) )

Estimation of the ARIMA model

Description

fit fits the univariate model to the time series z.

Usage

## S3 method for class 'ssm'
fit(
  mdl,
  z = NULL,
  updateSSM,
  param,
  show.iter = FALSE,
  tol = 1e-04,
  method = "BFGS",
  ...
)

fit(mdl, ...)

## S3 method for class 'um'
fit(
  mdl,
  z = NULL,
  method = c("exact", "cond"),
  optim.method = "BFGS",
  show.iter = FALSE,
  envir = NULL,
  ...
)

Arguments

Value

An object of class "ssm" with the estimated parameters.

An object of class "um" with the estimated parameters.

Note

The um function estimates the corresponding ARIMA model when a time series is provided. The fit function is useful to fit a model to several time series, for example, in a Monte Carlo study.

Examples

# Predefined local level model
ucm1 <- ucm(Nile, uc = "llm", fit = FALSE)
ucm1 <- fit(ucm1)
ucm1

# User defined local level model
ssm1 <- ssm(Nile, b = 1, C = 1, S = diag(c(1, 0.5)) )
param <- c(irr = var(Nile), lvl = var(diff(Nile)))
updateSSM <- function(mdl, param) {
mdl$S[1,1] <- param[1]
mdl$S[2,2] <- param[2]
mdl
}
fit(ssm1, updateSSM = updateSSM, param = param)

z <- AirPassengers
airl <- um(i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
airl <- fit(airl, z)

Fit a Transfer Function Model

Description

Estimates the parameters of a transfer function model of class tfm by (conditional or exact) maximum likelihood.

Usage

## S3 method for class 'tfm'
fit(
  mdl,
  y = NULL,
  method = c("exact", "cond"),
  optim.method = "BFGS",
  show.iter = FALSE,
  fit.noise = TRUE,
  envir = NULL,
  ...
)

Arguments

Value

An updated object of class tfm containing fitted parameters, estimated innovation variance, and optimization details.

See Also

tfm

Examples

## Not run: 
data(seriesJ)
Y <- seriesJ$Y - mean(seriesJ$Y)
X <- seriesJ$X - mean(seriesJ$X)
umx <- um(X, ar = 3)
umy <- fit(umx, Y)
tfx <- tfest(Y, X, delay = 3, p = 2, q = 2, um.x = umx, um.y = umy)
tfmy <- tfm(Y, inputs = tfx, noise = um(ar = 2), fit = FALSE)
tfmy_fit <- fit(tfmy)

## End(Not run)

Estimation of UCARIMA models

Description

Estimates the parameters of a UCARIMA model using maximum likelihood.

Usage

## S3 method for class 'ucarima'
fit(mdl, z = NULL, method = "BFGS", show.iter = FALSE, envir = NULL, ...)

Arguments

Value

An updated ucarima object with estimated parameters, log-likelihood, and convergence information.

Examples

# Define a local level model with trend and irregular components
trend <- um(i = 1, sig2 = c(s2t = 0.5))
irreg <- um(sig2 = c(s2i = 1))

# Create and estimate the UCARIMA model
uca <- ucarima(ucm = list(trend = trend, irreg = irreg))
uca_fitted <- fit(uca, Nile)

Identification plots

Description

ide displays graphs useful to identify a tentative ARIMA model for a time series.

Usage

ide(
  Y,
  transf = list(),
  order.polreg = 0,
  lag.max = NULL,
  lags.at = NULL,
  freq.at = NULL,
  wn.bands = TRUE,
  graphs = c("plot", "acf", "pacf"),
  set.layout = TRUE,
  byrow = TRUE,
  main = "",
  plot.abline.args = NULL,
  plot.points.args = NULL,
  envir = NULL,
  ...
)

Arguments

Examples

Y <- AirPassengers
ide(Y, graphs = c("plot", "rm"))
ide(Y, transf = list(list(bc = TRUE, S = TRUE), list(bc = TRUE, d = 1, D = 1)))

Initialization of Kalman filter

Description

init_kf computes the starting values x0 and P0 by generalized least squares using the first n observations.

Usage

init_kf(mdl, z = NULL, n = 0)

Arguments

Value

A list with components:

Intervention analysis/Outlier treatment

Description

intervention estimates the effect of a intervention at a known time.

Usage

## S3 method for class 'tfm'
intervention(
  mdl,
  y = NULL,
  type,
  time,
  n.ahead = 0,
  envir = parent.frame(),
  ...
)

intervention(mdl, ...)

## S3 method for class 'um'
intervention(
  mdl,
  y = NULL,
  type,
  time,
  n.ahead = 0,
  envir = parent.frame(),
  ...
)

Arguments

Value

an object of class "tfm" or a table.

Inverse of a lag polynomial

Description

inv inverts a lag polynomial until the indicated lag.

Usage

inv(lp, ...)

## S3 method for class 'lagpol'
inv(lp, lag.max = 10, ...)

Arguments

Value

inv returns a numeric vector with the coefficients of the inverse lag polynomial truncated at lag.max.

Examples

inv(as.lagpol(c(1, 1.2, -0.8))) 

Impulse response function

Description

Computes and plots the impulse response function (IRF) or step response function (SRF) of a transfer function.

Usage

irf(tf, lag.max = 10, cum = FALSE, plot = TRUE)

Arguments

Value

If plot = FALSE, a named numeric vector with IRF/SRF values. If plot = TRUE, creates a plot and returns nothing (invisibly).

Examples

# Create transfer function
x <- rep(0, 100); x[50] <- 1
tfx <- tf(x, w0 = 0.8, ar = "(1 - 0.5B)")

# Plot impulse response function
irf(tfx, lag.max = 15)

# Get step response values without plot
srf_values <- irf(tfx, lag.max = 10, cum = TRUE, plot = FALSE)

Kalman filter for SS models

Description

kf computes the innovations and the conditional states with the Kalman filter algorithm.

Usage

kf(mdl, z = NULL, x0 = NULL, P0 = NULL, filtered = FALSE, ...)

Arguments

Value

A list with the innovations, the conditional states and their covariance matrices.

Kalman smoother for SS models

Description

ks computes smoothed states and their covariance matrices.

Usage

ks(mdl, x0 = NULL, P0 = NULL)

Arguments

Lag polynomials

Description

lagpol creates a lag polynomial of the form:

(1 - coef_1 B^s - ... - coef_d B^{sd})^p

This class of lag polynomials is defined by:

• the base lag polynomial 1 - coef_1 B^s - ... - coef_d B^{sd},

• the exponent 'p' of the base lag polynomial (default is 'p = 1'),

• the spacing parameter 's' in sparse lag polynomials (default is 's = 1'),

• the vector of 'd' coefficients 'c(coef_1, ..., coef_d)', which can be mathematical expresions dependent on 'k' parameters 'c(param_1, ..., param_k)'.

Usage

lagpol(param = NULL, s = 1, p = 1, lags = NULL, coef = NULL)

Arguments

Value

lagpol An object of class 'lagpol' with the following components:

coef

vector of coefficients c(coef_1, ..., coef_p) provided to create the lag polynomial.

pol

base lag polynomial vector: 1 - \text{coef}_1 B^s - \dots - \text{coef}_d B^{sd}.

Pol

lag polynomial raised to the power 'p'. If 'p = 1', this equals 'pol'.

Examples

# Simple AR(1) lag polynomial: 1 - 0.8B
lagpol(param = c(phi = 0.8))

# AR(2) lag polynomial with seasonal lag s = 4: 1 - 1.2B^4 + 0.6B^8
lagpol(param = c(phi1 = 1.2, phi2 = -0.6), s = 4)

# Integration operator squared: (1 - B)^2 = 1 - 2B + B^2
lagpol(param = c(delta = 1), p = 2)

# Lag polynomial using explicit coefficients
lagpol(coef = c("1"), p = 2)  # (1 - B)^2 = 1 - 2B + B^2

# Custom coefficients defined by mathematical expressions
lagpol(param = c(theta = 0.8), coef = c("2*cos(pi/6)*sqrt(theta)", "-theta"))

Create lag polynomial objects

Description

'lagpol0' is a flexible constructor for lagpol objects. It accepts multiple input formats: polynomial orders (d, s, p), literal equations (e.g., 1 - 0.8B), or seasonal specifications for special lag polynomials like AR/I/MA(s-1).

Usage

lagpol0(op, type, envir = parent.frame())

Arguments

Value

List of lagpol objects.

See Also

lagpol

Examples

# AR(1) polynomial
lagpol0(op = 1, type = "ar")

# From literal equation
lagpol0(op = "1 - 0.8B", type = "ar")

# Multiple polynomials at once
lagpol0(op = list(1, "1 - 0.5B"), type = "ma")

# Seasonal polynomial
lagpol0(op = "12", type = "ar")

# Custom orders with seasonal component
lagpol0(op = c(2, 12, 1), type = "ar")

Log-likelihood of a SS model

Description

logLik.ssm computes the exact or conditional log-likelihood of a state space model.

Usage

## S3 method for class 'ssm'
logLik(object, method = c("exact", "cond"), ...)

Arguments

Value

The log-likelihood value.

Examples

# Local level model
b <- 1
C <- as.matrix(1)
ssm1 <- ssm(Nile, b, C, S = diag(c(irr = 15127.7, lvl = 1453.2)))
logLik(ssm1)
 

Log-Likelihood of Transfer Function Model

Description

Computes the log-likelihood for a fitted transfer function model.

Usage

## S3 method for class 'tfm'
logLik(
  object,
  y = NULL,
  method = c("exact", "cond"),
  envir = parent.frame(),
  ...
)

Arguments

Value

Numeric value of the log-likelihood.

See Also

tfm, fit.tfm, AIC.tfm

Log-likelihood of an ARIMA model

Description

logLik computes the exact or conditional log-likelihood of object of the class um.

Usage

## S3 method for class 'um'
logLik(object, z = NULL, method = c("exact", "cond"), ...)

Arguments

Value

The exact or conditional log-likelihood.

Modifying a TF or an ARIMA model

Description

modify modifies an object of class um or tfm by adding and/or removing lag polynomials.

Usage

## S3 method for class 'tfm'
modify(
  mdl,
  ar = NULL,
  i = NULL,
  ma = NULL,
  mu = NULL,
  sig2 = NULL,
  bc = NULL,
  ...
)

modify(mdl, ...)

## S3 method for class 'um'
modify(
  mdl,
  ar = NULL,
  i = NULL,
  ma = NULL,
  mu = NULL,
  sig2 = NULL,
  bc = NULL,
  ...
)

Arguments

Value

An object of class um or um.

Examples

um1 <- um(ar = "(1 - 0.8B)")
um2 <- modify(um1, ar = list(0, "(1 - 0.9B)"), ma = "(1 - 0.5B)")

Unscramble I polynomial

Description

nabla multiplies the I polynomials of an object of the um class.

Usage

## S3 method for class 'ucarima'
nabla(x, i = NULL, lp = TRUE, ...)

nabla(x, ...)

## S3 method for class 'um'
nabla(x, ...)

Arguments

Value

A numeric vector c(1, a1, ..., ad)

Note

This function returns the member variable um$nabla.

Examples

um1 <- um(i = "(1 - B)(1 - B^12)")
nabla(um1)

Extract Noise Component from Transfer Function Model

Description

Computes the noise series (output minus fitted signal) from a transfer function model.

Usage

## S3 method for class 'ssm'
noise(mdl, diff = TRUE, exp = FALSE, ...)

noise(mdl, ...)

## S3 method for class 'tfm'
noise(mdl, y = NULL, diff = TRUE, exp = FALSE, envir = parent.frame(), ...)

Arguments

Details

The noise represents the component of the output not explained by the transfer functions and exogenous regressors. When diff = TRUE, the differencing operator from the noise model is applied, resulting in a stationary series suitable for ARMA modeling.

Value

A ts object containing the noise series, computed as output minus all transfer function and regressor effects.

See Also

signal.tfm, residuals.tfm, tfm

Outlier dates

Description

outlierDates shows the indeces and dates of outliers.

Usage

outlierDates(x, c = 3)

Arguments

Value

A table with the indices, dates and z-scores of the outliers.

Outliers detection at known/unknown dates

Description

outliers performs a detection of four types of anomalies (AO, TC, LS and IO) in a time series described by an ARIMA model. If the dates of the outliers are unknown, an iterative detection process like that proposed by Chen and Liu (1993) is conducted.

Usage

## S3 method for class 'ssm'
outliers(
  mdl,
  types = c("AO", "LS", "TC"),
  dates = NULL,
  c = 3,
  calendar = FALSE,
  easter = FALSE,
  resid = c("exact", "cond"),
  n.ahead = 0,
  p.value = 1,
  ...
)

## S3 method for class 'tfm'
outliers(
  mdl,
  y = NULL,
  types = c("AO", "LS", "TC", "IO"),
  dates = NULL,
  c = 3,
  calendar = FALSE,
  easter = FALSE,
  resid = c("exact", "cond"),
  n.ahead = 0,
  p.value = 1,
  tc.fix = TRUE,
  envir = parent.frame(),
  ...
)

## S3 method for class 'ucarima'
outliers(
  mdl,
  types = c("AO", "LS", "TC"),
  dates = NULL,
  c = 3,
  calendar = FALSE,
  easter = FALSE,
  resid = c("exact", "cond"),
  n.ahead = 0,
  p.value = 1,
  ...
)

outliers(mdl, ...)

## S3 method for class 'um'
outliers(
  mdl,
  y = NULL,
  types = c("AO", "LS", "TC", "IO"),
  dates = NULL,
  c = 3,
  calendar = FALSE,
  easter = FALSE,
  resid = c("exact", "cond"),
  n.ahead = 0,
  p.value = 1,
  tc.fix = TRUE,
  envir = NULL,
  ...
)

Arguments

Value

an object of class "tfm" or a table.

Examples

data(rsales)
um1 <- um(rsales, i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
outliers(um1)

Output of a transfer function or a transfer function model

Description

output filters the input using the transfer function.

Usage

output(object, ...)

## S3 method for class 'tf'
output(object, ...)

Arguments

Value

A "ts" object

Prewhitened cross correlation function

Description

pccf displays cross correlation function between input and output after prewhitening both through a univariate model.

Usage

pccf(
  x,
  y,
  um.x = NULL,
  um.y = NULL,
  lag.max = NULL,
  plot = TRUE,
  envir = NULL,
  main = NULL,
  nu.weights = FALSE,
  ...
)

Arguments

Value

The estimated cross correlations are displayed in a graph or returned into a numeric vector.

Unscramble AR polynomial

Description

phi multiplies the AR polynomials of an object of the um class.

Usage

## S3 method for class 'ucarima'
phi(x, i = NULL, ar = TRUE, lp = TRUE, ...)

phi(x, ...)

## S3 method for class 'um'
phi(x, ...)

Arguments

Value

A numeric vector c(1, a1, ..., ad)

Note

This function returns the member variable um$phi.

Examples

um1 <- um(ar = "(1 - 0.8B)(1 - 0.5B)")
phi(um1)

Pi weights of an AR(I)MA model

Description

pi.weights computes the pi-weights of an AR(I)MA model.

Usage

pi.weights(um, ...)

## S3 method for class 'um'
pi.weights(um, lag.max = 10, var.pi = FALSE, ...)

Arguments

Value

A numeric vector.

Examples

um1 <- um(i = "(1 - B)(1 - B^12)", ma = "(1 - 0.8B)(1 - 0.8B^12)")
pi.weights(um1, var.pi = TRUE)

Evaluate the k-th derivative of a polynomial at point z

Description

Evaluate the k-th derivative of a polynomial at point z

Usage

polyderivEvalR(pol, z, k = 0)

Arguments

Value

Numeric value of the k-th derivative of P(z).

Examples

pol <- c(1, 2, 3, 4)  # P(z) = 1 + 2z + 3z² + 4z³
polyderivEvalR(pol, 2, 0)  # 49
polyderivEvalR(pol, 2, 1)  # 62

Predict method for state space models

Description

predict.ssm generates forecasts from fitted state space models by converting to univariate ARIMA or transfer function models and using their prediction methods.

Usage

## S3 method for class 'ssm'
predict(object, ...)

Arguments

Value

An object of class predict.um or predict.tfm.

See Also

predict.um, predict.tfm

Predict transfer function

Description

Predict transfer function

Usage

## S3 method for class 'tf'
predict(object, n.ahead, ...)

Arguments

Value

Point forecast for input.

Forecast Transfer Function Model

Description

Computes point forecasts and prediction intervals for transfer function models.

Usage

## S3 method for class 'tfm'
predict(
  object,
  newdata = NULL,
  y = NULL,
  ori = NULL,
  n.ahead = NULL,
  level = 0.95,
  i = NULL,
  envir = NULL,
  ...
)

Arguments

Details

Future values for transfer function inputs can be provided in three ways: (1) extending input series beyond output length, (2) automatic forecasting from associated um models, or (3) via the newdata argument.

If Box-Cox transformation was used, forecasts are back-transformed and intervals adjusted accordingly.

Value

Object of class predict.tfm containing:

See Also

tfm, fit.tfm

Forecasts from an ARIMA model

Description

predict computes point and interval predictions for a time series from models of class um.

Usage

## S3 method for class 'um'
predict(
  object,
  z = NULL,
  ori = NULL,
  n.ahead = 1,
  level = 0.95,
  i = NULL,
  envir = NULL,
  ...
)

Arguments

Value

An object of class "predict.um".

Examples

Z <- AirPassengers
um1 <- um(Z, i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
p <- predict(um1, n.ahead = 12)
p
plot(p, n.back = 60)

Print Method for Lag Polynomial Objects

Description

Prints objects of class lagpol.

Usage

## S3 method for class 'lagpol'
print(x, digits = 2, width = getOption("width"), ...)

Arguments

Value

Invisibly returns the lagpol object.

Print method for ssm objects

Description

Print method for ssm objects

Usage

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

Arguments

Value

Invisibly returns NULL.

Print summary of fitted state space model

Description

print.summary.ssm prints a detailed summary of the results of the estimation of a ssm object.

Usage

## S3 method for class 'summary.ssm'
print(x, stats = TRUE, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

Invisible NULL.

Print Summary of Transfer Function Model

Description

Print method for objects of class summary.tfm.

Usage

## S3 method for class 'summary.tfm'
print(
  x,
  stats = TRUE,
  short = FALSE,
  digits = max(3L, getOption("digits") - 3L),
  ...
)

Arguments

See Also

summary.tfm

Print Summary of Univariate Model

Description

Print method for objects of class summary.um.

Usage

## S3 method for class 'summary.um'
print(
  x,
  stats = TRUE,
  short = FALSE,
  digits = max(3L, getOption("digits") - 3L),
  ...
)

Arguments

See Also

summary.tfm

Print method for transfer function objects

Description

Print method for transfer function objects

Print ucarima models

Print univariate models

Print univariate models

Usage

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

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

## S3 method for class 'predict.um'
print(x, rows = NULL, ...)

## S3 method for class 'um'
print(x, arima = FALSE, ...)

Arguments

Print Transfer Function Model

Description

Print method for objects of class tfm.

Usage

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

Arguments

Details

Prints a summary of the transfer function model by calling summary(x) with short = TRUE.

See Also

tfm, summary.tfm

Print method for unobserved components

Description

Print method for unobserved components

Usage

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

Arguments

Value

Invisibly returns NULL.

Print non-normalized polynomial as a lag polynomial

Description

Prints a non-normalized polynomial as a lagpol object, preserving the original coefficients.

Usage

printLagpol(pol, digits = 2, width = getOption("width"))

Arguments

Value

Invisibly returns the input vector.

Prints a list of lagpol objects.

Description

Prints a list of lagpol objects.

Usage

printLagpolList(llp, digits = 2, width = getOption("width"))

Arguments

Value

Invisibly returns the list of lagpol objects.

Psi weights of an AR(I)MA model

Description

psi computes the psi-weights of an AR(I)MA model.

Usage

psi.weights(um, ...)

## S3 method for class 'um'
psi.weights(um, lag.max = 10, var.psi = FALSE, ...)

Arguments

Value

A numeric vector.

Examples

um1 <- um(i = "(1 - B)(1 - B^12)", ma = "(1 - 0.8B)(1 - 0.8B^12)")
psi.weights(um1)
psi.weights(um1, var.psi = TRUE)

Residuals of fitted state space models

Description

residuals.ssm generates the residuals of a fitted ssm object.

Usage

## S3 method for class 'ssm'
residuals(object, method = c("exact", "cond"), ...)

Arguments

Details

These residuals are calculated by first converting the ssm object to a um object and then using the residuals.um function.

Value

A ts object containing the residuals of the SSM.

Examples

# Local level model
b <- 1
C <- as.matrix(1)
ssm1 <- ssm(Nile, b, C, S = diag(c(irr = 15127.7, lvl = 1453.2)))
u <-residuals(ssm1)

Extract Residuals from Transfer Function Model

Description

Computes exact or conditional residuals from a fitted transfer function model.

Usage

## S3 method for class 'tfm'
residuals(
  object,
  y = NULL,
  method = c("exact", "cond"),
  envir = parent.frame(),
  ...
)

Arguments

Value

A ts object containing model residuals with the same time series attributes as the output series.

Residuals of fitted UCARIMA models

Description

residuals.ucarima generates the residuals of a fitted ucarima object.

Usage

## S3 method for class 'ucarima'
residuals(object, method = c("exact", "cond"), ...)

Arguments

Details

These residuals are calculated by first converting the ucarima object to a um object and then using the residuals.um function.

Value

A ts object containing the residuals of the SSM.

Residuals of the ARIMA model

Description

residuals computes the exact or conditional residuals.

Usage

## S3 method for class 'um'
residuals(object, z = NULL, method = c("exact", "cond"), envir = NULL, ...)

Arguments

Value

An object of class um.

Examples

z <- AirPassengers
airl <- um(z, i = list(1, c(1, 12)), ma = list(1, c(1, 12)), bc = TRUE)
r <- residuals(airl)
summary(r)

Roots of lag polynomials

Description

roots computes the roots of lag polynomials from polynomial objects and time series models that contain lag polynomials as components.

Usage

roots(x, ...)

## Default S3 method:
roots(x, ...)

## S3 method for class 'lagpol'
roots(x, table = TRUE, tol = 1e-05, ...)

## S3 method for class 'tf'
roots(x, opr = c("arma", "ar", "ma"), ...)

## S3 method for class 'um'
roots(x, opr = c("arma", "ar", "ma", "i", "arima"), ...)

Arguments

Value

Returns a summary table with the roots of each lagpol.

Examples

roots(c(1, 1.2, -0.8))
um1 <- um(ar = "(1 - 0.8B)(1 - 0.8B^12)")
roots(um1)

Lag polynomial from roots

Description

roots2lagpol creates a lag polynomial from its roots.

Usage

roots2lagpol(x, lp = TRUE, ...)

Arguments

Value

A lag polynomial or a numeric vector.

Examples

roots2lagpol(polyroot(c(1, -1)))
roots2lagpol(polyroot(c(1, -1, 1)))

Retail Sales of Variety Stores (U.S. Bureau of the Census)

Description

156 monthly observations from January 1967 to December 1979.

Usage

rsales

Format

An object of class ts of length 156.

References

Chen, C. and Liu, L. (1993) Joint Estimation of Model Parameters and Outlier Effects in Time Series, Journal of the American Statistical Association, Vol. 88, No. 421, pp. 284-297

Seasonal dummies

Description

'sdummies()' creates a full set of seasonal dummies (reference-coded).

Usage

sdummies(Y, ref = 1, constant = FALSE, n.ahead = 0)

Arguments

Value

A 'ts' matrix with seasonal dummies (and intercept if requested).

Examples

D <- sdummies(AirPassengers, ref = 1, constant = TRUE, n.ahead = 24)

Seasonal adjustment

Description

seasadj removes the seasonal component of time series.

Usage

seasadj(mdl, ...)

## S3 method for class 'um'
seasadj(
  mdl,
  z = NULL,
  method = c("ucarima", "ucarima0", "ssm", "ssm0", "mixed", "forecast", "backcast"),
  envir = parent.frame(),
  ...
)

Arguments

Value

seasadj returns a seasonal adjusted time series.

Examples

Y <- AirPassengers
um1 <- um(Y, bc = TRUE, i = list(1, c(1,12)), ma = list(1, c(1,12)))
Y <- seasadj(um1)
ide(Y)

Series C Chemical Process Temperature Readings: Every Minute.

Description

226 observations.

Usage

seriesC

Format

An object of class numeric of length 226.

References

Box, G.E., Jenkins, G.M., Reinsel, G.C. and Ljung, G.M. (2015) Time Series Analysis: Forecasting and Control. John Wiley & Sons, Hoboken.

Gas furnace data

Description

Sampling interval 9 seconds; observations for 296 pairs of data points.

Usage

seriesJ

Format

A object of class data.frame with 296 rows and 2 columns:

X

0.60-0.04 (input gas rate in cubir feet per minute.)

Y

% CO2 in outlet gas.

References

Box, G.E., Jenkins, G.M., Reinsel, G.C. and Ljung, G.M. (2015) Time Series Analysis: Forecasting and Control. John Wiley & Sons, Hoboken.

Add or Replace Inputs in Models

Description

Adds new inputs to transfer function or univariate models.

Usage

## S3 method for class 'tfm'
setinputs(
  mdl,
  xreg = NULL,
  inputs = NULL,
  y = NULL,
  envir = parent.frame(),
  ...
)

setinputs(mdl, ...)

## S3 method for class 'um'
setinputs(mdl, xreg = NULL, inputs = NULL, y = NULL, envir = NULL, ...)

Arguments

Details

For tfm objects: If the model already has inputs of the same type, new ones are appended (combined). The model is re-fitted by default unless fit = FALSE.

Value

A tfm object.

See Also

um, tfm

Signal component of a TF model

Description

signal extracts the signal of a TF model.

Usage

signal(mdl, ...)

## S3 method for class 'tfm'
signal(
  mdl,
  y = NULL,
  diff = FALSE,
  type = c("xreg", "inputs"),
  envir = parent.frame(),
  ...
)

Arguments

Value

A "ts" object.

Simulate Time Series from ARIMA or Transfer Function Models

Description

Generates random time series from ARIMA (um) or transfer function (tfm) models.

Usage

## S3 method for class 'tfm'
sim(
  mdl,
  n = 100,
  z0 = NULL,
  n0 = 0,
  a = NULL,
  seed = NULL,
  envir = parent.frame(),
  ...
)

sim(mdl, ...)

## S3 method for class 'um'
sim(
  mdl,
  n = 100,
  z0 = NULL,
  n0 = 0,
  a = NULL,
  seed = NULL,
  envir = parent.frame(),
  ...
)

Arguments

Value

A ts object with the simulated time series.

See Also

sim.um, sim.tfm

Examples

# AR(1) model
mdl1 <- um(ar = "1 - 0.8B", sig2 = 1)
z1 <- sim(mdl1, n = 100, seed = 123)

# ARIMA(0,1,1) with burn-in
mdl2 <- um(i = 1, ma = "1 - 0.5B", sig2 = 1)
z2 <- sim(mdl2, n = 100, n0 = 50, seed = 456)

Trigonometric variables

Description

'sincos()' creates a full set of seasonal trigonometric regressors (cos/sin harmonics) for a seasonal frequency.

Usage

sincos(Y, n.ahead = 0, constant = FALSE)

Arguments

Value

A 'ts' matrix with trigonometric variables (and intercept if requested).

Examples

X <- sincos(AirPassengers, constant = TRUE)

Spectrum of an ARMA model

Description

spec computes the spectrum of an ARMA model.

Usage

spec(um, ...)

## S3 method for class 'um'
spec(um, nabla = FALSE, n.freq = 501, ...)

Arguments

Value

A matrix with the frequencies and the power spectral densities.

Note

The I polynomial is ignored.

Examples

um1 <- um(i = "(1 - B)(1 - B^12)", ma = "(1 - 0.8B)(1 - 0.8B^12)")
s <- spec(um1, lag.max = 13)

Time Invariant State Space Model

Description

ssm creates an S3 object representing a time-invariant state space model:

Usage

ssm(z, b, C, S, xreg = NULL, bc = FALSE, cform = TRUE, tol = 1e-05)

Arguments

Details

z(t) = b'x(t-j) + u(t) (observation equation), x(t) = Cx(t-1) + v(t) (state equation), j = 0 for contemporaneous form or j = 1 for lagged form. Note: the lagged form (j=1) is equivalent to the future form x(t+1) = Cx(t) + v(t+1).

Value

An object of class ssm containing:

References

Durbin, J. and Koopman, S.J. (2012) Time Series Analysis by State Space Methods, 2nd ed., Oxford University Press, Oxford.

Harvey, A.C. (1989) Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press, Cambridge.

Examples

# Local level model
b <- 1
C <- as.matrix(1)
ssm1 <- ssm(Nile, b, C, S = diag(c(irr = 1, lvl = 0.5)) )
ssm1

Standardize time series

Description

Centers and scales a time series to zero mean and unit variance.

Usage

std(x)

Arguments

Value

Standardized time series with same class as input.

Summary of fitted state space model

Description

summary.ssm generates a detailed summary of the results of the estimation of a ssm object.

Usage

## S3 method for class 'ssm'
summary(object, ...)

Arguments

Value

An object of class summary.ssm.

Summarize Transfer Function Model

Description

Produces summary statistics for a fitted transfer function model including parameter estimates, standard errors, and diagnostic tests.

Usage

## S3 method for class 'tfm'
summary(
  object,
  y = NULL,
  method = c("exact", "cond"),
  digits = max(3L, getOption("digits") - 3L),
  envir = parent.frame(),
  ...
)

Arguments

Details

Computes parameter estimates with standard errors (from Jacobian), z-statistics, p-values, AIC, BIC, log-likelihood, Ljung-Box tests (at lags p+q+1 and n/4+p+q), and Bartlett heteroscedasticity test.

Value

Object of class summary.tfm containing: call, coefficient table, variance-covariance matrix, residuals, diagnostic statistics, information criteria, and time series attributes.

See Also

print.summary.tfm

Examples

## Not run: 
data(seriesJ)
Y <- seriesJ$Y - mean(seriesJ$Y)
X <- seriesJ$X - mean(seriesJ$X)
umx <- um(X, ar = 3)
umy <- fit(umx, Y)
tfx <- tfest(Y, X, delay = 3, p = 2, q = 2, um.x = umx, um.y = umy)
tfmy <- tfm(Y, inputs = tfx, noise = um(ar = 2))
sm <- summary(tfmy)
print(sm)

## End(Not run)

Summary of um model

Description

summary prints a summary of the estimation and diagnosis.

Usage

## S3 method for class 'um'
summary(
  object,
  z = NULL,
  method = c("exact", "cond"),
  digits = max(3L, getOption("digits") - 3L),
  envir = NULL,
  ...
)

Arguments

Value

A list with the summary of the estimation and diagonosis.

Examples

z <- AirPassengers
airl <- um(z, i = list(1, c(1,12)), ma = list(1, c(1,12)), bc = TRUE)
summary(airl)

Transfer function for input

Description

tf creates a rational transfer function for an input, V(B) = w0(1 - w_1B - ... - w_qB^q)/(1-d_1B - ... - d_pB^p)B^dX_t. Note that in this specification the constant term of the MA polynomial is factored out so that both polynomials in the numerator and denominator are normalized and can be specified with the lagpol function in the same way as the operators of univariate models.

Usage

tf(
  x = NULL,
  delay = 0,
  w0 = 0.01,
  ar = NULL,
  ma = NULL,
  um = NULL,
  n.back = NULL,
  par.prefix = "",
  envir = parent.frame()
)

Arguments

Value

An object of class "tf" containing the transfer function specification. Key components include:

x

Input time series data (possibly extended with backcasts).

delay

Number of periods delay in the transfer function.

w0

Constant gain parameter.

phi

AR polynomial coefficients (denominator).

theta

MA polynomial coefficients (numerator).

p, q

Orders of AR and MA polynomials respectively.

param

Named list of all model parameters.

um

Univariate model for the input series.

References

Box, G.E., Jenkins, G.M., Reinsel, G.C. and Ljung, G.M. (2015) Time Series Analysis: Forecasting and Control. John Wiley & Sons, Hoboken.

Wei, W.W.S. (2006) Time Series Analysis Univariate and Multivariate Methods. 2nd Edition, Addison Wesley, New York, 33-59.

See Also

um.

Examples

x <- rep(0, 100)
x[50] <- 1
tfx <- tf(x, w0 = 0.8, ar = "(1 - 0.5B)(1 - 0.7B^12)")

Helper function to create a tf object

Description

tfest estimates the transfer function

V(B) = w_0 * (theta(B)/phi(B)) * B^d

that relates the input X_t to the output Y_t.

Usage

tfest(
  y,
  x,
  delay = 0,
  p = 1,
  q = 2,
  um.y = NULL,
  um.x = NULL,
  n.back = NULL,
  par.prefix = "",
  envir = envir <- parent.frame()
)

Arguments

Details

Uses prewhitening to estimate initial parameter values.

Value

An object of class tf containing preestimated transfer function parameters.

Examples

data(seriesJ)
Y <- seriesJ$Y - mean(seriesJ$Y)
X <- seriesJ$X - mean(seriesJ$X)
umx <- um(X, ar = 3)
umy <- fit(umx, Y)
tfx <- tfest(Y, X, delay = 3, p = 2, q = 2, um.x = umx, um.y = umy)

Transfer Function Model Constructor

Description

Creates and optionally fits a multiple-input transfer function model. A transfer function model relates an output time series to one or more input series (transfer functions), exogenous regressors, and a noise model.

Usage

tfm(
  output = NULL,
  xreg = NULL,
  inputs = NULL,
  noise,
  fit = TRUE,
  new.name = TRUE,
  envir = parent.frame(),
  ...
)

Arguments

Details

All series must have the same frequency. Input series must span at least the same period as output. The function applies differencing and Box-Cox transformation as specified in noise.

Value

Object of class tfm with components: output, xreg, inputs, noise, param, kx, k, optim, method, and call.

References

Box, G. E., Jenkins, G. M., Reinsel, G. C., & Ljung, G. M. (2015). Time Series Analysis: Forecasting and Control (5th ed.). Wiley.

See Also

tf, um, fit.tfm

Examples

## Not run: 
data(seriesJ)
Y <- seriesJ$Y - mean(seriesJ$Y)
X <- seriesJ$X - mean(seriesJ$X)
umx <- um(X, ar = 3)
umy <- fit(umx, Y)
tfx <- tfest(Y, X, delay = 3, p = 2, q = 2, um.x = umx, um.y = umy)
tfmy <- tfm(Y, inputs = tfx, noise = um(ar = 2))

## End(Not run)

Unscramble MA polynomial

Description

Unscramble MA polynomial

Usage

theta(um)

## S3 method for class 'um'
theta(um)

Arguments

Value

A numeric vector c(1, a1, ..., ad)

Note

This function returns the member variable um$theta.

Examples

um1 <- um(ma = "(1 - 0.8B)(1 - 0.5B)")
theta(um1)

Diagnostic Plots for Time-Series Fits Description

Description

tsdiag.tfm is a wrap of the stats::tsdiag function.

Usage

## S3 method for class 'tfm'
tsdiag(object, gof.lag = 10, ...)

Arguments

See Also

stats::tsdiag.

Diagnostic Plots for Time-Series Fits Description

Description

tsdiag.um is a wrap of the stats::tsdiag function.

Usage

## S3 method for class 'um'
tsdiag(object, gof.lag = 10, ...)

Arguments

See Also

stats::tsdiag.

Extract time series value by date

Description

Retrieves the value of a time series at a specific date.

Usage

tsvalue(x, date)

Arguments

Value

Numeric value at the specified date.

Unobservable components

Description

uc creates an S3 object representing a predefined UC (trend, seasonal, cycle, autoregressive and irregular component).

Usage

uc(
  type,
  s2 = NULL,
  s = 12,
  form = c("trig", "dummy"),
  per = 5,
  phi = 0.9,
  counter = 1
)

Arguments

Value

An object of class uc.

References

Durbin, J. and Koopman, S.J. (2012) Time Series Analysis by State Space Methods, 2nd ed., Oxford University Press, Oxford.

Harvey, A.C. (1989) Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press, Cambridge.

Examples

# Trend component
trend <- uc("trend", s2 = c(s2_lvl = 0.5, s2_slp = 0.025))
# Seasonal component
seas <- uc("seasonal", s2 = c(s2_seas = 0.5), s = 12, form = "trig")
# Cycle component
cycle1 <- uc("cycle", s2 = c(s2_c1 = 0.5), per = 5, phi = 0.8)
cycle2 <- uc("cycle", s2 = c(s2_c2 = 0.5), per = 10, phi = 0.8, counter = 2)

Unobservable components (UC) for structural time series models

Description

uc0 constructs unobservable components by specifying their state-space representation matrices. This is the helper function used internally by uc to create predefined components like trends, seasonals, and cycles.

Usage

uc0(name, param, b, C = NULL, S = NULL)

Arguments

Value

An S3 object of class uc.

Note

Matrices b, C and S can include symbolic expressions in terms of the parameters of the model. These parameters are defined in the param argument with their corresponding names. See the ssm function for more information about b, C and S.

References

Durbin, J. and Koopman, S.J. (2012) Time Series Analysis by State Space Methods, 2nd ed., Oxford University Press, Oxford.

Harvey, A.C. (1989) Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press, Cambridge.

Examples

# Local linear trend component
param <- c(s2_lvl = 0.05, s2_slp = 0.025)
b <- c(1, 0)
C <- matrix(c(1, 1, 0, 1), 2, 2, byrow = TRUE)
S <- matrix(c("s2_lvl", "0", "0", "s2_slp"), 2, 2)
trend <- uc0("trend", param, b, C, S)

# Cycle component
param <- c(phi = 0.8, per = 5, s2c = 0.01)
b <- c(1, 0)
C <- matrix(c("phi*cos(2*pi/per)", "phi*sin(2*pi/per)", 
"-phi*sin(2*pi/per)", "phi*cos(2*pi/per)"), 2, 2, byrow = TRUE)
S <- matrix(c("s2c*(1 - phi^2)", "0", "0", "s2c*(1 - phi^2)"))
cycle <- uc0("cycle", param, b, C, S)

Unobserved components ARIMA models

Description

ucarima creates an S3 object that combines two or more ARIMA models (objects of class um).

Usage

ucarima(
  z = NULL,
  bc = FALSE,
  ucm = NULL,
  ar = NULL,
  xreg = NULL,
  fit = TRUE,
  envir = parent.frame(),
  ...
)

Arguments

Value

An object of class ucarima.

References

Harvey, A.C. (1989) Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press, Cambridge.

Examples

trend <- um(i = "(1 - B)", sig2 = c(s2t = 1))
seas <- um(i = "(1+B)", sig2 = c(s2s = 0.05))
irreg <- um(sig2 = c(s2i = 0.75))
uca1 <- ucarima(ucm = list(trend = trend, seas = seas, irreg = irreg))
uca1

# Trigonometric seasonality
uca2 <- ucarima(AirPassengers, bc = TRUE)
uca2

# Dummy seasonality
uca3 <- ucarima(AirPassengers, bc = TRUE, ucm = "ht")
uca3

Unobserved Components Time Series Models

Description

ucm creates an S3 object representing an UC model:

Usage

ucm(
  z,
  bc = FALSE,
  uc = NULL,
  xreg = NULL,
  cform = TRUE,
  fit = TRUE,
  s = 12,
  ...
)

Arguments

Details

z(t) = b'*x(t) + T(t - j) + S(t - j) + C(t - j) + AR(t - j) + I(t),

where z(t) is a time series; x(t) is a set of regressors; T(t - j), S(t - j), C(t - j), AR(t - j) and I(t) are the trend, seasonal, cycle, autoregressive and irregular unobserved components; and i indicates whether the model is written in lagged form (j = 1) or contemporaneous form (j = 0). See uc and ssm for more details.

Value

An object of class ucm and class ssm.

References

Durbin, J. and Koopman, S.J. (2012) Time Series Analysis by State Space Methods, 2nd ed., Oxford University Press, Oxford.

Harvey, A.C. (1989) Forecasting, Structural Time Series Models and the Kalman Filter. Cambridge University Press, Cambridge.

Examples

# Local level model
ucm1 <- ucm(Nile, uc = "llm")
ucm1

Univariate (ARIMA) model

Description

um creates an S3 object representing a univariate ARIMA model, which can contain multiple AR, I and MA polynomials, as well as parameter restrictions.

Usage

um(
  z = NULL,
  ar = NULL,
  i = NULL,
  ma = NULL,
  mu = NULL,
  sig2 = 1,
  bc = FALSE,
  fit = TRUE,
  envir = parent.frame(),
  warn = TRUE,
  ...
)

Arguments

Value

An object of class um.

References

Box, G.E.P., Jenkins, G.M., Reinsel, G.C. and Ljung, G.M. (2015) Time Series Analysis: Forecasting and Control. John Wiley & Sons, Hoboken.

Examples

ar1 <- um(ar = "(1 - 0.8B)")
ar2 <- um(ar = "(1 - 1.4B + 0.8B^2)")
ma1 <- um(ma = "(1 - 0.8B)")
ma2 <- um(ma = "(1 - 1.4B + 0.8B^2)")
arma11 <- um(ar = "(1 - 1.4B + 0.8B^2)", ma = "(1 - 0.8B)")

Unit circle

Description

unitcircle plots the inverse roots of a lag polynomial together the unit circle.

Usage

unitcircle(lp, ...)

## Default S3 method:
unitcircle(lp, ...)

## S3 method for class 'lagpol'
unitcircle(lp, s = 12, ...)

Arguments

Value

unitcircle returns a NULL value.

Examples

unitcircle(as.lagpol(c(1, rep(0, 11), -1)))

Variable selection

Description

varsel omits non-significant inputs from a transfer function model.

Usage

varsel(tfm, ...)

## S3 method for class 'tfm'
varsel(tfm, y = NULL, p.value = 0.1, envir = parent.frame(), ...)

Arguments

Value

A tfm object or a "um" if no input is significant at that level.

Wiener-Kolmogorov filter

Description

wkfilter extracts a signal for a time series described by an ARIMA model given the ARIMA model for the signal.

Usage

## S3 method for class 'as_ucarima'
wkfilter(object, z = NULL, tol = 1e-05, envir = parent.frame(), ...)

wkfilter(object, ...)

## S3 method for class 'um'
wkfilter(
  object,
  um.uc,
  z = NULL,
  output = c("series", "filter"),
  tol = 1e-05,
  envir = parent.frame(),
  ...
)

Arguments

Value

An object of class ts containing the estimated signal.

Examples

um1 <- airline(AirPassengers, bc = TRUE)
uca1 <- as.ucarima(um1, i = "(1-B)2")
trend <- wkfilter(um1, uca1$ucm$signal1)
seas <- wkfilter(um1, uca1$ucm$signal2)

Wold polynomial

Description

Transforming a palindromic polymonial into a Wold polynomial/ Computing the Cramer-Wold factorization

Usage

wold.pol(x, type = c("wold", "palindromic", "cramer-wold"), tol = 1e-05)

Arguments

Details

wold.pol can be used with three purposes:

(1) to transform a self-reciprocal or palindromic polynomial a_0 + a_1(B+F) + a_2(B^2+F^2) + ... + a_p(B^p+F^p) into a Wold polynomial b_0 + b_1(B+F) + b_2(B+F)^2 + ... + b_p(B+F)^p;

(2) to revert the previous transformation to obtain the palindromic polynominal from a Wold polynomial and

(3) to compute the Cramer-Wold factorization: b(B+F) = c(B)c(F).

Value

Numeric vector.

Examples

wold.pol(c(6, -4, 1))