Skip to main content

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.

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.