postshock: An R Package for Donor-Adjusted Forecasting After Structural Shocks

arXiv:2610.11841 · stat.CO · Submitted 2026-10-08 · Read on arXiv

Listen

Radio episode about this paper

Transcript

Introduction to the show: ident: Statistics. The day in statistics: methods, theory and the inference under them.

Tom: I'm Tom.

Jane: And I'm Jane, here with Lu, Meng and our in-house large language model, Lalam.

Tom: We're looking at the paper: "postshock: An R Package for Donor-Adjusted Forecasting After Structural Shocks".

Jane: Here's the gist of the paper. We present the postshock R package, which implements and extends a donor-based framework for forecasting when a structural shock is known and the target response of interest is not yet observed This package provides an end-to-end workflow for donor-effect estimation, donor weighting, target baseline forecasting, and post-shock adjustment.

Tom: The core methodological concept The central idea of Lin and Eck (2021) is to estimate shock effects from completed historical donor episodes, aggregate these estimated donor-specific effects, and use the resulting quantity to adjust a baseline forecast for the newly shocked target.

Jane: The distinctive feature of this framework is therefore not aggregation alone, but the information being transferred: estimated shock effects from completed outside episodes are borrowed before the corresponding response of the target is available.

Tom: This distinguishes donor-based adjustment from methods that aggregate complete forecasts or weight donor outcomes to construct counterfactual trajectories.

Paper summary: Tom: Moving into the summary of "postshock: An R Package for Donor-Adjusted Forecasting After Structural Shocks," we see they present an R package designed to forecast when a structural shock is known but you haven't observed the target response yet.

Jane: The main claim is that this package implements and extends a donor-based framework. It handles estimating shock effects from historical donor episodes, balances donors using specified matching features, and then transfers that adjustment into a baseline forecast for your target series.

Lu: The central idea they are building on is from Lin and Eck, two thousand twenty-one <ref:2610.11841#pg2>. They estimate shock effects from completed historical donor episodes, aggregate those estimated donor-specific effects, and use that resulting quantity to adjust a baseline forecast for the newly shocked target.

Meng: They distinguish this approach by saying it’s not just about aggregation; it's about transferring the information itself—borrowing estimated shock effects from completed outside episodes before you even see your target response.

Lalam: This distinguishes donor-based adjustment from methods that just aggregate complete forecasts or weight donor outcomes to build counterfactual trajectories. The aggregate adjustment targets the mean, or a covariate-dependent mean, of the shock-effect distribution rather than exact recovery of the realized effect.

Tom: Architecturally, they organize this as a modular workflow separating donor-effect estimation and weighting from your target-specific forecasting model. This allows for flexibility across different modeling approaches.

Jane: They provide interfaces like SynthPrediction for conditional mean forecasting through ARIMA and ARIMAX models, and SynthVolForecast for conditional variance forecasting through GARCH X models.

Lu: They also include extra functionality like structured donor pools, control-shock regressors, automated GARCH X order selection, and reproducible empirical workflows.

Meng: From a production standpoint, the focus on modularity is good because it means we can reuse the same weighting mechanism across different forecasting tasks if that works well for our specific needs.

Lalam: The paper is available as an R package, offering integrated workflows for conditional mean and variance forecasting after structural shocks.

Conclusion: Tom: Thinking about the title "postshock: An R Package for Donor-Adjusted Forecasting After Structural Shocks," it really boils down to providing a ready-made tool for this specific forecasting problem.

Jane: It’s essentially a way to systematically use historical donor episode data to adjust future forecasts when you know something big has changed but the outcome you care about is still in the future.

Lu: The authors are providing an end-to-end workflow that handles everything from estimating those donor effects to the final post-shock adjustment, with a modular design for flexibility.

Meng: For someone trying to deploy this, it means you get these pre-built interfaces for conditional mean and variance forecasts that you can plug into your existing system if it fits your modeling needs.

Lalam: The implication is that this framework offers a way to borrow information across related time series by balancing separate estimations of heterogeneous units against pooling information, which is important in panel data forecasting.

Tom: So the big picture here is using completed donor episodes to reduce forecast risk when structural shocks are present, as long as you accept targeting the mean rather than trying to hit the exact realized effect.

Jane: That’s a concrete summary: it's about reducing risk by borrowing information systematically from past donor behavior into future forecasts after a known structural change.

University of Illinois Urbana-Champaign

stat.CO

Submitted: 2026-10-08

Updated: 2026-11-15

Comments: 19 pages, 3 figures, 5 tables; supplementary material included. Revised exposition and notation; added a workflow diagram, a complete executable example, and computational timings. Original empirical results unchanged. The postshock R package is available on CRAN

License: http://arxiv.org/licenses/nonexclusive-distrib/1.0/

Importance score: 90/100

The gist: We present the postshock R package, which implements and extends a donor-based framework for forecasting when a structural shock is known and the target response of interest is not yet observed This…

Key concepts

Donor-based framework
This is a method where shock effects are estimated from historical 'donor' episodes. These estimates are then aggregated using weights to adjust a baseline forecast for a new, shocked target. The key is transferring estimated effects from completed outside episodes to inform the current forecast.
Postshock adjustment
This process involves adjusting an existing baseline forecast after a structural shock is known but the actual response of the target hasn't been measured yet. It uses aggregated donor-specific shock effects to modify the initial prediction, targeting a specific mean or covariate-dependent mean.
Donor balancing mechanism (dbw)
This function constructs weights for different donors so that their combination closely resembles the target in selected matching features. The goal is to find weights that make the weighted donor feature vector similar to the target's feature vector, controlled by a regularization parameter lambda.
Conditional forecasting
The package offers tools for generating forecasts based on specific conditions, such as conditional-mean forecasting (SynthPrediction) or conditional-variance forecasting (SynthVolForecast). This allows users to predict outcomes given certain known information or scenarios.

Terminology

Summary

We present the postshock R package, which implements and extends a donor-based framework for forecasting when a structural shock is known and the target response of interest is not yet observed This package provides an end-to-end workflow for donor-effect estimation, donor weighting, target baseline forecasting, and post-shock adjustment. p. 0

The core methodological concept

The central idea of Lin and Eck (2021) is to estimate shock effects from completed historical donor episodes, aggregate these estimated donor-specific effects, and use the resulting quantity to adjust a baseline forecast for the newly shocked target. The distinctive feature of this framework is therefore not aggregation alone, but the information being transferred: estimated shock effects from completed outside episodes are borrowed before the corresponding response of the target is available. p. 0 This distinguishes donor-based adjustment from methods that aggregate complete forecasts or weight donor outcomes to construct counterfactual trajectories. p. 0 The aggregate adjustment is not generally intended to recover the realized target-specific shock effect exactly, but rather targets the mean, or a covariate-dependent mean, of the shock-effect distribution. p. 2

Package architecture and components

The postshock package organizes donor-based post-shock forecasting as a modular workflow that separates donor-effect estimation and weighting from the target-specific forecasting model. The workflow decomposes the problem into a common sequence of operations: historical shock episodes are indexed relative to their respective boundaries, donor-specific shock effects are estimated, donor weights are constructed from selected matching features, a baseline model is fitted to the target observations available at the forecast origin, and the aggregated donor effect is added to the resulting forecast. p. 3 The package provides interfaces like SynthPrediction for conditional-mean forecasting and SynthVolForecast for conditional-variance forecasting. p. 3

Donor balancing mechanism

The function dbw constructs weights so that a weighted donor combination resembles the target in selected matching features. The general optimization problem in dbw seeks weights for which this weighted donor feature vector is close to the target feature vector z0. p. 5 The parameter λ ≥ 0 controls the strength of the optional regularization term pen(w), which is either the l1 norm w1 or the squared l2 norm w squared of the donor weights. p. 5

Structured extensions and applications

The package includes extensions such as a multiple-donor-pool interface for organizing donors into user-defined groups before aggregation and a control-shock interface for controlling for additional known events in the target fitting period. Applications like ConocoPhillips demonstrate conditional-mean forecasting and multiple donor pools, while IYG illustrates conditional-variance forecasting under alternative analyst-defined donor sets. p. 1

Conclusion

The postshock package provides R tools for donor-adjusted forecasts after structural shocks in conditional means and conditional variances. The empirical examples show that the same type of donor adjustment need not improve every baseline or specification. p. 2 The package is available from CRAN. p. 3

Green — the paper says it, and the page is printed. Red — no passage carries it, so treat that sentence as unverified. The same check runs on your own text: check a summary against its source, $5.

Improvements for AI systems

  1. Modular Workflow Implementation: The system can separate donor construction and weighting, donor-specific effect estimation, target baseline forecasting, and post-shock adjustment into reusable components to create a general implementation of the donor-based framework across different applications.

  2. Conditional Mean Forecasting Enhancement: The system can implement SynthPrediction to support ARIMA, seasonal ARIMA, and ARIMAX specifications while supporting user selected multi-step forecast horizons with a single aggregate shock adjustment added to every element.

  3. Conditional Variance Forecasting Extension: The system can implement SynthVolForecast to apply the donor-adjustment principle to GARCH-X models and use auto garchx for automated model order selection, combining donor-specific variance adjustments using the dbw weights.

  4. Structured Shock Handling: The system can include extensions like SynthPredictionMultiPool to organize donors into named pools and SynthVolForecast to incorporate a control-shock interface for additional known events in the target side baseline model.

  5. Covariate and Feature Matching Flexibility: The system can use the dbw function to construct weights based on user selected matching features, allowing users to specify feature rows from lookback observations or auxiliary series transformations before optimization.

  6. Comparison of Forecasting Approaches: The system can perform comparisons between donor-based post-shock forecasting and other approaches like intercept correction and forecast combination by explicitly aggregating different statistical objects (e.g., Forecast-combination methods apply weights to complete forecasts for the target quantity versus donor-based post-shock forecasting instead fits a separate baseline forecast for the target and applies the aggregation weights to estimated donor-specific shock effects).

Related papers