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.