geoprior.cli#

Command-line interface for GeoPrior-v3.

This subpackage exposes one versatile root entry point and its public wrapper modules.

Examples

Use the root dispatcher with an explicit family:

geoprior run stage1-preprocess
geoprior build full-inputs-npz --stage1-dir results/foo_stage1

Use the family-specific console scripts directly:

geoprior-run stage4-infer --help
geoprior-build full-inputs
geoprior-plot <command>
geoprior-init --yes

Notes

The package lazily exposes public CLI wrapper modules so geoprior.cli.<name> works with Sphinx autosummary without importing private execution backends such as geoprior.cli._stage2 at package import time.

geoprior.cli.main(argv=None)[source]#

Run the root GeoPrior command dispatcher.

This is the top-level CLI entry point behind the generic geoprior command. It routes user input to one of the three public command families exposed by the project:

run for staged model workflows,
build for artifact materialization and table generation,
plot for figure and map rendering.

The function itself is intentionally thin. It delegates all parsing, family resolution, alias expansion, help rendering, and command execution to the internal dispatcher while keeping a stable public entry point for console scripts and programmatic invocation.

Conceptually, the root command supports calls of the form

geoprior run <command> [args]
geoprior build <command> [args]
geoprior plot <command> [args]

which mirrors the stage-wise and artifact-aware workflow adopted by the GeoPrior project for forecasting, diagnostics, and uncertainty analysis [1, 2].

Parameters:: argv (list of str or None, default None) – Optional command-line tokens excluding the program name. When None, the function reads arguments from sys.argv.
Returns:: This function is executed for its side effects. It prints help, dispatches a command, or raises SystemExit on invalid user input.
Return type:: None
Raises:: SystemExit – Raised when command resolution fails, when help is requested, or when a delegated subcommand exits.

Notes

This function is the most user-facing CLI entry point in the module. Use it when you want the full family-aware dispatcher behavior.

For family-specific wrappers that do not require the explicit run, build, or plot prefix, see run_main(), build_main(), and plot_main().

Examples

Call from Python with an explicit token list:

>>> from geoprior.cli.__main__ import main
>>> main(["run", "stage1-preprocess"])

Request top-level help:

>>> main(["--help"])

Dispatch a plotting command:

>>> main(["plot", "physics-fields", "--help"])

See also

run_main: Run-family wrapper used by the geoprior-run entry point.
build_main: Build-family wrapper used by the geoprior-build entry point.
plot_main: Plot-family wrapper used by the geoprior-plot entry point.

geoprior.cli.run_main(argv=None)[source]#

Run the GeoPrior dispatcher in fixed run mode.

This wrapper exposes the workflow-oriented command family behind the geoprior-run console script. Unlike main(), it does not expect a family token as the first positional argument. Instead, it assumes that every command belongs to the run family and rejects attempts to repeat the family prefix.

Typical commands dispatched through this entry point include stage execution and synthetic or sensitivity workflows, such as preprocessing, training, tuning, inference, transfer evaluation, and selected supplementary diagnostics.

Supported usage therefore follows the shorter form

geoprior-run <command> [args]

rather than

geoprior run <command> [args]

Parameters:: argv (list of str or None, default None) – Optional command-line tokens excluding the program name. When None, the function reads arguments from sys.argv.
Returns:: This function dispatches a run-family command for its side effects.
Return type:: None
Raises:: SystemExit – Raised when the requested command is unknown, belongs to a different family, or explicitly requests help.

Notes

This wrapper is mainly intended for console-script integration and family-specific convenience. It is especially useful in automation, examples, and shell documentation where repeated family prefixes would add noise.

Examples

Run stage 1 preprocessing:

>>> from geoprior.cli.__main__ import run_main
>>> run_main(["stage1-preprocess"])

Inspect the help of a training command:

>>> run_main(["stage2-train", "--help"])

Request family-scoped help:

>>> run_main(["--help"])

See also

main: Root family-aware dispatcher.
build_main: Build-family wrapper.
plot_main: Plot-family wrapper.

geoprior.cli.build_main(argv=None)[source]#

Run the GeoPrior dispatcher in fixed build mode.

This wrapper exposes the artifact-building command family behind the geoprior-build console script. It assumes that the requested subcommand already belongs to the build family and therefore uses the compact invocation form

geoprior-build <command> [args]

Typical commands in this family generate or transform reproducible artifacts needed by downstream training, validation, interpretation, or documentation workflows. Examples include merged NPZ payloads, external-validation tables, spatial sampling products, hotspot summaries, and other materialized intermediate datasets.

Parameters:: argv (list of str or None, default None) – Optional command-line tokens excluding the program name. When None, the function reads arguments from sys.argv.
Returns:: This function dispatches a build-family command for its side effects.
Return type:: None
Raises:: SystemExit – Raised when the command is unknown, belongs to another family, or when help is requested.

Notes

Use this wrapper when you want a stable programmatic entry point for artifact generation without exposing the full root dispatcher. This is the recommended choice for shell examples, gallery preparation, and reproducible data-materialization scripts built around GeoPrior.

Examples

Build a full input archive:

>>> from geoprior.cli.__main__ import build_main
>>> build_main(["full-inputs-npz", "--help"])

Build a compact forecast-ready panel:

>>> build_main(["forecast-ready-sample"])

Show the build-family help page:

>>> build_main(["--help"])

See also

main: Root family-aware dispatcher.
run_main: Run-family wrapper.
plot_main: Plot-family wrapper.

geoprior.cli.plot_main(argv=None)[source]#

Run the GeoPrior dispatcher in fixed plot mode.

This wrapper exposes the visualization command family behind the geoprior-plot console script. It dispatches plotting commands without requiring the explicit plot family prefix and therefore supports the compact form

geoprior-plot <command> [args]

The plot family is used to render publication-style figures, diagnostic graphics, uncertainty summaries, spatial forecast maps, transfer panels, and other visual outputs derived from GeoPrior artifacts. In practice, this family is central to the project’s interpretability and reporting workflow, where forecast accuracy, uncertainty behavior, and physically informed diagnostics must be read together [2].

Parameters:: argv (list of str or None, default None) – Optional command-line tokens excluding the program name. When None, the function reads arguments from sys.argv.
Returns:: This function dispatches a plot-family command for its side effects.
Return type:: None
Raises:: SystemExit – Raised when the command is unknown, belongs to another family, or when help is requested.

Notes

This wrapper is useful when the calling context is already visualization-specific, such as gallery scripts, reproducible figure pipelines, or publication packaging code.

Examples

Inspect help for a physics-field plot:

>>> from geoprior.cli.__main__ import plot_main
>>> plot_main(["physics-fields", "--help"])

Render a transferability figure:

>>> plot_main(["xfer-transferability"])

Show the plot-family help page:

>>> plot_main(["--help"])

See also

main: Root family-aware dispatcher.
run_main: Run-family wrapper.
build_main: Build-family wrapper.