# gctest

Block-wise Granger causality and block exogeneity tests

## Syntax

## Description

The `gctest`

function conducts a block-wise Granger causality test by accepting sets of time series data representing the "cause" and "effect" multivariate response variables in the test. `gctest`

supports the inclusion of optional endogenous conditioning variables in the model for the test.

To conduct the leave-one-out, exclude-all, and block-wise Granger causality tests on the response variables of a fully specified VAR model (represented by a `varm`

model object), see `gctest`

.

returns the test decision from conducting a block-wise Granger causality test for
assessing whether a set of time series variables in the first input numeric array
Granger-causes a distinct set of the time series variables in the second input numeric
array. The `h`

= gctest(`Y1`

,`Y2`

)`gctest`

function conducts tests in the vector autoregression (VAR)
framework and treats the input arrays as response (endogenous) variables during
testing.

conducts a 1-step Granger causality test for the first two input arrays, conditioned on a
distinct set of time series variables in the third input numeric array. The variable
`h`

= gctest(`Y1`

,`Y2`

,`Y3`

)`Y3`

is endogenous in the underlying VAR model, but
`gctest`

does not consider it a "cause" or an "effect" in the
test.

returns a table containing the test results from conducting a block-wise Granger causality test for
assessing whether all variables, except the last variable, in the input table or timetable
Granger-cause the last variable.`StatTbl`

= gctest(`Tbl`

)* (since R2023a)*

To select different Granger-cause or effect variables for the test, use the
`CauseVariables`

or `EffectVariables`

name-value
argument.

`___ = gctest(___,`

specifies options using one or more name-value arguments. For example,
`Name,Value`

)`gctest(Y1,Y2,Test="f",NumLags=2)`

specifies conducting an
*F* test that compares the residual sum of squares between restricted
and unrestricted VAR(2) models for all response variables.
`gctest`

returns the output argument combination for the
corresponding input arguments.

## Examples

### Conduct Granger Causality Test Using Data in Numeric Arrays

Conduct a Granger causality test to assess whether the M1 money supply has an impact on the predictive distribution of the consumer price index (CPI). Supply data as numeric vectors.

Load the US macroeconomic data set `Data_USEconModel.mat`

.

`load Data_USEconModel`

The data set includes the MATLAB® timetable `DataTimeTable`

, which contains 14 variables measured from Q1 1947 through Q1 2009. `M1SL`

is the table variable containing the M1 money supply, and `CPIAUCSL`

is the table variable containing the CPI. For more details, enter `Description`

at the command line.

Visually assess whether the series are stationary by plotting them in the same figure.

figure; yyaxis left plot(DataTimeTable.Time,DataTimeTable.CPIAUCSL) ylabel("CPI"); yyaxis right plot(DataTimeTable.Time,DataTimeTable.M1SL); ylabel("Money Supply");

Both series are nonstationary.

Stabilize the series by converting them to rates.

m1slrate = price2ret(DataTimeTable.M1SL); inflation = price2ret(DataTimeTable.CPIAUCSL);

Assume that a VAR(1) model is an appropriate multivariate model for the rates. Conduct a default Granger causality test to assess whether the M1 money supply rate Granger-causes the inflation rate.

h = gctest(m1slrate,inflation)

`h = `*logical*
1

The test decision `h`

is `1`

, which indicates the rejection of the null hypothesis that the M1 money supply rate does not Granger-cause inflation.

### Test Series for Feedback

Time series undergo feedback when they Granger-cause each other. Assess whether the US inflation and M1 money supply rates undergo feedback.

Load the US macroeconomic data set `Data_USEconModel.mat`

. Convert the price series to returns.

```
load Data_USEconModel
inflation = price2ret(DataTimeTable.CPIAUCSL);
m1slrate = price2ret(DataTimeTable.M1SL);
```

Conduct a Granger causality test to assess whether the inflation rate Granger-causes the M1 money supply rate. Assume that an underlying VAR(1) model is appropriate for the two series. The default level of significance $\alpha $ for the test is 0.05. Because this example conducts two tests, decrease $\alpha \text{\hspace{0.17em}}$ by half for each test to achieve a family-wise level of significance of 0.05.

hIRgcM1 = gctest(inflation,m1slrate,Alpha=0.025)

`hIRgcM1 = `*logical*
1

The test decision `hIRgcM1`

= `1`

indicates rejection of the null hypothesis of noncausality. There is enough evidence to suggest that the inflation rate Granger-causes the M1 money supply rate at 0.025 level of significance.

Conduct another Granger causality test to assess whether the M1 money supply rate Granger-causes the inflation rate.

hM1gcIR = gctest(m1slrate,inflation,Alpha=0.025)

`hM1gcIR = `*logical*
0

The test decision `hM1gcIR`

= `0`

indicates that the null hypothesis of noncausality should not be rejected. There is not enough evidence to suggest that the M1 money supply rate Granger-causes the inflation rate at 0.025 level of significance.

Because not enough evidence exists to suggest that the inflation rate Granger-causes the M1 money supply rate, the two series do not undergo feedback.

### Conduct 1-Step Granger Causality Test Conditioned on Variable

Assess whether the US gross domestic product (GDP) Granger-causes CPI conditioned on the M1 money supply.

Load the US macroeconomic data set `Data_USEconModel.mat`

.

`load Data_USEconModel`

The variables `GDP`

and `GDPDEF`

of `DataTimeTable`

are the US GDP and its deflator with respect to year 2000 dollars, respectively. Both series are nonstationary.

Convert the M1 money supply and CPI to rates. Convert the US GDP to the real GDP rate.

m1slrate = price2ret(DataTimeTable.M1SL); inflation = price2ret(DataTimeTable.CPIAUCSL); rgdprate = price2ret(DataTimeTable.GDP./DataTimeTable.GDPDEF);

Assume that a VAR(1) model is an appropriate multivariate model for the rates. Conduct a Granger causality test to assess whether the real GDP rate has an impact on the predictive distribution of the inflation rate, conditioned on the M1 money supply. The inclusion of a conditional variable forces `gctest`

to conduct a 1-step Granger causality test.

h = gctest(rgdprate,inflation,m1slrate)

`h = `*logical*
0

The test decision `h`

is `0`

, which indicates failure to reject the null hypothesis that the real GDP rate is not a 1-step Granger-cause of inflation when you account for the M1 money supply rate.

`gctest`

includes the M1 money supply rate as a response variable in the underlying VAR(1) model, but it does not include the M1 money supply in the computation of the test statistics.

Conduct the test again, but without conditioning on the M1 money supply rate.

h = gctest(rgdprate,inflation)

`h = `*logical*
0

The test result is the same as before, suggesting that the real GDP rate does not Granger-cause inflation at all periods in a forecast horizon and regardless of whether you account for the M1 money supply rate in the underlying VAR(1) model.

### Adjust Number of Lags for Underlying VAR Model

By default, `gctest`

assumes an underlying VAR(1) model for all specified response variables. However, a VAR(1) model might be an inappropriate representation of the data. For example, the model might not capture all the serial correlation present in the variables.

To specify a more complex underlying VAR model, you can increase the number of lags by specifying the `NumLags`

name-value argument of `gctest`

.

Consider the Granger causality tests conducted in Conduct 1-Step Granger Causality Test Conditioned on Variable. Load the US macroeconomic data set `Data_USEconModel.mat`

. Convert the M1 money supply and CPI to rates. Convert the US GDP to the real GDP rate.

```
load Data_USEconModel
m1slrate = price2ret(DataTimeTable.M1SL);
inflation = price2ret(DataTimeTable.CPIAUCSL);
rgdprate = price2ret(DataTimeTable.GDP./DataTimeTable.GDPDEF);
```

Preprocess the data by removing all missing observations (indicated by `NaN`

).

```
idx = sum(isnan([m1slrate inflation rgdprate]),2) < 1;
m1slrate = m1slrate(idx);
inflation = inflation(idx);
rgdprate = rgdprate(idx);
T = numel(m1slrate); % Total sample size
```

Fit VAR models, with lags ranging from 1 to 4, to the real GDP and inflation rate series. Initialize each fit by specifying the first four observations. Store the Akaike information criteria (AIC) of the fits.

numseries = 2; numlags = (1:4)'; nummdls = numel(numlags); % Partition time base. maxp = max(numlags); % Maximum number of required presample responses idxpre = 1:maxp; idxest = (maxp + 1):T; % Preallocation EstMdl(1:nummdls) = varm(numseries,0); aic = zeros(nummdls,1); % Fit VAR models to data. Y0 = [rgdprate(idxpre) inflation(idxpre)]; % Presample Y = [rgdprate(idxest) inflation(idxest)]; % Estimation sample for j = 1:numel(numlags) Mdl = varm(numseries,numlags(j)); Mdl.SeriesNames = ["rGDP" "Inflation"]; EstMdl(j) = estimate(Mdl,Y,Y0=Y0); results = summarize(EstMdl(j)); aic(j) = results.AIC; end p = numlags(aic == min(aic))

p = 3

A VAR(3) model yields the best fit.

Assess whether the real GDP rate Granger-causes inflation. `gctest`

removes $\mathit{p}$ observations from the beginning of the input data to initialize the underlying VAR($\mathit{p}$) model for estimation. Prepend only the required $\mathit{p}$ = 3 presample observations to the estimation sample. Specify the concatenated series as input data. Return the $\mathit{p}$-value of the test.

rgdprate3 = [Y0((end - p + 1):end,1); Y(:,1)]; inflation3 = [Y0((end - p + 1):end,2); Y(:,2)]; [h,pvalue] = gctest(rgdprate3,inflation3,NumLags=p)

`h = `*logical*
1

pvalue = 7.7741e-04

The $\mathit{p}$-value is approximately `0.0008`

, indicating the existence of strong evidence to reject the null hypothesis of noncausality, that is, that the three real GDP rate lags in the inflation rate equation are jointly zero. Given the VAR(3) model, there is enough evidence to suggest that the real GDP rate Granger-causes at least one future value of the inflation rate.

Alternatively, you can conduct the same test by passing the estimated VAR(3) model (represented by the `varm`

model object in `EstMdl(3)`

), to the object function `gctest`

. Specify a block-wise test and the "cause" and "effect" series names.

h = gctest(EstMdl(3),Type="block-wise", ... Cause="rGDP",Effect="Inflation")

H0 Decision Distribution Statistic PValue CriticalValue ____________________________________________ ___________ ____________ _________ __________ _____________ "Exclude lagged rGDP in Inflation equations" "Reject H0" "Chi2(3)" 16.799 0.00077741 7.8147

`h = `*logical*
1

### Address Integrated Series During Testing

If you are testing integrated series for Granger causality, then the Wald test statistic does not follow a ${\chi}^{2}$ or $\mathit{F}$ distribution, and test results can be unreliable. However, you can implement the Granger causality test in [5] by specifying the maximum integration order among all the variables in the system using the `Integration`

name-value argument.

Consider the Granger causality tests conducted in Conduct 1-Step Granger Causality Test Conditioned on Variable. Load the US macroeconomic data set `Data_USEconModel.mat`

and take the log of real GDP and CPI.

```
load Data_USEconModel
cpi = log(DataTimeTable.CPIAUCSL);
rgdp = log(DataTimeTable.GDP./DataTimeTable.GDPDEF);
```

Assess whether the real GDP Granger-causes CPI. Assume the series are $\mathit{I}\left(1\right)$, or order-1 integrated. Also, specify an underlying VAR(3) model and the $\mathit{F}$ test. Return the test statistic and $\mathit{p}$-value.

[h,pvalue,stat] = gctest(rgdp,cpi,NumLags=3, ... Integration=1,Test="f")

`h = `*logical*
1

pvalue = 0.0031

stat = 4.7557

The $\mathit{p}$-value = `0.0031`

, indicating the existence of strong evidence to reject the null hypothesis of noncausality, that is, that the three real GDP lags in the CPI equation are jointly zero. Given the VAR(3) model, there is enough evidence to suggest that real GDP Granger-causes at least one future value of the CPI.

In this case, the test augments the VAR(3) model with an additional lag. In other words, the model is a VAR(4) model. However, `gctest`

tests only whether the first three lags are 0.

### Test for Block Exogeneity Using Data in Timetable

*Since R2023a*

Time series are *block exogenous* if they do not Granger-cause any other variables in a multivariate system. Test whether the effective federal funds rate is block exogenous with respect to the real GDP, personal consumption expenditures, and inflation rates. Provide data in a timetable.

Load the US macroeconomic data set `Data_USEconModel.mat`

. Convert the price series to returns; specify durations between sampling times relative to years.

load Data_USEconModel DataTimeTable.RGDP = DataTimeTable.GDP./DataTimeTable.GDPDEF; EffectVariables = ["CPIAUCSL" "RGDP" "PCEC"]; DTTRet = price2ret(DataTimeTable,DataVariables=EffectVariables, ... Units="years");

Test whether the federal funds rate is nonstationary by conducting an augmented Dickey-Fuller test. Specify that the alternative model has a drift term and an $\mathit{F}$ test.

StatTblADFTest = adftest(DataTimeTable,DataVariable="FEDFUNDS",Model="ard")

`StatTblADFTest=`*1×8 table*
h pValue stat cValue Lags Alpha Model Test
_____ ________ _______ _______ ____ _____ _______ ______
Test 1 false 0.071419 -2.7257 -2.8751 0 0.05 {'ARD'} {'T1'}

The test decision `h`

= `0`

indicates that the null hypothesis that the series has a unit root should not be rejected, at 0.05 significance level.

To stabilize the federal funds rate series, apply the first difference to it.

DTTRet.DFEDFUNDS = diff(DataTimeTable.FEDFUNDS);

Assume a 4-D VAR(3) model for the four series. Assess whether the federal funds rate is block exogenous with respect to the real GDP, personal consumption expenditures, and inflation rates. Supply the data in the timetable `DTTRet`

, and conduct an $\mathit{F}$-based Wald test.

StatTblGCTEST = gctest(DTTRet,CauseVariables="DFEDFUNDS", ... EffectVariables=EffectVariables,NumLags=2,Test="f")

`StatTblGCTEST=`*1×6 table*
h pValue stat cValue alpha test
_____ __________ ______ ______ _____ ____
Test 1 true 3.9311e-10 10.465 2.1426 0.05 "f"

The test decision `hgc`

= `1`

indicates that the null hypothesis that the federal funds rate is block exogenous should be rejected. This result suggests that the federal funds rate Granger-causes at least one of the other variables in the system.

To determine which variables the federal funds rate Granger-causes, you can run a leave-one-out test. For more details, see `gctest`

function of the VAR model object `varm`

.

## Input Arguments

`Y1`

— Data for response variables representing Granger-causes

numeric vector | numeric matrix

Data for the response variables representing the Granger-causes in the test, specified as a `numobs1`

-by-1 numeric vector or a `numobs1`

-by-`numseries1`

numeric matrix. `numobs1`

is the number of observations and `numseries1`

is the number of time series variables.

`Y1`

must have enough rows to initialize and estimate the
underlying VAR model. `gctest`

uses the first
`NumLags`

observations to initialize the model for
estimation.

Columns correspond to distinct time series variables.

**Data Types: **`double`

| `single`

`Y2`

— Data for response variables affected by Granger-causes

numeric vector | numeric matrix

Data for response variables affected by the Granger-causes in the test, specified as a `numobs2`

-by-1 numeric vector or a `numobs2`

-by-`numseries2`

numeric matrix. `numobs2`

is the number of observations in the data and `numseries2`

is the number of time series variables.

`Y2`

must have enough rows to initialize and estimate the
underlying VAR model. `gctest`

uses the first
`NumLags`

observations to initialize the model for
estimation.

Columns correspond to distinct time series variables.

**Data Types: **`double`

| `single`

`Y3`

— Data for conditioning response variables

numeric vector | numeric matrix

Data for conditioning response variables, specified as a `numobs3`

-by-1 numeric vector or a `numobs3`

-by-`numseries3`

numeric matrix. `numobs3`

is the number of observations in the data and `numseries3`

is the number of time series variables.

`Y3`

must have enough rows to initialize and estimate the
underlying VAR model. `gctest`

uses the first
`NumLags`

observations to initialize the model for
estimation.

Columns correspond to distinct time series variables.

If you specify `Y3`

, then `Y1`

,
`Y2`

, and `Y3`

represent the response variables in
the underlying VAR model. `gctest`

assesses whether
`Y1`

is a 1-step Granger-cause of `Y2`

, given the
presence of `Y3`

.

**Data Types: **`double`

| `single`

`Tbl`

— Time series data

table | timetable

*Since R2023a*

Time series data for the Granger-cause
*y*_{1,t}, effect
*y*_{2,t}, conditioning
*y*_{3,t}, and predictor
*x _{t}* variables of the test, specified as a
table or timetable with

`numseries`

variables and
`numobs`

rows. Row *t* contains the observation in time *t*, and
the last row contains the latest observation. `Tbl`

must have enough
rows to initialize and estimate the underlying VAR model.
`gctest`

uses the first `NumLags`

observations as a presample to initialize the model for estimation.

You can optionally select Granger-cause, effects, conditioning, or predictor
variables by using the `CauseVariables`

,
`EffectVariables`

, `ConditionVariables`

, or
`PredictorVariables`

name-value argument, respectively.

### 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: **`gctest(Y1,Y2,Alpha=0.10,NumLags=2)`

specifies a
`0.10`

significance level for the test and uses an underlying VAR(2)
model for all response variables.

`NumLags`

— Number of lagged responses

`1`

(default) | nonnegative integer

Number of lagged responses to include in the underlying VAR model for all response
variables, specified as a nonnegative integer. The resulting underlying model is a
VAR(`NumLags`

) model.

**Example: **`NumLags=2`

**Data Types: **`double`

| `single`

`Integration`

— Maximum order of integration

`0`

(default) | nonnegative integer

Maximum order of integration among all response variables, specified as a nonnegative integer.

To address integration, `gctest`

augments the VAR(`NumLags`

) model by adding additional lagged responses beyond `NumLags`

to all equations during estimation. For more details, see [5] and [3].

**Example: **`Integration=1`

**Data Types: **`double`

| `single`

`Constant`

— Flag indicating inclusion of model intercepts

`true`

(default) | `false`

Flag indicating the inclusion of model intercepts (constants) in the underlying VAR model, specified as a value in this table.

Value | Description |
---|---|

`true` | All equations in the underlying VAR model have an intercept.
`gctest` estimates the intercepts with all other
estimable parameters. |

`false` | All underlying VAR model equations do not have an intercept.
`gctest` sets all intercepts to 0. |

**Example: **`Constant=false`

**Data Types: **`logical`

`Trend`

— Flag indicating inclusion of linear time trends

`false`

(default) | `true`

Flag indicating the inclusion of linear time trends in the underlying VAR model, specified as a value in this table.

Value | Description |
---|---|

`true` | All equations in the underlying VAR model have a linear time trend.
`gctest` estimates the linear time trend
coefficients with all other estimable parameters. |

`false` | All underlying VAR model equations do not have a linear time trend. |

**Example: **`Trend=false`

**Data Types: **`logical`

`X`

— Predictor data for exogenous predictor variables *x*_{t}

numeric matrix

_{t}

Predictor data for exogenous predictor variables
*x _{t}* in the underlying VAR model,
specified as a numeric matrix containing

`numpreds`

columns.
`numpreds`

is the number of predictor variables.Row *t* contains the observation in time *t*,
and the last row contains the latest observation. `gctest`

does not use the regression component in the presample period. `X`

must have at least as many observations as the number of observations used by
`gctest`

after the presample period. Specifically,
`X`

must have at least `numobs`

–
`Mdl.P`

observations, where `numobs`

=
`min([numobs1 numobs2 numobs3])`

. If you supply more rows than
necessary, `gctest`

uses the latest observations only.

Columns correspond to individual predictor variables.
`gctest`

treats predictors as exogenous. All predictor
variables are present in the regression component of each response equation.

By default, `gctest`

excludes a regression component from
all equations.

**Example: **`X=x`

applies the numeric vector of data
`x`

to the 1-D regression component of each response equation of in
the underlying VAR model.

**Data Types: **`double`

`Alpha`

— Significance level

`0.05`

(default) | numeric scalar in (0,1)

Significance level for the test, specified as a numeric scalar in (0,1).

**Example: **`Alpha=0.1`

**Data Types: **`double`

| `single`

`Test`

— Test statistic distribution under the null hypothesis

`"chi-square"`

(default) | `"f"`

Test statistic distribution under the null hypothesis, specified as a value in this table.

Value | Description |
---|---|

`"chi-square"` | `gctest` derives outputs from conducting a χ^{2} test. |

`"f"` | `gctest` derives outputs from conducting an F test. |

For test statistic forms, see [4].

**Example: **`Test="f"`

**Data Types: **`char`

| `string`

`CauseVariables`

— Variables to select from `Tbl`

to treat as Granger-cause variables *y*_{1,t}

string vector | cell vector of character vectors | vector of integers | logical vector

*Since R2023a*

Variables to select from `Tbl`

to treat as the Granger-cause
variables *y*_{1,t}, specified
as one of the following data types:

String vector or cell vector of character vectors of variable names in

`Tbl.Properties.VariableNames`

A vector of unique indices (positive integers) of variables to select from

`Tbl.Properties.VariableNames`

A logical vector, where

`CauseVariables(`

selects variable) = true`j`

from`j`

`Tbl.Properties.VariableNames`

The selected variables must be numeric vectors and cannot
contain missing values (`NaN`

s). The variables in
`CauseVariables`

, `EffectVariables`

, and
`ConditionVariables`

, and `PredictorVariables`

must be
mutually exclusive.

The default specifies all variables in `Tbl`

except for the
variable specified by the `EffectVariables`

name-value
argument.

**Example: **`CauseVariables=["GDP" "CPI"]`

**Example: **`CauseVariables=[true false true false]`

or
`CauseVariable=[1 3]`

selects the first and third table variables
as the Granger-cause variables.

**Data Types: **`double`

| `logical`

| `char`

| `cell`

| `string`

`EffectVariables`

— Variables to select from `Tbl`

to treat as effect variables *y*_{2,t}

string vector | cell vector of character vectors | vector of integers | logical vector

*Since R2023a*

Variables to select from `Tbl`

to treat as the effect variables
*y*_{2,t}, specified as one
of the following data types:

String vector or cell vector of character vectors of variable names in

`Tbl.Properties.VariableNames`

A vector of unique indices (positive integers) of variables to select from

`Tbl.Properties.VariableNames`

A logical vector, where

`EffectVariables(`

selects variable) = true`j`

from`j`

`Tbl.Properties.VariableNames`

The selected variables must be numeric vectors and cannot
contain missing values (`NaN`

s). The variables in
`CauseVariables`

, `EffectVariables`

, and
`ConditionVariables`

, and `PredictorVariables`

must be
mutually exclusive.

The default specifies the last variable in `Tbl`

,
`Tbl.Properties.VariableNames(end)`

.

**Example: **`EffectVariables="COE"`

**Example: **`EffectVariables=[false true false false]`

or
`EffectVariable=2`

selects the second variable as the effect
variable.

**Data Types: **`double`

| `logical`

| `char`

| `cell`

| `string`

`ConditionVariables`

— Variables to select from `Tbl`

to treat as conditioning variables *y*_{3,t}

string vector | cell vector of character vectors | vector of integers | logical vector

*Since R2023a*

Variables to select from `Tbl`

to treat as the conditioning
variables *y*_{3,t}, specified
as one of the following data types:

String vector or cell vector of character vectors of variable names in

`Tbl.Properties.VariableNames`

A vector of unique indices (positive integers) of variables to select from

`Tbl.Properties.VariableNames`

A logical vector, where

`ConditionVariables(`

selects variable) = true`j`

from`j`

`Tbl.Properties.VariableNames`

The selected variables must be numeric vectors and cannot
contain missing values (`NaN`

s). The variables in
`CauseVariables`

, `EffectVariables`

, and
`ConditionVariables`

, and `PredictorVariables`

must be
mutually exclusive.

If you specify `ConditionVariables`

, the following conditions apply:

You must specify

`CauseVariables`

and`EffectVariables`

.The

`CauseVariables`

,`EffectVariables`

, and`ConditionVariables`

represent the response variables in the underlying VAR model.`gctest`

assesses whether`CauseVariables`

is a 1-step Granger-cause of`EffectVariables`

, given the presence of`ConditionVariables`

.

By default, `gctest`

does not apply conditioning
variables.

**Example: **`ConditionVariables=["GDP" "CPI"]`

**Example: **`ConditionVariables=[true true true false]`

or
`ConditionVariable=4`

selects the fourth table variable as the
conditioning variable.

**Data Types: **`double`

| `logical`

| `char`

| `cell`

| `string`

`PredictorVariables`

— Variables to select from `Tbl`

to treat as exogenous predictor variables *x*_{t}

string vector | cell vector of character vectors | vector of integers | logical vector

_{t}

*Since R2023b*

Variables to select from `Tbl`

to treat as exogenous predictor
variables *x _{t}* in the underlying VAR model,
specified as one of the following data types:

String vector or cell vector of character vectors of variable names in

`Tbl.Properties.VariableNames`

`Tbl.Properties.VariableNames`

A logical vector, where

`PredictorVariables(`

selects variable) = true`j`

from`j`

`Tbl.Properties.VariableNames`

The selected variables must be numeric vectors and cannot
contain missing values (`NaN`

s). The variables in
`CauseVariables`

, `EffectVariables`

, and
`ConditionVariables`

, and `PredictorVariables`

must be
mutually exclusive.
`gctest`

does not apply the regression component in the
presample period. All selected variables are present in the regression component of
each response equation.

If you specify `PredictorVariables`

, you must also specify
`CauseVariables`

and `EffectVariables`

.

By default, `gctest`

excludes a regression component from
all equations.

**Example: **`PredictorVariables=["M1SL" "TB3MS" "UNRATE"]`

selects
the variables `M1SL`

, `TB3MS`

, and
`UNRATE`

.

**Example: **`PredictorVariables=[true false true false]`

or
`=[1 3]`

selects the first and third table variables to supply the
predictor data.

**Data Types: **`double`

| `single`

| `logical`

| `char`

| `cell`

| `string`

**Note**

`gctest`

assumes you synchronize the input data sets and
arrange those inputs by increasing sampling time, regardless of data type.

## Output Arguments

`h`

— Block-wise Granger causality test decision

logical scalar

Block-wise Granger causality test
decision, returned as a logical scalar. `gctest`

returns
`h`

when you supply data as numeric arrays.

`h`

=`1`

indicates rejection of*H*_{0}.If you specify the conditioning response data

`Y3`

, then sufficient evidence exists to suggest that the response variables represented in`Y1`

are 1-step Granger-causes of the response variables represented in`Y2`

, conditioned on the response variables represented in`Y3`

.Otherwise, sufficient evidence exists to suggest that the variables in

`Y1`

are*h*-step Granger-causes of the variables in`Y2`

for some*h*≥ 0. In other words,`Y1`

is block endogenous with respect to`Y2`

.

`h`

=`0`

indicates failure to reject*H*_{0}.If you specify

`Y3`

, then the variables in`Y1`

are not 1-step Granger-causes of the variables in`Y2`

, conditioned on`Y3`

.Otherwise,

`Y1`

does not Granger-cause`Y2`

. In other words, there is not enough evidence to reject block exogeneity of`Y1`

with respect to`Y2`

.

`pvalue`

— *p*-value

numeric scalar

*p*-value, returned as a numeric scalar.
`gctest`

returns `pValue`

when you supply
data as numeric arrays.

`stat`

— Test statistic

numeric scalar

Test statistic, returned as a numeric scalar. `gctest`

returns `stat`

when you supply data as numeric arrays.

`cvalue`

— Critical value

numeric scalar

Critical value for the significance level `Alpha`

, returned as a
numeric scalar. `gctest`

returns `cValue`

when
you supply data as numeric arrays.

`StatTbl`

— Test summary

table

Test summary, returned as a table with variables for output rejection decisions
`h`

, *p*-values `pValue`

, test
statistics `stat`

, and critical values `cValue`

.
`gctest`

returns `StatTbl`

when you supply
the input `Tbl`

.

`StatTbl`

also contains
variables for the test settings specified by `Alpha`

and
`Test`

.* (since R2023b)*

## More About

### Granger Causality Test

The *Granger causality test* is a statistical hypothesis test that assesses whether past and present values of a set of *m*_{1} = `numseries1`

time series variables *y*_{1,t}, called the "cause" variables, affect the predictive distribution of a distinct set of *m*_{2} = `numseries2`

time series variables *y*_{2,t}, called the "effect" variables. The impact is a reduction in forecast mean squared error (MSE) of *y*_{2,t}. If past values of *y*_{1,t} affect *y*_{2,t + h}, then *y*_{1,t} is an *h*-step *Granger-cause* of *y*_{2,t}. In other words, *y*_{1,t}
*Granger-causes*
*y*_{2,t} if *y*_{1,t} is an *h*-step *Granger-cause* of *y*_{2,t} for all *h* ≥ 1.

Consider a stationary VAR(*p*) model for [*y*_{1,t}
*y*_{2,t}]:

$$\left[\begin{array}{c}{y}_{1,t}\\ {y}_{2,t}\end{array}\right]=c+\delta t+\beta {x}_{t}+\left[\begin{array}{cc}{\Phi}_{11,1}& {\Phi}_{12,1}\\ {\Phi}_{21,1}& {\Phi}_{22,1}\end{array}\right]\left[\begin{array}{c}{y}_{1,t-1}\\ {y}_{2,t-1}\end{array}\right]+\mathrm{...}+\left[\begin{array}{cc}{\Phi}_{11,p}& {\Phi}_{12,p}\\ {\Phi}_{21,p}& {\Phi}_{22,p}\end{array}\right]\left[\begin{array}{c}{y}_{1,t-p}\\ {y}_{2,t-p}\end{array}\right]+\left[\begin{array}{c}{\epsilon}_{1,t}\\ {\epsilon}_{2,t}\end{array}\right].$$

Assume the following conditions:

Future values cannot inform past values.

*y*_{1,t}uniquely informs*y*_{2,t}(no other variable has the information to inform*y*_{2,t}).

If Φ_{21,1} = … = Φ_{21,p} = 0_{m1,m2}, then *y*_{1,t} is not the *block-wise* Granger cause of *y*_{2,t + h}, for all *h* ≥ 1 and where 0_{m2,m1} is an *m*_{2}-by-*m*_{1} matrix of zeros. Also, *y*_{1,t} is block exogenous with respect to *y*_{2,t}. Consequently, the block-wise Granger causality test hypotheses are:

$$\begin{array}{l}{H}_{0}:{\Phi}_{21,1}=\mathrm{...}={\Phi}_{21,p}={0}_{{m}_{2},{m}_{1}}\\ {H}_{1}:\exists j\in \{1,\mathrm{...},p\}\ni {\Phi}_{21,j}\ne {0}_{{m}_{2},{m}_{1}}.\end{array}$$

*H*_{1} implies that at least one *h* ≥ 1 exists such that *y*_{1,t} is an *h*-step *Granger-cause* of *y*_{2,t}.

`gctest`

conducts *χ*^{2}-based or *F*-based Wald tests (see `'Test'`

). For test statistic forms, see [4].

Distinct *conditioning* endogenous variables *y*_{3,t} can be included in the system (see `Y3`

). In this case, the VAR(*p*) model is:

$$\left[\begin{array}{c}{y}_{1,t}\\ \begin{array}{l}{y}_{2,t}\\ {y}_{3,t}\end{array}\end{array}\right]=c+\delta t+\beta {x}_{t}+\left[\begin{array}{ccc}{\Phi}_{11,1}& {\Phi}_{12,1}& {\Phi}_{13,1}\\ {\Phi}_{21,1}& {\Phi}_{22,1}& {\Phi}_{23,1}\\ {\Phi}_{31,1}& {\Phi}_{32,1}& {\Phi}_{33,1}\end{array}\right]\left[\begin{array}{c}{y}_{1,t-1}\\ \begin{array}{l}{y}_{2,t-1}\\ {y}_{3,t-1}\end{array}\end{array}\right]+\mathrm{...}+\left[\begin{array}{ccc}{\Phi}_{11,p}& {\Phi}_{12,p}& {\Phi}_{13,p}\\ {\Phi}_{21,p}& {\Phi}_{22,p}& {\Phi}_{23,p}\\ {\Phi}_{31,p}& {\Phi}_{32,p}& {\Phi}_{33,p}\end{array}\right]\left[\begin{array}{c}{y}_{1,t-p}\\ \begin{array}{l}{y}_{2,t-p}\\ {y}_{3,t-p}\end{array}\end{array}\right]+\left[\begin{array}{c}{\epsilon}_{1,t}\\ \begin{array}{l}{\epsilon}_{2,t}\\ {\epsilon}_{3,t}\end{array}\end{array}\right].$$

`gctest`

does not test the parameters associated with the conditioning variables. The test assesses only whether *y*_{1,t} is an 1-step Granger-cause of *y*_{2,t}.

### Vector Autoregression Model

A *vector autoregression (VAR) model* is a
stationary multivariate time series model consisting of a system of *m*
equations of *m* distinct response variables as linear functions of lagged
responses and other terms.

A VAR(*p*) model in *difference-equation notation*
and in *reduced form* is

$${y}_{t}=c+{\Phi}_{1}{y}_{t-1}+{\Phi}_{2}{y}_{t-2}+\mathrm{...}+{\Phi}_{p}{y}_{t-p}+\beta {x}_{t}+\delta t+{\epsilon}_{t}.$$

*y*is a_{t}`numseries`

-by-1 vector of values corresponding to`numseries`

response variables at time*t*, where*t*= 1,...,*T*. The structural coefficient is the identity matrix.*c*is a`numseries`

-by-1 vector of constants.Φ

_{j}is a`numseries`

-by-`numseries`

matrix of autoregressive coefficients, where*j*= 1,...,*p*and Φ_{p}is not a matrix containing only zeros.*x*is a_{t}`numpreds`

-by-1 vector of values corresponding to`numpreds`

exogenous predictor variables.*β*is a`numseries`

-by-`numpreds`

matrix of regression coefficients.*δ*is a`numseries`

-by-1 vector of linear time-trend values.*ε*is a_{t}`numseries`

-by-1 vector of random Gaussian innovations, each with a mean of 0 and collectively a`numseries`

-by-`numseries`

covariance matrix Σ. For*t*≠*s*,*ε*and_{t}*ε*are independent._{s}

Condensed and in lag operator notation, the system is

$$\Phi (L){y}_{t}=c+\beta {x}_{t}+\delta t+{\epsilon}_{t},$$

where $$\Phi (L)=I-{\Phi}_{1}L-{\Phi}_{2}{L}^{2}-\mathrm{...}-{\Phi}_{p}{L}^{p}$$, Φ(*L*)*y _{t}* is
the multivariate autoregressive polynomial, and

*I*is the

`numseries`

-by-`numseries`

identity matrix.For example, a VAR(1) model containing two response series and three exogenous predictor variables has this form:

$$\begin{array}{l}{y}_{1,t}={c}_{1}+{\varphi}_{11}{y}_{1,t-1}+{\varphi}_{12}{y}_{2,t-1}+{\beta}_{11}{x}_{1,t}+{\beta}_{12}{x}_{2,t}+{\beta}_{13}{x}_{3,t}+{\delta}_{1}t+{\epsilon}_{1,t}\\ {y}_{2,t}={c}_{2}+{\varphi}_{21}{y}_{1,t-1}+{\varphi}_{22}{y}_{2,t-1}+{\beta}_{21}{x}_{1,t}+{\beta}_{22}{x}_{2,t}+{\beta}_{23}{x}_{3,t}+{\delta}_{2}t+{\epsilon}_{2,t}.\end{array}$$

## References

[1] Granger, C. W. J. "Investigating Causal Relations by Econometric Models and Cross-Spectral Methods." *Econometrica*. Vol. 37, 1969, pp. 424–459.

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

[3] Dolado, J. J., and H. Lütkepohl. "Making Wald Tests Work for Cointegrated VAR Systems." *Econometric Reviews*. Vol. 15, 1996, pp. 369–386.

[4] Lütkepohl, Helmut. *New Introduction to Multiple Time Series Analysis*. New York, NY: Springer-Verlag, 2007.

[5] Toda, H. Y., and T. Yamamoto. "Statistical Inferences in Vector Autoregressions with Possibly Integrated Processes." *Journal of Econometrics*. Vol. 66, 1995, pp. 225–250.

## Version History

**Introduced in R2019a**

### R2023b: Choose predictor data from input table or timetable and return test settings

The `PredictorVariables`

name-value argument enables you to select
exogenous predictor variables from the input table or timetable of data for the underlying
VAR model of the Granger-causality test. The output table of test results additionally
contains the level of significance `Alpha`

and test type
`Test`

settings of each test.

### R2023a: `gctest`

accepts input data in tables and timetables, and return results in tables and timetables

In addition to accepting input data in numeric arrays,
`gctest`

accepts input data in tables and timetables. `gctest`

chooses default series on which to operate, but you can use the following name-value arguments to select variables.

`CauseVariables`

selects the Granger-cause variables from the input. By default, all variables not specified as Granger-effect variables are Granger-cause variables.`EffectVariables`

selects the Granger-effect variables from the input. By default, the last variable is the Granger-effect variable.`ConditionVariables`

selects the conditioning variables from the input. The default is none of the variables.

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)