ConocoPhillips example

The target episode is the large decline in the ConocoPhillips (COP) share price in March 2020. Five earlier crisis and oil-market episodes are used as donors. The aligned series, covariates, and shock timing information are stored in the cop_oil_postshock object loaded in the previous section.

Fit a one-step post-shock forecast

We set k = 1 to forecast the first observation after the target’s pre-shock period. The call below uses the same feature columns, centering and scaling choices, and L2 penalty as the direct dbw() example above.

The covariate matrices are used to construct donor weights. Because covariate_indices = NULL, they are not included as regressors in the ARIMA models. In that case, each donor model contains the post-shock indicator, while the target baseline is fitted without covariate regressors.

cop_fit <- SynthPrediction(
  Y_series_list = cop_oil_postshock$Y,
  covariates_series_list = cop_oil_postshock$X,
  shock_time_vec = cop_oil_postshock$shock_time_vec,
  shock_length_vec = cop_oil_postshock$shock_length_vec,
  k = 1L,
  dbw_indices = seq_len(ncol(cop_oil_postshock$X[[1]])),
  dbw_center = TRUE,
  dbw_scale = TRUE,
  use_dbw = TRUE,
  covariate_indices = NULL,
  seasonal = TRUE,
  penalty_lambda = 1e-2,
  penalty_normchoice = "l2"
)

Setting seasonal = TRUE allows the function to consider a seasonal specification when a meaningful seasonal frequency is detected. It does not require every fitted model to contain a seasonal component.

Inspect forecasts

The returned object has three main components. predictions contains the forecast versions, linear_combinations contains the donor weights, and meta contains donor-specific effects and model information.

names(cop_fit)
#> [1] "linear_combinations" "predictions"         "meta"
names(cop_fit$predictions)
#> [1] "unadjusted"      "adjusted"        "arithmetic_mean"
names(cop_fit$meta)
#> [1] "n_donors"       "shock_time"     "shock_length"   "dbw_status"    
#> [5] "weights"        "omega_vec"      "combined_omega" "arima_order"   
#> [9] "ic_used"

Compare the forecasts

The first post-shock observation occurs at the index immediately following the last pre-shock observation of the target.

forecast_index <- cop_oil_postshock$shock_time_vec[1] + 1L

observed_value <- as.numeric(
  cop_oil_postshock$Y[[1]][forecast_index]
)

forecast_values <- c(
  as.numeric(cop_fit$predictions$unadjusted[1]),
  as.numeric(cop_fit$predictions$arithmetic_mean[1]),
  as.numeric(cop_fit$predictions$adjusted[1])
)

cop_forecast_table <- data.frame(
  Method = c(
    "Observed value",
    "Unadjusted",
    "Arithmetic mean",
    "DBW adjusted"
  ),
  Value = c(
    observed_value,
    forecast_values
  ),
  Absolute_error = c(
    NA_real_,
    abs(forecast_values - observed_value)
  )
)

knitr::kable(
  cop_forecast_table,
  digits = 3,
  col.names = c("Method", "Value", "Absolute error"),
  caption = paste(
    "One-step forecast comparison for the March 2020",
    "ConocoPhillips shock episode."
  )
)

The observed value is included only for retrospective evaluation. It is not supplied to SynthPrediction() when the target model or donor weights are estimated.

As shown in the table, both donor-adjusted forecasts reduce the absolute error relative to the unadjusted baseline. The DBW-adjusted forecast also has a smaller error than the arithmetic-mean adjustment in this example.

The improvement over the unadjusted baseline is substantial, whereas the additional gain from DBW weighting over equal weighting is more modest. Because the comparison is based on a single retrospective one-step forecast, it should be interpreted as an illustration of the workflow rather than general evidence that DBW always performs better.

Inspect donor weights and the combined adjustment

The donor weights used by SynthPrediction() are stored in linear_combinations. The estimated donor-specific post-shock effects are stored in meta$omega_vec.

cop_donor_summary <- data.frame(
  Donor = sub(
    "^Y_",
    "",
    names(cop_oil_postshock$Y)[-1]
  ),
  Weight = as.numeric(cop_fit$linear_combinations),
  Estimated_effect = as.numeric(cop_fit$meta$omega_vec)
)

knitr::kable(
  cop_donor_summary,
  digits = 3,
  col.names = c(
    "Donor",
    "DBW weight",
    "Estimated post-shock effect"
  ),
  caption = "Donor weights and estimated effects for the COP example."
)

Donors with weights close to zero make little contribution to the final adjustment, even when their estimated post-shock effects are relatively large, whereas donors with larger weights have greater influence.

data.frame(
  Unadjusted_forecast =
    as.numeric(cop_fit$predictions$unadjusted[1]),
  Combined_donor_effect =
    as.numeric(cop_fit$meta$combined_omega),
  Adjusted_forecast =
    as.numeric(cop_fit$predictions$adjusted[1])
) |>
  knitr::kable(
    digits = 3,
    col.names = c(
      "Unadjusted forecast",
      "Combined donor effect",
      "DBW-adjusted forecast"
    ),
    caption = "Construction of the DBW-adjusted COP forecast."
  )

The sign of the combined donor effect determines the direction of the adjustment. In this example, the combined effect is negative, so it lowers the unadjusted forecast and moves it closer to the observed post-shock value.

Define the donor pools

Pools are supplied as a named list. Each element contains donor names that must match the corresponding entries in names(Y_series_list).

cop_pools <- list(
  supply = "Y_2014_11_28",
  demand = c(
    "Y_2008_03_17",
    "Y_2008_09_09",
    "Y_2008_09_15",
    "Y_2008_09_29"
  )
)

cop_pool_table <- data.frame(
  Pool = names(cop_pools),
  Donors = unname(
    vapply(
      cop_pools,
      function(x) {
        paste(
          gsub("_", "-", sub("^Y_", "", x)),
          collapse = ", "
        )
      },
      character(1)
    )
  )
)

knitr::kable(
  cop_pool_table,
  row.names = FALSE,
  col.names = c("Pool", "Donor episodes"),
  caption = "Structured donor pools for the ConocoPhillips example."
)

The first element of Y_series_list is always treated as the target. Only donor names should therefore be included in pools; the target is added automatically when each pool-specific model is fitted.

Fit the MultiPool specification

Providing the pools argument causes SynthPrediction() to use the MultiPool extension. The function retains a common unadjusted target forecast and estimates a separate donor adjustment within each pool.

Here, pool_use_dbw = TRUE applies donor balancing within each pool. Because the supply pool contains only one donor, its within-pool weight is necessarily one. Donor balancing primarily affects the multi-donor demand pool.

cop_multipool <- SynthPrediction(
  Y_series_list = cop_oil_postshock$Y,
  covariates_series_list = cop_oil_postshock$X,
  shock_time_vec = cop_oil_postshock$shock_time_vec,
  shock_length_vec = cop_oil_postshock$shock_length_vec,
  k = 1L,
  covariate_indices = NULL,
  seasonal = TRUE,
  dbw_indices = seq_len(
    ncol(cop_oil_postshock$X[[1]])
  ),
  dbw_center = TRUE,
  dbw_scale = TRUE,
  penalty_lambda = 1e-2,
  penalty_normchoice = "l2",
  pools = cop_pools,
  pool_agg = "sum",
  base_use_dbw = FALSE,
  pool_use_dbw = TRUE
)

With pool_agg = "sum", the pool-specific adjustments are treated as additive components of the total post-shock adjustment. This is a modeling choice rather than a property automatically inferred from the data. Users can instead select pool_agg = "weighted" and provide a named numeric vector through pool_weights.

Inspect the pool-specific adjustments

The estimated adjustment for each pool is stored in meta$multi_pool$pool_effects, while the aggregated adjustment is stored in meta$multi_pool$aggregated_effect.

cop_pool_effects <- data.frame(
  Pool = names(
    cop_multipool$meta$multi_pool$pool_effects
  ),
  Estimated_adjustment = as.numeric(
    cop_multipool$meta$multi_pool$pool_effects
  )
)

knitr::kable(
  cop_pool_effects,
  row.names = FALSE,
  digits = 3,
  col.names = c(
    "Pool",
    "Estimated pool adjustment"
  ),
  caption = "Pool-specific adjustments for the ConocoPhillips example."
)

The MultiPool-adjusted forecast is returned in predictions$adjusted_multipool.

cop_multipool_values <- c(
  as.numeric(
    cop_multipool$predictions$unadjusted[1]
  ),
  as.numeric(
    cop_fit$predictions$adjusted[1]
  ),
  as.numeric(
    cop_multipool$predictions$adjusted_multipool[1]
  )
)

cop_multipool_table <- data.frame(
  Method = c(
    "Observed value",
    "Unadjusted",
    "Single-pool DBW",
    "MultiPool (sum)"
  ),
  Value = c(
    observed_value,
    cop_multipool_values
  ),
  Absolute_error = c(
    NA_real_,
    abs(cop_multipool_values - observed_value)
  )
)

knitr::kable(
  cop_multipool_table,
  digits = 3,
  col.names = c("Method", "Value", "Absolute error"),
  caption = paste(
    "Comparison of single-pool and MultiPool forecasts",
    "for the ConocoPhillips example."
  )
)

In this example, both pool-level effects lower the unadjusted forecast. Their sum produces the MultiPool adjustment and moves the forecast closer to the observed post-shock value.

The result should be interpreted as an illustration of how economically meaningful donor groups can be represented in the package. A closer forecast in this single retrospective example does not imply that splitting donors into multiple pools will always improve forecasting performance.

Load the IYG example

The target series is IYG, a financial-sector exchange-traded fund, and the target shock is the 2016 U.S. presidential election. Historical election and political-uncertainty episodes serve as potential donors.

The processed inputs are distributed with postshock in the iyg_onestep_input object.

data("iyg_onestep_input", package = "postshock")

names(iyg_onestep_input)
#> [1] "description"      "target_symbol"    "target_event"     "inputs"          
#> [5] "donor_pool_specs" "evaluation"
names(iyg_onestep_input$inputs)
#> [1] "all"            "restricted"     "elections_only"

The object provides three analyst-defined donor-pool configurations: all, restricted, and elections_only. In this vignette, we use the restricted configuration to demonstrate the main workflow. The donor-pool choice is treated as part of the analysis design rather than selected using the realized forecast error.

iyg_restricted <- iyg_onestep_input$inputs$restricted

names(iyg_restricted)
#> [1] "target_event"           "donor_events"           "Y_series_list"         
#> [4] "covariates_series_list" "target_covariates"      "shock_time_vec"        
#> [7] "shock_length_vec"

The restricted input contains the target and donor return series, the donor covariate matrices, a separate target covariate matrix, and the shock-timing vectors required by SynthVolForecast().

iyg_restricted$target_event
#> [1] "2016 Election"
iyg_restricted$donor_events
#> [1] "2012 Election"        "Brexit Poll Released" "Brexit"

c(
  number_of_series =
    length(iyg_restricted$Y_series_list),
  number_of_donors =
    length(iyg_restricted$donor_events),
  donor_covariate_sets =
    length(iyg_restricted$covariates_series_list),
  shock_time_entries =
    length(iyg_restricted$shock_time_vec),
  shock_length_entries =
    length(iyg_restricted$shock_length_vec)
)
#>     number_of_series     number_of_donors donor_covariate_sets 
#>                    4                    3                    3 
#>   shock_time_entries shock_length_entries 
#>                    4                    4

The restricted configuration contains one target series and three donor series. The three donor covariate matrices correspond to the three donor episodes, while the shock-time and shock-length vectors contain one entry for every target or donor series.

Produce a variance forecast

We use the restricted donor-pool configuration and produce a one-step-ahead conditional variance forecast. This configuration contains the 2012 Election, Brexit Poll Released, and Brexit donor episodes.

The GARCH-X orders are selected automatically. With garch_order = NULL, SynthVolForecast() calls auto_garchx() separately for each donor and for the pre-shock target series. Candidate specifications are compared using BIC over GARCH orders up to max.p = 3 and ARCH orders up to max.q = 3, including both symmetric and asymmetric specifications.

The donor covariates are used for DBW matching. Because covariate_indices = NULL, the donor-side variance models contain the post-shock indicator but do not include additional covariates as GARCH-X regressors.

iyg_fit <- SynthVolForecast(
  Y_series_list =
    iyg_restricted$Y_series_list,
  covariates_series_list =
    iyg_restricted$covariates_series_list,
  target_covariates =
    iyg_restricted$target_covariates,
  shock_time_vec =
    iyg_restricted$shock_time_vec,
  shock_length_vec =
    iyg_restricted$shock_length_vec,
  k = 1L,
  dbw_indices = seq_len(
    ncol(iyg_restricted$target_covariates)
  ),
  dbw_center = TRUE,
  dbw_scale = TRUE,
  penalty_lambda = 1e-2,
  penalty_normchoice = "l2",
  covariate_indices = NULL,
  garch_order = NULL,
  max.p = 3L,
  max.q = 3L,
  vcov.type = "robust",
  return_fits = FALSE
)

iyg_selected_orders <- do.call(
  rbind,
  c(
    iyg_fit$meta$donor_orders,
    list(iyg_fit$meta$target_order)
  )
)

iyg_order_table <- data.frame(
  Model = c(
    paste("Donor:", iyg_restricted$donor_events),
    paste("Target:", iyg_restricted$target_event)
  ),
  ARCH_q = iyg_selected_orders[, 1],
  GARCH_p = iyg_selected_orders[, 2],
  Asymmetry_o = iyg_selected_orders[, 3]
)

knitr::kable(
  iyg_order_table,
  row.names = FALSE,
  col.names = c(
    "Model",
    "ARCH order (q)",
    "GARCH order (p)",
    "Asymmetry indicator (o)"
  ),
  caption = paste(
    "Orders selected automatically by BIC for the",
    "donor and target variance models."
  )
)

Inspect donor weights and variance adjustments

The donor balancing weights are stored in linear_combinations, while the estimated donor-specific adjustments in the conditional variance equation are stored in meta$omega_vec.

iyg_donor_summary <- data.frame(
  Donor = as.character(iyg_restricted$donor_events),
  Weight = as.numeric(
    iyg_fit$linear_combinations
  ),
  Estimated_adjustment = as.numeric(
    iyg_fit$meta$omega_vec
  )
)

knitr::kable(
  iyg_donor_summary,
  row.names = FALSE,
  digits = 6,
  col.names = c(
    "Donor episode",
    "DBW weight",
    "Estimated variance adjustment"
  ),
  caption = paste(
    "Donor weights and estimated variance adjustments",
    "for the restricted IYG specification."
  )
)

In this example, Brexit and Brexit Poll Released receive the largest DBW weights, while the 2012 Election receives a smaller but still positive weight. All three estimated variance adjustments are positive, so each donor contributes to raising the target’s baseline variance forecast.

The weighted donor adjustment is stored in meta$combined_omega.

iyg_adjustment_table <- data.frame(
  Unadjusted_forecast = as.numeric(
    iyg_fit$predictions$unadjusted[1]
  ),
  Combined_adjustment = as.numeric(
    iyg_fit$meta$combined_omega
  ),
  Adjusted_forecast = as.numeric(
    iyg_fit$predictions$adjusted[1]
  )
)

knitr::kable(
  iyg_adjustment_table,
  row.names = FALSE,
  digits = 6,
  col.names = c(
    "Unadjusted variance forecast",
    "Combined donor adjustment",
    "DBW-adjusted variance forecast"
  ),
  caption = "Construction of the DBW-adjusted IYG variance forecast."
)

The sign of the combined donor adjustment determines the direction in which the baseline variance forecast is changed. In this example, the combined adjustment is positive, so it raises the unadjusted variance forecast.

SynthVolForecast() enforces a positive adjusted variance forecast. This constraint is not binding in the present example because the combined adjustment is positive.

iyg_proxy_index <-
  iyg_restricted$shock_time_vec[1] + 1L

iyg_observed_proxy <- as.numeric(
  iyg_restricted$Y_series_list[[1]][iyg_proxy_index]
)^2

iyg_forecast_values <- c(
  as.numeric(
    iyg_fit$predictions$unadjusted[1]
  ),
  as.numeric(
    iyg_fit$predictions$arithmetic_mean[1]
  ),
  as.numeric(
    iyg_fit$predictions$adjusted[1]
  )
)

iyg_forecast_table <- data.frame(
  Method = c(
    "Observed squared-return proxy",
    "Unadjusted",
    "Arithmetic mean",
    "DBW adjusted"
  ),
  Variance = c(
    iyg_observed_proxy,
    iyg_forecast_values
  ),
  Absolute_error = c(
    NA_real_,
    abs(
      iyg_forecast_values -
        iyg_observed_proxy
    )
  )
)

knitr::kable(
  iyg_forecast_table,
  row.names = FALSE,
  digits = 6,
  col.names = c(
    "Method",
    "Variance",
    "Absolute error"
  ),
  caption = paste(
    "One-step variance forecast comparison for IYG",
    "under the restricted donor-pool specification."
  )
)

Align episodes consistently

The target and donor series should be aligned relative to their own shock times. The entry in shock_time_vec identifies the final pre-shock observation, and the shock effect begins at the following observation.

The ordering of the series, covariate matrices, shock times, and shock lengths must remain consistent. For MultiPool analyses, donor names must also match the names used in the pools specification.

Separate donor matching from model regressors

The arguments dbw_indices and covariate_indices have different roles.

• dbw_indices selects the pre-shock covariates used to construct donor balancing weights.
• covariate_indices selects covariates included directly as regressors in the donor forecasting models.

Covariates may therefore be used for donor matching without being included in the ARIMA, ARIMAX, or GARCH-X equations. This distinction should be made explicit when defining an analysis.

Choose donors using substantive information

Donor episodes should be selected using information available independently of the realized target outcome. Economic interpretation, event type, market environment, and pre-shock comparability may all be relevant.

The MultiPool extension can be useful when donors represent distinct mechanisms. However, the pool definitions and aggregation rule are modeling choices. In particular, pool_agg = "sum" assumes that the pool-specific adjustments can be treated as additive components.

Inspect weights and convergence

Large DBW weights indicate donors that contribute more strongly to the synthetic adjustment under the selected pre-shock features and constraints. They should not be interpreted as probabilities that historical events will recur.

Users should also inspect the DBW convergence information and consider whether the resulting weights are concentrated on only a small number of donors. Alternative feature sets, scaling choices, penalties, or pool definitions may produce different weights.

Interpret empirical variance forecasts carefully

SynthVolForecast() returns forecasts on the conditional variance scale. Taking the square root converts a variance forecast to the corresponding standard-deviation scale.

In empirical applications, the latent conditional variance is not directly observed. A squared return can be used as a realized-variance proxy, but it is itself noisy. Forecast comparisons based on a single squared return should therefore be interpreted cautiously.

When garch_order = NULL, the GARCH-X specification is selected automatically for each donor and the target. Users who need additional diagnostic information can set return_fits = TRUE and inspect the fitted model objects.

Avoid post-shock information leakage

Donor weights and the target baseline model should be estimated without using the target’s post-shock observations. Historical donor post-shock outcomes are used by design to estimate donor-specific shock effects.

Realized post-shock target values may be used afterward for retrospective evaluation, but they should not influence donor selection, tuning choices, or model specification. Thus, the no-leakage restriction concerns information from the target’s post-shock period, not the already observed post-shock histories of the donor episodes.

See the help pages for dbw(), SynthPrediction(), and SynthVolForecast() for complete argument and return-value documentation.