Main Content

regARIMA

Create regression model with ARIMA time series errors

Description

The regARIMA function returns a regARIMA object specifying the functional form and storing the parameter values of a regression model with ARIMA time series errors for a univariate response process yt.

yt=c+Xtβ+uta(L)A(L)(1L)D(1Ls)ut=b(L)B(L)εt,

Because they completely specify the model structure, the key components of a regARIMA object are the:

  • Regression model coefficients c and β

  • Polynomial degrees of the ARIMA disturbances ut, for example, the AR polynomial degree p and the degree of integration D

Given only polynomial degrees, the regression model contains only a constant. All parameters, such as the model constant, and error model coefficients and innovation-distribution parameters, are unknown and estimable unless you specify their values. regARIMA determines the number of coefficients in the regression model by the number of variables in the supplied predictor data or by other specifications.

To estimate a model containing unknown parameter values, pass the model and data to the estimate object function. To work with an estimated or fully specified regARIMA object, pass it to an object function.

Alternatively, you can:

Creation

Description

Mdl = regARIMA creates a regression model containing degree 0 ARIMA disturbances. The regression model contains an intercept; the software determines the number of regression coefficients when you fit the model to data by using estimate. The innovations are iid Gaussian random variables with a mean of 0 and unknown variance.

example

Mdl = regARIMA(p,D,q) creates a regression model with ARIMA(p,D,q) disturbances. The disturbance model contains nonseasonal AR polynomial lags from 1 through p, a degree D nonseasonal integration polynomial, and nonseasonal MA polynomial lags from 1 through q. The regression model contains an intercept; the software determines the number of regression coefficients when you fit the model to data by using estimate. The innovations are iid Gaussian random variables with a mean of 0 and unknown variance.

This shorthand syntax provides an easy way to create a model template in which you specify the degrees of the nonseasonal polynomials explicitly. The model template is suited for unrestricted parameter estimation. After you create a model, you can alter property values using dot notation.

example

Mdl = regARIMA(Name=Value) sets properties and polynomial lags using name-value arguments. For example, regARIMA(ARLags=[1 4],AR={0.5 –0.1}) creates a regression model containing an unknown model intercept and innovations variance, and AR(4) disturbances, where the lag 1 nonseasonal AR coefficient is –0.5 and the lag 4 nonseasonal AR coefficient is 0.1.

This longhand syntax allows you to create more flexible models. For example, you can create a regression model with seasonal errors by using only longhand syntax. regARIMA infers all disturbance model polynomial degrees from the properties that you set. Therefore, property values that correspond to polynomial degrees must be consistent with each other.

Input Arguments

expand all

The shorthand syntax provides an easy way for you to create model templates of regression models with nonseasonal ARIMA errors. Model templates are suitable for unrestricted parameter estimation. For example, to create a regression model with ARMA(2,1) errors containing an unknown model intercept and innovations variance, enter:

Mdl = regARIMA(2,0,1);
To impose equality constraints on parameter values during estimation, or include seasonal components, set the appropriate property values using dot notation.

Nonseasonal autoregressive polynomial degree for the error model, specified as a nonnegative integer.

Data Types: double

Degree of nonseasonal integration (the degree of the nonseasonal differencing polynomial) for the error model, specified as a nonnegative integer. The D input argument sets the property D.

Data Types: double

Nonseasonal moving average polynomial degree for the error model, specified as a nonnegative integer.

Data Types: double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

The longhand syntax enables you to create seasonal error models or models in which some or all coefficients are known. During estimation, estimate imposes equality constraints on any known parameters.

Example: regARIMA(ARLags=[1 4],AR={0.5 –0.1}) creates a regression model containing an unknown model intercept and innovations variance, and AR(4) disturbances, where the lag 1 nonseasonal AR coefficient is –0.5 and the lag 4 nonseasonal AR coefficient is 0.1, symbolically, 10.5L1+0.1L4.

Lags associated with the nonseasonal AR polynomial coefficients for the error model ut, specified as a numeric vector of unique positive integers. The maximum lag is p.

AR{j} is the coefficient of lag ARLags(j), where AR is the value of the property AR.

Example: ARLags=4 specifies the nonseasonal AR polynomial 1ϕ4L4.

Example: ARLags=1:4 specifies the nonseasonal AR polynomial 1ϕ1L1ϕ2L2ϕ3L3ϕ4L4.

Example: ARLags=[1 4] specifies the nonseasonal AR polynomial 1ϕ1L1ϕ4L4.

Data Types: double

Lags associated with the nonseasonal MA polynomial coefficients for the error model ut, specified as a numeric vector of unique positive integers. The maximum lag is q.

MA{j} is the coefficient of lag MALags(j), where MA is the value of the property MA.

Example: MALags=3 specifies the nonseasonal MA polynomial 1+θ3L3.

Example: MALags=1:3 specifies the nonseasonal MA polynomial 1+θ1L1+θ2L2+θ3L3.

Example: MALags=[1 3] specifies the nonseasonal MA polynomial 1+θ1L1+θ3L3.

Data Types: double

Lags associated with the seasonal AR polynomial coefficients for the error model ut, specified as a numeric vector of unique positive integers. The maximum lag is ps.

SAR{j} is the coefficient of lag SARLags(j), where SAR is the value of the property SAR.

Specify SARLags as the periodicity of the observed data, not as multiples of the Seasonality property. This convention does not conform to standard Box and Jenkins [1] notation, but it is more flexible for incorporating multiplicative seasonality.

Example: SARLags=[4 8] specifies the seasonal AR polynomial 1Φ4L4Φ8L8.

Data Types: double

Lags associated with the seasonal MA polynomial coefficients for the error model ut, specified as a numeric vector of unique positive integers. The maximum lag is qs.

SMA{j} is the coefficient of lag SMALags(j), where SMA is the value of the property SMA.

Specify SMALags as the periodicity of the observed data, not as multiples of the Seasonality property. This convention does not conform to standard Box and Jenkins [1] notation, but it is more flexible for incorporating multiplicative seasonality.

Example: SMALags=4 specifies the seasonal MA polynomial 1+Θ4L4.

Data Types: double

Note

Polynomial degrees are not estimable. If you do not specify a polynomial degree, or regARIMA cannot infer it from other specifications, regARIMA does not include the polynomial in the model.

Properties

expand all

You can set writable property values when you create the model object by using name-value argument syntax, or after you create the model object by using dot notation. For example, to create the fully specified regression model with ARMA(2,1) disturbances

yt=1+3x1+5x2+utut=0.3ut10.15ut2+εt+0.2εt1,

enter:

Mdl = regARIMA(Intercept=1,Beta=[3; 5],AR={0.3 -0.15},MA=0.2);
Mdl.Variance = 1;

Note

  • NaN-valued properties indicate estimable parameters. Numeric properties indicate equality constraints on parameters during model estimation. Coefficient vectors can contain both numeric and NaN-valued elements.

  • You can specify polynomial coefficients as vectors in any orientation, but regARIMA stores them as row vectors.

Regression Model Properties

Regression model intercept c, specified as a numeric scalar.

Example: Intercept=1

Data Types: double

Regression component coefficients β associated with predictor variables xt, specified as a numeric vector.

The default indicates one of the following conditions:

  • estimate infers the size of Beta from the number of columns of the specified predictor data X. Therefore, if you plan to fit all regression coefficients to data, you do not need to specify Beta.

  • The model does not include regression coefficients.

Example: Beta=[0.5 NaN 3] specifies three regression coefficients. During estimation, estimate fixes β1 to 5 and β3 to 3, and it fits β2 to the data associated with the second predictor variable.

Data Types: double

Error Model Properties

This property is read-only.

Compound AR polynomial degree of the error model, specified as a nonnegative integer.

P does not necessarily conform to standard Box and Jenkins notation [1] because P captures the degrees of the nonseasonal and seasonal AR polynomials (properties AR and SAR, respectively), nonseasonal integration (property D), and seasonality (property Seasonality). Explicitly, P = p + D + ps + s. P conforms to Box and Jenkins notation for models without integration or a seasonal AR component (D = 0 and SAR = {}).

P specifies the number of lagged observations required to initialize the AR components of the model.

Data Types: double

This property is read-only.

Compound MA polynomial degree of the error model, specified as a nonnegative integer.

Q does not necessarily conform to standard Box and Jenkins notation [1] because Q captures the degrees of the nonseasonal and seasonal MA polynomials (properties MA and SMA, respectively). Explicitly, Q = q + qs. Q conforms to Box and Jenkins notation for models without a seasonal MA component (SMA = {}).

Q specifies the number of lagged innovations required to initialize the MA components of the model.

Data Types: double

Nonseasonal AR polynomial coefficients ϕ for the error model ut, specified as a cell vector. Cells contain numeric scalars or NaN values. A fully specified nonseasonal AR polynomial must be stable.

Coefficient signs correspond to the model expressed in difference-equation notation. For example, for the nonseasonal AR polynomial ϕ(L)=10.5L+0.1L2, specify AR={0.5 –0.1}.

If you do not set the ARLags name-value argument, AR{j} is the coefficient of lag j, j = 1,…,p, where p = numel(AR).

Otherwise, if ARLags = arlags, with p = max(arlags), the following conditions apply:

  • The lengths of AR and arlags must be equal.

  • AR{j} is the coefficient of lag arlags(j), for each j.

  • regARIMA stores AR as a length p cell vector. All cells that do not correspond to lags in arlags contain 0.

The default value of AR depends on other specifications:

  • If you use the shorthand syntax to specify p > 0, AR is a length p cell vector, where each cell contains a NaN value.

  • If you specify ARLags, AR is a length p cell vector. AR{j} = NaN for each lag arlags(j). All other cells contain 0.

  • Otherwise, AR is an empty cell vector {}, meaning the model does not contain a nonseasonal AR polynomial.

The coefficients in AR correspond to coefficients in an underlying LagOp lag operator polynomial, and they are subject to a near-zero tolerance exclusion test. If a coefficient is 1e–12 or below, regARIMA excludes that coefficient and its corresponding lag in ARLags from the model.

Example: AR={0.8} sets the only AR lag coefficient associated with lag ARLags(1) to 0.8.

Example: regARIMA(AR={0.2 0 0.1}) sets the error model, in difference-equation form, to ut=0.2ut1+0.1ut3+εt.

Example: regARIMA(AR={NaN –0.1},ARLags=[4 8]) sets the AR lag polynomial to 1ϕ4L4+0.1L8, where ϕ4 is unknown and estimable.

Data Types: cell

Nonseasonal MA polynomial coefficients θ for the error model ut, specified as a cell vector. Cells contain numeric scalars or NaN values. A fully specified nonseasonal MA polynomial must be invertible.

If you do not set the MALags name-value pair argument, MA{j} is the coefficient of lag j, j = 1,…,q, where q = numel(MA).

Otherwise, if MALags = malags, with q = max(MALags), the following conditions apply:

  • The lengths of MA and malags must be equal.

  • MA{j} is the coefficient of lag malags(j), for each j.

  • regARIMA stores MA as a length q cell vector. All cells that do not correspond to lags in malags contain 0.

The default value of MA depends on other specifications:

  • If you use the shorthand syntax to specify q > 0, MA is a length q cell vector, where each cell contains a NaN value.

  • If you specify MALags, MA is a length q cell vector. MA{j} = NaN for each lag malags(j). All other cells contain 0.

  • Otherwise, MA is an empty cell vector {}, meaning the error model does not contain a nonseasonal MA polynomial.

The coefficients in MA correspond to coefficients in an underlying LagOp lag operator polynomial, and they are subject to a near-zero tolerance exclusion test. If a coefficient is 1e–12 or below, regARIMA excludes that coefficient and its corresponding lag in MALags from the model.

Example: MA=0.8 sets the only MA lag coefficient associated with lag MALags(1) to 0.8.

Example: regARIMA(MA={0.2 0.1}) sets the error model to ut=εt+0.2εt1+0.1εt2.

Example: regARIMA(MA={NaN –0.1},MALags=[4 8]) sets the MA lag polynomial to 1+θ4L40.1L8, where θ4 is unknown and estimable.

Data Types: cell

Seasonal AR polynomial coefficients Φ for the error model ut, specified as a cell vector. Cells contain numeric scalars or NaN values. A fully specified seasonal AR polynomial must be stable.

Coefficient signs correspond to the model expressed in difference-equation notation. For example, for the seasonal AR polynomial Φ(L)=10.5L4+0.1L8, specify SAR={0.5 –0.1}.

If you do not set the SARLags name-value argument, SAR{j} is the coefficient of lag j, j = 1,…,ps, where ps = numel(SAR).

Otherwise, if SARLags = sarlags, with ps = max(sarlags), the following conditions apply:

  • The lengths of SAR and sarlags must be equal.

  • SAR{j} is the coefficient of lag sarlags(j), for each j.

  • regARIMA stores SAR as a length ps cell vector. All cells that do not correspond to lags in sarlags contain 0.

The default value of SAR depends on the value of SARLags:

  • If you specify SARLags, SAR is a length ps cell vector. SAR{j} = NaN for each lag SARLags(j). All other cells contain 0.

  • Otherwise, SAR is an empty cell vector {}, meaning the error model does not contain a seasonal AR polynomial.

The coefficients in SAR correspond to coefficients in an underlying LagOp lag operator polynomial, and they are subject to a near-zero tolerance exclusion test. If a coefficient is 1e–12 or below, regARIMA excludes that coefficient and its corresponding lag in SARLags from the model.

Example: SAR=0.8 sets the only SAR lag coefficient associated with lag SARLags(1) to 0.8.

Example: regARIMA(SAR={0.2 0.1},Seasonality=4) sets the error model to (10.2L10.1L2)(1L4)ut=εt.

Example: regARIMA(SAR={NaN –0.1},SARLags=[4 8],Seasonality=4) sets the SAR lag polynomial to (1Θ4L40.1L8)(1L4), where Φ4 is unknown and estimable.

Data Types: cell

Seasonal MA polynomial coefficients for the error model, specified as a cell vector. Cells contain numeric scalars or NaN values. A fully specified seasonal MA polynomial must be invertible.

If you do not set the SMALags name-value argument, SMA{j} is the coefficient of lag j, j = 1,…,qs, where qs = numel(SMA).

Otherwise, if SMALags = smalags, with qs = max(smalags), the following conditions apply:

  • The lengths of SMA and SMALags must be equal.

  • SMA{j} is the coefficient of lag smalags(j), for each j.

  • regARIMA stores SMA as a length qs cell vector. All cells that do not correspond to lags in smalags contain 0.

The default value of SMA depends on other specifications:

  • If you specify SMALags, MA is a length q cell vector. MA{j} = NaN for each lag MALags(j). All other cells contain 0.

  • Otherwise, SMA is an empty cell vector {}, meaning the error model does not contain a seasonal MA polynomial.

The coefficients in SMA correspond to coefficients in an underlying LagOp lag operator polynomial, and they are subject to a near-zero tolerance exclusion test. If a coefficient is 1e–12 or below, regARIMA excludes that coefficient and its corresponding lag in SMALags from the model.

Example: SMA=0.8 sets the only SMA lag coefficient associated with lag SMALags(1) to 0.8.

Example: regARIMA(SMA{0.2 0.1},Seasonality=4) specifies the error model (1L4)ut=(1+0.2L+0.1L2)εt.

Example: regARIMA(SMALags=[1 4],SMA={0.2 0.1},Seasonality = 4) specifies the error model (1L4)ut=(1+0.2L+0.1L4)εt.

Data Types: cell

Degree of nonseasonal integration, or the degree of the nonseasonal differencing polynomial, for the error model specified as a nonnegative integer.

If you use shorthand syntax to create Mdl, the input d sets D.

Example: D=1

Example: regARIMA(0,1,2) sets D to 1.

Data Types: double

Degree of the seasonal differencing polynomial s for the error model, specified as a nonnegative integer.

Example: Seasonality=12 specifies monthly periodicity.

Data Types: double

Variance σ2 of the model innovations process εt, specified as a positive scalar.

NaN specifies an unknown and estimable variance, which estimate fits to data.

Example: Variance=1

Data Types: double

Other Properties

Model description, specified as a string scalar or character vector. regARIMA stores the value as a string scalar. The default value describes the parametric form of the model, for example, "Regression with ARMA(2,1) Error Model (Gaussian Distribution)".

Example: "Model 1"

Data Types: string | char

Conditional probability distribution of the innovation process εt, specified as a string or structure array. regARIMA stores the value as a structure array.

DistributionStringStructure Array
Gaussian"Gaussian"struct('Name',"Gaussian")
Student’s t"t"struct('Name',"t",'DoF',DoF)

The 'DoF' field specifies the t distribution degrees of freedom parameter.

  • DoF > 2 or DoF = NaN.

  • DoF is estimable.

  • If you specify "t", DoF is NaN by default. You can change its value by using dot notation after you create the model. For example, Mdl.Distribution.DoF = 3.

  • If you supply a structure array to specify the Student's t distribution, then you must specify both the 'Name' and the 'DoF' fields.

Example: Distribution=struct('Name',"t",'DoF',10)

Since R2023b

Response series name, specified as a string scalar or character vector. regARIMA stores the value as a string scalar.

Example: "StockReturn"

Data Types: string | char

Object Functions

estimateFit univariate regression model with ARIMA errors to data
inferInfer residuals of univariate regression model with ARIMA time series errors
summarizeDisplay estimation results of regression model with ARIMA errors
simulateMonte Carlo simulation of univariate regression model with ARIMA time series errors
filterFilter disturbances through regression model with ARIMA errors
impulseGenerate regression model with ARIMA errors impulse response function
forecastForecast responses of univariate regression model with ARIMA time series errors
arimaConvert regression model with ARIMA errors to ARIMAX model

Examples

collapse all

Specify the following regression model with ARIMA(2,1,3) errors:

yt=ut(1-ϕ1L-ϕ2L2)(1-L)ut=(1+θ1L+θ2L2+θ3L3)εt.

Mdl = regARIMA(2,1,3)
Mdl = 
  regARIMA with properties:

     Description: "ARIMA(2,1,3) Error Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
       Intercept: NaN
            Beta: [1×0]
               P: 3
               D: 1
               Q: 3
              AR: {NaN NaN} at lags [1 2]
             SAR: {}
              MA: {NaN NaN NaN} at lags [1 2 3]
             SMA: {}
        Variance: NaN

The output displays the values of the properties P, D, and Q of Mdl. The corresponding autoregressive and moving average coefficients (contained in AR and MA) are cell arrays containing the correct number of NaN values. Because P = p + D = 3, you need three presample observations to initialize the model for estimation.

Define the regression model with ARIMA errors:

yt=2+Xt[1.50.2]+ut(1-0.2L-0.3L2)ut=(1+0.1L)εt,

where εt is Gaussian with variance 0.5.

Mdl = regARIMA(Intercept=2,AR={0.2 0.3},MA={0.1}, ...
    Variance=0.5,Beta=[1.5 0.2])
Mdl = 
  regARIMA with properties:

     Description: "Regression with ARMA(2,1) Error Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
       Intercept: 2
            Beta: [1.5 0.2]
               P: 2
               Q: 1
              AR: {0.2 0.3} at lags [1 2]
             SAR: {}
              MA: {0.1} at lag [1]
             SMA: {}
        Variance: 0.5

Mdl is fully specified to, for example, simulate a series of responses given the predictor data matrix, Xt.

Modify the model to estimate the regression coefficient, the AR terms, and the variance of the innovations.

Mdl.Beta = [NaN NaN];
Mdl.AR = {NaN NaN};
Mdl.Variance = NaN;

Change the innovations distribution to a t distribution with 15 degrees of freedom.

Mdl.Distribution = struct("Name","t","DoF",15)
Mdl = 
  regARIMA with properties:

     Description: "Regression with ARMA(2,1) Error Model (t Distribution)"
      SeriesName: "Y"
    Distribution: Name = "t", DoF = 15
       Intercept: 2
            Beta: [NaN NaN]
               P: 2
               Q: 1
              AR: {NaN NaN} at lags [1 2]
             SAR: {}
              MA: {0.1} at lag [1]
             SMA: {}
        Variance: NaN

Specify the following model:

yt=1+6Xt+ut(1-0.2L)(1-L)(1-0.5L4-0.2L8)(1-L4)ut=(1+0.1L)(1+0.05L4+0.01L8)εt,

where εt is Gaussian with variance 1.

Mdl = regARIMA(Intercept=1,Beta=6,AR=0.2,MA=0.1,D=1, ...
    SAR={0.5,0.2},SARLags=[4, 8],SMA={0.05,0.01},SMALags=[4 8], ...
    Seasonality=4,Variance=1)
Mdl = 
  regARIMA with properties:

     Description: "Regression with ARIMA(1,1,1) Error Model Seasonally Integrated with Seasonal AR(8) and MA(8) (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
       Intercept: 1
            Beta: [6]
               P: 14
               D: 1
               Q: 9
              AR: {0.2} at lag [1]
             SAR: {0.5 0.2} at lags [4 8]
              MA: {0.1} at lag [1]
             SMA: {0.05 0.01} at lags [4 8]
     Seasonality: 4
        Variance: 1

If you do not specify SARLags or SMALags, then the coefficients in SAR and SMA correspond to lags 1 and 2 by default.

Mdl = regARIMA(Intercept=1,Beta=6,AR=0.2,MA=0.1,D=1, ...
    SAR={0.5,0.2},SARLags=[4, 8], ...
    Seasonality=4,Variance=1)
Mdl = 
  regARIMA with properties:

     Description: "Regression with ARIMA(1,1,1) Error Model Seasonally Integrated with Seasonal AR(8) (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
       Intercept: 1
            Beta: [6]
               P: 14
               D: 1
               Q: 1
              AR: {0.2} at lag [1]
             SAR: {0.5 0.2} at lags [4 8]
              MA: {0.1} at lag [1]
             SMA: {}
     Seasonality: 4
        Variance: 1

More About

expand all

References

[1] Box, George E. P., Gwilym M. Jenkins, and Gregory C. Reinsel. Time Series Analysis: Forecasting and Control. 3rd ed. Englewood Cliffs, NJ: Prentice Hall, 1994.

Version History

Introduced in R2013b

expand all