API reference

The class names remain stable. The methodological repair changes numerical contracts and withdraws unsupported methods; see methodology.

Allocation

geostep.SimpleRandomizationDesigner(num_groups=2, seed=42).design(df, geo_col)
geostep.StratifiedRandomizationDesigner(num_groups=2, n_strata=4, seed=42).design(df, geo_col, strat_vars)
geostep.designer.randomize_within_strata(df, geo_col, seed=42, stratum_col=None)
geostep.StaircaseDesigner(num_sequences, clusters_per_sequence, control_periods, intervention_periods).design()
StaircaseDesigner.randomize(geos, seed=42, geo_col='geo_id')

Parallel analysis

LiftAnalyzer and DiDAnalyzer accept config=AnalyzerConfig(...) and expose analyze(df, **options) and prepare_data(df, **options).

Required options are geo_col, assignment_col, date_col, kpi_col and test_period_start. Set pre_period_start, pre_period_end and test_period_end explicitly to freeze the windows. stratum_col selects named strata; a column called stratum is retained automatically.

Inference options are confidence_level, random_seed, use_bca_bootstrap, n_bootstrap, use_permutation_test and n_permutations. The config defaults are 95% confidence, 1000 bootstrap draws and no fixed bootstrap seed. The randomisation-test default is 9999 draws. Set a seed for repeatability. Unsupported or misspelt options raise ValidationError; options for CRT do not apply to parallel analysis.

check_balance(df, geo_col, assignment_col, covariates) requires prespecified pre-treatment geo summaries. It never extracts an arbitrary first time-varying covariate observation.

CRT analysis

CRTAnalyzer(config=None, bootstrap_reps=None, bootstrap_seed=None) exposes analyze(df, geo_col=..., period_col=..., assignment_col=..., kpi_col=...). Optional settings are confidence_level, random_seed, bootstrap_ci and n_bootstraps, plus stratum_col (currently rejected because stratified CRT inference is not implemented). Constructor bootstrap settings default to the config values. Retain the sequence column for incomplete staircase panels and resampling. The internal treatment and outcome columns are isolated from the input schema, so a KPI may use any valid input-column name.

Power and diagnostics

geostep.run_power_analysis supports parallel Lift and DiD. See the function’s signature for calendar durations, frozen strata, seeds, worker count and test selection. CRT/staircase power is not supported.

geostep.diagnostics provides check_balance, advanced_balance_check, perform_placebo_test, descriptive standardised differences and multiple_testing_correction. sensitivity_analysis_rosenbaum raises NotImplementedError; its former calculation was invalid. Pass stratum_col to perform_placebo_test when the primary parallel analysis used a named stratum column. Multiplicity correction accepts only a non-empty, finite sequence of p-values in [0, 1] and an alpha strictly between zero and one.

Results and figures

LiftResult, DiDResult and CRTResult expose estimate, p_value, confidence_interval, confidence_level, method, metadata, warnings and to_dict(). is_significant uses the result’s confidence level. A sharp-null p-value and an average-effect interval can disagree because they test different hypotheses. is_significant_at(alpha) also requires a successful result and a numeric threshold strictly between zero and one.

geostep.reports.generate_display_results_report formats the declared units. geostep.visualizer provides plot_lift_distribution, plot_did_results and plot_power_analysis. There is no plot_analysis_results function.