Plot family#

The plot family is where you render figures, maps, and visual diagnostics from GeoPrior artifacts.

Use this page when your goal is to visualize model outputs, physics payloads, transfer results, uncertainty behavior, or supplementary diagnostics. In contrast to the run family, plot commands do not primarily execute the full workflow. In contrast to the build family, they do not primarily materialize reusable tabular or NPZ artifacts. Their job is to turn existing artifacts into clear visual outputs.

You can invoke these commands either from the root dispatcher:

geoprior plot <command> [args]

or from the family-specific entry point:

geoprior-plot <command> [args]

Many plot commands also preserve a legacy reproducibility path through:

python -m scripts <legacy-plot-command> [args]

This page is intentionally designed a little differently from the run and build family pages.

Because many plot commands share the same figure-output habits, text controls, and rendering conventions, this page introduces those shared patterns once near the top. That lets the per-command sections stay lighter later on.

How to choose a plot command#

A practical way to choose a plot command is to first decide what kind of visual story you want to tell:

  • choose a forecasting or uncertainty plot when you want to show predictive behavior, forecast spread, or uncertainty structure,

  • choose a physics or sensitivity plot when you want to inspect learned physical fields, diagnostics, or parameter sensitivity,

  • choose a transfer or validation plot when you want to compare cross-city generalization or external site support,

  • choose a supporting or supplementary plot when you want a figure focused on ablation, driver-response, lithology parity, or SM3 diagnostics.

Plot commands at a glance#

Command

Use it when

Main output

Related page

driver-response

You want a figure linking drivers to subsidence response.

Driver-response figure.

Driver-response plots: learning how the response moves with the drivers

core-ablation

You want the main ablation-style summary figure.

Core ablation figure.

Ablations and sensitivities: learning where the model behaves well in lambda space

litho-parity

You want lithology parity checks or supporting comparison plots.

Lithology parity figure.

Lithology parity: comparing the geological composition of the two cities

uncertainty

You want the main forecast uncertainty figure.

Uncertainty figure.

Forecast uncertainty: learning how calibration behaves across cities and horizons

spatial-forecasts

You want forecast maps across space.

Spatial forecast maps.

Spatial forecasts: how to read observed maps, fitted maps, and future forecast maps together

physics-sanity

You want compact physics sanity checks.

Physics sanity figure.

Physics sanity: checking closure agreement and residual behavior

physics-maps

You want mapped physics diagnostics.

Physics maps.

Physics maps: turning pointwise payloads into readable spatial fields

physics-fields

You want rendered learned physical fields.

Physics fields figure.

Physics fields: learning to read the physical story in a map

physics-profiles

You want appendix-style physical profiles.

Physics profiles figure.

Physics profiles: reducing a 2D lambda landscape into readable 1D lessons

uncertainty-extras

You want supplementary uncertainty panels.

Extra uncertainty figure.

Expanded uncertainty diagnostics: learning what the main uncertainty figure still hides

ablations-sensitivity

You want sensitivity-style ablation visualization.

Ablation sensitivity figure.

Figure generation

physics-sensitivity

You want visual summaries of physics sensitivity sweeps.

Physics sensitivity figure.

Physics sensitivity: learning how lambda choices reshape the physics diagnostics

sm3-identifiability

You want the figure view of SM3 identifiability experiments.

SM3 identifiability figure.

SM3 identifiability: learning when recovery is accurate and when parameters slide along a ridge

sm3-bounds-ridge-summary

You want a summary figure relating SM3 bounds and ridge behavior.

SM3 bounds/ridge summary.

SM3 bounds versus ridge: learning the two main failure modes

sm3-log-offsets

You want the visual diagnostic for SM3 log offsets.

SM3 log-offset figure.

SM3 log offsets: learning where the inferred fields drift from their priors

xfer-transferability

You want cross-city transferability comparison.

Transferability figure.

Cross-city transferability (v3.2): what survives when a workflow moves to the other city

xfer-impact

You want transfer impact summaries.

Transfer impact figure.

Transfer impact: what transfer changes for retention, risk, and hotspot stability

transfer

You want the short alias for the transferability plot.

Transferability figure.

Cross-city transferability (v3.2): what survives when a workflow moves to the other city

transfer-impact

You want the short alias for the transfer impact plot.

Transfer impact figure.

Transfer impact: what transfer changes for retention, risk, and hotspot stability

geo-cumulative

You want cumulative geoscience-style curves.

Cumulative geo figure.

Cumulative subsidence on a satellite-style map

hotspot-analytics

You want maps and timelines for hotspot behavior.

Hotspot analytics figure.

Hotspot analytics: turning future forecasts into decision-ready priority maps

external-validation

You want external point-support validation plots.

External validation figure.

External validation: comparing inferred effective fields against independent site evidence

Shared plot conventions#

Unlike many run and build commands, plot commands often share a strong set of output and rendering conventions. Learning these once makes the rest of the plot family much easier to use.

Common invocation patterns#

Most plotting workflows follow one of these forms:

geoprior plot physics-fields --help
geoprior-plot uncertainty
python -m scripts plot-physics-fields --help

The modern public interface is the first one users should learn. The legacy python -m scripts path remains useful for reproducibility, older notes, and backward-compatible script runs.

Figure output paths#

Many plot commands expose an --out argument.

GeoPrior resolves that output path with a simple rule set:

  • an absolute path is used as given,

  • a relative path with an explicit parent is respected as written,

  • a bare filename or stem is routed to the user-facing scripts/figs/ export area.

This is what makes commands like the following feel natural:

geoprior-plot physics-fields --out phys_main
geoprior-plot uncertainty --out exports/uncertainty_main
geoprior-plot hotspot-analytics --out /tmp/hotspots_main

In practice, a short bare name is often the nicest choice when you want the command to follow the standard artifact layout automatically.

Figure export formats#

Plot helpers treat the output as a figure stem. If you provide a suffix such as .png, the shared helpers can strip it and treat the value as a stem.

Many plot scripts save figures through the shared save_figure helper, which supports multi-format export such as:

  • PNG

  • SVG

  • PDF

  • EPS

That design is especially convenient when you want one figure for documentation, one for paper submission, and one editable vector version for later refinement.

Text visibility and Illustrator-friendly output#

Several figure scripts reuse a shared text-control layer intended for paper workflows and later editing. Common flags include:

  • --show-legend

  • --show-labels

  • --show-ticklabels

  • --show-title

  • --show-panel-titles

  • --title

These options make it easier to produce:

  • one version with full labels for gallery use,

  • another version with reduced text for Illustrator or layout editing.

A common pattern is:

geoprior-plot physics-fields \
    --out phys_fields_main \
    --show-title false \
    --show-panel-titles false

Render styles for sensitivity surfaces#

Several sensitivity-style figure scripts also share reusable rendering controls. Common options include:

  • --render with choices such as heatmap, tricontour, and pcolormesh,

  • --levels for contour density,

  • --clip for percentile-based color scaling,

  • --agg for duplicate-grid aggregation,

  • --show-points for overlaying sampled points.

That means many sensitivity figures can move smoothly between a more discrete grid-like rendering and a smoother contour-style rendering without changing the underlying workflow.

Example:

geoprior-plot physics-sensitivity \
    --out phys_sensitivity_main \
    --render tricontour \
    --levels 18 \
    --clip 2,98 \
    --show-points true

Artifact roots and environment variables#

The shared plotting layer also supports artifact-root environment variables such as:

  • GEOPRIOR_ARTIFACT_ROOT

  • GEOPRIOR_FIG_DIR

  • GEOPRIOR_OUT_DIR

When these are not set explicitly, the default figure export area is built under the project-level scripts/figs/ directory. This helps keep documentation figures, reproducibility figures, and quick manual runs aligned to the same filesystem logic.

How this plot family is organized#

To keep the page easy to navigate, the detailed plot sections that follow are grouped into a few practical categories.

The first group covers forecasting and uncertainty figures. These commands focus on predictive spread, uncertainty structure, forecast maps, and hotspot-style forecast summaries.

The second group covers physics and physical diagnostics. These commands focus on learned fields, physics sanity checks, profiles, sensitivity sweeps, and SM3-oriented diagnostics.

The third group covers transfer and validation figures. These commands focus on cross-city transfer behavior and external site-based validation.

The fourth group covers supporting and supplementary figures. These commands include ablation, driver-response, parity, and additional figure panels that support the broader GeoPrior workflow.

The rest of this page builds on that structure so that users can think in terms of what they want to visualize, not only in terms of individual command names.

Forecasting and uncertainty#

uncertainty#

Use uncertainty when you want the main uncertainty calibration figure built from calibrated forecast CSVs, optionally enriched with GeoPrior phys JSON for interval-calibration notes.

This command produces the main Fig. 5 style layout: reliability, per-horizon mini panels, and radial sharpness summaries. It also writes a compact metrics table to scripts/out/ through --out-csv.

Usage#

Run the figure from auto-detected city run directories:

geoprior plot uncertainty \
    --ns-src results/nansha_run \
    --zh-src results/zhongshan_run \
    --split auto

Use explicit forecast CSVs and phys JSON overrides:

geoprior-plot uncertainty \
    --ns-forecast results/nansha_eval_calibrated.csv \
    --zh-forecast results/zhongshan_eval_calibrated.csv \
    --ns-phys-json results/nansha_eval_phys.json \
    --zh-phys-json results/zhongshan_eval_phys.json \
    --out fig5_uncertainty_main \
    --out-csv ext-table-fig5-uncertainty.csv \
    --radial-title city \
    --show-point-values true \
    --show-mini-titles true \
    --show-json-notes true

Distinctive options to notice#

--ns-src / --zh-src and --ns-forecast / --zh-forecast

Choose between auto-discovery from run directories and explicit calibrated forecast CSV overrides.

--ns-phys-json / --zh-phys-json

Add GeoPrior JSON notes to the reliability panels when available.

--split

Choose auto, val, or test when inputs are discovered from run directories.

--out-csv

Write the exported uncertainty metrics table.

--radial-title

Control whether radial panels use full, city, or none.

--show-point-values / --show-mini-titles / --show-mini-legend / --show-json-notes

Fine-tune the richer uncertainty annotations.

Related examples:

spatial-forecasts#

Use spatial-forecasts when you want the main spatial validation plus forecast maps figure.

This command combines one observed validation-year map, one predicted validation-year map, and one or more future forecast-year maps. It can also mark hotspot contours and export hotspot points.

Usage#

Run the figure from auto-detected run directories:

geoprior plot spatial-forecasts \
    --ns-src results/nansha_run \
    --zh-src results/zhongshan_run \
    --split auto

Use explicit calibrated and future CSVs with forecast controls:

geoprior-plot spatial-forecasts \
    --ns-calib results/nansha_eval_calibrated.csv \
    --zh-calib results/zhongshan_eval_calibrated.csv \
    --ns-future results/nansha_future.csv \
    --zh-future results/zhongshan_future.csv \
    --year-val 2022 \
    --years-forecast 2025 2026 2027 \
    --cumulative \
    --subsidence-kind cumulative \
    --grid-res 300 \
    --clip 98 \
    --hotspot delta \
    --hotspot-quantile 0.90 \
    --hotspot-out fig6_hotspot_points.csv \
    --out fig6_spatial_forecasts_main

Distinctive options to notice#

--year-val and --years-forecast

Control the observed/predicted validation year and the additional forecast columns.

--cumulative and --subsidence-kind

Control whether forecast panels use cumulative or annualized values.

--grid-res and --clip

Control rasterization resolution and shared color clipping.

--hotspot

Choose hotspot contour mode: none, absolute, or delta.

--hotspot-quantile and --hotspot-out

Control hotspot selection and optional hotspot point export.

Related examples:

hotspot-analytics#

Use hotspot-analytics when you want the decision-maker hotspot figure: anomaly maps, exceedance-risk maps, a timeline view, and a priority ranking of hotspot clusters.

This command also exports three downstream tables by default: hotspot_points.csv, hotspot_years.csv, and hotspot_clusters.csv.

Usage#

Run the default hotspot analytics workflow from run directories:

geoprior plot hotspot-analytics \
    --ns-src results/nansha_run \
    --zh-src results/zhongshan_run \
    --years 2025 2026

Use explicit eval/future CSVs with richer hotspot controls:

geoprior-plot hotspot-analytics \
    --ns-eval results/nansha_eval.csv \
    --zh-eval results/zhongshan_eval.csv \
    --ns-future results/nansha_future.csv \
    --zh-future results/zhongshan_future.csv \
    --base-year 2022 \
    --years 2025 2026 2027 \
    --focus-year 2027 \
    --subsidence-kind cumulative \
    --hotspot-quantile 0.90 \
    --hotspot-rule combo \
    --hotspot-abs 40 \
    --risk-threshold 50 \
    --risk-min 0.6 \
    --exposure exposure.csv \
    --timeline-mode ever \
    --timeline-overlay-current true \
    --cluster-rank risk \
    --add-persistence \
    --persistence-mode fraction \
    --boundary boundary.geojson \
    --out hotspot_analytics_main \
    --out-points hotspot_points.csv \
    --out-years hotspot_years.csv \
    --out-clusters hotspot_clusters.csv

Distinctive options to notice#

--base-year / --years / --focus-year

Control anomaly reference year, analysis years, and the main focus year for maps and ranking.

--hotspot-rule

Choose the hotspot definition used for counts, clusters, and persistence: percentile, abs, risk, or combo.

--hotspot-abs / --risk-threshold / --risk-min

Control absolute anomaly and exceedance-probability thresholds.

--exposure / --exposure-col / --exposure-default

Add an exposure-weighted risk layer.

--timeline-mode and --timeline-overlay-current

Control how hotspot evolution is summarized over time.

--add-persistence / --persistence-mode

Add a persistence panel as fraction or count.

--boundary / --ns-boundary / --zh-boundary

Overlay or filter to optional boundary files.

--out-points / --out-years / --out-clusters

Control the three exported hotspot tables.

Related examples:

uncertainty-extras#

Use uncertainty-extras when you want the supplementary uncertainty diagnostics that go beyond the main uncertainty figure.

This command adds expanded reliability, PIT, coverage, sharpness, per-horizon calibration-factor views, and writes both CSV and TeX tables.

Usage#

Run the supplementary figure from run directories:

geoprior plot uncertainty-extras \
    --ns-src results/nansha_run \
    --zh-src results/zhongshan_run \
    --split auto

Use explicit forecast inputs and table export controls:

geoprior-plot uncertainty-extras \
    --ns-forecast results/nansha_eval_calibrated.csv \
    --zh-forecast results/zhongshan_eval_calibrated.csv \
    --ns-phys-json results/nansha_eval_phys.json \
    --zh-phys-json results/zhongshan_eval_phys.json \
    --bootstrap 2000 \
    --out supp-fig-s5-uncertainty-extras \
    --tables-stem supp-table-s5-reliability \
    --no-legends \
    --show-panel-titles true

Distinctive options to notice#

--bootstrap

Control the number of bootstrap draws used for confidence intervals.

--tables-stem

Set the shared stem for CSV and TeX table export.

--no-legends

Convenient switch for suppressing legends in this figure.

--ns-phys-json / --zh-phys-json

Provide optional per-horizon calibration factors from GeoPrior JSON.

Related examples:

Core physics figures#

physics-fields#

Use physics-fields when you want the richer spatial physics-field figure with more rendering and presentation controls.

This command renders the six core spatial physics panels (log10(K), log10(Ss), Hd, log10(tau), log10(tau_p), and Δlog10(tau)), and it supports either gridded imshow rendering or hexbin rendering, optional boundary overlays, scalebars, north arrows, PDF export, and optional JSON range export.

Usage#

Run the figure from one source directory or one payload:

geoprior plot physics-fields \
    --src results/nansha_run

or:

geoprior-plot physics-fields \
    --payload results/nansha_phys_payload.npz

Use richer rendering and overlay controls:

geoprior-plot physics-fields \
    --src results/nansha_run \
    --coords-npz results/nansha_coords.npz \
    --city Nansha \
    --coord-kind auto \
    --agg mean \
    --grid 240 \
    --render hexbin \
    --hex-gridsize 80 \
    --hex-mincnt 1 \
    --clip-q 2 98 \
    --delta-q 98 \
    --cbar-label-mode title \
    --boundary-auto true \
    --boundary-to-crs EPSG:4326 \
    --boundary-lw 0.4 \
    --boundary-alpha 0.75 \
    --scalebar true \
    --north-arrow true \
    --export-pdf true \
    --out-json fig_physics_fields_ranges.json \
    --out fig_physics_fields_main

Distinctive options to notice#

--src / --payload / --coords-npz

Choose between auto-detected payloads, explicit payload paths, and optional coordinate NPZ sidecars.

--render

Choose between hexbin and imshow-style rendering.

--hex-gridsize / --hex-mincnt

Matter when --render hexbin is used.

--boundary-auto / --boundary / --boundary-to-crs / --boundary-lw / --boundary-alpha

Control optional boundary discovery and overlay styling.

--scalebar / --north-arrow / --scalebar-km

Add map-style panel embellishments.

--export-pdf and --out-json

Control extra figure and range-metadata export.

Related examples:

physics-maps#

Use physics-maps when you want the lighter fixed-grid spatial physics map figure.

This command renders the same six core physics panels as physics-fields, but with a simpler gridded map interface and fewer presentation extras.

Usage#

Run the figure from one source directory or one payload:

geoprior plot physics-maps \
    --src results/nansha_run

or:

geoprior-plot physics-maps \
    --payload results/nansha_phys_payload.npz

Use explicit coordinate and styling controls:

geoprior-plot physics-maps \
    --src results/nansha_run \
    --coords-npz results/nansha_coords.npz \
    --city Nansha \
    --coord-kind auto \
    --agg median \
    --grid 220 \
    --clip-q 2 98 \
    --delta-q 98 \
    --cmap viridis \
    --cmap-div RdBu_r \
    --hatch-censored true \
    --show-panel-labels true \
    --out-json fig_physics_maps_ranges.json \
    --out fig_physics_maps_main

Distinctive options to notice#

--agg and --grid

Control how point payloads are rasterized into maps.

--clip-q and --delta-q

Control percentile clipping of the main ranges and the symmetric tension panel.

--hatch-censored

Overlay censored regions when that mask exists in the payload.

--out-json

Write the mapped value ranges as a JSON side artifact.

Related examples:

physics-sanity#

Use physics-sanity when you want the two-case physics sanity figure that compares learned and prior time scales and summarizes the consistency residual distribution.

This command is intentionally case-oriented rather than city-hardcoded: it expects exactly two --src inputs and can infer or accept one city label per source.

Usage#

Run the standard two-case sanity figure:

geoprior plot physics-sanity \
    --src results/nansha_run \
    --src results/zhongshan_run

Use a more diagnostic configuration:

geoprior-plot physics-sanity \
    --src results/nansha_run \
    --src results/zhongshan_run \
    --city Nansha \
    --city Zhongshan \
    --plot-mode residual \
    --tau-scale log10 \
    --cons-kind scaled \
    --gridsize 140 \
    --hist-bins 50 \
    --clip-q 1 99 \
    --subsample-frac 0.5 \
    --max-points 50000 \
    --extra k-from-tau,closure \
    --paper-format \
    --paper-no-offset \
    --out-json fig4_physics_sanity.json \
    --out fig4_physics_sanity_main

Distinctive options to notice#

--src

Must be given exactly twice.

--city

Optional per-source city labels, repeated to match --src order.

--plot-mode

Choose joint or residual.

--tau-scale

Control log10 or linear tau display in joint mode.

--cons-kind

Choose between raw cons_res_vals and scaled cons_res_scaled.

--extra

Add extra derived checks such as k-from-tau and closure.

--paper-format / --paper-no-offset

Enable paper-style scientific-axis formatting.

--out-json

Export summary sanity statistics as JSON.

Related examples:

physics-profiles#

Use physics-profiles when you want 1D physics sensitivity profiles from the ablation-record JSONL collection.

This command scans ablation records under the chosen root, keeps the physics-on rows, and plots metric profiles against lambda_prior and lambda_cons for two cities. It also writes a tidy CSV copy next to the figure.

Usage#

Run the default appendix-style profiles from the results root:

geoprior plot physics-profiles \
    --root results

Use custom cities and metrics:

geoprior-plot physics-profiles \
    --root results \
    --city-a Nansha \
    --city-b Zhongshan \
    --metric-prior epsilon_prior \
    --metric-cons epsilon_cons \
    --show-best true \
    --out appendix_fig_A1_phys_profiles

Distinctive options to notice#

--root

Root scanned for **/ablation_records/ablation_record*.jsonl.

--city-a / --city-b

Choose the two city names used in the two profile rows.

--metric-prior / --metric-cons

Choose which metrics are plotted against lambda_prior and lambda_cons.

--show-best

Highlight the best point in each panel.

--out-dir

Optional backward-compatible output-directory override.

Related examples:

Sensitivity and SM3 diagnostics#

physics-sensitivity#

Use physics-sensitivity when you want the 2D sensitivity surface figure over lambda_prior and lambda_cons.

This command scans ablation records, prefers updated records when possible, supports explicit CSV/JSON/JSONL inputs, and plots one row for the prior-oriented metric and one row for the consistency-oriented metric. It also writes the actually used tidy table as tableS7_physics_used.csv next to the figure.

Usage#

Scan the results root and render the default figure:

geoprior plot physics-sensitivity \
    --root results

Use explicit inputs, city/model filters, and richer rendering:

geoprior-plot physics-sensitivity \
    --input results/runA/ablation_record.updated.jsonl \
    --input results/runB/ablation_record.updated.jsonl \
    --cities Nansha Zhongshan \
    --models GeoPriorSubsNet \
    --pde-modes both \
    --metric-prior epsilon_prior \
    --metric-cons epsilon_cons \
    --render tricontour \
    --levels 18 \
    --agg median \
    --clip 2,98 \
    --show-points true \
    --trend-arrow true \
    --out supp_fig_S7_physics_sensitivity

Distinctive options to notice#

--input and --root

Choose between explicit ablation tables and root-directory scanning.

--cities / --models / --pde-modes

Filter the plotted rows before rendering.

--metric-prior and --metric-cons

Select the two metrics shown in the two figure rows.

--render / --levels / --agg / --clip

Control how the sensitivity surfaces are rendered and clipped.

--show-points and --trend-arrow

Add sampled-point overlays and an improvement-direction arrow.

Related figure:

sm3-identifiability#

Use sm3-identifiability when you want the main SM3 synthetic identifiability figure.

This command reads the SM3 synthetic runs CSV and builds the four-panel figure covering timescale recovery, permeability recovery, ridge degeneracy, and error versus identifiability metric. It also writes a summary CSV and JSON.

Usage#

Run the default SM3 identifiability figure:

geoprior plot sm3-identifiability \
    --csv results/sm3_synth_1d/sm3_synth_runs.csv

Use stricter filtering and richer overlays:

geoprior-plot sm3-identifiability \
    --csv results/sm3_synth_1d/sm3_synth_runs.csv \
    --only-identify tau \
    --nx-min 50 \
    --tau-units year \
    --metric ridge_resid \
    --k-from-tau auto \
    --k-cl-source prior \
    --n-boot 3000 \
    --ci 0.95 \
    --show-ci true \
    --show-stats true \
    --show-prior true \
    --show-tau-cl true \
    --out-csv sm3_identifiability_summary.csv \
    --out-json sm3_identifiability_summary.json \
    --out sm3-identifiability

Distinctive options to notice#

--only-identify and --nx-min

Filter the SM3 runs before plotting.

--tau-units

Switch panel (a) between year and second units.

--metric

Choose the identifiability metric used in panel (d).

--k-from-tau and --k-cl-source

Control whether permeability is derived from tau and which Ss/Hd source is used for that closure calculation.

--n-boot / --ci / --show-ci

Control bootstrap confidence intervals in the annotation blocks.

--show-prior and --show-tau-cl

Toggle the prior and closure overlays in panel (a).

Related figure:

sm3-bounds-ridge-summary#

Use sm3-bounds-ridge-summary when you want the SM3 failure-mode summary figure.

This command summarizes two failure modes in SM3 synthetic runs: clipping to inferred bounds and ridge-style non-identifiability. It also exports a category CSV and a JSON summary.

Usage#

Run the default summary from the SM3 runs CSV:

geoprior plot sm3-bounds-ridge-summary \
    --csv results/sm3_synth_1d/sm3_synth_runs.csv

Use stricter filtering and paper-style labels:

geoprior-plot sm3-bounds-ridge-summary \
    --csv results/sm3_synth_1d/sm3_synth_runs.csv \
    --only-identify both \
    --nx-min 50 \
    --use any \
    --ridge-thr 2.0 \
    --rtol 1e-6 \
    --paper-format \
    --out-csv sm3-clip-vs-ridge-categories.csv \
    --out-json sm3-clip-vs-ridge-summary.json \
    --out sm3-clip-vs-ridge

Distinctive options to notice#

--use

Choose the clipping definition used in panel (c): any or primary.

--ridge-thr and --rtol

Control the ridge threshold and the tolerance used when inferring clipped-to-bound flags.

--only-identify and --nx-min

Filter the SM3 runs before summary.

--paper-format

Switch to paper-friendly labels in the summary figure.

--out-csv and --out-json

Export the category table and summary payload.

Related figure:

sm3-log-offsets#

Use sm3-log-offsets when you want a payload-level SM3 offset diagnostic rather than a run-summary figure.

This command works directly from a physics payload, builds a raw offsets table, writes a compact summary table, and renders the histogram and tau scatter diagnostics. It can also use scalar priors when the payload does not embed them.

Usage#

Auto-discover the payload under one run directory:

geoprior plot sm3-log-offsets \
    --src results/sm3_synth_1d

Use an explicit payload and manual prior values:

geoprior-plot sm3-log-offsets \
    --payload results/sm3_synth_1d/physics_payload_run_val.npz \
    --K-prior 1e-7 \
    --Ss-prior 1e-5 \
    --Hd-prior 40 \
    --bins 60 \
    --out-raw-csv sm3-offsets-raw.csv \
    --out-summary-csv sm3-offsets-summary.csv \
    --out-json sm3-offsets.json \
    --out sm3-log-offsets

Distinctive options to notice#

--src / --payload

Choose between auto-discovery and one explicit payload file.

--K-prior / --Ss-prior / --Hd-prior

Provide scalar priors when the payload does not contain prior series.

--out-raw-csv / --out-summary-csv / --out-json

Export the raw offsets table, compact summary, and JSON payload.

--bins

Control the histogram bin count.

Related figure:

Transfer and validation#

xfer-transferability#

Use xfer-transferability when you want the lighter cross-city transferability figure built from xfer_results.csv.

This command focuses on the basic comparison view: transfer metrics across calibration modes plus the coverage–sharpness panel. It is the cleaner entry point when you want one concise transfer summary rather than the broader impact workflow.

Usage#

Auto-detect the latest transfer results under one source directory:

geoprior plot xfer-transferability \
    --src results/xfer/nansha__zhongshan \
    --split val

Use explicit CSV input and custom metric choices:

geoprior-plot xfer-transferability \
    --xfer-csv results/xfer/nansha__zhongshan/20260126-164613/xfer_results.csv \
    --split test \
    --strategies baseline xfer warm \
    --calib-modes none source target \
    --rescale-mode strict \
    --baseline-rescale as_is \
    --metric-top mae \
    --metric-bottom r2 \
    --reduce best \
    --cov-target 0.80 \
    --out xfer_transferability

Distinctive options to notice#

--xfer-csv / --src

Choose between explicit CSV input and latest-result discovery.

--strategies and --calib-modes

Control which transfer strategies and calibration modes appear in the figure.

--metric-top and --metric-bottom

Control the two bar-panel metrics.

--rescale-mode and --baseline-rescale

Matter when matching cross-city rows to their baseline references.

--reduce and --cov-target

Control duplicate reduction and the reference coverage line.

Related figure:

Alias: transfer

xfer-impact#

Use xfer-impact when you want the broader decision-oriented transfer figure.

This command extends the transferability view with retention panels, risk diagnostics, and optional hotspot stability panels. It can also use xfer_results.json when available to resolve evaluation CSVs for the risk and hotspot diagnostics.

Usage#

Run the core impact figure from one transfer-results directory:

geoprior plot xfer-impact \
    --src results/xfer/nansha__zhongshan \
    --split val \
    --calib source

Use explicit CSV/JSON inputs and enable hotspot stability panels:

geoprior-plot xfer-impact \
    --xfer-csv results/xfer/nansha__zhongshan \
    --xfer-json results/xfer/nansha__zhongshan/xfer_results.json \
    --split test \
    --calib target \
    --strategies baseline xfer warm \
    --rescale-mode strict \
    --baseline-rescale as_is \
    --horizon-metric rmse \
    --cov-target 0.80 \
    --threshold 50 \
    --add-hotspots true \
    --hotspot-k 100 \
    --hotspot-score exceed \
    --hotspot-horizon H3 \
    --hotspot-ref baseline \
    --hotspot-style timeline \
    --hotspot-errorbars true \
    --out figureS_xfer_impact

Distinctive options to notice#

--calib

Choose the calibration mode emphasized across the impact panels.

--horizon-metric

Control the metric used in the horizon-retention panels.

--threshold

Set the exceedance threshold used in the risk panel.

--xfer-json

Provide or override the JSON metadata used to resolve evaluation CSVs for risk and hotspot computations.

--add-hotspots / --hotspot-k / --hotspot-score / --hotspot-horizon / --hotspot-ref / --hotspot-style / --hotspot-errorbars

Enable and tune the hotspot-stability extensions.

Related figure:

Alias: transfer-impact

external-validation#

Use external-validation when you want the point-support external validation figure for inferred effective fields.

This command builds the three-panel supplementary validation figure from a site-level table, full_inputs.npz, and one full-city physics payload. It can also apply a coordinate scaler, add an optional boundary overlay, and write a compact summary JSON.

Usage#

Run the validation figure with the required artifacts:

geoprior plot external-validation \
    --site-csv nat.com/boreholes_zhongshan_with_model.csv \
    --full-inputs-npz results/zhongshan_GeoPriorSubsNet_stage1/external_validation_fullcity/full_inputs.npz \
    --full-payload-npz results/zhongshan_GeoPriorSubsNet_stage1/external_validation_fullcity/physics_payload_fullcity.npz

Use the full validation configuration with paper-style formatting:

geoprior-plot external-validation \
    --site-csv nat.com/boreholes_zhongshan_with_model.csv \
    --full-inputs-npz results/zhongshan_GeoPriorSubsNet_stage1/external_validation_fullcity/full_inputs.npz \
    --full-payload-npz results/zhongshan_GeoPriorSubsNet_stage1/external_validation_fullcity/physics_payload_fullcity.npz \
    --coord-scaler results/zhongshan_GeoPriorSubsNet_stage1/artifacts/zhongshan_coord_scaler.joblib \
    --city Zhongshan \
    --horizon-reducer mean \
    --site-reducer median \
    --boundary nat.com/zhongshan_boundary.csv \
    --grid-res 260 \
    --paper-format \
    --paper-no-offset \
    --out-json supp_zhongshan_external_validation.json \
    --out supp_external_validation

Distinctive options to notice#

--site-csv / --full-inputs-npz / --full-payload-npz

These three are the core required inputs.

--coord-scaler

Inverse-transforms the coordinate stream when the full inputs are in scaled space.

--horizon-reducer and --site-reducer

Control how horizon-level arrays and site-level matches are reduced.

--boundary

Add an optional boundary overlay in panel (a).

--paper-format and --paper-no-offset

Switch to a tighter paper layout and suppress offset text on linear

--out-json

Export a compact validation summary payload.

Related figure:

Supporting and supplementary figures#

driver-response#

Use driver-response when you want a driver-versus-response sanity grid across one or two cities.

This command builds a compact hexbin figure that compares one response column against several driver columns, with optional robust trend lines. It is useful when you want a quick physical sanity check rather than a formal model-evaluation plot.

Usage#

Run the default driver-response figure from one dataset source:

geoprior plot driver-response \
    --src data/final_dataset

Use explicit drivers, response, sampling, and trend controls:

geoprior-plot driver-response \
    --src data/final_dataset \
    --drivers rainfall,head_m,building_density,seismic_risk \
    --response subsidence_cum \
    --year 2022 \
    --sample-frac 0.20 \
    --sharey row \
    --gridsize 70 \
    --vmin 1 \
    --trend true \
    --trend-bins 35 \
    --trend-min-n 25 \
    --out figS2_driver_response

Distinctive options to notice#

--drivers

Comma-separated list of driver columns used for the x-axes.

--response and --subs-kind

Choose the response column directly, or let the command select subsidence_cum or subsidence automatically.

--sharey

Choose shared y-axis behavior across panels: none, row, or all.

--gridsize and --vmin

Control the hexbin density rendering.

--trend / --trend-bins / --trend-min-n

Enable and tune the robust median-trend overlay.

Related figure:

core-ablation#

Use core-ablation when you want the main core-versus-ablation comparison figure built from paired “with physics” and “no physics” run directories.

This command collects headline metrics from phys JSON and evaluation diagnostic JSON files, then renders the compact multi-panel comparison used for the core ablation story. It also writes a CSV and can optionally export TeX or XLSX tables.

Usage#

Run the default core ablation figure from paired run folders:

geoprior plot core-ablation \
    --ns-with results/nansha_with_phys \
    --ns-no results/nansha_no_phys \
    --zh-with results/zhongshan_with_phys \
    --zh-no results/zhongshan_no_phys

Use the alternative metric layout and table exports:

geoprior-plot core-ablation \
    --ns-with results/nansha_with_phys \
    --ns-no results/nansha_no_phys \
    --zh-with results/zhongshan_with_phys \
    --zh-no results/zhongshan_no_phys \
    --core-metric r2 \
    --err-metric rmse \
    --out-csv ext-table-fig3-metrics.csv \
    --out-tex ext-table-fig3-metrics.tex \
    --out-xlsx ext-table-fig3-metrics.xlsx \
    --show-values true \
    --show-panel-labels true \
    --out fig3-core-ablation

Distinctive options to notice#

--ns-with / --ns-no / --zh-with / --zh-no

Supply the paired run directories for the two cities.

--core-metric

Choose whether the main large panel emphasizes mae or r2.

--err-metric

Choose rmse or mse for the error-oriented comparison panel.

--out-csv / --out-tex / --out-xlsx

Export the collected comparison table in one or more formats.

--show-values and --show-panel-labels

Control bar annotations and panel lettering.

Related figure:

litho-parity#

Use litho-parity when you want a city-to-city lithology composition comparison.

This command compares class proportions between Nansha and Zhongshan, renders normalized composition bars plus a difference panel, and reports a chi-square / Cramér’s V style parity summary in the title. It is a good fit for quick distributional context rather than model evaluation.

Usage#

Run the default lithology parity figure:

geoprior plot litho-parity \
    --src data/final_dataset \
    -ns -zh

Use a different categorical column, year filter, and sampling setup:

geoprior-plot litho-parity \
    --src data/final_dataset \
    --col lithology_class \
    --year 2022 \
    --sample-frac 0.25 \
    --top-n 8 \
    --group-others true \
    --sharey true \
    --out figS1_lithology_parity

Distinctive options to notice#

--col

Select the categorical column whose parity is being compared.

--year

Restrict the comparison to one year or use all.

--sample-frac / --sample-n

Subsample the city datasets before computing proportions.

--top-n and --group-others

Control how many classes are shown explicitly and whether the rest are grouped into Others.

Related figure:

ablations-sensitivity#

Use ablations-sensitivity when you want the extended S6 ablations and sensitivity figure.

This is the richer supplementary ablation command. It can scan ablation records or accept explicit inputs, prefer updated records, deduplicate them, normalize the PDE mode into stable buckets, and then render bars, maps, or even Pareto-style trade-off views.

Usage#

Run the default S6 figure from the results root:

geoprior plot ablations-sensitivity \
    --root results

Use multiple heatmap metrics with a richer rendering setup:

geoprior-plot ablations-sensitivity \
    --root results \
    --models GeoPriorSubsNet \
    --cities Nansha,Zhongshan \
    --heatmap-metrics mae,coverage80,sharpness80 \
    --no-bars true \
    --map-kind tricontour \
    --levels 14 \
    --contour-lines true \
    --cmap viridis \
    --align-grid true \
    --mark-lambda-cons 0.1 \
    --mark-lambda-prior 0.05 \
    --out supp_fig_S6_ablations

Or switch to a Pareto trade-off view:

geoprior-plot ablations-sensitivity \
    --root results \
    --pareto true \
    --pareto-x mae \
    --pareto-y sharpness80 \
    --pareto-color coverage80 \
    --pareto-front true \
    --pareto-density true \
    --pareto-density-gridsize 35 \
    --out supp_fig_S6_pareto

Distinctive options to notice#

--input and --root

Choose between explicit ablation tables and root-directory scanning.

--heatmap-metrics and --no-bars

Build a heatmap-only multi-metric layout instead of the legacy bar-plus-map figure.

--map-kind

Choose heatmap, smooth, contour, or tricontour.

--align-grid

Keep lambda grids aligned across cities and metrics.

--mark-lambda-cons and --mark-lambda-prior

Highlight one selected lambda pair on the maps.

--pareto and related --pareto-* options

Switch from map mode to trade-off scatter mode with optional Pareto front and density overlay.

Related figure:

geo-cumulative#

Use geo-cumulative when you want cumulative subsidence maps on a satellite basemap for validation and forecast years.

This command combines calibrated validation CSVs and future forecast CSVs for Nansha and Zhongshan, converts them into cumulative subsidence-since-start-year panels, and renders them over satellite imagery. It can also overlay hotspot points and auto-detect whether the coordinates are lon/lat or UTM.

Usage#

Run the default cumulative satellite-map figure:

geoprior plot geo-cumulative \
    --ns-val results/nansha_eval_calibrated.csv \
    --zh-val results/zhongshan_eval_calibrated.csv \
    --ns-future results/nansha_future.csv \
    --zh-future results/zhongshan_future.csv

Use richer cumulative, rendering, and hotspot options:

geoprior-plot geo-cumulative \
    --ns-val results/nansha_eval_calibrated.csv \
    --zh-val results/zhongshan_eval_calibrated.csv \
    --ns-future results/nansha_future.csv \
    --zh-future results/zhongshan_future.csv \
    --start-year 2020 \
    --year-val 2022 \
    --years-forecast 2024 2025 2026 \
    --subsidence-kind cumulative \
    --clip 99 \
    --cmap viridis \
    --render-mode auto \
    --surface-levels 15 \
    --surface-alpha 0.72 \
    --basemap-alpha 1.0 \
    --panel-title-mode column \
    --hotspot-csv fig6_hotspot_points.csv \
    --hotspot-color black \
    --coords-mode auto \
    --utm-epsg 32649 \
    --out spatial_satellite_cumulative

Distinctive options to notice#

--start-year / --year-val / --years-forecast

Control the baseline year, validation-year panels, and forecast-year panels.

--subsidence-kind

Choose whether the input CSV values are already cumulative or must be accumulated from yearly increments.

--coords-mode and --utm-epsg

Control CRS inference or override it explicitly.

--render-mode / --surface-levels / --surface-alpha

Control whether the map panels use point rendering or a smoother surface-style overlay.

--hotspot-csv and related hotspot options

Overlay hotspot points on the forecast panels.

--panel-title-mode

Choose whether panel titles are hidden, column-only, or shown on every panel.

Related figure:

From here#

A good next reading path is:

In practice, the fastest workflow is often:

  1. find the plotting command on this page,

  2. inspect its example page in the gallery,

  3. then adapt the command line to your own results, payloads, or exported tables.

On this page
Edit on GitHub
Show Source