CLI Reference

Canonical reference for the installed geolift command surface.

Examples below use source-tree config paths such as data-config/... when that helps illustrate the shipped demo workflow. Built wheel and sdist installs do not include data-config/; packaged users should supply their own YAML config paths.

Top-Level Command

geolift --help

Installed subcommands:

  • geolift power
  • geolift donors
  • geolift infer
  • geolift pipeline

Shared Flags

All commands accept:

  • --config CONFIG
  • --output-dir OUTPUT_DIR
  • --jobs JOBS
  • --use-gpu
  • --no-progress
  • --quiet

Semantics:

  • --config points to the YAML configuration file for the command
  • --output-dir overrides the configured output directory for stage commands
  • --jobs overrides n_jobs
  • --use-gpu is meaningful for power analysis
  • --no-progress disables progress output
  • --quiet reduces non-critical output without hiding errors

geolift power

Source-checkout example:

geolift power --config data-config/power_analysis_config.yaml --use-gpu --jobs -1

Purpose:

  • run GeoLift power-analysis workflows through the installed CLI

Typical outputs:

  • power_analysis_results.csv
  • power_curves.png

geolift donors

Source-checkout example:

geolift donors --config data-config/donor_eval_config.yaml --jobs -1

Purpose:

  • run donor-evaluation workflows through the installed CLI

Typical outputs:

  • donor_eval_results.csv
  • donor_map_*.png

geolift infer

Packaged-install example:

geolift infer --config /path/to/geolift_analysis_config.yaml --create-plots

Source-checkout example:

geolift infer --config data-config/geolift_analysis_config.yaml --create-plots

Infer-only flags:

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

Semantics:

  • --data overrides the CSV path defined in YAML
  • --create-plots forces plot generation
  • --no-create-plots disables plot generation

Typical outputs:

  • geolift_results.json
  • geolift_diagnostics.json
  • uplift_timeseries.png when plots are enabled

geolift pipeline

Packaged-install example:

geolift pipeline --config /path/to/geolift_analysis_config.yaml

Source-checkout example:

geolift pipeline --config data-config/geolift_analysis_config.yaml

Pipeline-only flags:

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

Pipeline config contract:

  • --config is an anchor to one canonical stage YAML file
  • in a source checkout, GeoLift resolves sibling canonical YAMLs from the same directory:
    • power_analysis_config.yaml
    • donor_eval_config.yaml
    • geolift_analysis_config.yaml
  • there is no pipeline --stage
  • there is no separate pipeline config schema

Stage-selection semantics:

  • --skip-power skips power analysis
  • --skip-donor skips donor evaluation
  • --only-inference skips both earlier stages

Report semantics:

  • reports are generated by default
  • --report forces report generation explicitly
  • --no-report suppresses report generation

Output-root semantics:

geolift pipeline \
  --config data-config/geolift_analysis_config.yaml \
  --output-dir results/campaign_a

This preserves the legacy stage/report layout under the supplied root:

  • results/campaign_a/multicell_power_analysis/
  • results/campaign_a/multicell_donor_eval/
  • results/campaign_a/multicell_geolift_analysis/
  • results/campaign_a/geolift_pipeline_report.md
  • results/campaign_a/geolift_pipeline_report.html

Migration From Legacy Entry Points

Legacy source-checkout command Preferred command
python runme.py geolift pipeline --config data-config/geolift_analysis_config.yaml
python recipes/power_calculator_sparsesc.py --config data-config/power_analysis_config.yaml --use-gpu --jobs -1 geolift power --config data-config/power_analysis_config.yaml --use-gpu --jobs -1
python recipes/donor_evaluator.py --config data-config/donor_eval_config.yaml geolift donors --config data-config/donor_eval_config.yaml
python recipes/geolift_multi_cell.py --config data-config/geolift_analysis_config.yaml geolift infer --config data-config/geolift_analysis_config.yaml

runme.py remains available as a compatibility wrapper. recipes/ remain available for migration and legacy stage-specific workflows.