Skip to main content

Inference Result Schemas

JSON persistence contract

Analysis, validation and donor JSON artefacts use strict JSON: non-finite Python/NumPy numbers and pandas missing scalars become null, including inside arrays and nested containers. null means unavailable; it does not establish the reason or change the recorded result status. Finite estimates, interval bounds and other supported values retain their values. Finite extended-precision NumPy floats that overflow or underflow Python’s float range raise an error rather than becoming unavailable or zero.

Lists and NumPy arrays are written in full, without truncation or flattening. DataFrames retain split orientation (index, columns, data); Series retain a mapping from labels to values. Dates and times use ISO strings. JSON object keys are strings: supported scalar and date/time keys are converted explicitly. Duplicate Series labels, keys that collide after conversion (such as 1 and "1"), non-finite keys and unsupported values raise an error rather than silently discarding or stringifying data. Tuple values become JSON arrays; tuple keys and arbitrary Python objects are unsupported.

The diagnostics whitelist still omits raw fitted matrices and frames; their existing availability metadata remains. Accepted containers have no artificial size cap, so callers remain responsible for the size of explicitly supplied payloads. Historical files with non-standard NaN/Infinity tokens or truncated data must be regenerated from the original analysis inputs.

All analysis payloads are converted before any existing artefact is replaced. Each JSON file is written to a unique temporary file and atomically replaced; failed writes clean up their temporary file and preserve that destination. The artefact family is not a transaction: an I/O failure after an earlier successful replacement can leave files from different runs. JSON configuration saves reject non-finite settings rather than turning them into null, and serialisation errors leave the existing configuration file intact.

geolift_results.json

Schema 1.0 contains the primary unscaled result:

Field Contract
status ok, partial, or failed.
estimand att_unscaled.
att Average post-period treated-minus-counterfactual effect in outcome units.
p_value Two-sided in-space placebo p-value for the average effect.
p_value_method in_space_placebo.
n_placebos, max_n_placebos, possible_placebos, p_value_placebo_mode, placebo_seed, p_value_granularity Finite reference-set metadata.
ci_lower, ci_upper, ci, ci_source Unscaled SparseSC placebo interval or explicit unavailability.
se / se_available No estimator-provided standard error is claimed.
se_approx_from_ci Optional normal approximation from interval width; not a sampling SE.
significance_available, significant Detection availability and p_value < alpha flag.
analysis_window Launch, cooldown, and measurement metadata.
assumption_status, assumption_required, assumption_checks_completed Diagnostic/gate summary; advisory never establishes identification.
warnings, errors, caveats Interpretation controls.

Rendered inference contract

CLI, recipe and pipeline summaries lead with status, errors and warnings. A failed or unknown status, non-empty errors, missing unscaled estimand or non-finite ATT withholds primary inference. Otherwise, significance_available and the stored significant flag determine the displayed decision. An unavailable decision is not reported as non-significance; a retained finite p-value is explicitly diagnostic when significance is unavailable.

The nested ci object supplies canonical lower, upper and level values. Rendering requires ci.available: true, ci.source: sparsesc_unscaled_placebo, ci_source: unscaled, finite ordered bounds and a numeric level strictly in (0, 1). For ci.level: 0.8, the label is 80% CI for average ATT (unscaled). Top-level bounds alone do not establish availability or level, and scaled diagnostics never replace the primary interval. Unavailable intervals retain their recorded unavailable_reason when present.

plot_results() rejects failed or incomplete primary results. Partial plots show status, warnings and uncertainty/significance limitations. The horizontal band represents the interval for the average ATT, not pointwise or simultaneous coverage of the period-by-period effect path. Older incomplete dictionaries must be regenerated; these presentation checks do not change schema 1.0 or the estimator’s numerical output.

geolift_diagnostics.json

Contains pre-period RMS effect and p-value, scaled post-effect diagnostics, period effects, fitted donor-weight summaries, synthetic-control availability, assumption state, analysis window, and warnings/errors. Scaled effects are not interchangeable with the unscaled top-level ATT and interval.

Validation artefacts

data_validation.json records file and model panel construction. When imputation is used, imputation.method is linear_interpolate_within_analysis_windows and imputation.windows records affected-cell counts, period counts, and start/end dates for pre_treatment, cooldown, and measurement. Input missing counts remain available after preparation. When CSV covariates are supplied, covariates records method: pre_treatment_period_mean, the intervention date, retained pre-period count, missing pre-value count, and missing-value handling rule. These are additive fields in schema 1.0.

assumption_validation.json uses schema 1.2. Regression and visual pre-trend checks and the interference screen have gate_eligible: false, with signal, no_signal or indeterminate statuses. A regression signal concerns mean raw unit slopes, not the fitted synthetic trajectory. An unavailable or failed advisory diagnostic remains visible without changing estimator status or significance availability.

Only the experimental pre-period placebo method can have gate_eligible: true and pass, fail, error or skipped status. Its numerical procedure is unchanged; passing means only that its configured discrepancy criterion was met. It does not establish causal identification or calibrated error rates.

When checks ran without an eligible gate, overall_status is advisory and overall_valid is null. Otherwise the overall status reflects eligible placebo checks, or is skipped when none ran. overall_valid refers only to that diagnostic gate. all_checks_completed concerns eligible gate checks when present, otherwise advisory checks; an indeterminate check is incomplete. Remove required-gate requests from regression/visual configurations, or explicitly request parallel_trends_method: placebo. Regenerate schema 1.1 artefacts before current release validation.