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.
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,
...
)Invisibly returns a plain list with the following components, for programmatic use (e.g. exporting a table for a manuscript appendix):
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.
As returned by summary.PanelMatch().
As returned by
compare_treated_observations(), if covariates was
supplied.
As returned by summary.PanelBalance(),
if pb.object was supplied.
The placebo test table, if placebo.results
was supplied.
A PanelMatch object. Required.
A PanelData object corresponding to
pm.object. Required only if covariates is supplied.
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.
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.
Output of placebo_test(..., plot = FALSE).
If NULL (default), the placebo section is omitted.
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.
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.
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.
Number of digits to round printed numeric output to. Default 3.
Additional arguments passed to summary.PanelMatch().
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).