API Reference

Technical reference for the shipped GeoSC interfaces.

Interface Hierarchy

Primary operational interface:

  • installed geosc CLI and compatibility geolift CLI

Programmatic interface:

  • GeoLiftAnalyzer
  • load_config
  • load_and_prepare_data
  • process_sparse_sc_results

Compatibility interfaces:

  • runme.py
  • recipes/

For the exact CLI command surface, see CLI Reference.

Installed CLI

Installed commands:

  • geosc power
  • geosc donors
  • geosc infer
  • geosc pipeline

Shared flags on all commands:

  • --config
  • --output-dir
  • --jobs
  • --use-gpu
  • --no-progress
  • --quiet

Infer-only flags:

  • --data
  • --create-plots
  • --no-create-plots

Pipeline-only flags:

  • --skip-power
  • --skip-donor
  • --only-inference
  • --report
  • --no-report

Pipeline config contract:

  • pipeline --config accepts one canonical stage YAML path
  • GeoSC resolves sibling canonical YAMLs from the same directory
  • there is no separate pipeline config schema

Core Classes

GeoLiftAnalyzer

Main orchestration class for causal inference analysis using SparseSC-backed estimation.

Initialization modes:

  1. File-based: config_path plus data_path
  2. Direct data: prepared outcomes_df plus unit_treatment_periods

File-based example with user-owned config and data paths:

from geolift import GeoLiftAnalyzer

analyzer = GeoLiftAnalyzer(
    config_path="/path/to/geolift_analysis_config.yaml",
    data_path="/path/to/input.csv",
)

Source-checkout example:

from geolift import GeoLiftAnalyzer

analyzer = GeoLiftAnalyzer(
    config_path="data-config/geolift_analysis_config.yaml",
    data_path="data-config/synthetic_geolift_multi.csv",
)

Direct-data example:

import pandas as pd
from geolift import GeoLiftAnalyzer

outcomes_df = pd.DataFrame(...)
unit_treatment_periods = pd.Series(...)

analyzer = GeoLiftAnalyzer(
    outcomes_df=outcomes_df,
    unit_treatment_periods=unit_treatment_periods,
    intervention_date="2023-06-01",
    config={
        "estimator": "sparsesc",
        "sparse_sc_model_type": "retrospective",
        "sparse_sc_max_n_pl": 1000,
        "sparse_sc_placebo_seed": 110011,
        "sparse_sc_level": 0.95,
    },
)

run_geolift_analysis()

Executes the full inference workflow and returns the compact top-level results dictionary.

Returned fields include:

  • schema_version
  • status
  • att
  • p_value
  • p_value_method
  • n_placebos
  • max_n_placebos
  • possible_placebos
  • p_value_placebo_mode
  • placebo_seed
  • ci_lower
  • ci_upper
  • ci
  • se
  • se_available
  • se_approx_from_ci
  • se_approx_available
  • se_approximation_method
  • significant
  • significance_available
  • assumption_status
  • assumption_required
  • assumption_checks_run
  • assumption_checks_completed

Detailed diagnostics remain on analyzer.diagnostics. Assumption validation is available on analyzer.assumption_validation and, when output_dir is set, in assumption_validation.json.

analyzer.diagnostics["inference"] records the estimator method, placebo mode, seed, requested placebo count, possible combinations, and effective placebo count. The seed is material only when the placebo mode is sampled.

For the 0.3.0 beta, these public wrapper semantics are release-certified by the statistical certification gate in scripts/verify_release_candidate.py. That gate covers SparseSC parity, deterministic effect recovery, timing/orientation, artifact parity, uncertainty and placebo metadata, donor design-stage semantics, power failure accounting, assumption-validator status metadata, and release-preflight schema regressions. It does not certify that a specific campaign satisfies causal-design assumptions.

run_analysis()

Primary convenience entry point that delegates to run_geolift_analysis(). Either method is valid on the shipped class.

plot_results(output_path: str | None = None) -> str

Generates and saves the uplift time-series plot. When output_path is omitted, the plot is written to <output_dir>/uplift_timeseries.png.

Utility Functions

load_and_prepare_data(...)

from geolift.data_handler import load_and_prepare_data

File-based data preparation helper used by the analyser path.

load_config(path)

from geolift.config_manager import load_config

Loads one YAML config file.

process_sparse_sc_results(sparse_sc_results, config)

from geolift.results_processor import process_sparse_sc_results

Transforms SparseSC outputs into the compact top-level results plus the richer diagnostics payload.

Output Artifacts

Inference outputs:

  • geolift_results.json
  • geolift_diagnostics.json
  • data_validation.json
  • assumption_validation.json
  • uplift_timeseries.png when plot generation is enabled

Power outputs:

  • power_analysis_results.csv
  • power_curves.png

Power CSV rows include reproducibility and failure fields such as random_seed, n_failed, failure_rate, valid, dgp_rank, and requested_max_n_pl, possible_placebos, effective_max_n_pl, dgp_backend, and generation_backend.

Donor outputs:

  • donor_eval_results.csv
  • donor_pool_quality.json
  • donor_map_*.png

Pipeline reports:

  • geolift_pipeline_report.md
  • geolift_pipeline_report.html

Compatibility Surfaces

runme.py and the scripts in recipes/ remain available for compatibility. They are not the primary documented interface.

Migration map:

  • source-checkout: python runme.py -> geosc pipeline --config data-config/geolift_analysis_config.yaml
  • source-checkout: python recipes/power_calculator_sparsesc.py ... -> geosc power ...
  • source-checkout: python recipes/donor_evaluator.py ... -> geosc donors ...
  • source-checkout: python recipes/geolift_multi_cell.py ... -> geosc infer ...