CLI Reference

Canonical reference for the installed geosc command surface. The legacy geolift command remains available as a compatibility alias during the beta.

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

geosc --help

Installed subcommands:

  • geosc power
  • geosc donors
  • geosc infer
  • geosc 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

geosc power

Source-checkout example:

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

Purpose:

  • run GeoSC power-analysis workflows through the installed CLI

Typical outputs:

  • power_analysis_results.csv
  • power_curves.png

geosc donors

Source-checkout example:

geosc 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

geosc infer

Packaged-install example:

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

Source-checkout example:

geosc 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

geosc pipeline

Packaged-install example:

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

Source-checkout example:

geosc 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, GeoSC 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:

geosc 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 geosc 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 geosc power --config data-config/power_analysis_config.yaml --use-gpu --jobs -1
python recipes/donor_evaluator.py --config data-config/donor_eval_config.yaml geosc donors --config data-config/donor_eval_config.yaml
python recipes/geolift_multi_cell.py --config data-config/geolift_analysis_config.yaml geosc 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.