geoprior.cli.build_external_validation_metrics#

Build external validation metrics from Stage-1 inputs and a physics payload.

This command computes borehole / pumping validation metrics by matching site coordinates from an external validation table to the nearest pixel in a Stage-1 input grid. It then joins model-derived fields from a saved physics payload and writes both a site-level table and a metrics JSON.

Functions

`build_external_validation_metrics_main`([argv])	CLI entry point for external validation metrics build.
`build_parser`()	Build the command-line parser.
`build_pixel_table`(inputs_npz, payload_npz, ...)	Aggregate model pixels to one row per unique site location.
`compute_metrics`(*, validation_csv, ...[, ...])	Compute site-level validation joins and headline metrics.
`infer_stage1_dir`(*, stage1_dir, manifest_path)	Infer Stage-1 directory from explicit hints.
`infer_stage1_dir_from_layout`(*, results_dir, ...)	Infer Stage-1 directory from a standard results layout.
`inverse_txy`(coords_bh3, coord_scaler)	Inverse-transform BH3 coordinates to physical space.
`load_npz_dict`(path)	Load all arrays from a compressed NPZ file.
`mae`(x, y)	Compute mean absolute error.
`main`([argv])	CLI entry point for external validation metrics build.
`median_bias`(obs, pred)	Compute median prediction bias.
`nearest_match`(pixels, sx, sy, well_id)	Return the nearest pixel using direct and swapped XY checks.
`pick_existing`(*paths)	Return the first existing path from a candidate list.
`read_json`(path)	Read a JSON file into a dictionary.
`reduce_horizon`(arr, n_seq, horizon, how)	Reduce a sequence or horizon-aligned array to one value per site.
`resolve_coord_scaler_path`(stage1_manifest, ...)	Resolve optional coordinate scaler path.
`resolve_inputs_npz`(stage1_manifest, split, ...)	Resolve the inputs NPZ used for validation matching.
`resolve_outdir`(args, *, stage1_dir, ...)	Resolve output directory for metrics artifacts.
`resolve_payload_path`(override, stage2_manifest)	Resolve saved physics payload path.
`resolve_stage1_manifest`(*, manifest, ...)	Resolve Stage-1 manifest path from CLI and layout hints.
`resolve_stage2_manifest`(*, override, stage1_dir)	Resolve optional Stage-2 manifest.
`resolve_validation_csv`(args, cfg)	Resolve validation CSV path from CLI or config.
`spearman_rho`(x, y)	Compute Spearman rank correlation with finite-value checks.
`validate_site_matches`(site_df, *[, ...])	Sanity-check site-to-pixel matches.

Classes

MatchResult(well_id, match_mode, site_x, ...)

Nearest matched model pixel for one validation site.

class geoprior.cli.build_external_validation_metrics.MatchResult(well_id, match_mode, site_x, site_y, pixel_x, pixel_y, distance_m, pixel_idx)[source]#

Bases: object

Nearest matched model pixel for one validation site.

Parameters:

well_id (str)
match_mode (str)
site_x (float)
site_y (float)
pixel_x (float)
pixel_y (float)
distance_m (float)
pixel_idx (int)

well_id: str#

match_mode: str#

site_x: float#

site_y: float#

pixel_x: float#

pixel_y: float#

distance_m: float#

pixel_idx: int#

__init__(well_id, match_mode, site_x, site_y, pixel_x, pixel_y, distance_m, pixel_idx)#

Parameters:

well_id (str)
match_mode (str)
site_x (float)
site_y (float)
pixel_x (float)
pixel_y (float)
distance_m (float)
pixel_idx (int)

Return type:

None

geoprior.cli.build_external_validation_metrics.read_json(path)[source]#

Read a JSON file into a dictionary.

Parameters:: path (str | Path)
Return type:: dict[str, Any]

geoprior.cli.build_external_validation_metrics.load_npz_dict(path)[source]#

Load all arrays from a compressed NPZ file.

Parameters:: path (str | Path)
Return type:: dict[str, ndarray]

geoprior.cli.build_external_validation_metrics.pick_existing(*paths)[source]#

Return the first existing path from a candidate list.

Parameters:: paths (str | Path | None)
Return type:: Path | None

geoprior.cli.build_external_validation_metrics.infer_stage1_dir(*, stage1_dir, manifest_path)[source]#

Infer Stage-1 directory from explicit hints.

Parameters:

stage1_dir (str | None)
manifest_path (str | None)

Return type:

Path | None

geoprior.cli.build_external_validation_metrics.infer_stage1_dir_from_layout(*, results_dir, city, model)[source]#

Infer Stage-1 directory from a standard results layout.

Parameters:

results_dir (str | None)
city (str | None)
model (str | None)

Return type:

Path | None

geoprior.cli.build_external_validation_metrics.resolve_stage1_manifest(*, manifest, stage1_dir, results_dir, city, model)[source]#

Resolve Stage-1 manifest path from CLI and layout hints.

Parameters:

manifest (str | None)
stage1_dir (str | None)
results_dir (str | None)
city (str | None)
model (str | None)

Return type:

Path

geoprior.cli.build_external_validation_metrics.resolve_inputs_npz(stage1_manifest, split, override)[source]#

Resolve the inputs NPZ used for validation matching.

Parameters:

stage1_manifest (dict[str, Any])
split (str)
override (str | None)

Return type:

Path

geoprior.cli.build_external_validation_metrics.resolve_coord_scaler_path(stage1_manifest, override)[source]#

Resolve optional coordinate scaler path.

Parameters:

stage1_manifest (dict[str, Any])
override (str | None)

Return type:

Path | None

geoprior.cli.build_external_validation_metrics.resolve_stage2_manifest(*, override, stage1_dir)[source]#

Resolve optional Stage-2 manifest.

Parameters:

override (str | None)
stage1_dir (Path | None)

Return type:

Path | None

geoprior.cli.build_external_validation_metrics.resolve_payload_path(override, stage2_manifest)[source]#

Resolve saved physics payload path.

Parameters:

override (str | None)
stage2_manifest (dict[str, Any] | None)

Return type:

Path

geoprior.cli.build_external_validation_metrics.resolve_validation_csv(args, cfg)[source]#

Resolve validation CSV path from CLI or config.

Parameters:

args (Namespace)
cfg (dict[str, Any])

Return type:

Path

geoprior.cli.build_external_validation_metrics.resolve_outdir(args, *, stage1_dir, stage2_manifest_path, split)[source]#

Resolve output directory for metrics artifacts.

Parameters:

args (Namespace)
stage1_dir (Path)
stage2_manifest_path (Path | None)
split (str)

Return type:

Path

geoprior.cli.build_external_validation_metrics.inverse_txy(coords_bh3, coord_scaler)[source]#

Inverse-transform BH3 coordinates to physical space.

Parameters:: coords_bh3 (ndarray)
Return type:: ndarray

geoprior.cli.build_external_validation_metrics.reduce_horizon(arr, n_seq, horizon, how)[source]#

Reduce a sequence or horizon-aligned array to one value per site.

Parameters:

arr (ndarray)
n_seq (int)
horizon (int)
how (str)

Return type:

ndarray

geoprior.cli.build_external_validation_metrics.build_pixel_table(inputs_npz, payload_npz, coord_scaler, horizon_reducer, site_reducer)[source]#

Aggregate model pixels to one row per unique site location.

Parameters:

inputs_npz (str | Path)
payload_npz (str | Path)
horizon_reducer (str)
site_reducer (str)

Return type:

DataFrame

geoprior.cli.build_external_validation_metrics.nearest_match(pixels, sx, sy, well_id)[source]#

Return the nearest pixel using direct and swapped XY checks.

Parameters:

pixels (DataFrame)
sx (float)
sy (float)
well_id (str)

Return type:

MatchResult

geoprior.cli.build_external_validation_metrics.spearman_rho(x, y)[source]#

Compute Spearman rank correlation with finite-value checks.

Parameters:

x (ndarray)
y (ndarray)

Return type:

float

geoprior.cli.build_external_validation_metrics.mae(x, y)[source]#

Compute mean absolute error.

Parameters:

x (ndarray)
y (ndarray)

Return type:

float

geoprior.cli.build_external_validation_metrics.median_bias(obs, pred)[source]#

Compute median prediction bias.

Parameters:

obs (ndarray)
pred (ndarray)

Return type:

float

geoprior.cli.build_external_validation_metrics.validate_site_matches(site_df, *, max_distance_m=5000.0, min_unique_pixels=3)[source]#

Sanity-check site-to-pixel matches.

Parameters:

site_df (DataFrame)
max_distance_m (float)
min_unique_pixels (int)

Return type:

None

geoprior.cli.build_external_validation_metrics.compute_metrics(*, validation_csv, stage1_manifest_path, outdir, split='test', inputs_npz=None, physics_payload=None, coord_scaler=None, stage2_manifest_path=None, productivity_col='step3_specific_capacity_Lps_per_m', horizon_reducer='mean', site_reducer='median', max_distance_m=5000.0, min_unique_pixels=3)[source]#

Compute site-level validation joins and headline metrics.

Parameters:

validation_csv (str | Path)
stage1_manifest_path (str | Path)
outdir (str | Path)
split (str)
inputs_npz (str | Path | None)
physics_payload (str | Path | None)
coord_scaler (str | Path | None)
stage2_manifest_path (str | Path | None)
productivity_col (str)
horizon_reducer (str)
site_reducer (str)
max_distance_m (float)
min_unique_pixels (int)

Return type:

tuple[DataFrame, dict[str, Any]]

geoprior.cli.build_external_validation_metrics.build_parser()[source]#

Build the command-line parser.

Return type:: ArgumentParser

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

CLI entry point for external validation metrics build.

Parameters:: argv (list[str] | None)
Return type:: None

geoprior.cli.build_external_validation_metrics.main(argv=None)#

CLI entry point for external validation metrics build.

Parameters:: argv (list[str] | None)
Return type:: None