updated batch comparison documentation

Author: tkschuler

Changelog

@@ -1,6 +1,10 @@
 version 1.3.1 (pre-release)
 ===============================
 * Added evaluation support for Helium Augmented and GrandSlam flights (ignoring ascent phase in evaluation)
+* Added new wind interpolation methods, selectable via `config_earth.forecast['wind_interpolation']`
+* Added batch comparison script `python -m evaluation.compare_batches <A> <B>`
+* Fixed blank GFS hodograph in `plot_windmap` - `plotWind2` was indexing the full netCDF arrays with cropped-region indices, landing in the wrong geographic cell
+
 
 version 1.3 
 ===============================

docs/source/conf.py

@@ -23,7 +23,7 @@
 author = 'Tristan Schuler'
 
 # The full version, including alpha/beta/rc tags
-release = '1.3.0'
+release = '1.3.1'
 
 # The suffix of source filenames.
 #source_suffix = '.rst'

docs/source/evaluation/batchComparison.rst

@@ -20,8 +20,8 @@ and overview bar + scatter plots for every metric. This builds on
    error, so **negative Δ means improvement** (and is colored green).
 
 
-Quick start
------------
+Running a comparison
+--------------------
 
 .. code-block:: bash
 
@@ -43,8 +43,8 @@ Self-comparison (``compare_batches X X``) is allowed and useful as a
 sanity check — every delta should be zero.
 
 
-Output structure
-----------------
+Comparison output folder
+------------------------
 
 Each comparison writes a self-contained folder next to ``batches/``:
 
@@ -67,9 +67,23 @@ relative path so the folder is portable.
 HTML report
 -----------
 
+The example below is the per-launch detail table from the linear_neighbors → linear_full
+comparison, filtered to the Sandia launches. Each metric occupies three sub-cells
+(``A | B | Δ``), and Δ cells are colored only when the change clears both the
+absolute and percent thresholds — green for improvement, red for regression,
+gray for "within noise". Metrics that don't depend on wind interpolation
+(time-to-float, temp MAE, ascent rate, etc.) stay at "+0.0 (+0.0%)" across the
+board, which is itself a useful sanity check.
+
+|cmp_html|
+
+.. |cmp_html| image:: ../../../img/compare_html_sandia_table.png
+   :width: 100%
+   :alt: Per-launch deltas table from compare.html, filtered to Sandia launches
+
 The report opens with a **summary** block — 5–7 lines covering the headline
 metrics (landing distance, landing time error, float altitude error) to
-see whether the change helped or hurt. 
+see whether the change helped or hurt.
 
 Below the summary:
 

evaluation/compare_batches.py

@@ -77,7 +77,7 @@
     "abs_floor": 1000.0, "fmt": ".0f",
 }
 
-# Headlines shown in the stdout/HTML TL;DR block (in order).
+# Headlines shown in the stdout/HTML Summary block (in order).
 PRIMARY_METRIC_KEYS = [
     "landing_distance_km",
     "time_to_ground_diff_min",
@@ -386,10 +386,10 @@ def compute_aggregates(rows: list[dict], available_metrics: list[dict]) -> list[
     return out
 
 
-# ── TL;DR ─────────────────────────────────────────────────────────────────────
+# ── Summary ─────────────────────────────────────────────────────────────────────
 
 
-def build_tldr_lines(rows: list[dict], available_metrics: list[dict]) -> list[str]:
+def build_summary_lines(rows: list[dict], available_metrics: list[dict]) -> list[str]:
     """Build short headline strings: one per primary metric per forecast type."""
     keys_by = {m["key"]: m for m in available_metrics}
     forecasts = sorted({r["forecast_type"] for r in rows})
@@ -494,11 +494,11 @@ def main(argv=None) -> int:
         reforecast_section, out_dir,
     )
 
-    # TL;DR.
-    tldr = build_tldr_lines(per_launch, available_metrics)
+    # Summary.
+    summary_lines = build_summary_lines(per_launch, available_metrics)
     print()
-    print("TL;DR:")
-    for line in tldr:
+    print("Summary:")
+    for line in summary_lines:
         print(line)
     print()
 
@@ -511,7 +511,7 @@ def main(argv=None) -> int:
         reforecast_section=reforecast_section,
         asymmetries=asym, missing=missing,
         available_metrics=available_metrics,
-        tldr_lines=tldr, plot_files=plot_files,
+        summary_lines=summary_lines, plot_files=plot_files,
     )
     print(f"  Wrote: {html_path}")
     return 0

evaluation/compare_reporting.py

@@ -4,7 +4,7 @@
   - Minimal header (batch IDs, timestamps, git hashes, notes for A and B)
   - Schema-mismatch warning banner (if any metrics were dropped)
   - Asymmetries section (only-in-A, only-in-B, failed-in-one)
-  - TL;DR block (one line per primary metric x forecast type)
+  - Summary block (one line per primary metric x forecast type)
   - Aggregate table (Overall, per forecast_type, per campaign)
   - Win/Loss count table (per metric, per group)
   - Per-launch diff table (3 sub-cells per metric: A | B | Δ)
@@ -208,10 +208,10 @@ def info_block(label: str, b: BatchData) -> str:
     )
 
 
-def _build_tldr_section(lines: list[str]) -> str:
+def _build_summary_section(lines: list[str]) -> str:
     body = _html.escape("\n".join(lines)) if lines else "(no primary metrics available)"
     return (
-        "<div class='section'><h2>TL;DR</h2>"
+        "<div class='section'><h2>Summary</h2>"
         f"<pre style='background:#fff;padding:12px;border:1px solid #ccc;border-radius:4px;"
         f"font-size:0.95em;line-height:1.5'>{body}</pre></div>"
     )
@@ -377,7 +377,7 @@ def write_compare_html(out_dir: str, batch_a: BatchData, batch_b: BatchData,
                        per_launch: list[dict], aggregates: list[dict],
                        reforecast_section: Optional[dict],
                        asymmetries: dict, missing: dict,
-                       available_metrics: list[dict], tldr_lines: list[str],
+                       available_metrics: list[dict], summary_lines: list[str],
                        plot_files: dict) -> str:
     leading = ["Launch", "Forecast", "Campaign"]
     per_launch_header = _build_metric_header(available_metrics, leading)
@@ -456,7 +456,7 @@ def write_compare_html(out_dir: str, batch_a: BatchData, batch_b: BatchData,
     &nbsp;&nbsp;<span style='color:#666'>Click any column header to sort ↑↓</span>
   </div>
 
-  {_build_tldr_section(tldr_lines)}
+  {_build_summary_section(summary_lines)}
   {_build_asymmetries_section(asymmetries)}
 
   <div class='section'>

img/compare_html_sandia_table.png

@@ -3,7 +3,7 @@
 
 setup(
     name='EarthSHAB',
-    version='1.3.0',
+    version='1.3.1',
     package_dir={"": "src"},
     packages=find_packages(where="src"),
     install_requires=[],

img/compare_landing_dist_ERA5_bar.png

@@ -37,7 +37,7 @@
     #                        np.interp fallback when alt is outside the
     #                        profile bounds (avoids spline overshoot above
     #                        the highest pressure level).
-    wind_interpolation = 'spline_full',
+    wind_interpolation = 'linear_neighbors',
 )
 
 #These parameters are for both downloading new forecasts, and running simulations with downloaded forecasts.