Main Content

# jcitest

Johansen cointegration test

## Syntax

``h = jcitest(Y)``
``h = jcitest(Tbl)``
``h = jcitest(___,Name=Value)``
``````[h,pValue,stat,cValue] = jcitest(___)``````
``````[h,pValue,stat,cValue,mles] = jcitest(___)``````

## Description

example

````h = jcitest(Y)` returns the rejection decisions `h` from conducting the Johansen test, which assesses each null hypothesis H(r) of cointegration rank less than or equal to r among the `numDims`-dimensional multivariate time series `Y` against the alternatives H(`numDims`) (`trace` test) or H(r + 1) (`maxeig` test). The tests produce maximum likelihood estimates of the parameters in a vector error-correction (VEC) model of the cointegrated series.```

example

````h = jcitest(Tbl)` returns rejection decisions from conducting the Johansen test on the variables of the table or timetable `Tbl`.To select a subset of variables in `Tbl` to test, use the `DataVariables` name-value argument.```

example

````h = jcitest(___,Name=Value)` uses additional options specified by one or more name-value arguments, using any input-argument combination in the previous syntaxes.Some options control the number of tests to conduct. The following conditions apply when `jcitest` conducts multiple tests: `jcitest` treats each test as separate from all other tests.Each row of all outputs contains the results of the corresponding test. For example, `jcitest(Tbl,Model="H2",DataVariables=1:5)` tests the first 5 variables in the input table `Tbl` using the Johansen model that excludes all deterministic terms.```

example

``````[h,pValue,stat,cValue] = jcitest(___)``` displays, at the command window, the results of the Johansen test and returns the p-values `pValue`, test statistics `stat`, and critical values `cValue` of the test. The results display includes the ranks r, corresponding rejection decisions, p-values, decision statistics, and specified options.```

example

``````[h,pValue,stat,cValue,mles] = jcitest(___)``` also returns a structure of maximum likelihood estimates associated with the VEC(q) model of the multivariate time series yt.```

## Examples

collapse all

Test a multivariate time series for cointegration using the default values of the Johansen cointegration test. Input the time series data as a numeric matrix.

Load data of Canadian inflation and interest rates `Data_Canada.mat`, which contains the series in the matrix `Data`.

```load Data_Canada series'```
```ans = 5x1 cell {'(INF_C) Inflation rate (CPI-based)' } {'(INF_G) Inflation rate (GDP deflator-based)'} {'(INT_S) Interest rate (short-term)' } {'(INT_M) Interest rate (medium-term)' } {'(INT_L) Interest rate (long-term)' } ```

Test the interest rate series for cointegration by using the Johansen cointegration test. Use default options and return the rejection decision.

`h = jcitest(Data(:,3:end))`
```h=1×6 table r0 r1 r2 Model Test Alpha _____ _____ _____ ______ _________ _____ t1 true true false {'H1'} {'trace'} 0.05 ```

By default, `jcitest` conducts the `trace` test and uses the `H1` Johansen form by default. The test fails to reject the null hypothesis of rank 2 cointegration in the series.

Conduct the Johansen cointegration test on a multivariate time series using default options, which tests all table variables.

Load data of Canadian inflation and interest rates `Data_Canada.mat`. Convert the table `DataTable` to a timetable.

```load Data_Canada dates = datetime(dates,12,31); TT = table2timetable(DataTable,RowTimes=dates); TT.Observations = [];```

Conduct the Johansen cointegration test by passing the timetable to `jcitest` and using default options. `jcitest` tests for cointegration among all table variables by default.

`h = jcitest(TT)`
```h=1×8 table r0 r1 r2 r3 r4 Model Test Alpha _____ _____ _____ _____ _____ ______ _________ _____ t1 true true false false true {'H1'} {'trace'} 0.05 ```

The test fails to reject the null hypotheses of rank 2 and 3 cointegration among the series.

By default, `jcitest` includes all input table variables in the cointegration test. To select a subset of variables to test, set the `DataVariables` option.

`jcitest` supports two types Johansen tests. Conduct a test for each type.

Load data of Canadian inflation and interest rates `Data_Canada.mat`. Convert the table `DataTable` to a timetable. Identify the interest rate series.

```load Data_Canada dates = datetime(dates,12,31); TT = table2timetable(DataTable,RowTimes=dates); TT.Observations = []; idxINT = contains(TT.Properties.VariableNames,"INT");```

Conduct the Johansen cointegration test to assess cointegration among the interest rate series. Specify both test types `trace` and `maxeig`, and set the level of significance to 2.5%.

`h = jcitest(TT,DataVariables=idxINT,Test=["trace" "maxeig"],Alpha=0.025)`
```h=2×6 table r0 r1 r2 Model Test Alpha _____ _____ _____ ______ __________ _____ t1 true false false {'H1'} {'trace' } 0.025 t2 false false false {'H1'} {'maxeig'} 0.025 ```

h is a 2-row table; rows contain results of separate tests. At 2.5% level of significance:

• The `trace` test fails to reject the null hypotheses of ranks 1 and 2 cointegration among the series.

• The `maxeig` test fails to reject the null hypotheses for each cointegration rank.

Load data of Canadian inflation and interest rates `Data_Canada.mat`. Convert the table `DataTable` to a timetable. Identify the interest rate series.

```load Data_Canada dates = datetime(dates,12,31); TT = table2timetable(DataTable,RowTimes=dates); TT.Observations = []; idxINT = contains(TT.Properties.VariableNames,"INT");```

Conduct the Johansen cointegration test to assess cointegration among the interest rate series. Specify both test types `trace` and `maxeig`.

`[h,pValue,stat,cValue] = jcitest(TT,DataVariables=idxINT,Test=["trace" "maxeig"])`
```************************ Results Summary (Test 1) Data: TT Effective sample size: 40 Model: H1 Lags: 0 Statistic: trace Significance level: 0.05 r h stat cValue pValue eigVal ---------------------------------------- 0 1 37.6886 29.7976 0.0050 0.4101 1 1 16.5770 15.4948 0.0343 0.2842 2 0 3.2003 3.8415 0.0737 0.0769 ************************ Results Summary (Test 2) Data: TT Effective sample size: 40 Model: H1 Lags: 0 Statistic: maxeig Significance level: 0.05 r h stat cValue pValue eigVal ---------------------------------------- 0 0 21.1116 21.1323 0.0503 0.4101 1 0 13.3767 14.2644 0.0687 0.2842 2 0 3.2003 3.8415 0.0737 0.0769 ```
```h=2×6 table r0 r1 r2 Model Test Alpha _____ _____ _____ ______ __________ _____ t1 true true false {'H1'} {'trace' } 0.05 t2 false false false {'H1'} {'maxeig'} 0.05 ```
```pValue=2×6 table r0 r1 r2 Model Test Alpha _________ ________ ________ ______ __________ _____ t1 0.0050497 0.034294 0.073661 {'H1'} {'trace' } 0.05 t2 0.050346 0.06874 0.073661 {'H1'} {'maxeig'} 0.05 ```
```stat=2×6 table r0 r1 r2 Model Test Alpha ______ ______ ______ ______ __________ _____ t1 37.689 16.577 3.2003 {'H1'} {'trace' } 0.05 t2 21.112 13.377 3.2003 {'H1'} {'maxeig'} 0.05 ```
```cValue=2×6 table r0 r1 r2 Model Test Alpha ______ ______ ______ ______ __________ _____ t1 29.798 15.495 3.8415 {'H1'} {'trace' } 0.05 t2 21.132 14.264 3.8415 {'H1'} {'maxeig'} 0.05 ```

`jcitest` prints a results display for each test to the command window. All outputs are tables containing the corresponding statistics and test options.

Load data of Canadian inflation and interest rates `Data_Canada.mat`. Convert the table `DataTable` to a timetable.

```load Data_Canada dates = datetime(dates,12,31); TT = table2timetable(DataTable,RowTimes=dates); TT.Observations = []; idxINT = contains(TT.Properties.VariableNames,"INT");```

Plot the interest series.

```plot(TT.Time,TT{:,idxINT}) legend(series(idxINT),Location="northwest") grid on```

Test the interest rate series for cointegration; use the default Johansen form `H1`. Return all outputs.

`[h,pValue,stat,cValue,mles] = jcitest(TT,DataVariables=idxINT);`
```************************ Results Summary (Test 1) Data: TT Effective sample size: 40 Model: H1 Lags: 0 Statistic: trace Significance level: 0.05 r h stat cValue pValue eigVal ---------------------------------------- 0 1 37.6886 29.7976 0.0050 0.4101 1 1 16.5770 15.4948 0.0343 0.2842 2 0 3.2003 3.8415 0.0737 0.0769 ```
`h`
```h=1×6 table r0 r1 r2 Model Test Alpha _____ _____ _____ ______ _________ _____ t1 true true false {'H1'} {'trace'} 0.05 ```
`pValue`
```pValue=1×6 table r0 r1 r2 Model Test Alpha _________ ________ ________ ______ _________ _____ t1 0.0050497 0.034294 0.073661 {'H1'} {'trace'} 0.05 ```

The test fails to reject the null hypothesis of rank 2 cointegration in the series.

Plot the estimated cointegrating relations ${B}^{\prime }{y}_{t-1}+{c}_{0}$:

```TTLag = lagmatrix(TT,1); T = height(TTLag); B = mles.r2.paramVals.B; c0 = mles.r2.paramVals.c0; plot(TTLag.Time,TTLag{:,idxINT}*B+repmat(c0',T,1)) grid on```

## Input Arguments

collapse all

Data representing observations of a multivariate time series yt, specified as a `numObs`-by-`numDims` numeric matrix. Each column of `Y` corresponds to a variable, and each row corresponds to an observation.

Data Types: `double`

Data representing observations of a multivariate time series yt, specified as a table or timetable with `numObs` rows. Each row of `Tbl` is an observation.

To select a subset of variables in `Tbl` to test, use the `DataVariables` name-value argument.

Note

`jcitest` removes the following observations from the specified data:

• All rows containing at least one missing observation, represented by a `NaN` value

• From the beginning of the data, initial values required to initialize lagged variables

### 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.

Example: `jcitest(Tbl,Model="H2",DataVariables=1:5)` tests the first 5 variables in the input table `Tbl` using the Johansen model that excludes all deterministic terms.

Johansen form of the VEC(q) model deterministic terms [3], specified as a Johansen form name in the table, or a string vector or cell vector of character vectors of such values (for model parameter definitions, see Vector Error-Correction (VEC) Model).

ValueError-Correction TermDescription
`"H2"`

AB´yt − 1

No intercepts or trends are present in the cointegrating relations, and no deterministic trends are present in the levels of the data.

Specify this model only when all response series have a mean of zero.

`"H1*"`

A(B´yt−1+c0)

Intercepts are present in the cointegrating relations, and no deterministic trends are present in the levels of the data.

`"H1"`

A(B´yt−1+c0)+c1

Intercepts are present in the cointegrating relations, and deterministic linear trends are present in the levels of the data.

`"H*"`A(B´yt−1+c0+d0t)+c1

Intercepts and linear trends are present in the cointegrating relations, and deterministic linear trends are present in the levels of the data.

`"H"`A(B´yt−1+c0+d0t)+c1+d1t

Intercepts and linear trends are present in the cointegrating relations, and deterministic quadratic trends are present in the levels of the data.

If quadratic trends are not present in the data, this model can produce good in-sample fits but poor out-of-sample forecasts.

`jcitest` conducts a separate test for each value in `Model`.

Example: `Model="H1*"` uses the Johansen form `H1*` for all tests.

Example: `Model=["H1*" "H1"]` uses Johansen form `H1*` for the first test, and then uses Johansen form `H1` for the second test.

Data Types: `string` | `char` | `cell`

Number of lagged differences q in the VEC(q) model, specified as a nonnegative integer or vector of nonnegative integers.

`jcitest` conducts a separate test for each value in `Lags`.

Example: `Lags=1` includes Δyt – 1 in the model for all tests.

Example: `Lags=[0 1]` includes no lags in the model for the first test, and then includes Δyt – 1 in the model for the second test.

Data Types: `double`

Test to perform, specified as a value in this table, or a string vector or cell vector of character vectors of such values.

ValueDescription
`"trace"`

The alternative hypothesis is H(`numDims`), and the test statistics are

`$-T\left[\mathrm{log}\left(1-{\lambda }_{r+1}\right)+\dots +\mathrm{log}\left(1-{\lambda }_{m}\right)\right].$`

`"maxieig"`

The alternative hypothesis is H(r + 1), and the test statistics are

`$-T\mathrm{log}\left(1-{\lambda }_{r+1}\right).$`

Both tests assess the null hypothesis H(r) of cointegration rank less than or equal to r. `jcitest` computes statistics using the effective sample size T ≤ n`numObs` and ordered estimates of the eigenvalues of C = AB′, λ1 > ... > λm, where m = `numDims`.

`jcitest` conducts a separate test for each value in `Test`.

Example: `Test="maxeig"` conducts the `maxeig` test for all tests.

Example: `Test=["maxeig" "trace"]` conducts the `maxeig` test for the first test, and then conducts the `trace` test for the second test.

Data Types: `char` | `string` | `cell`

Nominal significance level for the hypothesis test, specified as a numeric scalar between `0.001` and `0.999` or a numeric vector of such values.

`jcitest` conducts a separate test for each value in `Alpha`.

Example: `Alpha=[0.01 0.05]` uses a level of significance of `0.01` for the first test, and then uses a level of significance of `0.05` for the second test.

Data Types: `double`

Command window display type, specified as a value in this table.

ValueDescription
`"off"``jcitest` does not display the results to the command window. If `jcitest` returns `h` or no outputs, this display is the default.
`"summary"`

`jcitest` displays a tabular summary of test results. The tabular display includes null ranks r = `0:(numDims − 1)` in the first column of each summary. `jcitest` displays multiple test results in separate summaries.

When `jcitest` returns any other output than `h` (for example, `pValue`), this display is the default. You cannot set this display when `jcitest` returns `h` or no outputs.

`"params"``jcitest` displays maximum likelihood estimates of the parameter values associated with the reduced-rank VEC(q) model of yt. You can set this display only when `jcitest` returns `mles`. `jcitest` returns the displayed parameter estimates in the field `mles.rn(j).paramVals` for null rank r = n and test `j`.
`"full"``jcitest` displays both `"summary"` and `"params"`.

Example: `Display="off"`

Data Types: `char` | `string`

Variables in `Tbl` for which `jcitest` conducts the test, specified as a string vector or cell vector of character vectors containing variable names in `Tbl.Properties.VariableNames`, or an integer or logical vector representing the indices of names. The selected variables must be numeric.

Example: `DataVariables=["GDP" "CPI"]`

Example: `DataVariables=[true true false false]` or `DataVariables=[1 2]` selects the first and second table variables.

Data Types: `double` | `logical` | `char` | `cell` | `string`

Note

• When `jcitest` conducts multiple tests, the function applies all single settings (scalars or character vectors) to each test.

• All vector-valued specifications that control the number of tests must have equal length.

• A lagged and differenced time series has a reduced sample size. Absent presample values, if the test series yt is defined for t = 1,…,T, the lagged series yt– k is defined for t = k+1,…,T. The first difference applied to the lagged series yt– k further reduces the time base to k+2,…,T. With p lagged differences, the common time base is p+2,…,T and the effective sample size is T–(p+1).

## Output Arguments

collapse all

Test rejection decisions, returned as a `numTests`-by-(`numDims` + 3) table, where `numTests` is the number of tests, which is determined by specified options.

Row `j` of `h` corresponds to test `j` with options.

Rows of `h` correspond to tests specified by the values of the last three variables `Model`, `Test`, and `Alpha`. Row labels are `t1`, `t2`, …, `tu`, where `u` = `numTests`.

Variables of `h` correspond to different, maintained cointegration ranks r = 0, 1, …, `numDims` – 1 and specified name-value arguments that control the number of tests. Variable labels are `r0`, `r1`, …, `rR`, where `R` = `numDims` – 1, and `Model`, `Test`, and `Alpha`.

To access results, for example, the result for test `j` of null rank `k`, use `h.rk(j)`.

Variable k, labeled `rk`, is logical vector whose entries have the following interpretations:

• `1` (`true`) indicates rejection of the null hypothesis of cointegration rank k in favor of the alternative hypothesis.

• `0` (`false`) indicates failure to reject the null hypothesis of cointegration rank k.

Test statistic p-values, returned as a table with the same dimensions and labels as `h`. Variable k, labeled `rk`, is a numeric vector of p-values for the corresponding tests. The p-values are right-tailed probabilities.

When test statistics are outside tabulated critical values, `jcitest` returns maximum (`0.999`) or minimum (`0.001`) p-values.

Test statistics, returned as a table with the same dimensions and labels as `h`.

The `Test` setting of a particular test determines the test statistic.

Critical values, returned as a table with the same dimensions and labels as `h`. Variable k, labeled `rk`, is a numeric vector of critical values for the corresponding tests. The critical values are for right-tailed probabilities determined by `Alpha`.

`jcitest` loads tables of critical values from the file `Data_JCITest.mat`, and then linearly interpolates test critical values from the tables. Critical values in the tables derive from methods described in [4].

Maximum likelihood estimates associated with the VEC(q) model of yt, returned as a table with the same dimensions and labels as `h`. Variable k, labeled `rk`, is a structure array of MLEs with elements for the corresponding tests.

Each element of `mles.rk` has the fields in this table. You can access a field using dot notation, for example, `mles.r2(3).paramVals` contains the parameter estimates of the third test corresponding to the null hypothesis of rank 2 cointegration.

FieldDescription
`paramNames`

Cell vector of parameter names, of the form:

{`A`, `B`, `B1`, … `Bq`, `c0`, `d0`, `c1`, `d1`}

Elements depend on the values of the `Lags` and `Model` name-value arguments.

`paramVals`Structure of parameter estimates with field names corresponding to the parameter names in `paramNames`.
`res` T-by-`numDims` matrix of residuals, where T is the effective sample size, obtained by fitting the VEC(q) model of yt to the input data.
`EstCov`Estimated covariance Q of the innovations process εt.
`eigVal`Eigenvalue associated with H(r).
`eigVec`Eigenvector associated with the eigenvalue in `eigVal`. Eigenvectors v are normalized so that vS11v = 1, where S11 is defined as in [3].
`rLL` Restricted loglikelihood of yt under the null.
`uLL`Unrestricted loglikelihood of yt under the alternative.

## More About

collapse all

### Vector Error-Correction (VEC) Model

A vector error-correction (VEC) model is a multivariate, stochastic time series model consisting of a system of m = `numDims` equations of m distinct, differenced response variables. Equations in the system can include an error-correction term, which is a linear function of the responses in levels used to stabilize the system. The cointegrating rank r is the number of cointegrating relations that exist in the system.

Each response equation can include a degree q autoregressive polynomial composed of first differences of the response series, a constant, a time trend, and a constant and time trend in the error-correction term.

Expressed in lag operator notation, a VEC(q) model for a multivariate time series yt is

`$\begin{array}{c}\Phi \left(L\right)\left(1-L\right){y}_{t}=A\left(B\prime {y}_{t-1}+{c}_{0}+{d}_{0}t\right)+{c}_{1}+{d}_{1}t+{\epsilon }_{t}\\ =c+dt+C{y}_{t-1}+{\epsilon }_{t},\end{array}$`

where

• yt is an m = `numDims` dimensional time series corresponding to m response variables at time t, t = 1,...,T.

• $\Phi \left(L\right)=I-{\Phi }_{1}-{\Phi }_{2}-...-{\Phi }_{q}$, I is the m-by-m identity matrix, and Lyt = yt – 1.

• The cointegrating relations are B'yt – 1 + c0 + d0t and the error-correction term is A(B'yt – 1 + c0 + d0t).

• r is the number of cointegrating relations and, in general, 0 ≤ rm.

• A is an m-by-r matrix of adjustment speeds.

• B is an m-by-r cointegration matrix.

• C = AB′ is an m-by-m impact matrix with a rank of r.

• c0 is an r-by-1 vector of constants (intercepts) in the cointegrating relations.

• d0 is an r-by-1 vector of linear time trends in the cointegrating relations.

• c1 is an m-by-1 vector of constants (deterministic linear trends in yt).

• d1 is an m-by-1 vector of linear time-trend values (deterministic quadratic trends in yt).

• c = Ac0 + c1 and is the overall constant.

• d = Ad0 + d1 and is the overall time-trend coefficient.

• Φj is an m-by-m matrix of short-run coefficients, where j = 1,...,q and Φq is not a matrix containing only zeros.

• εt is an m-by-1 vector of random Gaussian innovations, each with a mean of 0 and collectively an m-by-m covariance matrix Σ. For ts, εt and εs are independent.

If m = r, then the VEC model is a stable VAR(q + 1) model in the levels of the responses. If r = 0, then the error-correction term is a matrix of zeros, and the VEC(q) model is a stable VAR(q) model in the first differences of the responses.

## Algorithms

• `jcitest` identifies deterministic terms that are outside of the cointegrating relations, c1 and d1, by projecting constant and linear regression coefficients, respectively, onto the orthogonal complement of A.

• If `jcitest` fails to reject the null hypothesis of cointegration rank r = 0, the inference is that the error-correction coefficient C is zero, and the VEC(q) model reduces to a standard VAR(q) model in first differences. If `jcitest` rejects all cointegration ranks r less than `numDims`, the inference is that C has full rank, and yt is stationary in levels.

• The parameters A and B in the reduced-rank VEC(q) model are not identifiable, but their product C = AB is identifiable. `jcitest` constructs `B` = `V(:,1:r)` using the orthonormal eigenvectors `V` returned by `eig`, and then renormalizes so that `V'*S11*V = I` [3].

• The time series in the specified input data can be stationary in levels or first differences (that is, I(0) or I(1)). Rather than pretesting series for unit roots (using, e.g., `adftest`, `pptest`, `kpsstest`, or `lmctest`), the Johansen procedure formulates the question within the model. An I(0) series is associated with a standard unit vector in the space of cointegrating relations, and the `jcontest` can test for its presence.

• Deterministic cointegration, where cointegrating relations, perhaps with an intercept, produce stationary series, is the traditional sense of cointegration introduced by Engle and Granger [1] (see `egcitest`). Stochastic cointegration, where cointegrating relations produce trend-stationary series (that is, `d0` is nonzero), extends the definition of cointegration to accommodate a greater variety of economic series.

• Unless higher-order trends are present in the data, models with fewer restrictions can produce good in-sample fits, but poor out-of-sample forecasts.

## Alternative Functionality

### App

The Econometric Modeler app enables you to conduct the Johansen cointegration test.

## References

[1] Engle, R. F. and C. W. J. Granger. "Co-Integration and Error-Correction: Representation, Estimation, and Testing." Econometrica. Vol. 55, 1987, pp. 251–276.

[2] Hamilton, James D. Time Series Analysis. Princeton, NJ: Princeton University Press, 1994.

[3] Johansen, S. Likelihood-Based Inference in Cointegrated Vector Autoregressive Models. Oxford: Oxford University Press, 1995.

[4] MacKinnon, J. G. "Numerical Distribution Functions for Unit Root and Cointegration Tests." Journal of Applied Econometrics. Vol. 11, 1996, pp. 601–618.

[5] Turner, P. M. "Testing for Cointegration Using the Johansen Approach: Are We Using the Correct Critical Values?" Journal of Applied Econometrics. v. 24, 2009, pp. 825–831.

## Version History

Introduced in R2011a