fevd

Generate forecast error variance decomposition (FEVD) of state-space model

Since R2021a

Syntax

Decomposition = fevd(Mdl)

Decomposition = fevd(Mdl,Name,Value)

Decomposition = fevd(___,'Params',estParams)

[Decomposition,Lower,Upper] = fevd(___,'Params',estParams,'EstParamCov',EstParamCov)

Description

The fevd function returns the forecast error variance decomposition (FEVD) of the measurement variables in a state-space model attributable to component-wise shocks to each state disturbance. The FEVD provides information about the relative importance of each state disturbance in affecting the forecast error variance of all measurement variables in the system. Other state-space model tools to characterize the dynamics of a specified system include the following:

• The impulse response function (IRF), computed by irf and plotted by irfplot, traces the effects of a shock to a state disturbance on the state and measurement variables in the system.

• Model-implied temporal correlations, computed by corr for a standard state-space model, measure the association between current and lagged state or measurement variables, as prescribed by the form of the model.

Fully Specified State-Space Model

Decomposition = fevd(Mdl) returns the FEVD of each measurement variable Decomposition of the fully specified state-space model Mdl.

Decomposition = fevd(Mdl,Name,Value) uses additional options specified by one or more name-value arguments. For example, 'NumPeriods',10 specifies estimating the FEVD for periods 1 through 10.

Partially Specified State-Space Model and Confidence Interval Estimation

Decomposition = fevd(___,'Params',estParams) returns the FEVD of all measurement variables of the partially specified state-space model Mdl. estParams specifies estimates of all unknown parameters in the model, using any of the input argument combinations in the previous syntaxes.

[Decomposition,Lower,Upper] = fevd(___,'Params',estParams,'EstParamCov',EstParamCov) also returns the lower and upper 95% Monte Carlo confidence bounds Lower and Upper of each measurement variable FEVD. EstParamCov specifies the estimated covariance matrix of the parameter estimates, as returned by the estimate function, and is required for confidence interval estimation.

Examples

FEVD of Measurement Variables

Compute the model-implied FEVD of two state-space models: one with measurement error and one without measurement error.

Model Without Measurement Error

Explicitly create the state-space model without measurement error

$$\begin{array}{l}{x}_{1,t}=x_{1,t-1}+0.2u_{1,t}\\ x_{2,t}=x_{1,t-1}+0.3x_{2,t-1}+u_{2,t}\\ y_{1,t}=x_{1,t}\\ y_{2,t}=x_{1,t}+x_{2,t}.\end{array}$$

A = [1 0; 1 0.3];
B = [0.2 0; 0 1];
C = [1 0; 1 1];
Mdl1 = ssm(A,B,C,'StateType',[2 2])

Mdl1 = 
State-space model type: ssm

State vector length: 2
Observation vector length: 2
State disturbance vector length: 2
Observation innovation vector length: 0
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + (0.20)u1(t)
x2(t) = x1(t-1) + (0.30)x2(t-1) + u2(t)

Observation equations:
y1(t) = x1(t)
y2(t) = x1(t) + x2(t)

Initial state distribution:

Initial state means
 x1  x2 
  0   0 

Initial state covariance matrix
     x1     x2    
 x1  1e+07  0     
 x2  0      1e+07 

State types
    x1       x2   
 Diffuse  Diffuse 

Mdl1 is an ssm model object. Because all parameters have known values, the object is fully specified.

Compute the 20-period FEVD of the measurement variables.

Decomposition1 = fevd(Mdl1);
size(Decomposition1)

ans = 1×3

    20     2     2

Decomposition is a 20-by-2-by-2 array representing the 20-period FEVD of the two measurement variables. Display Decomposition(5,1,2).

Decomposition1(5,1,2)

ans = 
0.4429

In this case, 44.29% of the volatility of ${\mathit{y}}_{2,\mathit{t}}$ is attributed to the shock applied to ${\mathit{u}}_{1,\mathit{t}-5}$.

Plot the FEVD of ${\mathit{y}}_{2,\mathit{t}}$ for each state disturbance.

bar(Decomposition1(:,:,2),'stacked')
xlabel('Period')
ylabel('Variance Decompositions of $y_{2,t}$','Interpreter','latex')
legend('$u_{1,t}$','$u_{2,t}$','Interpreter','latex')

Because the state-space model is free of measurement error ($\mathit{D}$ = 0), the variance decompositions of each period sum to 1. The volatility attributable to ${\mathit{u}}_{1,\mathit{t}}$ increases with each period.

Model with Measurement Error

Explicitly create the state-space model

$$\begin{array}{l}{x}_{1,t}=x_{1,t-1}+0.2u_{1,t}\\ x_{2,t}=x_{1,t-1}+0.3x_{2,t-1}+u_{2,t}\\ y_{1,t}=x_{1,t}+{\epsilon }_{1,t}\\ y_{2,t}=x_{1,t}+x_{2,t}+{\epsilon }_{2,t}.\end{array}$$

D = eye(2);
Mdl2 = ssm(A,B,C,D,'StateType',[2 2])

Mdl2 = 
State-space model type: ssm

State vector length: 2
Observation vector length: 2
State disturbance vector length: 2
Observation innovation vector length: 2
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + (0.20)u1(t)
x2(t) = x1(t-1) + (0.30)x2(t-1) + u2(t)

Observation equations:
y1(t) = x1(t) + e1(t)
y2(t) = x1(t) + x2(t) + e2(t)

Initial state distribution:

Initial state means
 x1  x2 
  0   0 

Initial state covariance matrix
     x1     x2    
 x1  1e+07  0     
 x2  0      1e+07 

State types
    x1       x2   
 Diffuse  Diffuse 

Compute the 20-period FEVD of the measurement variables.

Decomposition2 = fevd(Mdl2);

Plot the FEVD of ${\mathit{y}}_{2,\mathit{t}}$ for each state disturbance.

bar(Decomposition2(:,:,2),'stacked')
xlabel('Period')
ylabel('Variance Decompositions of $y_{2,t}$','Interpreter','latex')
legend('$u_{1,t}$','$u_{2,t}$','Interpreter','latex')

Because the model contains measurement error, the variance proportions do not sum to 1 during each period.

Specify Number of Periods

Explicitly create the multivariate diffuse state-space model

$$\begin{array}{l}{x}_{1,t}=x_{1,t-1}+0.2u_{1,t}\\ x_{2,t}=x_{1,t-1}+0.3x_{2,t-1}+u_{2,t}\\ y_{1,t}=x_{1,t}\\ y_{2,t}=x_{1,t}+x_{2,t}.\end{array}$$

A = [1 0; 1 0.3];
B = [0.2 0; 0 1];
C = [1 0; 1 1];
Mdl = dssm(A,B,C,'StateType',[2 2])

Mdl = 
State-space model type: dssm

State vector length: 2
Observation vector length: 2
State disturbance vector length: 2
Observation innovation vector length: 0
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + (0.20)u1(t)
x2(t) = x1(t-1) + (0.30)x2(t-1) + u2(t)

Observation equations:
y1(t) = x1(t)
y2(t) = x1(t) + x2(t)

Initial state distribution:

Initial state means
 x1  x2 
  0   0 

Initial state covariance matrix
     x1   x2  
 x1  Inf  0   
 x2  0    Inf 

State types
    x1       x2   
 Diffuse  Diffuse 

Mdl is a dssm model object.

Compute the 50-period FEVD of the measurement variables.

Decomposition = fevd(Mdl,'NumPeriods',50);
size(Decomposition)

ans = 1×3

    50     2     2

Plot the FEVD of ${\mathit{y}}_{2,\mathit{t}}$ for each state disturbance.

bar(Decomposition(:,:,2),'stacked')
xlabel('Period')
ylabel('Variance Decompositions of $y_{2,t}$','Interpreter','latex')
legend('$u_{1,t}$','$u_{2,t}$','Interpreter','latex')

The contribution of ${\mathit{u}}_{1,\mathit{t}}$ to the volatility of ${\mathit{y}}_{2,\mathit{t}}$ approaches 90%.

FEVD of Estimated Model

Simulate data from a known model, fit the data to a state-space model, and then estimate the FEVD of the measurement variables.

Consider the time series decomposition ${\mathit{y}}_{\mathit{t}}={\tau }_{\mathit{t}}+{\mathit{c}}_{\mathit{t}}$, where ${\tau }_{\mathit{t}}$ is a random walk with drift representing the trend component, and ${\mathit{c}}_{\mathit{t}}$ is an AR(1) model representing the cycle component.

$$\begin{array}{l}{\tau }_t=3+{\tau }_{t-1}+u_{1,t}\\ c_t=0.5c_{t-1}+2u_{2,t}.\end{array}$$

The model in state-space notation is

$$\begin{array}{l}{x}_t=\left[\begin{array}{c}{\tau }_t\\ d_t\\ c_t\end{array}\right]=\left[\begin{array}{ccc}1& 3& 0\\ 0& 1& 0\\ 0& 0& 0.5\end{array}\right]\left[\begin{array}{c}{\tau }_{t-1}\\ d_{t-1}\\ c_{t-1}\end{array}\right]+\left[\begin{array}{cc}1& 0\\ 0& 0\\ 0& 2\end{array}\right]\left[\begin{array}{c}{u}_{1,t}\\ u_{2,t}\end{array}\right]\\ y_t=\left[\begin{array}{ccc}1& 0& 1\end{array}\right]x_t,\end{array}$$

where ${\mathit{d}}_{\mathit{t}}$ is a dummy state representing the drift parameter, which is 1 for all $\mathit{t}$.

Simulate 500 observations from the true model.

rng(1); % For reproducibility
ADGP = [1 3 0; 0 1 0; 0 0 0.5];
BDGP = [1 0; 0 0; 0 2];
CDGP = [1 0 1];
DGP = ssm(ADGP,BDGP,CDGP,'StateType',[2 1 0]);
y = simulate(DGP,500);

Assume that the drift constant, disturbance variances, and AR coefficient are unknown. Explicitly create a state-space model template for estimation that represents the model by replacing the unknown parameters in the model with NaN.

A = [1 NaN 0; 0 1 0; 0 0 NaN];
B = [NaN 0; 0 0; 0 NaN];
C = CDGP;
Mdl = ssm(A,B,C,'StateType',[2 1 0]);

Fit the model template to the data. Specify a set of positive, random standard Gaussian starting values for the four model parameters. Return the estimated model and vector of parameter estimates.

[EstMdl,estParams] = estimate(Mdl,y,abs(randn(4,1)),'Display','off')

EstMdl = 
State-space model type: ssm

State vector length: 3
Observation vector length: 1
State disturbance vector length: 2
Observation innovation vector length: 0
Sample size supported by model: Unlimited

State variables: x1, x2,...
State disturbances: u1, u2,...
Observation series: y1, y2,...
Observation innovations: e1, e2,...

State equations:
x1(t) = x1(t-1) + (2.91)x2(t-1) + (0.92)u1(t)
x2(t) = x2(t-1)
x3(t) = (0.52)x3(t-1) + (2.13)u2(t)

Observation equation:
y1(t) = x1(t) + x3(t)

Initial state distribution:

Initial state means
 x1  x2  x3 
  0   1   0 

Initial state covariance matrix
     x1        x2  x3   
 x1  1.00e+07   0   0   
 x2   0         0   0   
 x3   0         0  6.20 

State types
    x1       x2         x3     
 Diffuse  Constant  Stationary 

estParams = 4×1

    2.9115
    0.5189
    0.9200
    2.1278

EstMdl is a fully specified ssm model object. Model estimates are close to their true values.

Compute and plot the FEVD of the measurement variable. Specify the model template Mdl and the vector of estimated parameters estParams.

Decomposition = fevd(Mdl,'Params',estParams);

bar(Decomposition,'stacked')
xlabel('Period')
ylabel('Variance Decompositions of $y_{t}$','Interpreter','latex')
legend('$u_{1,t}$','$u_{2,t}$','Interpreter','latex')

Noise in the cyclical component dominates the volatility of the measurement variable in low lags, with increasing contribution from the trend component noise as the lag increases.

Time-Varying FEVD

Simulate data from a time-varying state-space model, fit a model to the data, and then estimate the time-varying FEVD of the measurement variable.

Consider the time series decomposition ${\mathit{y}}_{\mathit{t}}={\tau }_{\mathit{t}}+{\mathit{c}}_{\mathit{t}}$, where ${\tau }_{\mathit{t}}$ is a random walk with drift representing the trend component, and ${\mathit{c}}_{\mathit{t}}$ is an AR(1) model representing the cyclical component. Suppose that the cyclical component changes during period 26 over a 50-period time span.

$$\begin{array}{l}{\tau }_t=1+{\tau }_{t-1}+u_{1,t}\\ c_t=\{\begin{array}{cc}0.5c_t+2u_{2,t};& t<26\\ -0.2c_t+0.5u_{2,t};& t\ge 26\end{array}.\end{array}$$

Write a function that specifies how the parameters params map to the state-space model matrices, the initial state moments, and the state types. Save this code as a file named timeVariantTrendCycleParamMap.m on your MATLAB® path. Alternatively, open the example to access the function.

type timeVariantTrendCycleParamMap.m

% Copyright 2021 The MathWorks, Inc.

function [A,B,C,D,Mean0,Cov0,StateType] = timeVariantTrendCycleParamMap(params)
% Time-varying state-space model parameter mapping function example. This
% function maps the vector params to the state-space matrices (A, B, C, and
% D). The measurement equation is a times series decomposed into trend and
% cyclical components, with a structural break in the cycle during period
% 26.
% 
% The trend component is tau_t = drift + tau_{t-1} + s_1u1_t.
%
% The cyclical component is:
%     * c_t = phi_1*c_{t-1} + s_2*u2_t; t = 1 through 25
%     * c_t = phi_2*c_{t-1} + s_3*u2_t; t = 11 through 26.
%
% The measurement equation is y_t = tau_t + c_t.
    A1 = {[1 params(1) 0; 0 1 0; 0 0 params(2)]};
    A2 = {[1 params(1) 0; 0 1 0; 0 0 params(3)]};
    varu1 = exp(params(4));  % Positive variance constraints
    varu21 = exp(params(5));
    varu22 = exp(params(6));
    B1 = {[sqrt(varu1) 0; 0 0; 0 sqrt(varu21)]}; 
    B2 = {[sqrt(varu1) 0; 0 0; 0 sqrt(varu22)]}; 
    C = [1 0 1];
    D = 0;
    sc = 25;
    A = [repmat(A1,sc,1); repmat(A2,sc,1)];
    B = [repmat(B1,sc,1); repmat(B2,sc,1)];
    Mean0 = [];
    Cov0 = [];
    StateType = [2 1 0];
end

Implicitly create a partially specified state-space model representing the data generating process (DGP).

ParamMap = @timeVariantTrendCycleParamMap;
DGP = ssm(ParamMap);

Simulate 50 observations from the DGP. Because DGP is partially specified, pass the true parameter values to simulate by using the 'Params' name-value argument.

rng(5) % For reproducibility
trueParams = [1 0.5 -0.2 2*log(1) 2*log(2) 2*log(0.5)]; % Transform variances for parameter map
y = simulate(DGP,50,'Params',trueParams);

y is a 50-by-1 vector of simulated measurements ${\mathit{y}}_{\mathit{t}}$ from the DGP.

Because DGP is a partially specified, implicit model object, its parameters are unknown. Therefore, it can serve as a model template for estimation.

Fit the model to the simulated data. Specify random standard Gaussian draws for the initial parameter values, and turn off the estimation display. Return the parameter estimates.

[~,estParams] = estimate(DGP,y,randn(1,6),'Display','off')

estParams = 1×6

    0.8510    0.0118    0.6309   -0.3227    1.3778   -0.2200

estParams is a 1-by-6 vector of parameter estimates. The output argument list of the parameter mapping function determines the order of the estimates.

Estimate the FEVD of the measurement variable by supplying DGP (not the estimated model) and the estimated parameters using the 'Params' name-value argument.

Decomposition = fevd(DGP,'Params',estParams,'NumPeriods',50);

bar(Decomposition,'stacked')
xlabel('Period')
ylabel('Variance Decompositions of $y_{t}$','Interpreter','latex')
legend('$u_{1,t}$','$u_{2,t}$','Interpreter','latex')

The FEVD jumps at period 26, when the structural break occurs.

Estimate FEVD Confidence Bounds

Simulate data from a known model, fit the data to a state-space model, and then estimate the FEVD of the measurement variables with 90% Monte Carlo confidence bounds.

Consider the time series decomposition ${\mathit{y}}_{\mathit{t}}={\tau }_{\mathit{t}}+{\mathit{c}}_{\mathit{t}}$, where ${\tau }_{\mathit{t}}$ is a random walk with drift representing the trend component, and ${\mathit{c}}_{\mathit{t}}$ is an AR(1) model representing the cycle component.

$$\begin{array}{l}{\tau }_t=3+{\tau }_{t-1}+u_{1,t}\\ c_t=0.5c_{t-1}+2u_{2,t}.\end{array}$$

The model in state-space notation is

$$\begin{array}{l}{x}_t=\left[\begin{array}{c}{\tau }_t\\ d_t\\ c_t\end{array}\right]=\left[\begin{array}{ccc}1& 3& 0\\ 0& 1& 0\\ 0& 0& 0.5\end{array}\right]\left[\begin{array}{c}{\tau }_{t-1}\\ d_{t-1}\\ c_{t-1}\end{array}\right]+\left[\begin{array}{cc}1& 0\\ 0& 0\\ 0& 2\end{array}\right]\left[\begin{array}{c}{u}_{1,t}\\ u_{2,t}\end{array}\right]\\ y_t=\left[\begin{array}{ccc}1& 0& 1\end{array}\right]x_t,\end{array}$$

where ${\mathit{d}}_{\mathit{t}}$ is a dummy state representing the drift parameter, which is 1 for all t.

Simulate 500 observations from the true model.

rng(1); % For reproducibility
ADGP = [1 3 0; 0 1 0; 0 0 0.5];
BDGP = [1 0; 0 0; 0 2];
CDGP = [1 0 1];
DGP = ssm(ADGP,BDGP,CDGP,'StateType',[2 1 0]);
y = simulate(DGP,500);

Assume that the drift constant, disturbance variances, and AR coefficient are unknown. Explicitly create a state-space model template for estimation that represents the model by replacing the unknown parameters in the model with NaN.

A = [1 NaN 0; 0 1 0; 0 0 NaN];
B = [NaN 0; 0 0; 0 NaN];
C = CDGP;
Mdl = ssm(A,B,C,'StateType',[2 1 0]);

Fit the model template to the data. Specify a set of positive, random standard Gaussian starting values for the four model parameters, and turn off the estimation display. Return the estimated model and vector of parameter estimates and their estimated covariance matrix.

[EstMdl,estParams,EstParamCov] = estimate(Mdl,y,abs(randn(4,1)),'Display','off');

EstMdl is a fully specified ssm model object. Model estimates are close to their true values.

Compute the FEVD of the measurement variable with period-wise 90% Monte Carlo confidence bounds. Specify the model template Mdl, vector of estimated parameters estParams, and their estimated covariance matrix EstParamCov.

[Decomposition,Lower,Upper] = fevd(Mdl,'Params',estParams,'EstParamCov',EstParamCov,...
    'Confidence',0.9);

Plot the proportion of volatility of ${\mathit{y}}_{\mathit{t}}$ attributable to ${\mathit{u}}_{1,\mathit{t}}$ with corresponding 90% confidence bounds.

plot(Decomposition(:,1),'r-o')
hold on
plot([Lower(:,1) Upper(:,1)],'b-o')
hold off
xlabel('Period')
ylabel('Proportion of Volatility')
title('Volatility Attributable to $u_{1,t}$','Interpreter','latex')
legend('Proportion','90% confidence bounds')

The confidence bounds are initially relatively tight, but widen as the lag and volatility increase.

Input Arguments

Mdl — State-space model

ssm model object | dssm model object

State-space model, specified as an ssm model object returned by ssm or its estimate function, or a dssm model object returned by dssm or its estimate function.

If Mdl is partially specified (that is, it contains unknown parameters), specify estimates of the unknown parameters by using the 'Params' name-value argument. Otherwise, fevd issues an error.

fevd issues an error when Mdl is a dimension-varying model, which is a time-varying model containing at least one variable that changes dimension during the sampling period (for example, a state variable drops out of the model; see Decide on Model Structure).

Tip

If Mdl is fully specified, you cannot estimate confidence bounds. To estimate confidence bounds:

1. Create a partially specified state-space model template for estimation Mdl.

2. Estimate the model by using the estimate function and data. Return the estimated parameters estParams and estimated parameter covariance matrix EstParamCov.

3. Pass the model template for estimation Mdl to fevd, and specify the parameter estimates and covariance matrix by using the 'Params' and 'EstParamCov' name-value arguments.

4. For the fevd function, return the appropriate output arguments for lower and upper confidence bounds.

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: 'NumPeriods',10 estimating the FEVD for specifies estimating the FEVD for periods 1 through 10.

FEVD Options

NumPeriods — Number of periods

20 (default) | positive integer

Number of periods for which fevd computes the FEVD, specified as a positive integer. Periods in the FEVD start at time 1 and end at time NumPeriods.

Example: 'NumPeriods',10 specifies the inclusion of 10 consecutive time points in the FEVD, starting at time 1 and ending at time 10.

Data Types: double

Params — Estimates of unknown parameters

numeric vector

Estimates of the unknown parameters in the partially specified state-space model Mdl, specified as a numeric vector.

If Mdl is partially specified (contains unknown parameters specified by NaNs), you must specify Params. The estimate function returns parameter estimates of Mdl in the appropriate form. However, you can supply custom estimates by arranging the elements of Params as follows:

• If Mdl is an explicitly created model (Mdl.ParamMap is empty []), arrange the elements of Params to correspond to hits of a column-wise search of NaNs in the state-space model coefficient matrices, initial state mean vector, and covariance matrix.

  • If Mdl is time invariant, the order is A, B, C, D, Mean0, and Cov0.

  • If Mdl is time varying, the order is A{1} through A{end}, B{1} through B{end}, C{1} through C{end}, D{1} through D{end}, Mean0, and Cov0.

• If Mdl is an implicitly created model (Mdl.ParamMap is a function handle), the first input argument of the parameter-to-matrix mapping function determines the order of the elements of Params.

If Mdl is fully specified, fevd ignores Params.

Example: Consider the state-space model Mdl with A = B = [NaN 0; 0 NaN] , C = [1; 1], D = 0, and initial state means of 0 with covariance eye(2). Mdl is partially specified and explicitly created. Because the model parameters contain a total of four NaNs, Params must be a 4-by-1 vector, where Params(1) is the estimate of A(1,1), Params(2) is the estimate of A(2,2), Params(3) is the estimate of B(1,1), and Params(4) is the estimate of B(2,2).

Data Types: double

Confidence Bound Estimation Options

EstParamCov — Estimated covariance matrix of unknown parameters

positive semidefinite numeric matrix

Estimated covariance matrix of unknown parameters in the partially specified state-space model Mdl, specified as a positive semidefinite numeric matrix.

estimate returns the estimated parameter covariance matrix of Mdl in the appropriate form. However, you can supply custom estimates by setting EstParamCov(i,j) to the estimated covariance of the estimated parameters Params(i) and Params(j), regardless of whether Mdl is time invariant or time varying.

If Mdl is fully specified, fevd ignores EstParamCov.

By default, fevd does not estimate confidence bounds.

Data Types: double

NumPaths — Number of Monte Carlo sample paths

1000 (default) | positive integer

Number of Monte Carlo sample paths (trials) to generate to estimate confidence bounds, specified as a positive integer.

Example: 'NumPaths',5000

Data Types: double

Confidence — Confidence level

0.95 (default) | numeric scalar in [0,1]

Confidence level for the confidence bounds, specified as a numeric scalar in the interval [0,1].

For each period, randomly drawn confidence intervals cover the true response 100*Confidence% of the time.

The default value is 0.95, which implies that the confidence bounds represent 95% confidence intervals.

Example: Confidence=0.9 specifies 90% confidence intervals.

Data Types: double

Output Arguments

Decomposition — FEVD

numeric array

FEVD of the measurement variables y_t, returned as a NumPeriods-by-k-by-n numeric array.

Decomposition(t,i,j) is the FEVD of measurement variable j at period t, when a unit shock is applied to state-disturbance variable i during period 1, for t = 1,2,...,NumPeriods, i = 1,2,...,k, and j = 1,2,...,n.

Lower — Pointwise lower confidence bounds of FEVD

numeric array

Pointwise lower confidence bounds of the FEVD of the measurement variables, returned as a NumPeriods-by-k-by-n numeric array.

Lower(t,i,j) is the lower bound of the 100*Confidence% percentile interval on the true FEVD of measurement variable j at period t, when a unit shock is applied to state-disturbance variable i during period 1.

Upper — Pointwise upper confidence bounds of FEVD

numeric array

Pointwise upper confidence bounds of the FEVD of the measurement variables, returned as a NumPeriods-by-k-by-n numeric array.

Upper(t,i,j) is the upper confidence bound corresponding to the lower confidence bound Lower(t,i,j).

More About

Forecast Error Variance Decomposition

The forecast error variance decomposition (FEVD) of a state-space model measures the volatility in each measurement variable y_t as a result of a unit impulse to each state disturbance u_t at period 1. The FEVD tracks the volatility as the impulses propagate the system for each period t ≥ 1. The FEVD provides information about the relative importance of each state disturbance in affecting the forecast error variance of all measurement variables in the system.

Consider the time-invariant state-space model at time t

$$\begin{array}{l}{x}_t=A{x}_{t-1}+B{u}_t\\ y_t=C{x}_t+D{\epsilon }_t,\end{array}$$

and consider unit shocks to all state disturbances u_t during period t – s, where s < t.

The state equation, expressed as a function of u_{t – s} is $$x_t=A^{s+1}{x}_{t-s-1}+{\displaystyle \sum _{i=0}^s{A}^{i}B{u}_{t-i}.}$$ The corresponding measurement equation is

$$y_t=C{A}^{s+1}{x}_{t-s-1}+C{\displaystyle \sum _{i=0}^s{A}^{i}B{u}_{t-i}}+D{\epsilon }_t.$$

Therefore, the total volatility of y_t, attributed to shocks from periods t – s through t, is

$$V_s=C\left({\displaystyle \sum _{i=0}^s{A}^i}B{B}^{\prime }{\left(A^i\right)}^{\prime }\right)C^{\prime }+D{D}^{\prime }.$$

This result implies that noise in both the transition and measurement equations contributes to the forecast error variance.

The volatility attributed to state disturbance j u_j,t is

$$V_{sj}=C\left({\displaystyle \sum _{i=0}^s{A}^i}B{I}_k^{(j)}{B}^{\prime }{\left(A^i\right)}^{\prime }\right)C^{\prime },$$

where:

• I_k^(j) is a k-by-k selection matrix, a matrix of zeros except for the value 1 in element (j,j).

• $$V_s={\displaystyle \sum _{j=1}^k{V}_{sj}}+D{D}^{\prime }$$

As a result, the s-step ahead forecast error variance of y_i,t, attributable to a unit shock to u_j,t, is

$${\gamma }_{s,ij}=\frac{V_{js}(i,i)}{V_s(i,i)}.$$

If D is zero, the FEVD of a measurement variable at period t sums to one (in other words, the sum of each row is one). Otherwise, the FEVD of a measurement variable at period t does not necessarily sum to one; the remaining portion is attributable to DD'.

The FEVD of a time-varying, dimension-invariant state-space model is also time varying. In this case, fevd always applies the unit shock during period 1. For an s-period-ahead FEVD, the measurement equation is

$$y_s=C_s{A}_s\cdots A_2{A}_1{x}_0+C_s{\displaystyle \sum _{i=1}^{s-1}\left({\displaystyle \prod _{\ell =1}^i{A}_{s-\ell +1}}\right)B_{s-i}{u}_{s-i}}+C_s{B}_s{u}_s+D_s{\epsilon }_s.$$

The total volatility of y_s is

$$V_s=C_s\left\{{\displaystyle \sum _{i=1}^{s-1}\left[\left({\displaystyle \prod _{\ell =1}^i{A}_{s-\ell +1}}\right)B_{s-i}{B}_{s-i}^{\prime }{\left({\displaystyle \prod _{\ell =1}^i{A}_{s-\ell +1}}\right)}^{\prime }\right]}\right\}{C}_s{}^{\prime }+D_s{D}_s{}^{\prime }.$$

As with time-invariant models, the s-period-ahead volatility attributed to state disturbance j shocked during period 1 u_j,1 is

$$V_{sj}=C_s\left\{{\displaystyle \sum _{i=1}^{s-1}\left[\left({\displaystyle \prod _{\ell =1}^i{A}_{s-\ell +1}}\right)B_{s-i}{I}_k^{(j)}{B}_{s-i}^{\prime }{\left({\displaystyle \prod _{\ell =1}^i{A}_{s-\ell +1}}\right)}^{\prime }\right]}\right\}{C}_s{}^{\prime }.$$

As a result, the s-step-ahead forecast error variance of y_i,s, attributable to a unit shock to u_j,1, is

$${\gamma }_{s,ij}=\frac{V_{js}(i,i)}{V_s(i,i)}.$$

Because time-invariant and time-varying FEVDs do not include initial state distribution terms, the formulas apply to standard and diffuse state-space models.

Algorithms

• If you do not supply the EstParamCov name-value argument, confidence bounds of each period overlap.

• fevd uses Monte Carlo simulation to compute confidence intervals.

  1. fevd randomly draws NumPaths variates from the asymptotic sampling distribution of the unknown parameters in Mdl, which is N_p(Params,EstParamCov), where p is the number of unknown parameters.

  2. For each randomly drawn parameter set j, fevd does the following:

     1. Create a state-space model that is equal to Mdl, but substitute in parameter set j.

     2. Compute the random FEVD of the resulting model γ_j(t), where t = 1 through NumPaths.

  3. For each time t, the lower bound of the confidence interval is the (1 – c)/2 quantile of the simulated FEVD at period t γ(t), where c = Confidence. Similarly, the upper bound of the confidence interval at time t is the (1 – c)/2 upper quantile of γ(t).

Version History

Introduced in R2021a