Overview

The G20 panel that ships with contagionchannels is one possible application; the same machinery applies to any directed network of return series and any set of channel proxies a user can construct. This vignette shows how to plug in custom data, explains the contracts each function expects, and ends with a worked example using a synthetic five-market panel seeded for reproducibility.

library(contagionchannels)
library(xts)
#> Loading required package: zoo
#> 
#> Attaching package: 'zoo'
#> The following objects are masked from 'package:base':
#> 
#>     as.Date, as.Date.numeric
library(dplyr)
#> 
#> ######################### Warning from 'xts' package ##########################
#> #                                                                             #
#> # The dplyr lag() function breaks how base R's lag() function is supposed to  #
#> # work, which breaks lag(my_xts). Calls to lag(my_xts) that you type or       #
#> # source() into this session won't work correctly.                            #
#> #                                                                             #
#> # Use stats::lag() to make sure you're not using dplyr::lag(), or you can add #
#> # conflictRules('dplyr', exclude = 'lag') to your .Rprofile to stop           #
#> # dplyr from breaking base R's lag() function.                                #
#> #                                                                             #
#> # Code in packages is not affected. It's protected by R's namespace mechanism #
#> # Set `options(xts.warn_dplyr_breaks_lag = FALSE)` to suppress this warning.  #
#> #                                                                             #
#> ###############################################################################
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:xts':
#> 
#>     first, last
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

1. Required data structure

Two objects drive the entire pipeline.

Returns. An xts object with one column per market. Rows are trading days (the index must be Date or POSIXct); columns are demeaned daily log returns. Missing values are allowed but should be sparse; na.locf or listwise deletion are both acceptable, but the user is responsible for the choice.

Channel proxies. A data.frame with a Date column matching the returns index plus one column per raw component of each channel. The helper build_channel_composites() does the standardisation and PCA reduction; the user must only ensure that the components are aligned on date and roughly stationary (returns or first-differenced spreads, never raw levels).

str(my_returns_xts)
# An 'xts' object on 2010-01-04/2024-12-31 of 18 columns

str(my_channels_df)
# 'data.frame' with Date + raw component columns

2. Custom market list and crisis periods

The package does not hard-code 18 markets; the WQTE estimator accepts any $N \ge 3$ markets. To pass your own crisis periods, build a named list of Date-vector pairs:

my_periods <- list(
  Pre_Pandemic = as.Date(c("2018-01-02", "2020-01-31")),
  Pandemic     = as.Date(c("2020-02-01", "2021-12-31")),
  Recovery     = as.Date(c("2022-01-01", "2024-12-31"))
)

Periods need not be contiguous and can overlap, though overlapping windows complicate cross-period comparisons. The conventional non-overlap rule is what the paper uses.

3. Custom channel composites

build_channel_composites() exposes a mapping argument that lets the user override the default component-to-channel assignment. Each channel must have at least two components for the PCA reduction to be defined.

my_mapping <- list(
  Trade           = c("BDI_chg", "TradeWeightedFX_chg", "ContainerRate_chg"),
  Financial       = c("FRAOIS", "TEDspread", "CDS_lvl"),
  Geopolitical    = c("GPR_daily", "GPR_actions"),
  Behavioral      = c("VIX_innov", "VVIX_innov", "PutCallRatio"),
  Monetary_Policy = c("ShadowRate_surp", "FF_futures_surp")
)

my_channels <- build_channel_composites(
  proxy_grid = my_proxies_df,
  mapping    = my_mapping,
  standardise = "rolling_252"
)

The standardise argument selects between "global" (one z-score over the whole sample), "rolling_252" (one-year rolling), or "period" (within each crisis period). The paper uses "rolling_252" to match the daily update cadence of the underlying components.

4. Calling the pipeline

Once returns and composites are in hand, run_contagion_pipeline() consumes both. The full call mirrors the replication vignette but with user-supplied objects:

results <- run_contagion_pipeline(
  returns       = my_returns_xts,
  channels      = my_channels,
  periods       = my_periods,
  scale         = 5,
  tau           = 0.50,
  abs_threshold = NULL,    # NULL => derive from first period Q75
  methods       = c("iv2sls", "lp"),
  bootstrap_B   = 499,
  n_cores = 4
)

Setting abs_threshold = NULL instructs the pipeline to derive the absolute threshold from the 75th percentile of the first listed period’s WQTE distribution. Alternatively, pass a numeric value to fix the threshold across applications, which is useful for cross-paper comparability.

5. Adapting visualisations for custom data

The plotting helpers accept any tidy data.frame with a Period and Channel column; they do not assume the eight G20 sub-periods. To customise:

plot_attribution_stack(
  shares_long = results$shares_long,
  period_order = names(my_periods),
  palette      = c(Trade = "#1f77b4", Financial = "#d62728",
                   Geopolitical = "#9467bd", Behavioral = "#2ca02c",
                   Monetary_Policy = "#ff7f0e")
)

plot_qte_intensity(
  F_matrix  = results$F_matrices$Pandemic,
  threshold = results$abs_threshold,
  market_order = c("US", "EU", "JP", "EM_Asia", "EM_LatAm")
)

Both helpers return a ggplot object that can be modified with the standard ggplot2 grammar.

6. Worked example: synthetic five-market panel

A small, fully-reproducible example is the most reliable way to confirm the contracts. Below we simulate five correlated equity-like return series together with five channel components, build the composites, and run a trimmed Stage 1 + Stage 2 pipeline.

set.seed(20260429)

n_obs   <- 1500
markets <- c("US", "EU", "JP", "EM_Asia", "EM_LatAm")
dates   <- seq.Date(from = as.Date("2018-01-02"), by = "day",
                    length.out = n_obs)

# Common factor + idiosyncratic shocks
Fcom <- rnorm(n_obs, sd = 0.012)
ret_mat <- sapply(markets, function(m) {
  loading <- runif(1, 0.4, 0.9)
  loading * Fcom + rnorm(n_obs, sd = 0.010)
})
my_returns <- xts(ret_mat, order.by = dates)

# Channel proxy raw components
my_proxies <- data.frame(
  Date              = dates,
  BDI_chg           = rnorm(n_obs, sd = 0.5),
  TradeFX_chg       = rnorm(n_obs, sd = 0.4),
  FRAOIS            = arima.sim(list(ar = 0.95), n_obs) * 0.01,
  TEDspread         = arima.sim(list(ar = 0.93), n_obs) * 0.01,
  GPR_daily         = exp(rnorm(n_obs, sd = 0.2)),
  GPR_actions       = exp(rnorm(n_obs, sd = 0.3)),
  VIX_innov         = rnorm(n_obs, sd = 1.5),
  VVIX_innov        = rnorm(n_obs, sd = 1.0),
  ShadowRate_surp   = rnorm(n_obs, sd = 0.05),
  FF_futures_surp   = rnorm(n_obs, sd = 0.04)
)

my_mapping <- list(
  Trade           = c("BDI_chg", "TradeFX_chg"),
  Financial       = c("FRAOIS", "TEDspread"),
  Geopolitical    = c("GPR_daily", "GPR_actions"),
  Behavioral      = c("VIX_innov", "VVIX_innov"),
  Monetary_Policy = c("ShadowRate_surp", "FF_futures_surp")
)

my_periods <- list(
  Calm   = as.Date(c("2018-01-02", "2019-12-31")),
  Stress = as.Date(c("2020-01-01", "2021-12-31"))
)

my_channels <- build_channel_composites(
  proxy_grid  = my_proxies,
  mapping     = my_mapping,
  standardise = "rolling_252"
)

head(my_channels, 3)

A trimmed Stage 1 estimate on the Calm sub-period:

calm_dates    <- my_periods$Calm
returns_calm  <- my_returns[paste0(calm_dates[1], "/", calm_dates[2])]

F_calm <- compute_wqte_matrix(
  returns   = returns_calm,
  scale     = 5,
  tau       = 0.50,
  n_cores = 1,
)

abs_thr_calm <- quantile(
  F_calm[upper.tri(F_calm) | lower.tri(F_calm)],
  probs = 0.75, na.rm = TRUE
)

links_calm <- which(F_calm >= abs_thr_calm, arr.ind = TRUE)
nrow(links_calm)

A Stage 2 IV/2SLS attribution on the same window:

channels_calm <- my_channels[
  my_channels$Date >= calm_dates[1] & my_channels$Date <= calm_dates[2], ]

iv_calm <- iv_2sls_attribute(
  returns_period  = returns_calm,
  channels_period = channels_calm,
  links           = links_calm,
  cluster_se      = TRUE
)

iv_calm$shares

End-to-end pipeline call on the synthetic data:

synth_results <- run_contagion_pipeline(
  returns       = my_returns,
  channels      = my_channels,
  periods       = my_periods,
  scale         = 5,
  tau           = 0.50,
  abs_threshold = abs_thr_calm,
  methods       = c("iv2sls"),
  bootstrap_B   = 199,
  n_cores = 1
)

synth_results$summary_table

The synthetic panel is too small for inference to be meaningful, but running the chain end-to-end is the cleanest way to verify that the data contracts are satisfied before committing compute to a real estimation.

Common pitfalls

A few user errors recur in support requests:

Date misalignment. my_proxies$Date must match index(my_returns) exactly; the pipeline performs an inner_join and silently drops dates that do not match. Always inspect nrow(my_channels) after composites are built.
Levels rather than changes. Channel proxies should be stationary. Pass first-differenced spreads, log-changes of indices, or innovations from a fitted model — never raw levels of an integrated series.
Too few markets. WQTE is defined for $N \ge 3$, but Stage 2 attribution needs enough directional links per period to estimate five channel coefficients. Plan for at least eight markets and a sub-period spanning 250 trading days.
Wrong threshold base. When using abs_threshold = NULL the pipeline defaults to the first listed period; if your first period is a stress period the resulting threshold will be conservative and may zero out links in calmer periods. List a calm period first when relying on the default.

These pitfalls aside, the package’s contracts are deliberately minimal: an xts of returns, a data.frame of proxies, and a list of period endpoints. Anything that satisfies those three constraints can be analysed with the same machinery that produces the headline results in the paper.

Session info

sessionInfo()
#> R version 4.1.2 (2021-11-01)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Ubuntu 22.04.5 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.10.0
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_IN       LC_NUMERIC=C         LC_TIME=en_IN       
#>  [4] LC_COLLATE=C         LC_MONETARY=en_IN    LC_MESSAGES=en_IN   
#>  [7] LC_PAPER=en_IN       LC_NAME=C            LC_ADDRESS=C        
#> [10] LC_TELEPHONE=C       LC_MEASUREMENT=en_IN LC_IDENTIFICATION=C 
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] dplyr_1.1.4             xts_0.14.1              zoo_1.8-14             
#> [4] contagionchannels_0.1.3
#> 
#> loaded via a namespace (and not attached):
#>  [1] bslib_0.9.0        compiler_4.1.2     pillar_1.11.1      jquerylib_0.1.4   
#>  [5] tools_4.1.2        digest_0.6.37      tibble_3.3.0       jsonlite_2.0.0    
#>  [9] evaluate_1.0.5     lifecycle_1.0.5    lattice_0.20-45    pkgconfig_2.0.3   
#> [13] rlang_1.2.0        Matrix_1.5-4.1     igraph_2.2.0       cli_3.6.6         
#> [17] yaml_2.3.10        parallel_4.1.2     SparseM_1.84-2     xfun_0.53         
#> [21] fastmap_1.2.0      multitaper_1.0-17  knitr_1.50         generics_0.1.4    
#> [25] sass_0.4.10        vctrs_0.6.5        MatrixModels_0.5-1 tidyselect_1.2.1  
#> [29] grid_4.1.2         glue_1.8.0         R6_2.6.1           survival_3.2-13   
#> [33] waveslim_1.8.5     rmarkdown_2.30     magrittr_2.0.4     htmltools_0.5.8.1 
#> [37] MASS_7.3-55        splines_4.1.2      quantreg_6.1       cachem_1.1.0

Using Custom Datasets

Avishek Bhandari

2026-05-05