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

h = jcitest(Y) returns rejection decisions from conducting the Johansen test, which assesses each null hypothesis H(r) of cointegration rank less than or equal to r among an input numDims-dimensional multivariate time series 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.

h = jcitest(Tbl) returns rejection decisions from conducting the Johansen test on the variables of an input table or timetable.

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

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.

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

[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 y_t.

Examples

Conduct Johansen Cointegration Test on Matrix of Data

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×7 table
           r0       r1       r2      Model     Lags      Test       Alpha
          _____    _____    _____    ______    ____    _________    _____

    t1    true     true     false    {'H1'}     0      {'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 Default Johansen Cointegration Test on Table Variables

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×9 table
           r0       r1       r2       r3       r4      Model     Lags      Test       Alpha
          _____    _____    _____    _____    _____    ______    ____    _________    _____

    t1    true     true     false    false    true     {'H1'}     0      {'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.

Conduct Johansen Test for Each Test Statistic

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×7 table
           r0       r1       r2      Model     Lags       Test       Alpha
          _____    _____    _____    ______    ____    __________    _____

    t1    true     false    false    {'H1'}     0      {'trace' }    0.025
    t2    false    false    false    {'H1'}     0      {'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.

Return Test $\mathit{p}$-Values and Decision Statistics

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×7 table
           r0       r1       r2      Model     Lags       Test       Alpha
          _____    _____    _____    ______    ____    __________    _____

    t1    true     true     false    {'H1'}     0      {'trace' }    0.05 
    t2    false    false    false    {'H1'}     0      {'maxeig'}    0.05 

pValue=2×7 table
             r0           r1          r2       Model     Lags       Test       Alpha
          _________    ________    ________    ______    ____    __________    _____

    t1    0.0050497    0.034294    0.073661    {'H1'}     0      {'trace' }    0.05 
    t2     0.050346     0.06874    0.073661    {'H1'}     0      {'maxeig'}    0.05 

stat=2×7 table
            r0        r1        r2      Model     Lags       Test       Alpha
          ______    ______    ______    ______    ____    __________    _____

    t1    37.689    16.577    3.2003    {'H1'}     0      {'trace' }    0.05 
    t2    21.112    13.377    3.2003    {'H1'}     0      {'maxeig'}    0.05 

cValue=2×7 table
            r0        r1        r2      Model     Lags       Test       Alpha
          ______    ______    ______    ______    ____    __________    _____

    t1    29.798    15.495    3.8415    {'H1'}     0      {'trace' }    0.05 
    t2    21.132    14.264    3.8415    {'H1'}     0      {'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.

Plot Estimated Cointegrating Relations

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×7 table
           r0       r1       r2      Model     Lags      Test       Alpha
          _____    _____    _____    ______    ____    _________    _____

    t1    true     true     false    {'H1'}     0      {'trace'}    0.05 

pValue

pValue=1×7 table
             r0           r1          r2       Model     Lags      Test       Alpha
          _________    ________    ________    ______    ____    _________    _____

    t1    0.0050497    0.034294    0.073661    {'H1'}     0      {'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

Y — Data representing observations of multivariate time series y_t

numeric matrix

Data representing observations of a multivariate time series y_t, 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

Tbl — Data representing observations of multivariate time series y_t

table | timetable

Data representing observations of a multivariate time series y_t, 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.

Model — Johansen form of VEC(q) model deterministic terms

"H1" (default) | "H2" | "H1*" | "H*" | "H" | character vector | string vector | cell vector of character vectors

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

Value	Error-Correction Term	Description
"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

Lags — Number of lagged differences q

0 (default) | nonnegative integer | vector of nonnegative integers

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 Δy_{t – 1} in the model for all tests.

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

Data Types: double

Test — Test to perform

"trace" (default) | "maxeig" | character vector | string vector | cell vector of character vectors

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

Value	Description
"trace"	The alternative hypothesis is H(numDims), and the test statistics are $$-T\left[\log (1-{\lambda }_{r+1})+\dots +\log (1-{\lambda }_m)\right].$$
"maxieig"	The alternative hypothesis is H(r + 1), and the test statistics are $$-T\log (1-{\lambda }_{r+1}).$$

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 ≤ nnumObs and ordered estimates of the eigenvalues of C = AB′, λ₁ > ... > λ_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

Alpha — Nominal significance level

0.05 (default) | numeric scalar | numeric vector

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

Display — Command window display control

"off" | "summary" | "params" | "full"

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

Value	Description
"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

DataVariables — Variables in Tbl

all variables (default) | string vector | cell vector of character vectors | vector of integers | logical vector

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 y_t is defined for t = 1,…,T, the lagged series y_{t– k} is defined for t = k+1,…,T. The first difference applied to the lagged series y_{t– 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

h — Test rejection decisions

table

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.

pValue — Test statistic p-values

table

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.

stat — Test statistics

table

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.

cValue — Critical values

table

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

mles — Maximum likelihood estimates (MLE) associated with VEC(q) model of y_t

structure array

Maximum likelihood estimates associated with the VEC(q) model of y_t, 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.

Field	Description
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 v′S11v = 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

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 y_t is

$$\begin{array}{c}\Phi (L)(1-L)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

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

• $$\Phi (L)=I-{\Phi }_1-{\Phi }_2-\mathrm{...}-{\Phi }_q$$, I is the m-by-m identity matrix, and Ly_t = y_{t – 1}.

• The cointegrating relations are B'y_{t – 1} + c₀ + d₀t and the error-correction term is A(B'y_{t – 1} + c₀ + d₀t).

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

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

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

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

• c₁ is an m-by-1 vector of constants (deterministic linear trends in y_t).

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

• c = Ac₀ + c₁ and is the overall constant.

• d = Ad₀ + d₁ 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 t ≠ s, ε_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.

Tips

• To convert VEC(q) model parameters in the mles output to VAR(q + 1) model parameters, use vec2var.

• To test linear constraints on the error-correction speeds A and the space of cointegrating relations spanned by B, use jcontest.

Algorithms

• jcitest identifies deterministic terms that are outside of the cointegrating relations, c₁ and d₁, 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 y_t 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