Input Schema
Inference and power
Both stages consume a long CSV and pivot it to a unit-by-period outcome matrix.
| Field role | Required property |
|---|---|
| Geography | Stable scalar identifier; treatment IDs must match after the stage’s documented coercion. |
| Period | Both stages sort unique, timezone-naive dates; inference uses its configured date format, while power accepts ISO date/time strings and dd/mm/yyyy. |
| Outcome | Numeric and finite under the configured data policy. |
| Covariates | Optional inference columns named by covariate_col_names. |
Inference requires every treated unit’s supplied treatment date to equal the
common intervention_date. This is checked before cooldown periods are removed
and estimator-facing treatment dates are moved to the common measurement start.
Staggered launches and inconsistent global/unit dates are rejected, including
when cooldown is zero. The control count must be at least the treated count;
this alone does not satisfy cross-fitting or p-value-resolution requirements.
Fitting requires at least ten effective never-treated controls because the backend uses ten honest cross-fitting folds. Inference counts retained controls after preparation, including missing-data drops; power counts only the selected controls. Preparation can inspect a smaller panel, but inference dispatch rejects it before fitting, and power rejects it before fitting its DGP. No automatic fold reduction or small-pool estimator is supplied. Ten is an operational minimum, not a statistically qualified design size.
impute_with_report interpolates by observed-period position separately within
the pre-treatment, cooldown, and measurement windows, filling endpoints from
the same window. It rejects a unit/window with no observed outcome and never
borrows across a boundary. This policy can affect estimates and does not
establish that the missingness process is ignorable.
Sum aggregation preserves an all-missing unit-period as missing so the chosen
missing-outcome policy can handle it.
CSV covariates are baseline summaries. For each feature, GeoSC averages duplicate records within each retained pre-treatment unit-period, then averages the observed period values within each geography. Missing covariate observations are skipped; every retained unit/feature needs at least one observed numeric value, and infinity is rejected. Cooldown, post-treatment, and dropped outcome periods do not contribute. Static covariates therefore retain their value, while time-varying covariates become pre-period means. The direct API expects an already prepared finite numeric baseline table with the outcome panel’s index; the caller is responsible for its temporal provenance. Accepted direct baseline entries are normalised to float, matching file means; the caller’s original table is preserved.
Power uses DataFrame.pivot, so duplicate unit-period rows fail and missing
cells remain in the wide matrix. Its shared calculator parses dates, rejects
missing, timezone-aware, or duplicate periods, and sorts columns with their
values before selecting the pre-period. Distinct labels that parse to the same
timestamp are duplicates. Slash dates use the explicit %d/%m/%Y format;
convert other string formats before use. The direct API also accepts naive
datetime objects. Numeric period positions are not dates.
The direct power API requires unique, non-missing panel identifiers and unique,
disjoint treatment_units and control_units present in that panel. Only those
declared rows enter DGP fitting and simulation; their original row order is
retained and caller-owned inputs are copied. File-driven power treats every
non-treated input geography as a control, so its CSV must contain only eligible
geographies.
Power does not apply inference’s explicit duplicate or missing-outcome policies. Missing or non-finite values in the eligible pre-period are rejected by DGP validation. Filtering eligible units and sorting dates do not establish a regular observation cadence or statistical calibration.
Donor evaluation
The donor stage expects literal source columns date, location, and either
Y or metric. It uses rows before treatment_date. Each treatment-donor pair
is aligned on unique parsed dates; duplicates or insufficient finite overlap
produce incomplete metrics.
Adaptive scoring uses all geographies’ pre-treatment rows from the same parsed
data used for pair evaluation, independently of treatment labels. At least two
finite pre-treatment observations are required. The run records its resolved
statistics and weights in donor_pool_quality.json.
Recommended external contract
Store the panel frequency, timezone policy, outcome unit, currency, attribution logic, geography version, extract timestamp, source owner, and row-count checks alongside the CSV. These are project data-governance requirements, not fields GeoSC can infer.
The shared inference CSV loader uses round-trip floating-point parsing to preserve values serialised from an in-memory panel. Equivalent direct and file inputs therefore avoid parser-induced rounding differences; numerical stability still depends on fit.