Skip to contents

Plot Historical Decomposition

Source: R/fplot_histdec.R
fplot_histdec.Rd

Plots the historical decomposition for multiple variables, showing the contribution of the chosen structural shock, the residual (all other shocks), and the total explained variation as a stacked bar chart with a total line overlay. Mirrors the MATLAB Bloom replication figure with facets per variable.

Usage

fplot_histdec(
  histdec_list,
  shock,
  shockname,
  dates = NULL,
  p = 0L,
  return_data = FALSE,
  facet_ncol = 2,
  shock_fill = "#407EC9",
  resid_fill = "#E87722",
  total_color = "#1a1a1a",
  total_linewidth = 0.8,
  area_alpha = 1
)

Arguments

histdec_list

Named list of (T-p) x N matrices, one per variable to plot. Each element is the $histdec output of fhistdec() called for that variable. Names are used as facet labels.

shock

Integer (1-indexed) selecting the shock of interest.

shockname

Character string label for the selected shock (legend entry).

dates

Optional vector of dates (Date, numeric, or integer). Can be the full T-length vector (trimmed internally using p) or the already- trimmed (T-p)-length vector. Default NULL uses an integer index.

p

Integer lag order of the VAR. Used only when dates has length T (full sample) to trim to dates[(p+1):T]. Default 0L.

return_data

Logical. If TRUE returns the wide-format tibble (columns: date, variable, shockname, Residual, Total) instead of the plot. Default FALSE.

facet_ncol

Number of columns in the facet grid. Default 2.

shock_fill

Fill color for the shock contribution area (default: "#407EC9").

resid_fill

Fill color for the residual (other shocks) area (default: "#E87722").

total_color

Color for the total line overlay (default: "#1a1a1a").

total_linewidth

Line width for the total line (default: 0.8).

area_alpha

Transparency for the stacked areas (default: 1).

Value

A ggplot object (if return_data = FALSE) or a tibble with columns date, variable, series, and value.

Details

For each variable and each time period t the plot shows:

  • Shock bar — histdec[t, shock]: contribution of the selected structural shock.

  • Residual bar — sum of histdec[t, -shock]: combined contribution of all other shocks.

  • Total line — sum of both bars: total explained variation.

See also

fhistdec

Examples

if (FALSE) { # \dontrun{
var_result <- fVAR(y, p = 12, c = 1)
K      <- t(chol(var_result$sigma_full))
shock  <- match("UNCERT", colnames(y))
series <- setdiff(seq_len(ncol(y)), shock)

# Call fhistdec for each variable and collect into a named list
histdec_list <- setNames(
    lapply(series, function(i) fhistdec(y, var_result, K, i)$histdec),
    colnames(y)[series]
)

fplot_histdec(
    histdec_list = histdec_list,
    shock        = shock,
    shockname    = "Uncertainty",
    dates        = dates_vec,
    p            = 12
) + ftheme_tidyMacro()
} # }