geostep.designer.StaircaseDesigner

class geostep.designer.StaircaseDesigner(num_sequences: int, clusters_per_sequence: int, control_periods: int, intervention_periods: int)

Methods

__init__(num_sequences, ...)	Initialize designer with configuration.
design()	Creates a design matrix for a staircase cluster randomized trial.
enable_monitoring([enabled])	Enable or disable performance monitoring.
get_metrics()	Get performance and execution metrics.
monitor_operation(operation_name[, ...])	Context manager for monitoring operations.
post_process_design(design_df)	Post-process design results.
prepare_data(*args, **kwargs)	Prepare data for staircase design.
set_metrics_collector(collector)	Set the metrics collector for this instance.
validate_inputs(*args, **kwargs)	Validate staircase design parameters.

Attributes

__init__(num_sequences: int, clusters_per_sequence: int, control_periods: int, intervention_periods: int)

Initialize designer with configuration.

validate_inputs(*args, **kwargs) → None

Validate staircase design parameters.

Raises:

ValidationError – If any design parameter is invalid.

prepare_data(*args, **kwargs) → None

Prepare data for staircase design.

For staircase design, no data preparation is needed as it’s parameter-based.

design() → DataFrame

Creates a design matrix for a staircase cluster randomized trial.

Returns:

A design matrix with columns for sequence, cluster, period, and assignment. ‘assignment’ is ‘Control’ or ‘Treatment’.

Return type:

pd.DataFrame

Raises:

ValidationError – If input validation fails.

randomize(geos, seed: int = 42, geo_col: str = 'geo_id') → DataFrame

Randomly allocate actual eligible geos to the generated sequences.

The returned table is the retained allocation and observation schedule. design() alone creates a synthetic schedule, not an allocation.