Main Content

jcontest

Johansen constraint test

Description

example

h = jcontest(Y,r,test,Cons) returns the rejection decisions h from conducting the Johansen constraint test, which assesses linear constraints on either the error-correction (adjustment) speeds A or the cointegration space spanned by the cointegrating matrix B in the reduced-rank VEC(q) model of the multivariate time series yt, where:

  • Y is a matrix of observations of yt.

  • r is the common rank of matrices A and B.

  • test specifies the constraint types, including linear or equality constraints on A or B.

  • Cons specifies the test constraint values.

For a particular test, the constraint type and values form the null hypotheses tested against the alternative hypothesis H(r) of cointegration rank less than or equal to r (an unconstrained VEC model). The tests also produce maximum likelihood estimates of the parameters in the VEC(q) model, subject to the constraints.

Each element of test and Cons results in a separate test.

example

[h,pValue,stat,cValue] = jcontest(Y,r,test,Cons) also returns the p-values pValue, test statistics stat, and critical values cValue of the test.

example

StatTbl = jcontest(Tbl,r,test,Cons) returns the table StatTbl containing variables for the test results, statistics, and settings from conducting the Johansen constraint test on all variables of the input table or timetable Tbl.

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

example

[___] = jcontest(___,Name=Value) uses additional options specified by one or more name-value arguments, using any input-argument combination in the previous syntaxes. jcontest returns the output-argument combination for the corresponding input arguments.

In addition to bp, some options control the number of tests to conduct.

For example, jcontest(Tbl,r,test,Cons,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

[___,mles] = jcontest(___) also returns a structure of maximum likelihood estimates associated with the constrained VEC(q) models of the multivariate time series yt.

Examples

collapse all

Test for weak exogeneity of a time series, with respect to other series in the system, by using default options of jcontest. 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)'          }

Use the Johansen constraint test to assess whether the CPI-based inflation rate y1,t is weakly exogenous with respect to the three interest rate series by testing the following constraint in a 4-D VEC model of the series:

(1-L)y1,t=c+εt.

Specify a rank of 1 for the test, a linear constraint on the 4-by-1 adjustment speed vectorA so that a1=0, and default options. Return the rejection decision.

Cons = [1; 0; 0; 0];
Y = Data(:,[1 3:5]);
h = jcontest(Y,1,"ACon",Cons)
h = logical
   0

Given default options and assumptions, h = 0 suggests that the test fails to reject the null hypothesis of the constrained model, which is that the inflation rate is weakly exogenous with respect to the interest rate series.

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

load Data_Canada

Conduct the default Johansen constraint test to assess whether the CPI-based inflation rate is weakly exogenous with respect to the interest rate series. Return the test decisions and p-values.

Cons = [1; 0; 0; 0];
Y = Data(:,[1 3:5]);
[h,pValue,stat,cValue] = jcontest(Y,1,"ACon",Cons)
h = logical
   0

pValue = 0.3206
stat = 0.9865
cValue = 3.8415

Test for weak exogeneity of a time series, which are variables in a table, with respect to the other time series in the table. Return a table of results.

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

load Data_Canada
dates = datetime(dates,ConvertFrom="datenum");
TT = table2timetable(DataTable,RowTimes=dates);
TT.Observations = [];

Use the Johansen constraint test to assess whether the CPI-based and GDP-deflator-based inflation rates (y1,t and y2,t, respectively) are weakly exogenous with respect to the three interest rate series by testing the following constraint in a 5-D VEC model of the series:

(1-L)y1,t=c1,1+ε1,t(1-L)y2,t=c2,1+ε2,t.

Specify a rank of 2 for the test, a linear constraint on the 4-by-2 adjustment speed vectorA so that a1=0 and a2=0, and default options.

Cons = [1 0;
        0 1;
        0 0;
        0 0;
        0 0];
StatTbl = jcontest(TT,2,"ACon",Cons)
StatTbl=1×8 table
                h        pValue       stat     cValue    Lags    Alpha    Model       Test  
              _____    __________    ______    ______    ____    _____    ______    ________

    Test 1    true     1.3026e-05    27.907    9.4877     0      0.05     {'H1'}    {'acon'}

StatTbl.h = 1 means that the test rejects the null hypothesis of the constrained model that the inflation rates are jointly weakly exogenous. StatTbl.pValue = 1.3026e-5 suggests that the evidence to reject is strong.

By default, jcontest conducts the Johansen constraint test on all variables in the input table. To select a subset of variables from an input table, set the DataVariables option.

Use the Johansen framework to test multivariate time series with the following characteristics:

  1. The log Australian CPI, log US CPI, and the exchange rate series of the countries are stationary.

  2. The three series exhibit cointegration.

  3. The Australian and the US dollars have the same purchasing power.

Load and Inspect Data

Load the data on Australian and U.S. prices Data_JAustralian.mat, which contains the table DataTable. Convert the table to a timetable.

load Data_JAustralian
dates = datetime(dates,ConvertFrom="datenum");
TT = table2timetable(DataTable,RowTimes=dates);
TT.Dates = [];

Plot the log Australian and log US CPI series (PAU and PUS, respectively), and the log AUD/USD exchange rate series EXCH.

varnames = ["PAU" "PUS" "EXCH"];
plot(TT.Time,TT{:,varnames})
legend(varnames,Location="best")
grid on

Figure contains an axes object. The axes object contains 3 objects of type line. These objects represent PAU, PUS, EXCH.

Pretest for Stationarity

Use jcontest to test the null hypothesis that the individual series are stationary by specifying, for each variable j, the following constrained model

(1-L)yt=[a1,ja2,ja3,j](yt-1+c0)+c1+εt.

Specify the variables to use in the test.

Cons = num2cell(eye(3),1)
Cons=1×3 cell array
    {3x1 double}    {3x1 double}    {3x1 double}

StatTbl0 = jcontest(TT,1,"BVec",Cons,DataVariables=varnames)
StatTbl0=3×8 table
                h        pValue       stat     cValue    Lags    Alpha    Model       Test  
              _____    __________    ______    ______    ____    _____    ______    ________

    Test 1    true      1.307e-05     22.49    5.9915     0      0.05     {'H1'}    {'bvec'}
    Test 2    true     1.0274e-05    22.972    5.9915     0      0.05     {'H1'}    {'bvec'}
    Test 3    false       0.06571     5.445    5.9915     0      0.05     {'H1'}    {'bvec'}

jcontest returns a table of test results. Each row corresponds to a separate test and columns correspond to results or specified options for each test.

StatTbl.h(j) = 1 rejects the null hypothesis of stationarity of variable j, and StatTbl.h(j) = 0 fails to reject stationarity.

Test for Cointegration

Test for cointegration by using jcitest.

StatTbl1 = jcitest(TT,DataVariables=varnames)
StatTbl1=1×6 table
           r0       r1       r2      Model       Test       Alpha
          _____    _____    _____    ______    _________    _____

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

StatTbl1.r1 = 0 and StatTbl1.r2 = 0 suggest that the series exhibit at least rank 1 cointegration.

Test for Purchasing Power Parity

Test for purchasing power parity PAU = PUS + EXCH.

StatTbl2 = jcontest(TT,1,"BCon",[1 -1 -1]',DataVariables=varnames)
StatTbl2=1×8 table
                h       pValue      stat     cValue    Lags    Alpha    Model       Test  
              _____    ________    ______    ______    ____    _____    ______    ________

    Test 1    false    0.053995    3.7128    3.8415     0      0.05     {'H1'}    {'bcon'}

StatTbl2.h = 0 means that the test fails to reject the null hypothesis of the constrained model, that is, purchasing power parity between the models should not be rejected.

Compare the four types of supported constraints on the adjustment-speed and cointegrating matrices.

Load the data on Australian and US prices Data_JAustralian.mat, which contains the table DataTable. Convert the table to a timetable. Consider a 3-D VEC model consisting of the log Australian and US CPI, and the log AUD/USD exchange rate series.

load Data_JAustralian
dates = datetime(dates,ConvertFrom="datenum");
TT = table2timetable(DataTable,RowTimes=dates);
TT.Dates = [];
varnames = ["PAU" "PUS" "EXCH"];

Conduct the four Johansen constraint tests; specify the arbitrary constraint value [1-1-1]. Return the test results and maximum likelihood estimates of the constrained model.

[StatTbl,mle] = jcontest(TT,1,["ACon" "AVec" "BCon" "BVec"], ...
    [1 -1 -1]',DataVariables=varnames);
StatTbl
StatTbl=4×8 table
                h        pValue       stat     cValue    Lags    Alpha    Model       Test  
              _____    __________    ______    ______    ____    _____    ______    ________

    Test 1    false       0.11047    2.5475    3.8415     0      0.05     {'H1'}    {'acon'}
    Test 2    true     3.0486e-08    34.612    5.9915     0      0.05     {'H1'}    {'avec'}
    Test 3    false      0.053995    3.7128    3.8415     0      0.05     {'H1'}    {'bcon'}
    Test 4    false      0.074473    5.1946    5.9915     0      0.05     {'H1'}    {'bvec'}

mle is a 4-by-1 structure array with fields containing the maximum likelihood estimates of the constrained models for each test.

For each test, display the estimates of A and B, and compute the MLE of the impact matrix Cˆ=AˆBˆ. The impactmat function is a local supporting function that computes the MLE of the impact matrix and displays the estimated matrices.

[AACon,BACon,CACon] = impactmat(mle(1))
AACon = 3×1

    0.0043
    0.0055
   -0.0012

BACon = 3×1

    2.8496
   -2.3341
   -6.2670

CACon = 3×3

    0.0121   -0.0099   -0.0267
    0.0156   -0.0128   -0.0343
   -0.0035    0.0028    0.0076

[1 -1 -1]*AACon
ans = 0
[AAVec,BAVec,CAVec] = impactmat(mle(2))
AAVec = 3×1

     1
    -1
    -1

BAVec = 3×1

   -0.0204
    0.0158
    0.0246

CAVec = 3×3

   -0.0204    0.0158    0.0246
    0.0204   -0.0158   -0.0246
    0.0204   -0.0158   -0.0246

[ABCon,BBCon,CBCon] = impactmat(mle(3))
ABCon = 3×1

   -0.0043
   -0.0052
   -0.0089

BBCon = 3×1

    1.8001
   -3.9210
    5.7211

CBCon = 3×3

   -0.0078    0.0170   -0.0248
   -0.0094    0.0206   -0.0300
   -0.0159    0.0347   -0.0507

[1 -1 -1]*BBCon
ans = 0
[ABVec,BBVec,CBVec] = impactmat(mle(4))
ABVec = 3×1

    0.0252
    0.0422
    0.0556

BBVec = 3×1

     1
    -1
    -1

CBVec = 3×3

    0.0252   -0.0252   -0.0252
    0.0422   -0.0422   -0.0422
    0.0556   -0.0556   -0.0556

Observe that the AVec and BVec constraints apply the constraint value directly to the coefficients, whereas the estimates of the ACon and BCon constraints fulfill the corresponding linear constraint.

Supporting Function

function [A,B,C] = impactmat(mlest)
    A = mlest.paramVals.A;
    B = mlest.paramVals.B;
    C = A*B';
end

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.

Common rank of A and B, specified by a positive integer in the interval [1,numDims − 1].

Tip

Infer r by conducting a Johansen test using jcitest.

Data Types: double

Null hypothesis constraint type, specified as a constraint name in the table, or a string vector or cell vector of character vectors of such values.

Constraint NameDescription
"ACon"Test linear constraints on A.
"AVec"Test specific vectors in A.
"BVec"Test linear constraints on B.
"BVec"Test specific vectors in B.

jcontest conducts a separate test for each value in test.

Data Types: string | char | cell

Null hypothesis constraint values, specified as a value for the corresponding constraint type test, or a cell vector of such values, in this table.

For constraints on B, the number of rows in each matrix numDims1 is one of the following, where numDims is the number of dimensions in the input data:

  • numDims + 1 when the Model name-value argument is "H*" or "H1*" and constraints include the restricted deterministic term in the model

  • numDims otherwise

Constraint Type testConstraint Value ConsDescription
"ACon"R, a numDims-by-numCons numeric matrixSpecifies numCons constraints on A given by R'A = 0, where numConsnumDimsr.
"AVec"numDims1-by-numCons numeric matrixSpecifies numCons equality constraints imposed on error-correction speed vectors in A, where numConsr.
"BCon"R, numDims-by-numCons numeric matrix Specifies numCons constraints on B given by R'B = 0, where numConsnumDimsr.
"BVec"numDims1-by-numCons numeric matrixSpecifies numCons equality constraints imposed on numCons of the cointegrating vectors in B, where numConsr.

Tip

When you construct constraint values, use the following interpretations of the rows and columns of A and B.

  • Row i of A contains the adjustment speeds of variable yi,t to disequilibrium in each of the r cointegrating relations.

  • Column j of A contains the adjustment speeds of each of the numDims variables to disequillibrium in cointegrating relation j.

  • Row i of B contains the coefficients of variable yi,t in each of the r cointegrating relations.

  • Column j of B contains the coefficients of each of the numDims variables in cointegrating relation j.

jcontest conducts a separate test for each cell in Cons.

Data Types: string | char | cell

Note

jcontest 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: jcontest(Tbl,r,test,Cons,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.

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

jcontest 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

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.

jcontest 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

Variables in Tbl for which jcontest 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 jcontest 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.

  • If you specify the vector y and any value is a row vector, all outputs are row vectors.

  • 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 logical scalar or vector with length equal to the number of tests. jcontest returns h when you supply the input Y.

  • Values of 1 indicate rejection of the null hypothesis that the specified constraints test and Cons hold in favor of the alternative hypothesis that they do not hold.

  • Values of 0 indicate failure to reject the null hypothesis that the constraints hold.

Test statistic p-values, returned as a numeric scalar or vector with length equal to the number of tests. jcontest returns pValue when you supply the input Y.

The p-values are right-tail probabilities.

Test statistics, returned as a numeric scalar or vector with length equal to the number of tests. jcontest returns stat when you supply the input Y.

The test statistics are likelihood ratios determined by the test.

Critical values, returned as a numeric scalar or vector with length equal to the number of tests. jcontest returns cValue when you supply the input Y.

The asymptotic distributions of the test statistics are chi-square, with the degree-of-freedom parameter determined by the test. The critical value of the test statistics are for a right-tail probability.

Test summary, returned as a table with variables for the outputs h, pValue, stat, and cValue, and with a row for each test. jcontest returns StatTbl when you supply the input Tbl.

StatTbl contains variables for the test settings specified by Lags, Alpha, Model, and Test.

Maximum likelihood estimates associated with the constrained VEC(q) model of yt, return as a structure array with the number of records equal to the number of tests.

Each element of mles has the fields in this table. You can access a field using dot notation, for example, mles(3).paramVals contains a structure of the parameter estimates.

FieldDescription
paramNames

Cell vector of parameter names, of the form:

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

Elements depend on the values of Lags and Model.

paramValsStructure 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.
EstCovEstimated covariance Q of the innovations process εt.
rLL Restricted loglikelihood of yt under the null hypothesis.
uLLUnrestricted loglikelihood of yt under the alternative hypothesis.
dofDegrees of freedom of the asymptotic chi-square distribution of the test statistic.

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

Φ(L)(1L)yt=A(Byt1+c0+d0t)+c1+d1t+εt=c+dt+Cyt1+εt,

where

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

  • Φ(L)=IΦ1Φ2...Φ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.

Tips

  • jcontest compares finite-sample statistics to asymptotic critical values, and tests can show significant size distortions for small samples [2]. Larger samples lead to more reliable inferences.

  • To convert VEC(q) model parameters in the mles output to vector autoregressive (VAR) model parameters, use the vec2var function.

Algorithms

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

  • The parameters A and B in the reduced-rank VEC(q) model are not identifiable. jcontest identifies B using the methods in [3], depending on the test.

  • Tests on B answer questions about the space of cointegrating relations. Tests on A answer questions about common driving forces in the system. For example, an all-zero row in A indicates a variable that is weakly exogenous with respect to the coefficients in B. Such a variable can affect other variables, but it does not adjust to disequilibrium in the cointegrating relations. Similarly, a standard unit vector column in A indicates a variable that is exclusively adjusting to disequilibrium in a particular cointegrating relation.

  • Constraint matrices R satisfying RA = 0 or RB = 0 are equivalent to A = Hφ or B = Hφ, where H is the orthogonal complement of R (null(R')) and φ is a vector of free parameters.

References

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

[2] Haug, A. “Testing Linear Restrictions on Cointegrating Vectors: Sizes and Powers of Wald Tests in Finite Samples.” Econometric Theory. v. 18, 2002, pp. 505–524.

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

[4] Juselius, K. The Cointegrated VAR Model. Oxford: Oxford University Press, 2006.

[5] Morin, N. "Likelihood Ratio Tests on Cointegrating Vectors, Disequilibrium Adjustment Vectors, and their Orthogonal Complements." European Journal of Pure and Applied Mathematics. v. 3, 2010, pp. 541–571.

Version History

Introduced in R2011a