Package 'feasts' reference manual

Title:	Feature Extraction and Statistics for Time Series
Description:	Provides a collection of features, decomposition methods, statistical summaries and graphics functions for the analysing tidy time series data. The package name 'feasts' is an acronym comprising of its key features: Feature Extraction And Statistics for Time Series.
Authors:	Mitchell O'Hara-Wild [aut, cre], Rob Hyndman [aut], Earo Wang [aut], Di Cook [ctb], Thiyanga Talagala [ctb] (Correlation features), Leanne Chhay [ctb] (Guerrero's method)
Maintainer:	Mitchell O'Hara-Wild <[email protected]>
License:	GPL-3
Version:	0.5.0.9000
Built:	2026-05-30 10:59:43 UTC
Source:	https://github.com/tidyverts/feasts

feasts: Feature Extraction and Statistics for Time Series

Description

logo

Provides a collection of features, decomposition methods, statistical summaries and graphics functions for the analysing tidy time series data. The package name 'feasts' is an acronym comprising of its key features: Feature Extraction And Statistics for Time Series.

Author(s)

Maintainer: Mitchell O'Hara-Wild [email protected]

Authors:

Rob Hyndman
Earo Wang

Other contributors:

Di Cook [contributor]
Thiyanga Talagala (Correlation features) [contributor]
Leanne Chhay (Guerrero's method) [contributor]

(Partial) Autocorrelation and Cross-Correlation Function Estimation

Description

The function ACF computes an estimate of the autocorrelation function of a (possibly multivariate) tsibble. Function PACF computes an estimate of the partial autocorrelation function of a (possibly multivariate) tsibble. Function CCF computes the cross-correlation or cross-covariance of two columns from a tsibble.

Usage

ACF(
  .data,
  y,
  ...,
  lag_max = NULL,
  type = c("correlation", "covariance", "partial"),
  na.action = na.contiguous,
  demean = TRUE,
  tapered = FALSE
)

PACF(.data, y, ..., lag_max = NULL, na.action = na.contiguous, tapered = FALSE)

CCF(
  .data,
  y,
  x,
  ...,
  lag_max = NULL,
  type = c("correlation", "covariance"),
  na.action = na.contiguous
)
ACF(
  .data,
  y,
  ...,
  lag_max = NULL,
  type = c("correlation", "covariance", "partial"),
  na.action = na.contiguous,
  demean = TRUE,
  tapered = FALSE
)

PACF(.data, y, ..., lag_max = NULL, na.action = na.contiguous, tapered = FALSE)

CCF(
  .data,
  y,
  x,
  ...,
  lag_max = NULL,
  type = c("correlation", "covariance"),
  na.action = na.contiguous
)

Arguments

.data

A tsibble

...

The column(s) from the tsibble used to compute the ACF, PACF or CCF.

lag_max

maximum lag at which to calculate the acf. Default is 10*log10(N/m) where N is the number of observations and m the number of series. Will be automatically limited to one less than the number of observations in the series.

type

character string giving the type of ACF to be computed. Allowed values are "correlation" (the default), "covariance" or "partial".

na.action

function to be called to handle missing values. na.pass can be used.

demean

logical. Should the covariances be about the sample means?

tapered

Produces banded and tapered estimates of the (partial) autocorrelation.

x, y

a univariate or multivariate (not ccf) numeric time series object or a numeric vector or matrix, or an "acf" object.

Details

The functions improve the stats::acf(), stats::pacf() and stats::ccf() functions. The main differences are that ACF does not plot the exact correlation at lag 0 when type=="correlation" and the horizontal axes show lags in time units rather than seasonal units.

The resulting tables from these functions can also be plotted using autoplot() with the methods provided by the ggtime package.

Value

The ACF, PACF and CCF functions return objects of class "tbl_cf", which is a tsibble containing the correlations computed.

Author(s)

Mitchell O'Hara-Wild and Rob J Hyndman

References

Hyndman, R.J. (2015). Discussion of "High-dimensional autocovariance matrices and optimal linear prediction". Electronic Journal of Statistics, 9, 792-796.

McMurry, T. L., & Politis, D. N. (2010). Banded and tapered estimates for autocovariance matrices and the linear process bootstrap. Journal of Time Series Analysis, 31(6), 471-482.

Examples

library(tsibble)
library(tsibbledata)
library(dplyr)

vic_elec %>% ACF(Temperature)

vic_elec %>% ACF(Temperature) %>% autoplot()

vic_elec %>% PACF(Temperature)

vic_elec %>% PACF(Temperature) %>% autoplot()

global_economy %>%
  filter(Country == "Australia") %>%
  CCF(GDP, Population)

global_economy %>%
  filter(Country == "Australia") %>%
  CCF(GDP, Population) %>%
  autoplot()

library(tsibble)
library(tsibbledata)
library(dplyr)

vic_elec %>% ACF(Temperature)

vic_elec %>% ACF(Temperature) %>% autoplot()

vic_elec %>% PACF(Temperature)

vic_elec %>% PACF(Temperature) %>% autoplot()

global_economy %>%
  filter(Country == "Australia") %>%
  CCF(GDP, Population)

global_economy %>%
  filter(Country == "Australia") %>%
  CCF(GDP, Population) %>%
  autoplot()

Classical Seasonal Decomposition by Moving Averages

Description

Decompose a time series into seasonal, trend and irregular components using moving averages. Deals with additive or multiplicative seasonal component.

Usage

classical_decomposition(formula, type = c("additive", "multiplicative"), ...)
classical_decomposition(formula, type = c("additive", "multiplicative"), ...)

Arguments

formula

Decomposition specification (see "Specials" section).

type

The type of seasonal component. Can be abbreviated.

...

Other arguments passed to stats::decompose().

Details

The additive model used is:

$Y_t = T_t + S_t + e_t$

The multiplicative model used is:

$Y_t = T_t\,S_t\, e_t$

The function first determines the trend component using a moving average (if filter is NULL, a symmetric window with equal weights is used), and removes it from the time series. Then, the seasonal figure is computed by averaging, for each time unit, over all periods. The seasonal figure is then centered. Finally, the error component is determined by removing trend and seasonal figure (recycled as needed) from the original time series.

This only works well if x covers an integer number of complete periods.

Value

A fabletools::dable() containing the decomposed trend, seasonality and remainder from the classical decomposition.

Specials

season

The season special is used to specify seasonal attributes of the decomposition.

season(period = NULL)

period The periodic nature of the seasonality. This can be either a number indicating the number of observations in each seasonal period, or text to indicate the duration of the seasonal window (for example, annual seasonality would be "1 year").

Examples

as_tsibble(USAccDeaths) %>%
  model(classical_decomposition(value)) %>%
  components()

as_tsibble(USAccDeaths) %>%
  model(classical_decomposition(value ~ season(12), type = "mult")) %>%
  components()

as_tsibble(USAccDeaths) %>%
  model(classical_decomposition(value)) %>%
  components()

as_tsibble(USAccDeaths) %>%
  model(classical_decomposition(value ~ season(12), type = "mult")) %>%
  components()

Hurst coefficient

Description

Computes the Hurst coefficient indicating the level of fractional differencing of a time series.

Usage

coef_hurst(x)
coef_hurst(x)

Arguments

x

a vector. If missing values are present, the largest contiguous portion of the vector is used.

Value

A numeric value.

Author(s)

Rob J Hyndman

Johansen Procedure for VAR

Description

Conducts the Johansen procedure on a given data set. The "trace" or "eigen" statistics are reported and the matrix of eigenvectors as well as the loading matrix.

Usage

cointegration_johansen(x, ...)
cointegration_johansen(x, ...)

Arguments

x

Data matrix to be investigated for cointegration.

...

Additional arguments passed to urca::ca.jo().

Details

Given a general VAR of the form:

$\bold{X}_t = \bold{\Pi}_1 \bold{X}_{t-1} + \dots + \bold{\Pi}_k \bold{X}_{t-k} + \bold{\mu} + \bold{\Phi D}_t + \bold{\varepsilon}_t , \quad (t = 1, \dots, T),$

the following two specifications of a VECM exist:

$\Delta \bold{X}_t = \bold{\Gamma}_1 \Delta \bold{X}_{t-1} + \dots + \bold{\Gamma}_{k-1} \Delta \bold{X}_{t-k+1} + \bold{\Pi X}_{t-k} + \bold{\mu} + \bold{\Phi D}_t + \bold{\varepsilon}_t$

where

$\bold{\Gamma}_i = - (\bold{I} - \bold{\Pi}_1 - \dots - \bold{\Pi}_i), \quad (i = 1, \dots , k-1),$

and

$\bold{\Pi} = -(\bold{I} - \bold{\Pi}_1 - \dots - \bold{\Pi}_k)$

The $\bold{\Gamma}_i$ matrices contain the cumulative long-run impacts, hence if spec="longrun" is choosen, the above VECM is estimated.

The other VECM specification is of the form:

$\Delta \bold{X}_t = \bold{\Gamma}_1 \Delta \bold{X}_{t-1} + \dots + \bold{\Gamma}_{k-1} \Delta \bold{X}_{t-k+1} + \bold{\Pi X}_{t-1} + \bold{\mu} + \bold{\Phi D}_t + \bold{\varepsilon}_t$

where

$\bold{\Gamma}_i = - (\bold{\Pi}_{i+1} + \dots + \bold{\Pi}_k), \quad(i = 1, \dots , k-1),$

and

$\bold{\Pi} = -(\bold{I} - \bold{\Pi}_1 - \dots - \bold{\Pi}_k).$

The $\bold{\Pi}$ matrix is the same as in the first specification. However, the $\bold{\Gamma}_i$ matrices now differ, in the sense that they measure transitory effects, hence by setting spec="transitory" the second VECM form is estimated. Please note that inferences drawn on $\bold{\Pi}$ will be the same, regardless which specification is choosen and that the explanatory power is the same, too.

If "season" is not NULL, centered seasonal dummy variables are included.

If "dumvar" is not NULL, a matrix of dummy variables is included in the VECM. Please note, that the number of rows of the matrix containing the dummy variables must be equal to the row number of x.

Critical values are only reported for systems with less than 11 variables and are taken from Osterwald-Lenum.

Value

An object of class ca.jo.

Author(s)

Bernhard Pfaff

References

Johansen, S. (1988), Statistical Analysis of Cointegration Vectors, Journal of Economic Dynamics and Control, 12, 231–254.

Johansen, S. and Juselius, K. (1990), Maximum Likelihood Estimation and Inference on Cointegration – with Applications to the Demand for Money, Oxford Bulletin of Economics and Statistics, 52, 2, 169–210.

Johansen, S. (1991), Estimation and Hypothesis Testing of Cointegration Vectors in Gaussian Vector Autoregressive Models, Econometrica, Vol. 59, No. 6, 1551–1580.

Osterwald-Lenum, M. (1992), A Note with Quantiles of the Asymptotic Distribution of the Maximum Likelihood Cointegration Rank Test Statistics, Oxford Bulletin of Economics and Statistics, 55, 3, 461–472.

Examples


cointegration_johansen(cbind(mdeaths, fdeaths))


cointegration_johansen(cbind(mdeaths, fdeaths))

Phillips and Ouliaris Cointegration Features

Description

cointegration_phillips_ouliaris() calls urca::ca.po() and returns a named numeric vector containing:

phillips_ouliaris_stat: the $P_u$ or $P_z$ test statistic; and
phillips_ouliaris_pvalue: an approximate p-value obtained by linearly interpolating the tabulated critical values in result@cval.

Since it returns a simple numeric vector, this function is suitable for use as a feature extractor within the fabletools features framework.

Usage

cointegration_phillips_ouliaris(x, ...)
cointegration_phillips_ouliaris(x, ...)

Arguments

x

A numeric matrix (or object coercible to a matrix) of time series to be tested for cointegration. Columns represent series and rows represent ordered observations.

...

Additional arguments passed to urca::ca.po(), such as demean, lag, type, and tol. See ca.po for details.

Details

Compute Phillips and Ouliaris (1990) residual-based cointegration test statistics and an approximate p-value as numeric features.

This is a small wrapper around urca::ca.po() designed so that the Phillips–Ouliaris test can be used directly inside features.

The function requires the urca package; an informative error is raised if it is not installed.

The p-value is computed by interpolating over the first row of result@cval, which contains critical values at various significance levels (e.g., "10pct", "5pct", "1pct"). These labels are converted to probabilities (0.10, 0.05, 0.01), and approx is used to obtain the approximate p-value at the observed test statistic. The interpolation is done with rule = 2, implying linear extrapolation outside the tabulated range.

Value

A named numeric vector of length two:

phillips_ouliaris_stat
phillips_ouliaris_pvalue

References

Phillips, P.C.B. and Ouliaris, S. (1990), “Asymptotic Properties of Residual Based Tests for Cointegration”, Econometrica, 58(1), 165–193.

Examples


cointegration_phillips_ouliaris(cbind(mdeaths, fdeaths))

cointegration_phillips_ouliaris(cbind(mdeaths, fdeaths))

Autocorrelation-based features

Description

Computes various measures based on autocorrelation coefficients of the original series, first-differenced series and second-differenced series

Usage

feat_acf(x, .period = 1, lag_max = NULL, ...)
feat_acf(x, .period = 1, lag_max = NULL, ...)

Arguments

x

a univariate time series

.period

The seasonal period (optional)

lag_max

maximum lag at which to calculate the acf. The default is max(.period, 10L) for feat_acf, and max(.period, 5L) for feat_pacf

...

Further arguments passed to stats::acf() or stats::pacf()

Value

A vector of 6 values: first autocorrelation coefficient and sum of squared of first ten autocorrelation coefficients of original series, first-differenced series, and twice-differenced series. For seasonal data, the autocorrelation coefficient at the first seasonal lag is also returned.

Author(s)

Thiyanga Talagala

Intermittency features

Description

Computes various measures that can indicate the presence and structures of intermittent data.

Usage

feat_intermittent(x)
feat_intermittent(x)

Arguments

x

A vector to extract features from.

Value

A vector of named features:

zero_run_mean: The average interval between non-zero observations
nonzero_squared_cv: The squared coefficient of variation of non-zero observations
zero_start_prop: The proportion of data which starts with zero
zero_end_prop: The proportion of data which ends with zero

References

Kostenko, A. V., & Hyndman, R. J. (2006). A note on the categorization of demand patterns. Journal of the Operational Research Society, 57(10), 1256-1257.

Partial autocorrelation-based features

Description

Computes various measures based on partial autocorrelation coefficients of the original series, first-differenced series and second-differenced series.

Usage

feat_pacf(x, .period = 1, lag_max = NULL, ...)
feat_pacf(x, .period = 1, lag_max = NULL, ...)

Arguments

x

a univariate time series

.period

The seasonal period (optional)

lag_max

maximum lag at which to calculate the acf. The default is max(.period, 10L) for feat_acf, and max(.period, 5L) for feat_pacf

...

Further arguments passed to stats::acf() or stats::pacf()

Value

A vector of 3 values: Sum of squared of first 5 partial autocorrelation coefficients of the original series, first differenced series and twice-differenced series. For seasonal data, the partial autocorrelation coefficient at the first seasonal lag is also returned.

Author(s)

Thiyanga Talagala

Spectral features of a time series

Description

Computes spectral entropy from a univariate normalized spectral density, estimated using an AR model.

Usage

feat_spectral(x, .period = 1, ...)
feat_spectral(x, .period = 1, ...)

Arguments

x

a univariate time series

.period

The seasonal period.

...

Further arguments for stats::spec.ar()

Details

The spectral entropy equals the Shannon entropy of the spectral density $f_x(\lambda)$ of a stationary process $x_t$ :

$H_s(x_t) = - \int_{-\pi}^{\pi} f_x(\lambda) \log f_x(\lambda) d \lambda,$

where the density is normalized such that $\int_{-\pi}^{\pi} f_x(\lambda) d \lambda = 1$ . An estimate of $f(\lambda)$ can be obtained using spec.ar with the burg method.

Value

A non-negative real value for the spectral entropy $H_s(x_t)$ .

Author(s)

Rob J Hyndman

References

Jerry D. Gibson and Jaewoo Jung (2006). “The Interpretation of Spectral Entropy Based Upon Rate Distortion Functions”. IEEE International Symposium on Information Theory, pp. 277-281.

Goerg, G. M. (2013). “Forecastable Component Analysis”. Journal of Machine Learning Research (JMLR) W&CP 28 (2): 64-72, 2013. Available at https://proceedings.mlr.press/v28/goerg13.html.

Examples

feat_spectral(rnorm(1000))
feat_spectral(lynx)
feat_spectral(sin(1:20))
feat_spectral(rnorm(1000))
feat_spectral(lynx)
feat_spectral(sin(1:20))

STL features

Description

Computes a variety of measures extracted from an STL decomposition of the time series. This includes details about the strength of trend and seasonality.

Usage

feat_stl(x, .period, s.window = 11, ...)
feat_stl(x, .period, s.window = 11, ...)

Arguments

x

A vector to extract features from.

.period

The period of the seasonality.

s.window

The seasonal window of the data (passed to stats::stl())

...

Further arguments passed to stats::stl()

Value

A vector of numeric features from a STL decomposition.

Generate block bootstrapped series from an STL decomposition

Description

Produces new data with the same structure by resampling the residuals using a block bootstrap procedure. This method can only generate within sample, and any generated data out of the trained sample will produce NA simulations.

Usage

## S3 method for class 'stl_decomposition'
generate(x, new_data, specials = NULL, ...)
## S3 method for class 'stl_decomposition'
generate(x, new_data, specials = NULL, ...)

Arguments

x

A fitted model.

new_data

A tsibble containing the time points and exogenous regressors to produce forecasts for.

specials

(passed by fabletools::forecast.mdl_df()).

...

Other arguments passed to methods

References

Bergmeir, C., R. J. Hyndman, and J. M. Benitez (2016). Bagging Exponential Smoothing Methods using STL Decomposition and Box-Cox Transformation. International Journal of Forecasting 32, 303-312.

Examples

as_tsibble(USAccDeaths) %>%
  model(STL(log(value))) %>%
  generate(as_tsibble(USAccDeaths), times = 3)

as_tsibble(USAccDeaths) %>%
  model(STL(log(value))) %>%
  generate(as_tsibble(USAccDeaths), times = 3)

Guerrero's method for Box Cox lambda selection

Description

Applies Guerrero's (1993) method to select the lambda which minimises the coefficient of variation for subseries of x.

Usage

guerrero(x, lower = -0.9, upper = 2, .period = 2L)
guerrero(x, lower = -0.9, upper = 2, .period = 2L)

Arguments

x

A numeric vector. The data used to identify the transformation parameter lambda.

lower

The lower bound for lambda.

upper

The upper bound for lambda.

.period

The length of each subseries (usually the length of seasonal period). Subseries length must be at least 2.

Details

Note that this function will give slightly different results to forecast::BoxCox.lambda(y) if your data does not start at the start of the seasonal period. This function will make use of all of your data, whereas the forecast package will not use data that doesn't complete a seasonal period.

Value

A Box Cox transformation parameter (lambda) chosen by Guerrero's method.

References

Box, G. E. P. and Cox, D. R. (1964) An analysis of transformations. JRSS B 26 211–246.

Guerrero, V.M. (1993) Time-series analysis supported by power transformations. Journal of Forecasting, 12, 37–48.

Portmanteau tests

Description

Compute the Box–Pierce or Ljung–Box test statistic for examining the null hypothesis of independence in a given time series. These are sometimes known as ‘portmanteau’ tests.

Usage

ljung_box(x, lag = 1, dof = 0, ...)

box_pierce(x, lag = 1, dof = 0, ...)

portmanteau_tests
ljung_box(x, lag = 1, dof = 0, ...)

box_pierce(x, lag = 1, dof = 0, ...)

portmanteau_tests

Arguments

x

A numeric vector

lag

The number of lag autocorrelation coefficients to use in calculating the statistic

dof

Degrees of freedom of the fitted model (useful if x is a series of residuals).

...

Unused.

Format

An object of class list of length 2.

Value

A vector of numeric features for the test's statistic and p-value.

Examples

ljung_box(rnorm(100))

box_pierce(rnorm(100))
ljung_box(rnorm(100))

box_pierce(rnorm(100))

Longest flat spot length

Description

"Flat spots” are computed by dividing the sample space of a time series into ten equal-sized intervals, and computing the maximum run length within any single interval.

Usage

longest_flat_spot(x)
longest_flat_spot(x)

Arguments

x

a vector

Value

A numeric value.

Author(s)

Earo Wang and Rob J Hyndman

Number of crossing points

Description

Computes the number of times a time series crosses the median.

Usage

n_crossing_points(x)
n_crossing_points(x)

Arguments

x

a univariate time series

Value

A numeric value.

Author(s)

Earo Wang and Rob J Hyndman

Sliding window features

Description

Computes feature of a time series based on sliding (overlapping) windows. shift_level_max finds the largest mean shift between two consecutive windows. shift_var_max finds the largest var shift between two consecutive windows. shift_kl_max finds the largest shift in Kulback-Leibler divergence between two consecutive windows.

Usage

shift_level_max(x, .size = NULL, .period = 1)

shift_var_max(x, .size = NULL, .period = 1)

shift_kl_max(x, .size = NULL, .period = 1)
shift_level_max(x, .size = NULL, .period = 1)

shift_var_max(x, .size = NULL, .period = 1)

shift_kl_max(x, .size = NULL, .period = 1)

Arguments

x

a univariate time series

.size

size of sliding window, if NULL .size will be automatically chosen using .period

.period

The seasonal period (optional)

Details

Computes the largest level shift and largest variance shift in sliding mean calculations

Value

A vector of 2 values: the size of the shift, and the time index of the shift.

Author(s)

Earo Wang, Rob J Hyndman and Mitchell O'Hara-Wild

ARCH LM Statistic

Description

Computes a statistic based on the Lagrange Multiplier (LM) test of Engle (1982) for autoregressive conditional heteroscedasticity (ARCH). The statistic returned is the $R^2$ value of an autoregressive model of order lags applied to $x^2$ .

Usage

stat_arch_lm(x, lags = 12, demean = TRUE)
stat_arch_lm(x, lags = 12, demean = TRUE)

Arguments

x

a univariate time series

lags

Number of lags to use in the test

demean

Should data have mean removed before test applied?

Value

A numeric value.

Author(s)

Yanfei Kang

Multiple seasonal decomposition by Loess

Description

Decompose a time series into seasonal, trend and remainder components. Seasonal components are estimated iteratively using STL. Multiple seasonal periods are allowed. The trend component is computed for the last iteration of STL. Non-seasonal time series are decomposed into trend and remainder only. In this case, stats::supsmu() is used to estimate the trend. Optionally, the time series may be Box-Cox transformed before decomposition. Unlike stats::stl(), mstl is completely automated.

Usage

STL(formula, iterations = 2, ...)
STL(formula, iterations = 2, ...)

Arguments

formula

Decomposition specification (see "Specials" section).

iterations

Number of iterations to use to refine the seasonal component.

...

Other arguments passed to stats::stl().

Value

A fabletools::dable() containing the decomposed trend, seasonality and remainder from the STL decomposition.

Specials

trend

The trend special is used to specify the trend extraction parameters.

trend(window, degree, jump)

`window`	The span (in lags) of the loess window, which should be odd. If NULL, the default, nextodd(ceiling((1.5*period) / (1-(1.5/s.window)))), is taken.
`degree`	The degree of locally-fitted polynomial. Should be zero or one.
`jump`	Integers at least one to increase speed of the respective smoother. Linear interpolation happens between every `jump`th value.

season

The season special is used to specify the season extraction parameters.

season(period = NULL, window = NULL, degree, jump)

`period`	The periodic nature of the seasonality. This can be either a number indicating the number of observations in each seasonal period, or text to indicate the duration of the seasonal window (for example, annual seasonality would be "1 year").
`window`	The span (in lags) of the loess window, which should be odd. If the `window` is set to `"periodic"` or `Inf`, the seasonal pattern will be fixed. The window size should be odd and at least 7, according to Cleveland et al. The default (NULL) will choose an appropriate default, for a dataset with one seasonal pattern this would be 11, the second larger seasonal window would be 15, then 19, 23, ... onwards.
`degree`	The degree of locally-fitted polynomial. Should be zero or one.
`jump`	Integers at least one to increase speed of the respective smoother. Linear interpolation happens between every `jump`th value.

lowpass

The lowpass special is used to specify the low-pass filter parameters.

lowpass(window, degree, jump)

`window`	The span (in lags) of the loess window of the low-pass filter used for each subseries. Defaults to the smallest odd integer greater than or equal to the seasonal `period` which is recommended since it prevents competition between the trend and seasonal components. If not an odd integer its given value is increased to the next odd one.
`degree`	The degree of locally-fitted polynomial. Must be zero or one.
`jump`	Integers at least one to increase speed of the respective smoother. Linear interpolation happens between every `jump`th value.

References

R. B. Cleveland, W. S. Cleveland, J.E. McRae, and I. Terpenning (1990) STL: A Seasonal-Trend Decomposition Procedure Based on Loess. Journal of Official Statistics, 6, 3–73.

Examples

as_tsibble(USAccDeaths) %>%
  model(STL(value ~ trend(window = 10))) %>%
  components()

as_tsibble(USAccDeaths) %>%
  model(STL(value ~ trend(window = 10))) %>%
  components()

Unit root tests

Description

Performs a test for the existence of a unit root in the vector.

Usage

unitroot_kpss(x, type = c("mu", "tau"), lags = c("short", "long", "nil"), ...)

unitroot_pp(
  x,
  type = c("Z-tau", "Z-alpha"),
  model = c("constant", "trend"),
  lags = c("short", "long"),
  ...
)
unitroot_kpss(x, type = c("mu", "tau"), lags = c("short", "long", "nil"), ...)

unitroot_pp(
  x,
  type = c("Z-tau", "Z-alpha"),
  model = c("constant", "trend"),
  lags = c("short", "long"),
  ...
)

Arguments

x

A vector to be tested for the unit root.

type

Type of deterministic part.

lags

Maximum number of lags used for error term correction.

...

Arguments passed to unit root test function.

model

Determines the deterministic part in the test regression.

Details

unitroot_kpss computes the statistic for the Kwiatkowski et al. unit root test with linear trend and lag 1.

unitroot_pp computes the statistic for the Z-tau version of Phillips & Perron unit root test with constant trend and lag 1.

Value

A vector of numeric features for the test's statistic and p-value.

Number of differences required for a stationary series

Description

Use a unit root function to determine the minimum number of differences necessary to obtain a stationary time series.

Usage

unitroot_ndiffs(
  x,
  alpha = 0.05,
  unitroot_fn = ~unitroot_kpss(.)["kpss_pvalue"],
  differences = 0:2,
  ...
)

unitroot_nsdiffs(
  x,
  alpha = 0.05,
  unitroot_fn = ~feat_stl(., .period)[2] < 0.64,
  differences = 0:2,
  .period = 1,
  ...
)
unitroot_ndiffs(
  x,
  alpha = 0.05,
  unitroot_fn = ~unitroot_kpss(.)["kpss_pvalue"],
  differences = 0:2,
  ...
)

unitroot_nsdiffs(
  x,
  alpha = 0.05,
  unitroot_fn = ~feat_stl(., .period)[2] < 0.64,
  differences = 0:2,
  .period = 1,
  ...
)

Arguments

x

A vector to be tested for the unit root.

alpha

The level of the test.

unitroot_fn

A function (or lambda) that provides a p-value for a unit root test.

differences

The possible differences to consider.

...

Additional arguments passed to the unitroot_fn function

.period

The period of the seasonality.

Details

Note that the default 'unit root function' for unitroot_nsdiffs() is based on the seasonal strength of an STL decomposition. This is not a test for the presence of a seasonal unit root, but generally works reasonably well in identifying the presence of seasonality and the need for a seasonal difference.

Value

A numeric corresponding to the minimum required differences for stationarity.

Time series features based on tiled windows

Description

Computes feature of a time series based on tiled (non-overlapping) windows. Means or variances are produced for all tiled windows. Then stability is the variance of the means, while lumpiness is the variance of the variances.

Usage

var_tiled_var(x, .size = NULL, .period = 1)

var_tiled_mean(x, .size = NULL, .period = 1)
var_tiled_var(x, .size = NULL, .period = 1)

var_tiled_mean(x, .size = NULL, .period = 1)

Arguments

x

a univariate time series

.size

size of sliding window, if NULL .size will be automatically chosen using .period

.period

The seasonal period (optional)

Value

A numeric vector of length 2 containing a measure of lumpiness and a measure of stability.

Author(s)

Earo Wang and Rob J Hyndman

X-13ARIMA-SEATS Seasonal Adjustment

Description

X-13ARIMA-SEATS is a seasonal adjustment program developed and maintained by the U.S. Census Bureau.

Usage

X_13ARIMA_SEATS(
  formula,
  ...,
  na.action = seasonal::na.x13,
  defaults = c("seasonal", "none")
)
X_13ARIMA_SEATS(
  formula,
  ...,
  na.action = seasonal::na.x13,
  defaults = c("seasonal", "none")
)

Arguments

formula

Decomposition specification.

...

Other arguments passed to seasonal::seas().

na.action

a function which indicates what should happen when the data contain NAs. na.omit (default), na.exclude or na.fail. If na.action = na.x13, NA handling is done by X-13, i.e. NA values are substituted by -99999.

defaults

If defaults="seasonal", the default options of seasonal::seas() will be used, which should work well in most circumstances. Setting defaults="none" gives an empty model specification, which can be added to in the model formula.

Details

The SEATS decomposition method stands for "Seasonal Extraction in ARIMA Time Series", and is the default method for seasonally adjusting the data. This decomposition method can extract seasonality from data with seasonal periods of 2 (biannual), 4 (quarterly), 6 (bimonthly), and 12 (monthly). This method is specified using the seats() function in the model formula.

Alternatively, the seasonal adjustment can be done using an enhanced X-11 decomposition method. The X-11 method uses weighted averages over a moving window of the time series. This is used in combination with the RegARIMA model to prepare the data for decomposition. To use the X-11 decomposition method, the x11() function can be used in the model formula.

Specials

The specials of the X-13ARIMA-SEATS model closely follow the individual specification options of the original function. Refer to Chapter 7 of the X-13ARIMA-SEATS Reference Manual for full details of the arguments.

The available specials for this model are:

arima

The arima special is used to specify the ARIMA part of the regARIMA model. This defines a pure ARIMA model if the regression() special absent and if no exogenous regressors are specified. The lags of the ARIMA model can be specified in the model argument, potentially along with ar and ma coefficients.

arima(...)