diagnostic_summary: Print aggregated diagnostic information for a PanelMatch...

In PanelMatch: Matching Methods for Causal Inference with Time-Series Cross-Sectional Data

Print aggregated diagnostic information for a PanelMatch analysis

Description

Prints a diagnostic report that is otherwise obtainable via separate calls to summary.PanelMatch(), compare_treated_observations(), summary.PanelBalance(), and placebo_test(). This function does not perform any new estimation, matching, or refinement – it only aggregates and formats results the user has already computed and supplied. Sections for which the corresponding object is not provided are simply reported as not available; this function will not run those steps on the user's behalf, consistent with the package's philosophy of requiring users to explicitly perform and inspect each stage of an analysis. Each underlying piece already has its own print/ summary/plot methods (PanelMatch, PanelBalance, PanelEstimate); this function is a higher-level report layered on top, not a new object type.

Usage

diagnostic_summary(
  pm.object,
  panel.data = NULL,
  covariates = NULL,
  pb.object = NULL,
  placebo.results = NULL,
  balance.threshold = 0.2,
  empty.set.threshold = 0.25,
  min.matched.sets = 10,
  digits = 3,
  ...
)

Arguments

pm.object	A PanelMatch object. Required.
panel.data	A PanelData object corresponding to pm.object. Required only if covariates is supplied.
covariates	Character vector of covariate names to pass to compare_treated_observations(), comparing matched and unmatched treated units. If NULL (default), this section is omitted. If pm.object has qoi = "ate", this comparison is run for both "att" and "atc" automatically.
pb.object	A PanelBalance object, as returned by get_covariate_balance(). If NULL (default), the balance section is omitted. Only refined balance results are shown, regardless of whether pb.object was built with include.unrefined = TRUE. If pm.object has qoi = "ate", balance results for both "att" and "atc" are reported automatically. pb.object may contain balance results for multiple PanelMatch configurations, since get_covariate_balance() accepts more than one via .... Only the configuration matching pm.object is used; the others (if any) are ignored. This match is made by variable name: get_covariate_balance() names each configuration using the argument name at its own call site (e.g. get_covariate_balance(pm.obj, ...) produces a configuration named "pm.obj"), so pm.object must be passed to diagnostic_summary() using that same variable name for the match to succeed – passing it through an intermediate variable with a different name, or as a more complex expression, will fail to match and raise an error naming the configurations that were found instead.
placebo.results	Output of placebo_test(..., plot = FALSE). If NULL (default), the placebo section is omitted.
balance.threshold	Numeric. Refined covariate-period balance statistics (in standard deviations) exceeding this value in absolute terms are counted and flagged (addressing poor post-refinement balance). Default 0.2.
empty.set.threshold	Numeric, between 0 and 1. If the proportion of treated observations with no matched controls exceeds this threshold (for any QOI present in pm.object), this is flagged (addressing too few matched sets, as a proportion). Default 0.25.
min.matched.sets	Numeric. If the number of non-empty matched sets (for any QOI present in pm.object) falls below this count, this is flagged (addressing too few matched sets, in absolute terms). Default 10.
digits	Number of digits to round printed numeric output to. Default 3.
...	Additional arguments passed to summary.PanelMatch().

Details

If pm.object has qoi = "ate", the covariate balance and matched-vs-unmatched-treated sections are automatically computed for both "att" and "atc" and reported side by side, since both are always available for an ate PanelMatch object.

In addition to the printed report, this function raises R warnings for four conditions: too few matched sets, both as a proportion (via empty.set.threshold) and in absolute terms (via min.matched.sets); poor covariate balance persisting after refinement (via balance.threshold); and any placebo test estimate whose confidence interval excludes 0 (if placebo.results is supplied – any such estimate is flagged, since there is no tunable threshold for this check).

Value

Invisibly returns a plain list with the following components, for programmatic use (e.g. exporting a table for a manuscript appendix):

checks

A data.frame with one row per threshold check, giving the QOI, configuration (if applicable), metric, a human-readable label, the observed value, the threshold, which direction is considered problematic, and whether the check is flagged.

matched.set.summary

As returned by summary.PanelMatch().

matched.treated.summary

As returned by compare_treated_observations(), if covariates was supplied.

balance.summary

As returned by summary.PanelBalance(), if pb.object was supplied.

placebo.table

The placebo test table, if placebo.results was supplied.

PanelMatch documentation built on Oct. 2, 2026, 1:07 a.m.