.. _sphx_glr_auto_examples_tables_and_summaries:

Tables and summaries
====================

This gallery focuses on **artifact-building workflows** in GeoPrior.

Unlike the examples in ``figure_generation/``, the pages collected here
usually do not begin from a final paper figure. They begin from forecast
CSVs, experiment records, Stage-1 artifacts, hotspot point clouds,
processed city tables, and compact synthetic spatial supports, then show
how to turn those materials into clean, reusable outputs.

The emphasis is therefore on **builders**, not on presentation. These
lessons explain how GeoPrior produces the tables, merged datasets,
selection subsets, and lightweight spatial layers that later diagnostics,
applications, maps, and publication figures depend on.

What this gallery produces
--------------------------

Typical outputs in this section include:

- run-level metric tables,
- grouped ablation summaries,
- exceedance-scoring tables,
- extended or merged forecast artifacts,
- forecast-ready demo panels,
- manifest-driven NPZ bundles,
- spatial samples and non-overlapping batches,
- rectangular ROI extracts and threshold-based zones,
- cluster-labeled support tables,
- nearest-city borehole assignments,
- coordinate-enriched datasets with ``z_surf`` and optional head,
- boundary, grid, exposure, and zone-aware support layers.

In other words, this gallery is about building the intermediate
artifacts that make later reporting, debugging, mapping, and
interpretation possible.

How these lessons are structured
--------------------------------

Most pages in this section follow the same general pattern:

#. create or load a compact synthetic input,
#. call the real GeoPrior builder,
#. inspect the generated artifact,
#. add a small preview plot only when it helps explain the result,
#. finish with the matching command-line usage.

Even when a page contains a map, chart, or spatial preview, the main
teaching goal remains the same: to explain the **table or reusable
artifact** produced by the command.

For the newer spatial build lessons, the synthetic inputs often come
from the reusable spatial-support utilities rather than from ad hoc
random coordinates. That keeps the examples compact while still showing
realistic spatial footprints and stable command behavior.

Module guide
------------

.. list-table::
   :header-rows: 1
   :widths: 28 24 48

   * - Module
     - Main output
     - Purpose
   * - ``build_ablation_table.py``
     - CSV / JSON / TXT / TeX summary tables
     - Build tidy ablation archives from sensitivity records,
       including optional grouped summaries and best-per-city views.
   * - ``build_model_metrics.py``
     - Unified metrics tables
     - Build wide run-level and long horizon-level metrics tables from
       experiment outputs.
   * - ``compute_brier_exceedance.py``
     - Exceedance-scoring tables
     - Score exceedance events from calibrated forecast quantiles and
       export tidy Brier-score tables by threshold and year.
   * - ``extend_forecast.py``
     - Extended forecast CSVs
     - Extend future forecast products to later years using simple
       extrapolation rules.
   * - ``build_forecast_ready_sample.py``
     - Compact forecast-ready panel sample
     - Sample spatial groups rather than rows so the retained subset
       still preserves enough temporal structure for forecasting demos,
       tests, and tutorials.
   * - ``build_full_inputs_npz.py``
     - Merged ``full_inputs.npz`` archive
     - Merge split Stage-1 input NPZ artifacts through the manifest into
       one reusable bundle.
   * - ``compute_hotspots.py``
     - Hotspot summary products
     - Build per-city, per-year hotspot summaries relative to a chosen
       baseline year.
   * - ``summarize_hotspots.py``
     - Grouped hotspot tables
     - Summarize hotspot point clouds into compact city/year/kind
       tables for inspection and reuse.
   * - ``build_spatial_sampling.py``
     - Stratified spatial sample table
     - Build one representative sample from one or many input tables by
       combining spatial bins with optional extra stratification
       columns.
   * - ``build_batch_spatial_sampling.py``
     - Non-overlapping sampled batches
     - Build repeated spatial samples for benchmarking, demos, or batch
       experiments without reusing the same rows across batches.
   * - ``build_spatial_clusters.py``
     - Cluster-labeled spatial table
     - Attach spatial cluster labels to support points using methods
       such as k-means, DBSCAN, or agglomerative clustering.
   * - ``build_spatial_roi.py``
     - Region-of-interest subset table
     - Extract a rectangular spatial window from one or many tabular
       inputs, with optional snapping to the nearest available support
       coordinates.
   * - ``build_extract_zones.py``
     - Threshold-based zone table
     - Extract high, low, or bounded-response zones from a spatial table
       using percentile or explicit threshold rules.
   * - ``build_assign_boreholes.py``
     - Classified borehole tables
     - Assign boreholes to the nearest city support cloud and export one
       combined table plus optional per-city splits.
   * - ``build_add_zsurf_from_coords.py``
     - ``z_surf``-enriched harmonized datasets
     - Merge rounded coordinate-elevation lookups into city datasets and
       optionally compute hydraulic head.
   * - ``make_boundary.py``
     - Boundary polygons
     - Build simple city boundary layers from forecast point clouds.
   * - ``make_district_grid.py``
     - Grid / zone layers
     - Build district-style grids over the forecast support domain,
       optionally clipped to a boundary and linked to samples.
   * - ``make_exposure.py``
     - Exposure layer
     - Build compact exposure products from sample geometry using
       uniform or density-based weighting schemes.
   * - ``tag_clusters_with_zones.py``
     - Zone-tagged cluster artifacts
     - Attach zone identifiers to cluster outputs so they can be
       interpreted and summarized in a zone-aware way.

Reading path
------------

A useful way to move through this gallery is to follow the logic of a
real workflow:

#. start from experiment logs, evaluation records, Stage-1 artifacts,
   or forecast exports,
#. turn them into tidy summary tables or merged reusable bundles,
#. derive compact forecast-ready subsets or extended forecast products,
#. build spatial samples, batches, ROI selections, zones, or clusters
   for downstream analysis,
#. enrich those products with support metadata such as borehole
   assignment or surface elevation,
#. continue into diagnostics, hotspot analysis, applications, or figure
   generation.

That is why the examples are naturally grouped into four broad themes:
metric builders, forecast-derived products, spatial sampling and
selection tools, and spatial support/enrichment layers.

Gallery organization
--------------------

Metrics and experiment summaries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These examples start from evaluation records, ablation logs, or
sensitivity runs and convert them into compact tabular outputs that are
much easier to compare, archive, filter, and report.

The main pages in this group are:

- ``build_ablation_table.py``
- ``build_model_metrics.py``
- ``compute_brier_exceedance.py``

Forecast-derived products and merged inputs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These examples start from forecast products or Stage-1 split artifacts
and build secondary outputs that are easier to inspect, reuse, or carry
into later workflow stages.

The main pages in this group are:

- ``extend_forecast.py``
- ``build_forecast_ready_sample.py``
- ``build_full_inputs_npz.py``
- ``compute_hotspots.py``
- ``summarize_hotspots.py``

Spatial sampling and selection tools
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These examples focus on choosing *which* part of a large spatial table
should be kept, grouped, or highlighted before later modelling,
inspection, or mapping.

The main pages in this group are:

- ``build_spatial_sampling.py``
- ``build_batch_spatial_sampling.py``
- ``build_spatial_clusters.py``
- ``build_spatial_roi.py``
- ``build_extract_zones.py``

Spatial support and enrichment layers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

These examples build or enrich lightweight spatial artifacts that help
later analysis stay geographically interpretable.

The main pages in this group are:

- ``build_assign_boreholes.py``
- ``build_add_zsurf_from_coords.py``
- ``make_boundary.py``
- ``make_district_grid.py``
- ``make_exposure.py``
- ``tag_clusters_with_zones.py``

Why this separation matters
---------------------------

This gallery deliberately keeps four concerns distinct:

- **data production and merging**,
- **tabulation and forecast-derived summaries**,
- **spatial selection and reduction**,
- **support-layer enrichment and interpretation**.

That separation makes the workflow easier to reason about. It also
helps users understand which commands generate reusable data products,
which commands reduce large tables into compact subsets, which commands
add geographic meaning, and which later pages merely visualize the
results.

Notes
-----

- These examples are intentionally compact and lesson-oriented.
- Many pages include a small preview figure, but that figure is only
  there to make the artifact easier to understand.
- The main output of this gallery is usually a **CSV, JSON, TXT, TeX,
  NPZ, or lightweight spatial layer**, not a final publication figure.
- Several lessons end with both ``geoprior-build ...`` and
  ``geoprior build ...`` forms so the reader can move easily between the
  family-specific entrypoint and the root dispatcher.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s build-ablation-table utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_ablation_table_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_ablation_table`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build ablation tables from sensitivity records</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This lesson teaches how to use GeoPrior&#x27;s add-zsurf-from-coords build command.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_add_zsurf_from_coords_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_add_zsurf_from_coords`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Enrich main datasets with surface elevation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches how to use GeoPrior&#x27;s assign-boreholes build utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_assign_boreholes_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_assign_boreholes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Assign boreholes to the nearest city cloud</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s batch-spatial-sampling build utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_batch_spatial_sampling_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_batch_spatial_sampling`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build non-overlapping spatial sample batches</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This lesson teaches how to build compact zone tables from a spatial field using GeoPrior&#x27;s extract-zones workflow.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_extract_zones_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_extract_zones`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extract threshold-based spatial zones with extract-zones</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s forecast-ready-sample build utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_forecast_ready_sample_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_forecast_ready_sample`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build a compact forecast-ready panel sample</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This lesson teaches how to use GeoPrior&#x27;s full-inputs-npz build command.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_full_inputs_npz_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_full_inputs_npz`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build one merged full_inputs.npz from Stage-1 split artifacts</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s build-model-metrics utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_model_metrics_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_model_metrics`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build unified model-metrics tables from GeoPrior runs</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This lesson teaches how to use GeoPrior&#x27;s spatial-clusters build command.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_spatial_clusters_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_spatial_clusters`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build spatial cluster tables with spatial-clusters</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This lesson teaches how to use GeoPrior&#x27;s spatial-roi build utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_spatial_roi_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_spatial_roi`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extract a rectangular region of interest with spatial-roi</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s spatial-sampling build utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_build_spatial_sampling_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/build_spatial_sampling`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build a stratified spatial sample table</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s brier-exceedance utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_compute_brier_exceedance_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/compute_brier_exceedance`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compute exceedance Brier scores from calibrated forecasts</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s compute-hotspots utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_compute_hotspots_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/compute_hotspots`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compute hotspot summary tables from forecast CSVs</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s extend-forecast utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_extend_forecast_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/extend_forecast`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Extend forecast CSVs to later years</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s make-boundary utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_make_boundary_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/make_boundary`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Build city boundary polygons from forecast points</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s make-district-grid utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_make_district_grid_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/make_district_grid`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create district grid layers from forecast points</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s make-exposure utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_make_exposure_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/make_exposure`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Create exposure weights from forecast point density</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches you how to use GeoPrior&#x27;s summarize-hotspots utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_summarize_hotspots_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/summarize_hotspots`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Summarize hotspot point clouds into tidy group tables</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example teaches the workflow idea behind GeoPrior&#x27;s tag-clusters-with-zones utility.">

.. only:: html

  .. image:: /auto_examples/tables_and_summaries/images/thumb/sphx_glr_tag_clusters_with_zones_thumb.png
    :alt:

  :doc:`/auto_examples/tables_and_summaries/tag_clusters_with_zones`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Tag hotspot clusters with district Zone IDs</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_examples/tables_and_summaries/build_ablation_table
   /auto_examples/tables_and_summaries/build_add_zsurf_from_coords
   /auto_examples/tables_and_summaries/build_assign_boreholes
   /auto_examples/tables_and_summaries/build_batch_spatial_sampling
   /auto_examples/tables_and_summaries/build_extract_zones
   /auto_examples/tables_and_summaries/build_forecast_ready_sample
   /auto_examples/tables_and_summaries/build_full_inputs_npz
   /auto_examples/tables_and_summaries/build_model_metrics
   /auto_examples/tables_and_summaries/build_spatial_clusters
   /auto_examples/tables_and_summaries/build_spatial_roi
   /auto_examples/tables_and_summaries/build_spatial_sampling
   /auto_examples/tables_and_summaries/compute_brier_exceedance
   /auto_examples/tables_and_summaries/compute_hotspots
   /auto_examples/tables_and_summaries/extend_forecast
   /auto_examples/tables_and_summaries/make_boundary
   /auto_examples/tables_and_summaries/make_district_grid
   /auto_examples/tables_and_summaries/make_exposure
   /auto_examples/tables_and_summaries/summarize_hotspots
   /auto_examples/tables_and_summaries/tag_clusters_with_zones