asp-plot 1.12.1__tar.gz → 1.13.0__tar.gz

{asp_plot-1.12.1 → asp_plot-1.13.0}/.gitignore

@@ -143,3 +143,4 @@ CLAUDE*
 scripts/
 /*.parquet
 reports/regenerate_reports.sh
+*.csv

{asp_plot-1.12.1 → asp_plot-1.13.0}/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.13.0] - 2026-04-20
+
+### Added
+- **Automatic `pc_align` step in the Earth altimetry block**, gated by a new `--pc_align` CLI flag (default `True`; disabled automatically when `--plot_altimetry` / `--plot_icesat` is `False`). Runs `pc_align` against ICESat-2 ATL06-SR, evaluates whether the aligned DEM is worth keeping, and appends the outcome as one or more report pages:
+  - Always: an **alignment report page** with the parameters table, a single-row horizontal stats table (p16/p50/p84 beg/end, north/east/down shifts, translation magnitude, values to 2 sig figs), a description explaining what `pc_align` does and the meaning of every column in the tables above, and a bold status line for the outcome of this run.
+  - On success (p50 drops toward 0 by more than `improvement_threshold_pct`, default 5%, **and** `pc_align` actually wrote an aligned DEM): three additional full-page diagnostic figures against the aligned DEM — a pre-/post-alignment landcover histogram, the full profile, and the best/worst 1 km segments.
+  - On insufficient ATL06-SR coverage or no meaningful improvement: the aligned DEM on disk is cleaned up so its presence is a truthy signal that the alignment is worth using.
+- **`Altimetry.align_and_evaluate(...)`** (new method) returning a plain `AlignmentResult` dataclass (`status ∈ {"insufficient_points", "no_improvement", "success"}`, `alignment_report_df`, `aligned_dem_fn`, `improvement_pct`, `message`, `parameters_used`). Does not import any `fpdf` / report dependencies, so it is safe to call from notebooks.
+- **`plot_aligned` kwargs** on `Altimetry.histogram_by_landcover` and `Altimetry.plot_best_worst_segments`:
+  - `histogram_by_landcover(plot_aligned=True)` overlays the pre- and post-alignment distributions using shared bin edges and renders two vertically stacked per-landcover stats text boxes whose outline colors match the bar colors (color = legend).
+  - `plot_best_worst_segments(plot_aligned=True)` keeps segment selection fixed (based on the unaligned `dh` so segments are comparable), overlays aligned DEM heights on each segment, and appends aligned Median/NMAD to the segment titles.
+- **`AlignmentReportPage`** dataclass in `asp_plot.report`: a report-section type that renders a kwargs table + single-row stats table + description + bold status line + optional figure with caption. Body text blocks render left-aligned to avoid justified word-spacing gaps.
+
+### Changed
+- **Processing Parameters is now page 2 of the PDF**, immediately after the DEM Summary on the title page, instead of the trailing appendix. Page order is now: title + DEM summary → processing parameters → diagnostic figures → (if any) alignment results.
+- **`plot_atl06sr_dem_profile(plot_aligned=True)`**: the lower `dh` panel now plots the post-alignment residuals (`icesat_minus_aligned_dem`) with Med/NMAD recomputed against the aligned DEM, with the legend entry tagged `"(Aligned DEM)"`. The upper elevation panel still overlays both the unaligned and aligned DEM for comparison. `plot_aligned=False` behavior is unchanged.
+
 ## [1.12.1] - 2026-04-14
 
 ### Changed

{asp_plot-1.12.1 → asp_plot-1.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asp_plot
-Version: 1.12.1
+Version: 1.13.0
 Summary: Package for plotting outputs Ames Stereo Pipeline processing
 Project-URL: Homepage, https://github.com/uw-cryo/asp_plot
 Project-URL: Documentation, https://asp-plot.readthedocs.io

{asp_plot-1.12.1 → asp_plot-1.13.0}/asp_plot/altimetry.py

@@ -1,7 +1,9 @@
 import json
 import logging
 import os
+from dataclasses import dataclass, field
 from datetime import datetime, timedelta, timezone
+from typing import Optional
 
 import contextily as ctx
 import geopandas as gpd
@@ -43,6 +45,49 @@ def _nmad(a, c=1.4826):
     return np.nanmedian(np.fabs(a - np.nanmedian(a))) * c
 
 
+@dataclass
+class AlignmentResult:
+    """Outcome of :meth:`Altimetry.align_and_evaluate`.
+
+    Plain dataclass — importing this or the method does not pull in any
+    report/fpdf dependencies, so it is safe to use from notebooks.
+
+    Attributes
+    ----------
+    status : str
+        One of:
+          - ``"insufficient_points"``: not enough ATL06-SR points for
+            pc_align to run (the aligned DEM is removed if one was written).
+          - ``"no_improvement"``: pc_align ran but p50 did not improve
+            toward 0 by more than the ``improvement_threshold_pct``; the
+            aligned DEM has been removed.
+          - ``"success"``: p50 improved by more than the threshold; the
+            aligned DEM is retained and ``Altimetry.aligned_dem_fn`` points
+            to it.
+    alignment_report_df : pandas.DataFrame
+        The alignment report table produced by
+        :meth:`Altimetry.alignment_report`. Empty for ``insufficient_points``.
+    aligned_dem_fn : str or None
+        Path to the aligned DEM on success; None otherwise (the file is
+        cleaned up on non-success branches).
+    improvement_pct : float or None
+        ``(p50_beg - p50_end) / p50_beg * 100`` when computable, else None.
+    message : str
+        Short human-readable summary suitable for a status line in the
+        PDF report.
+    parameters_used : dict
+        The kwargs used for the alignment attempt (e.g. processing_level,
+        minimum_points, improvement_threshold_pct). Echoed into the report.
+    """
+
+    status: str
+    alignment_report_df: Optional[pd.DataFrame] = None
+    aligned_dem_fn: Optional[str] = None
+    improvement_pct: Optional[float] = None
+    message: str = ""
+    parameters_used: dict = field(default_factory=dict)
+
+
 # --- ODE GDS REST API (for LOLA/MOLA planetary altimetry) ---
 
 GDS_BASE_URL = "https://oderest.rsl.wustl.edu/livegds"
@@ -1124,6 +1169,173 @@ class Altimetry:
 
         self.alignment_report_df = alignment_report_df
 
+    def align_and_evaluate(
+        self,
+        processing_level="all",
+        improvement_threshold_pct=5.0,
+        min_translation_threshold=0.1,
+        minimum_points=500,
+        agreement_threshold=0.25,
+    ):
+        """
+        Run pc_align against ICESat-2 and evaluate whether to keep the result.
+
+        Wraps :meth:`alignment_report` with a decision step so the aligned
+        DEM is only retained when it represents a meaningful improvement.
+        Returns an :class:`AlignmentResult`; notebook callers can inspect
+        ``result.status`` to decide what to display.
+
+        Decision logic:
+
+        1. If the alignment report is empty (fewer than ``minimum_points``
+           ICESat-2 points, or the pc_align log is missing), delete any
+           aligned DEM file and return ``status="insufficient_points"``.
+        2. Otherwise compute
+           ``improvement_pct = (p50_beg - p50_end) / p50_beg * 100``. If
+           ``p50_end >= p50_beg`` or
+           ``improvement_pct <= improvement_threshold_pct``, delete the
+           aligned DEM, clear ``self.aligned_dem_fn``, and return
+           ``status="no_improvement"``.
+        3. Otherwise re-run :meth:`atl06sr_to_dem_dh` so the
+           ``icesat_minus_aligned_dem`` column is populated, and return
+           ``status="success"`` with the aligned DEM retained.
+
+        Parameters
+        ----------
+        processing_level : str, optional
+            ATL06-SR processing level key to align against. Default "all".
+        improvement_threshold_pct : float, optional
+            Minimum required ``(p50_beg - p50_end) / p50_beg * 100`` for the
+            aligned DEM to be kept. Default 5.0.
+        min_translation_threshold : float, optional
+            Forwarded to :meth:`alignment_report`. Default 0.1.
+        minimum_points : int, optional
+            Forwarded to :meth:`alignment_report`. Default 500.
+        agreement_threshold : float, optional
+            Forwarded to :meth:`alignment_report`. Default 0.25.
+
+        Returns
+        -------
+        AlignmentResult
+        """
+        parameters_used = {
+            "processing_level": processing_level,
+            "minimum_points": minimum_points,
+            "agreement_threshold": agreement_threshold,
+            "min_translation_threshold": min_translation_threshold,
+            "improvement_threshold_pct": improvement_threshold_pct,
+        }
+
+        self.alignment_report(
+            processing_level=processing_level,
+            key_for_aligned_dem=processing_level,
+            minimum_points=minimum_points,
+            agreement_threshold=agreement_threshold,
+            min_translation_threshold=min_translation_threshold,
+            write_out_aligned_dem=True,
+        )
+        df = getattr(self, "alignment_report_df", None)
+
+        if df is None or df.empty:
+            self._remove_aligned_dem_if_present()
+            return AlignmentResult(
+                status="insufficient_points",
+                alignment_report_df=df if df is not None else pd.DataFrame(),
+                aligned_dem_fn=None,
+                improvement_pct=None,
+                message=(
+                    f"Alignment skipped: fewer than {minimum_points} "
+                    f"ATL06-SR points available for processing_level="
+                    f"'{processing_level}', or pc_align did not produce a "
+                    "usable log."
+                ),
+                parameters_used=parameters_used,
+            )
+
+        row = df.iloc[0]
+        p50_beg = float(row.get("p50_beg", float("nan")))
+        p50_end = float(row.get("p50_end", float("nan")))
+        if not np.isfinite(p50_beg) or not np.isfinite(p50_end) or p50_beg == 0:
+            improvement_pct = None
+        else:
+            improvement_pct = (p50_beg - p50_end) / p50_beg * 100.0
+
+        # alignment_report may decline to write the aligned DEM if the
+        # translation magnitude is under min_translation_threshold × GSD
+        # (self.aligned_dem_fn stays None in that case). Without a written
+        # aligned DEM we cannot render the success-path plots, so treat
+        # that as no_improvement even if p50 happened to drop > threshold.
+        translation_too_small = self.aligned_dem_fn is None
+
+        if (
+            improvement_pct is None
+            or p50_end >= p50_beg
+            or improvement_pct <= improvement_threshold_pct
+            or translation_too_small
+        ):
+            self._remove_aligned_dem_if_present()
+            improvement_repr = (
+                f"{improvement_pct:.1f}%" if improvement_pct is not None else "n/a"
+            )
+            if (
+                translation_too_small
+                and improvement_pct is not None
+                and (p50_end < p50_beg and improvement_pct > improvement_threshold_pct)
+            ):
+                reason = (
+                    f"Translation magnitude is below {min_translation_threshold*100:.0f}% "
+                    "of the DEM GSD, so no aligned DEM was written despite a "
+                    f"{improvement_repr} p50 reduction."
+                )
+            else:
+                reason = (
+                    f"p50 {p50_beg:.2f} m -> {p50_end:.2f} m, "
+                    f"{improvement_repr} <= {improvement_threshold_pct:.1f}% "
+                    "threshold. Aligned DEM removed."
+                )
+            return AlignmentResult(
+                status="no_improvement",
+                alignment_report_df=df,
+                aligned_dem_fn=None,
+                improvement_pct=improvement_pct,
+                message=f"No significant improvement: {reason}",
+                parameters_used=parameters_used,
+            )
+
+        # Populate icesat_minus_aligned_dem without re-running the 3σ
+        # outlier filter (the unaligned column is already 3σ-clean from the
+        # initial atl06sr_to_dem_dh call, and we do not want the aligned-DEM
+        # plots to operate on a different sample than the unaligned ones).
+        # This does not re-request ICESat-2 data; it only interpolates DEM
+        # heights at the existing ATL06-SR point locations.
+        self.atl06sr_to_dem_dh(n_sigma=None)
+        return AlignmentResult(
+            status="success",
+            alignment_report_df=df,
+            aligned_dem_fn=self.aligned_dem_fn,
+            improvement_pct=improvement_pct,
+            message=(
+                f"p50 improved from {p50_beg:.2f} m -> {p50_end:.2f} m "
+                f"({improvement_pct:.1f}% reduction). Aligned DEM written to "
+                f"{self.aligned_dem_fn}."
+            ),
+            parameters_used=parameters_used,
+        )
+
+    def _remove_aligned_dem_if_present(self):
+        """Delete the aligned DEM file if pc_align created one.
+
+        Safe to call when no aligned DEM exists. Clears
+        ``self.aligned_dem_fn`` on success.
+        """
+        aligned = getattr(self, "aligned_dem_fn", None)
+        if aligned and os.path.exists(aligned):
+            try:
+                os.remove(aligned)
+            except OSError as e:
+                logger.warning(f"\nCould not remove aligned DEM {aligned}: {e}\n")
+        self.aligned_dem_fn = None
+
     # ------------------------------------------------------------------ #
     #  Planetary altimetry: LOLA (Moon) and MOLA (Mars) via ODE GDS API  #
     # ------------------------------------------------------------------ #
@@ -2110,6 +2322,7 @@ class Altimetry:
         top_n=4,
         title="ICESat-2 ATL06-SR vs DEM",
         xlim=None,
+        plot_aligned=False,
         save_dir=None,
         fig_fn=None,
     ):
@@ -2120,6 +2333,11 @@ class Altimetry:
         ATL06-SR data and the DEM, with a text annotation showing overall
         and per-landcover-class statistics (count, median, NMAD).
 
+        When ``plot_aligned=True`` and an aligned DEM is available,
+        overlays the pre- and post-alignment distributions and renders two
+        vertically stacked stats text boxes whose outline colors match the
+        bar colors (color serves as the legend).
+
         Parameters
         ----------
         key : str, optional
@@ -2131,6 +2349,10 @@ class Altimetry:
         xlim : tuple or None, optional
             Symmetric x-axis limits as (min, max). If None, uses ±3σ
             range (data is already 3σ-filtered in atl06sr_to_dem_dh).
+        plot_aligned : bool, optional
+            Whether to overlay the aligned-DEM distribution alongside the
+            unaligned one. Requires ``self.aligned_dem_fn`` and the
+            ``icesat_minus_aligned_dem`` column. Default is False.
         save_dir : str or None, optional
             Directory to save figure, default is None
         fig_fn : str or None, optional
@@ -2142,32 +2364,131 @@ class Altimetry:
             self.atl06sr_to_dem_dh()
             atl06sr = self.atl06sr_processing_levels_filtered[key]
 
-        dh = atl06sr["icesat_minus_dem"].dropna()
-        if dh.empty:
+        distributions = [("icesat_minus_dem", "steelblue", "DEM")]
+        if plot_aligned:
+            if not self.aligned_dem_fn:
+                logger.warning(
+                    "\nplot_aligned=True but no aligned DEM is available; "
+                    "plotting unaligned distribution only.\n"
+                )
+            elif "icesat_minus_aligned_dem" not in atl06sr.columns:
+                logger.warning(
+                    "\n'icesat_minus_aligned_dem' column missing; call "
+                    "atl06sr_to_dem_dh() after setting aligned_dem_fn.\n"
+                )
+            else:
+                distributions.append(
+                    ("icesat_minus_aligned_dem", "darkorange", "Aligned DEM")
+                )
+
+        # Preserve the pre-existing "All" header label when there is only
+        # one distribution (no plot_aligned overlay). This keeps reports
+        # generated with plot_aligned=False textually identical to prior
+        # versions.
+        if len(distributions) == 1:
+            col, color, _ = distributions[0]
+            distributions = [(col, color, "All")]
+
+        dh_series = [
+            (col, color, label, atl06sr[col].dropna())
+            for col, color, label in distributions
+        ]
+        dh_series = [t for t in dh_series if not t[3].empty]
+        if not dh_series:
             logger.warning(f"\nNo valid dh values for key: {key}\n")
             return
 
-        overall_med = np.nanmedian(dh.values)
-        overall_nmad = _nmad(dh.values)
-        overall_n = len(dh)
+        if xlim is not None:
+            xmin, xmax = xlim
+            xlabel_note = ""
+        else:
+            abs_max = max(
+                max(abs(dv.min()), abs(dv.max())) for _, _, _, dv in dh_series
+            )
+            xmin, xmax = -abs_max, abs_max
+            xlabel_note = " [±3σ]"
+
+        fig, ax = plt.subplots(1, 1, figsize=(8, 5), dpi=220)
 
-        stats_lines = [
-            f"All: n={overall_n}, Med={overall_med:+.2f} m, NMAD={overall_nmad:.2f} m"
+        # Shared bin edges so pre- and post-alignment bars line up exactly
+        # (default bins=128 recomputes edges per call, which leaves the
+        # two distributions with incompatible binning).
+        shared_bins = np.linspace(xmin, xmax, 129)
+        for _, color, _, dv in dh_series:
+            ax.hist(dv.values, bins=shared_bins, alpha=0.55, color=color)
+        ax.set_xlim(xmin, xmax)
+
+        stats_blocks = [
+            (
+                self._build_landcover_stats_text(atl06sr, col, label, top_n=top_n),
+                color,
+            )
+            for col, color, label, _ in dh_series
+        ]
+
+        # Stack text boxes vertically at top-left. Approximate each box's
+        # height from its line count so the second box doesn't overlap the
+        # first. Empirical constants tuned for fontsize=8 monospace in an
+        # 8x5 inch axes.
+        line_h_axes = 0.030
+        pad_axes = 0.04
+        gap_axes = 0.02
+        box_y = 0.98
+        for text, color in stats_blocks:
+            ax.text(
+                0.02,
+                box_y,
+                text,
+                transform=ax.transAxes,
+                verticalalignment="top",
+                fontsize=8,
+                fontfamily="monospace",
+                bbox=dict(
+                    boxstyle="round,pad=0.4",
+                    facecolor="white",
+                    edgecolor=color,
+                    linewidth=1.5,
+                    alpha=0.9,
+                ),
+            )
+            nlines = text.count("\n") + 1
+            box_y -= nlines * line_h_axes + pad_axes + gap_axes
+
+        ax.set_xlabel(f"ICESat-2 - DEM (m){xlabel_note}")
+        ax.set_ylabel("Count")
+        overall_n = len(dh_series[0][3])
+        suptitle = f"{title}\n{key} (n={overall_n})"
+        if self._time_range_label:
+            suptitle += f"\n{self._time_range_label}"
+        fig.suptitle(suptitle, size=10)
+        fig.tight_layout()
+        if save_dir and fig_fn:
+            save_figure(fig, save_dir, fig_fn)
+
+    def _build_landcover_stats_text(self, atl06sr, dh_col, label, top_n=4):
+        """Build the multi-line stats text for one dh column.
+
+        Includes an "all" header line (n, Med, NMAD) and up to ``top_n``
+        per-landcover-class rows, each requiring at least 10 points.
+        """
+        dv = atl06sr[dh_col].dropna()
+        overall_n = len(dv)
+        overall_med = np.nanmedian(dv.values)
+        overall_nmad = _nmad(dv.values)
+        lines = [
+            f"{label}: n={overall_n}, Med={overall_med:+.2f} m, NMAD={overall_nmad:.2f} m"
         ]
 
         wc_col = "esa_worldcover.value"
         if wc_col in atl06sr.columns:
-            valid = atl06sr.dropna(subset=["icesat_minus_dem"])
-            valid_wc = valid.dropna(subset=[wc_col])
-
+            valid_wc = atl06sr.dropna(subset=[dh_col, wc_col])
             if not valid_wc.empty:
                 valid_wc = valid_wc.copy()
-                valid_wc["lc_name"] = valid_wc[wc_col].map(WORLDCOVER_NAMES)
-                valid_wc["lc_name"] = valid_wc["lc_name"].fillna("Unknown")
-
-                grouped = valid_wc.groupby("lc_name")["icesat_minus_dem"]
+                valid_wc["lc_name"] = (
+                    valid_wc[wc_col].map(WORLDCOVER_NAMES).fillna("Unknown")
+                )
                 class_stats = []
-                for name, group in grouped:
+                for name, group in valid_wc.groupby("lc_name")[dh_col]:
                     if len(group) >= 10:
                         class_stats.append(
                             {
@@ -2177,52 +2498,16 @@ class Altimetry:
                                 "nmad": _nmad(group.values),
                             }
                         )
-
                 class_stats.sort(key=lambda x: x["n"], reverse=True)
                 class_stats = class_stats[:top_n]
-
                 if class_stats:
-                    stats_lines.append("─" * 35)
+                    lines.append("─" * 35)
                     for cs in class_stats:
-                        stats_lines.append(
-                            f"{cs['name']}: n={cs['n']}, Med={cs['med']:+.2f}, NMAD={cs['nmad']:.2f}"
+                        lines.append(
+                            f"{cs['name']}: n={cs['n']}, Med={cs['med']:+.2f}, "
+                            f"NMAD={cs['nmad']:.2f}"
                         )
-
-        fig, ax = plt.subplots(1, 1, figsize=(8, 5), dpi=220)
-
-        if xlim is not None:
-            xmin, xmax = xlim
-            xlabel_note = ""
-        else:
-            # Symmetric ±3σ centered on 0 (data was already 3σ-filtered in
-            # atl06sr_to_dem_dh; stats above are on the filtered data)
-            abs_max = max(abs(dh.min()), abs(dh.max()))
-            xmin, xmax = -abs_max, abs_max
-            xlabel_note = " [±3σ]"
-        ax.hist(dh.values, bins=128, alpha=0.7, color="steelblue")
-        ax.set_xlim(xmin, xmax)
-
-        stats_text = "\n".join(stats_lines)
-        ax.text(
-            0.02,
-            0.98,
-            stats_text,
-            transform=ax.transAxes,
-            verticalalignment="top",
-            fontsize=8,
-            fontfamily="monospace",
-            bbox=dict(boxstyle="round,pad=0.4", facecolor="white", alpha=0.9),
-        )
-
-        ax.set_xlabel(f"ICESat-2 - DEM (m){xlabel_note}")
-        ax.set_ylabel("Count")
-        suptitle = f"{title}\n{key} (n={overall_n})"
-        if self._time_range_label:
-            suptitle += f"\n{self._time_range_label}"
-        fig.suptitle(suptitle, size=10)
-        fig.tight_layout()
-        if save_dir and fig_fn:
-            save_figure(fig, save_dir, fig_fn)
+        return "\n".join(lines)
 
     def _resolve_best_track(self, key="all", rgt=None, cycle=None, spot=None):
         """
@@ -2567,17 +2852,32 @@ class Altimetry:
         plt.setp(ax_elev.get_xticklabels(), visible=False)
 
         # ===================== Row 2: dh profile =====================
-        if not dh_vals.empty:
-            med = np.nanmedian(dh_vals.values)
-            nmad_val = _nmad(dh_vals.values)
+        # When plot_aligned is active, show the *post*-alignment dh and
+        # recompute Med/NMAD against the aligned DEM so the bottom panel
+        # reflects what the aligned-DEM page is actually evaluating.
+        use_aligned_dh = (
+            plot_aligned
+            and self.aligned_dem_fn
+            and "icesat_minus_aligned_dem" in track.columns
+        )
+        if use_aligned_dh:
+            dh_plot = track["icesat_minus_aligned_dem"].dropna()
+            dh_label_suffix = " (Aligned DEM)"
+        else:
+            dh_plot = dh_vals
+            dh_label_suffix = ""
+
+        if not dh_plot.empty:
+            med = np.nanmedian(dh_plot.values)
+            nmad_val = _nmad(dh_plot.values)
             ax_dh.scatter(
-                dist.loc[dh_vals.index],
-                dh_vals,
+                dist.loc[dh_plot.index],
+                dh_plot,
                 color="gray",
                 s=4,
                 alpha=0.6,
                 zorder=2,
-                label=f"Med={med:+.2f} m, NMAD={nmad_val:.2f} m",
+                label=f"Med={med:+.2f} m, NMAD={nmad_val:.2f} m{dh_label_suffix}",
             )
             ax_dh.axhline(0, color="black", linewidth=0.5, linestyle="--", zorder=1)
 
@@ -2624,6 +2924,7 @@ class Altimetry:
         rgt=None,
         cycle=None,
         spot=None,
+        plot_aligned=False,
         save_dir=None,
         fig_fn=None,
     ):
@@ -2635,7 +2936,9 @@ class Altimetry:
         - Column 2: Worse agreement segment (highest score)
 
         Segment score is ``3·|median(dh)| + NMAD(dh)`` (see
-        ``_find_best_worst_segments``).
+        ``_find_best_worst_segments``). Segment selection is based on the
+        unaligned dh so best/worst segments remain comparable across the
+        pre- and post-alignment variants of this plot.
 
         Parameters
         ----------
@@ -2647,6 +2950,11 @@ class Altimetry:
             Cycle number (auto-selected if None)
         spot : int or None, optional
             Spot number (auto-selected if None)
+        plot_aligned : bool, optional
+            Whether to overlay the aligned DEM heights and include aligned
+            Median/NMAD in each segment title. Requires
+            ``self.aligned_dem_fn`` and the ``aligned_dem_height`` /
+            ``icesat_minus_aligned_dem`` columns. Default False.
         save_dir : str or None, optional
             Directory to save figure, default is None
         fig_fn : str or None, optional
@@ -2668,6 +2976,24 @@ class Altimetry:
         seg_best_color = "tab:blue"
         seg_worst_color = "tab:red"
 
+        show_aligned = False
+        if plot_aligned:
+            if not self.aligned_dem_fn:
+                logger.warning(
+                    "\nplot_aligned=True but no aligned DEM is available; "
+                    "showing unaligned segments only.\n"
+                )
+            elif (
+                "aligned_dem_height" not in track.columns
+                or "icesat_minus_aligned_dem" not in track.columns
+            ):
+                logger.warning(
+                    "\nAligned DEM columns missing from track; call "
+                    "atl06sr_to_dem_dh() after setting aligned_dem_fn.\n"
+                )
+            else:
+                show_aligned = True
+
         # --- 1×2 layout: better agreement | worse agreement ---
         fig, axes = plt.subplots(
             1,
@@ -2698,6 +3024,20 @@ class Altimetry:
                     label="DEM",
                 )
 
+            if show_aligned:
+                seg_ald = seg["aligned_dem_height"].dropna()
+                if not seg_ald.empty:
+                    seg_ald_dist = (
+                        seg.loc[seg_ald.index, "x_atc"].values - seg["x_atc"].values[0]
+                    )
+                    ax_seg.plot(
+                        seg_ald_dist,
+                        seg_ald.values,
+                        color="darkorange",
+                        linewidth=1,
+                        label="Aligned DEM",
+                    )
+
             # COP30 in segment
             cop30_col = "cop30.value"
             if cop30_col in seg.columns:
@@ -2731,8 +3071,19 @@ class Altimetry:
             seg_dh = seg[dh_col].dropna()
             seg_med = np.nanmedian(seg_dh.values) if not seg_dh.empty else 0
             seg_nmad = _nmad(seg_dh.values) if len(seg_dh) >= 3 else 0
+            title_parts = [
+                f"{label_prefix} (Med={seg_med:+.1f} m, NMAD={seg_nmad:.1f} m)"
+            ]
+            if show_aligned:
+                seg_dh_ald = seg["icesat_minus_aligned_dem"].dropna()
+                if not seg_dh_ald.empty:
+                    med_ald = np.nanmedian(seg_dh_ald.values)
+                    nmad_ald = _nmad(seg_dh_ald.values) if len(seg_dh_ald) >= 3 else 0
+                    title_parts.append(
+                        f"Aligned (Med={med_ald:+.1f} m, NMAD={nmad_ald:.1f} m)"
+                    )
             ax_seg.set_title(
-                f"{label_prefix} (Med={seg_med:+.1f} m, NMAD={seg_nmad:.1f} m)",
+                "\n".join(title_parts),
                 fontsize=9,
                 color=color,
             )

{asp_plot-1.12.1 → asp_plot-1.13.0}/asp_plot/cli/asp_plot.py

@@ -9,7 +9,12 @@ import contextily as ctx
 from asp_plot.altimetry import Altimetry
 from asp_plot.bundle_adjust import PlotBundleAdjustFiles, ReadBundleAdjustFiles
 from asp_plot.processing_parameters import ProcessingParameters
-from asp_plot.report import ReportMetadata, ReportSection, compile_report
+from asp_plot.report import (
+    AlignmentReportPage,
+    ReportMetadata,
+    ReportSection,
+    compile_report,
+)
 from asp_plot.scenes import ScenePlotter
 from asp_plot.stereo import StereoPlotter
 from asp_plot.stereo_geometry import StereoGeometryPlotter
@@ -84,6 +89,12 @@ from asp_plot.utils import Raster, detect_planetary_body, get_acquisition_dates
     type=click.Path(exists=True),
     help="Path to a LOLA/MOLA *_topo_csv.csv file from the ODE GDS API. Required for planetary altimetry plots. Obtain via: request_planetary_altimetry --dem <dem> --email <email>, then download and unzip the result.",
 )
+@click.option(
+    "--pc_align",
+    prompt=False,
+    default=True,
+    help="If True and --plot_altimetry is True, run pc_align against ICESat-2 (Earth only) and append the alignment-report pages. Disabled automatically when --plot_altimetry / --plot_icesat is False. Default: True.",
+)
 @click.option(
     "--plot_geometry",
     prompt=False,
@@ -126,6 +137,7 @@ def main(
     plot_altimetry,
     plot_icesat,
     altimetry_csv,
+    pc_align,
     plot_geometry,
     subset_km,
     atl06sr_time_range,
@@ -574,6 +586,151 @@ def main(
                 )
             )
 
+            # ---- pc_align + ICESat-2 alignment report (Earth only) ----
+            if pc_align:
+                align_result = icesat.align_and_evaluate(
+                    processing_level="all",
+                    improvement_threshold_pct=5.0,
+                )
+                stats_row = {}
+                if (
+                    align_result.alignment_report_df is not None
+                    and not align_result.alignment_report_df.empty
+                ):
+                    row = align_result.alignment_report_df.iloc[0].to_dict()
+                    row.pop("key", None)
+                    stats_row = row
+
+                align_title = "DEM Alignment with ICESat-2"
+                alignment_description = (
+                    "ASP's pc_align estimates a rigid 3D translation that "
+                    "minimizes the height residuals between the ASP DEM and "
+                    "ICESat-2 ATL06-SR ground-track points used as the "
+                    "reference point cloud. The translation is applied to "
+                    "the DEM directly (geotransform + pixel-value shift, no "
+                    "resampling) to produce the aligned DEM.\n\n"
+                    "Alignment Parameters (above):\n"
+                    "  - processing_level: ATL06-SR filter key used as the "
+                    "reference; 'all' uses every filtered point.\n"
+                    "  - minimum_points: minimum ATL06-SR point count "
+                    "required; fewer points skips the alignment.\n"
+                    "  - agreement_threshold: maximum relative disagreement "
+                    "across temporal sub-filters before the aligned DEM is "
+                    "flagged as inconsistent.\n"
+                    "  - min_translation_threshold: minimum translation "
+                    "magnitude (as a fraction of the DEM GSD) required to "
+                    "write out an aligned DEM.\n"
+                    "  - improvement_threshold_pct: minimum percentage "
+                    "reduction in p50 required to keep the aligned DEM on "
+                    "disk; below this, the aligned DEM is removed.\n\n"
+                    "Alignment Statistics (above, in meters):\n"
+                    "  - p16_beg / p50_beg / p84_beg: 16th / 50th / 84th "
+                    "percentile of the DEM-vs-ICESat absolute height "
+                    "residuals before alignment.\n"
+                    "  - p16_end / p50_end / p84_end: same percentiles "
+                    "after alignment.\n"
+                    "  - N_shift / E_shift / D_shift: north / east / down "
+                    "components of the applied translation vector.\n"
+                    "  - |T|: magnitude of the translation vector."
+                )
+
+                if align_result.status == "insufficient_points":
+                    sections.append(
+                        AlignmentReportPage(
+                            title=align_title,
+                            parameters=align_result.parameters_used,
+                            description=alignment_description,
+                            status_message=align_result.message,
+                        )
+                    )
+                elif align_result.status == "no_improvement":
+                    sections.append(
+                        AlignmentReportPage(
+                            title=align_title,
+                            parameters=align_result.parameters_used,
+                            stats_row=stats_row,
+                            description=alignment_description,
+                            status_message=align_result.message,
+                        )
+                    )
+                elif align_result.status == "success":
+                    # Page A: alignment parameters + stats + description
+                    # (the histogram gets its own full page below so the
+                    # figure isn't squeezed into the remaining space)
+                    sections.append(
+                        AlignmentReportPage(
+                            title=align_title,
+                            parameters=align_result.parameters_used,
+                            stats_row=stats_row,
+                            description=alignment_description,
+                            status_message=align_result.message,
+                        )
+                    )
+
+                    # Page B: pre/post landcover histogram
+                    fig_fn = f"{next(figure_counter):02}.png"
+                    icesat.histogram_by_landcover(
+                        key="all",
+                        plot_aligned=True,
+                        save_dir=plots_directory,
+                        fig_fn=fig_fn,
+                    )
+                    sections.append(
+                        ReportSection(
+                            title="ICESat-2 ATL06-SR Histogram (Aligned DEM)",
+                            image_path=os.path.join(plots_directory, fig_fn),
+                            caption=(
+                                "Pre- (steelblue) and post-alignment (orange) "
+                                "distributions of ICESat-2 minus DEM height "
+                                "differences, with per-landcover statistics in "
+                                "the two stacked text boxes. Box outline color "
+                                "matches the bar color."
+                            ),
+                        )
+                    )
+
+                    # Page C: profile with aligned DEM
+                    fig_fn = f"{next(figure_counter):02}.png"
+                    icesat.plot_atl06sr_dem_profile(
+                        key="all",
+                        plot_aligned=True,
+                        save_dir=plots_directory,
+                        fig_fn=fig_fn,
+                    )
+                    sections.append(
+                        ReportSection(
+                            title="ICESat-2 ATL06-SR Profile (Aligned DEM)",
+                            image_path=os.path.join(plots_directory, fig_fn),
+                            caption=(
+                                "Elevation profile along the ICESat-2 track after "
+                                "pc_align. The aligned DEM is overlaid on the "
+                                "profile and used to recompute the height "
+                                "differences shown in the lower panel."
+                            ),
+                        )
+                    )
+
+                    # Page D: best/worst segments with aligned DEM
+                    fig_fn = f"{next(figure_counter):02}.png"
+                    icesat.plot_best_worst_segments(
+                        key="all",
+                        plot_aligned=True,
+                        save_dir=plots_directory,
+                        fig_fn=fig_fn,
+                    )
+                    sections.append(
+                        ReportSection(
+                            title="ICESat-2 ATL06-SR Agreement Segments (Aligned DEM)",
+                            image_path=os.path.join(plots_directory, fig_fn),
+                            caption=(
+                                "The same better- and worse-agreement segments "
+                                "as above, now with the aligned DEM overlaid. "
+                                "Segment selection is held fixed so Median/NMAD "
+                                "can be compared directly."
+                            ),
+                        )
+                    )
+
         elif body in ("moon", "mars"):
             instrument = {"moon": "LOLA", "mars": "MOLA"}[body]
 

{asp_plot-1.12.1 → asp_plot-1.13.0}/asp_plot/report.py

@@ -1,7 +1,9 @@
 import logging
+import math
 import os
 import textwrap
 from dataclasses import dataclass, field
+from typing import Optional
 
 from fpdf import FPDF
 from PIL import Image
@@ -31,6 +33,54 @@ class ReportSection:
     figure_number: int = 0
 
 
+@dataclass
+class AlignmentReportPage:
+    """A PDF page for the pc_align-vs-ICESat-2 alignment workflow.
+
+    Each page carries (optionally) a small kwargs table, a single-row
+    alignment-stats table, a description paragraph, a status/message block,
+    and an optional figure with caption below. Rendered by compile_report
+    alongside ReportSection entries. Body text blocks are rendered
+    left-aligned (not justified) to avoid large inter-word gaps.
+
+    Attributes
+    ----------
+    title : str
+        Page heading.
+    parameters : dict
+        Alignment kwargs passed to ``Altimetry.align_and_evaluate``. Rendered
+        as a small two-column table above the stats table. Use an empty dict
+        to skip.
+    stats_row : dict
+        Single-row alignment statistics (e.g. p16_beg/p50_beg/... from
+        ``pc_align_report``). Rendered as a horizontal 1-row table with
+        column headers. Values are formatted to two significant figures.
+        Use an empty dict to skip.
+    description : str
+        Long-form explanation of pc_align and the meaning of each column in
+        the parameters and stats tables. Rendered between the stats table
+        and the status message. Empty string to skip.
+    status_message : str
+        Short status paragraph (e.g. path to aligned DEM, or a note that
+        alignment was skipped / produced no significant improvement).
+    image_path : str or None
+        Optional absolute path to a PNG figure rendered below the tables.
+    caption : str
+        Optional caption shown below the figure when ``image_path`` is set.
+    figure_number : int
+        Auto-assigned by compile_report().
+    """
+
+    title: str
+    parameters: dict = field(default_factory=dict)
+    stats_row: dict = field(default_factory=dict)
+    description: str = ""
+    status_message: str = ""
+    image_path: Optional[str] = None
+    caption: str = ""
+    figure_number: int = 0
+
+
 @dataclass
 class ReportMetadata:
     """Metadata about the output DEM for the report title page.
@@ -186,9 +236,16 @@ def compile_report(
     if report_metadata is not None:
         _add_metadata_table(pdf, report_metadata)
 
+    # ---- Processing Parameters page (page 2) ----
+    _add_processing_parameters_page(pdf, processing_parameters_dict, report_command)
+
     # ---- Figure sections ----
     for i, section in enumerate(sections, start=1):
         section.figure_number = i
+        if isinstance(section, AlignmentReportPage):
+            _render_alignment_report_page(pdf, section)
+            continue
+
         if not os.path.exists(section.image_path):
             logger.warning(f"Image not found, skipping: {section.image_path}")
             continue
@@ -198,48 +255,204 @@ def compile_report(
         pdf.cell(0, 10, section.title, new_x="LMARGIN", new_y="NEXT")
         pdf.ln(2)
 
-        usable_width = pdf.w - pdf.l_margin - pdf.r_margin
-        # Reserve space for caption below the image and bottom margin.
-        # Caption font is 9pt with ~80 chars/line at usable_width; 5mm per line + spacing.
-        if section.caption:
-            caption_text = f"Figure {section.figure_number}: {section.caption}"
-            estimated_lines = max(1, -(-len(caption_text) // 80))  # ceil division
-            caption_reserve = estimated_lines * 5 + 8
-        else:
-            caption_reserve = 0
-        usable_height = pdf.h - pdf.get_y() - pdf.b_margin - caption_reserve
-
-        # Determine image dimensions that fit within usable area
-        with Image.open(section.image_path) as img:
-            img_w, img_h = img.size
-        aspect = img_h / img_w
-        render_w = usable_width
-        render_h = render_w * aspect
-        if render_h > usable_height:
-            render_h = usable_height
-            render_w = render_h / aspect
-
-        pdf.image(
-            section.image_path,
-            x=pdf.l_margin + (usable_width - render_w) / 2,
-            w=render_w,
+        _render_figure_with_caption(
+            pdf, section.image_path, section.caption, section.figure_number
         )
 
-        if section.caption:
-            pdf.ln(3)
-            pdf.set_font("Helvetica", "I", 9)
-            pdf.multi_cell(0, 5, f"Figure {section.figure_number}: {section.caption}")
+    pdf.output(report_pdf_path)
+
+
+def _render_figure_with_caption(pdf, image_path, caption, figure_number):
+    """Render a figure scaled to the remaining page, with optional caption.
+
+    Parameters
+    ----------
+    pdf : ASPReportPDF
+    image_path : str
+    caption : str
+    figure_number : int
+    """
+    usable_width = pdf.w - pdf.l_margin - pdf.r_margin
+    if caption:
+        caption_text = f"Figure {figure_number}: {caption}"
+        estimated_lines = max(1, -(-len(caption_text) // 80))
+        caption_reserve = estimated_lines * 5 + 8
+    else:
+        caption_reserve = 0
+    usable_height = pdf.h - pdf.get_y() - pdf.b_margin - caption_reserve
+
+    with Image.open(image_path) as img:
+        img_w, img_h = img.size
+    aspect = img_h / img_w
+    render_w = usable_width
+    render_h = render_w * aspect
+    if render_h > usable_height:
+        render_h = usable_height
+        render_w = render_h / aspect
+
+    pdf.image(
+        image_path,
+        x=pdf.l_margin + (usable_width - render_w) / 2,
+        w=render_w,
+    )
+
+    if caption:
+        pdf.ln(3)
+        pdf.set_font("Helvetica", "I", 9)
+        pdf.multi_cell(0, 5, f"Figure {figure_number}: {caption}")
 
-    # ---- Processing Parameters page ----
+
+def _render_alignment_report_page(pdf, page):
+    """Render an AlignmentReportPage: header + optional tables + status + figure.
+
+    Parameters
+    ----------
+    pdf : ASPReportPDF
+    page : AlignmentReportPage
+    """
+    pdf.add_page()
+    pdf.set_font("Helvetica", "B", 14)
+    pdf.cell(0, 10, page.title, new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(2)
+
+    if page.parameters:
+        _add_alignment_parameters_table(pdf, page.parameters)
+        pdf.ln(3)
+
+    if page.stats_row:
+        _add_alignment_stats_row_table(pdf, page.stats_row)
+        pdf.ln(3)
+
+    if page.description:
+        pdf.set_font("Helvetica", "", 9)
+        pdf.multi_cell(0, 4.5, page.description, align="L")
+        pdf.ln(2)
+
+    if page.status_message:
+        pdf.set_font("Helvetica", "B", 10)
+        pdf.multi_cell(0, 5, page.status_message, align="L")
+        pdf.ln(3)
+
+    if page.image_path and os.path.exists(page.image_path):
+        _render_figure_with_caption(
+            pdf, page.image_path, page.caption, page.figure_number
+        )
+
+
+def _fmt_sig(x):
+    """Format a numeric value compactly with roughly two significant figures.
+
+    Uses fixed-point notation with 2 decimals for |x| < 10, 1 decimal for
+    10 <= |x| < 100, and 0 decimals above. Returns "n/a" for non-finite
+    values.
+    """
+    try:
+        xf = float(x)
+    except (TypeError, ValueError):
+        return str(x)
+    if not math.isfinite(xf):
+        return "n/a"
+    if xf == 0:
+        return "0"
+    ax = abs(xf)
+    if ax < 10:
+        return f"{xf:.2f}"
+    if ax < 100:
+        return f"{xf:.1f}"
+    return f"{xf:.0f}"
+
+
+def _add_alignment_parameters_table(pdf, parameters):
+    """Render the alignment kwargs table (two columns: parameter, value).
+
+    Parameters
+    ----------
+    pdf : ASPReportPDF
+    parameters : dict
+    """
+    pdf.set_font("Helvetica", "B", 11)
+    pdf.cell(0, 8, "Alignment Parameters", new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(1)
+
+    col_w = (pdf.w - pdf.l_margin - pdf.r_margin) / 2
+    pdf.set_font("Helvetica", "B", 9)
+    pdf.set_fill_color(220, 220, 220)
+    pdf.cell(col_w, 6, "Parameter", border=1, fill=True)
+    pdf.cell(col_w, 6, "Value", border=1, fill=True, new_x="LMARGIN", new_y="NEXT")
+
+    pdf.set_font("Helvetica", "", 9)
+    for key, val in parameters.items():
+        pdf.cell(col_w, 6, str(key), border=1)
+        pdf.cell(col_w, 6, str(val), border=1, new_x="LMARGIN", new_y="NEXT")
+
+
+_ALIGNMENT_STATS_DISPLAY_LABELS = {
+    "north_shift": "N_shift",
+    "east_shift": "E_shift",
+    "down_shift": "D_shift",
+    "translation_magnitude": "|T|",
+}
+
+
+def _add_alignment_stats_row_table(pdf, stats_row):
+    """Render a single-row horizontal alignment stats table.
+
+    Each key becomes a column header; the corresponding value becomes the
+    single data row (formatted to two significant figures). Long pc_align
+    field names are shortened via ``_ALIGNMENT_STATS_DISPLAY_LABELS`` so the
+    headers fit inside the table columns.
+
+    Parameters
+    ----------
+    pdf : ASPReportPDF
+    stats_row : dict
+        Ordered dict-like of ``{column_name: value}``.
+    """
+    pdf.set_font("Helvetica", "B", 11)
+    pdf.cell(0, 8, "Alignment Statistics (m)", new_x="LMARGIN", new_y="NEXT")
+    pdf.ln(1)
+
+    keys = list(stats_row.keys())
+    if not keys:
+        return
+
+    usable_w = pdf.w - pdf.l_margin - pdf.r_margin
+    col_w = usable_w / len(keys)
+
+    pdf.set_font("Helvetica", "B", 7)
+    pdf.set_fill_color(220, 220, 220)
+    for k in keys:
+        label = _ALIGNMENT_STATS_DISPLAY_LABELS.get(k, str(k))
+        pdf.cell(col_w, 6, label, border=1, fill=True, align="C")
+    pdf.ln(6)
+
+    pdf.set_font("Helvetica", "", 8)
+    for k in keys:
+        pdf.cell(col_w, 6, _fmt_sig(stats_row[k]), border=1, align="C")
+    pdf.ln(6)
+
+
+def _add_processing_parameters_page(pdf, params, report_command):
+    """Add the Processing Parameters page (runtime table + commands).
+
+    Parameters
+    ----------
+    pdf : ASPReportPDF
+        The PDF document.
+    params : dict
+        Processing parameters dictionary from ProcessingParameters.from_log_files().
+    report_command : str or None
+        The asp_plot CLI command used to generate this report.
+    """
     pdf.add_page()
     pdf.set_font("Helvetica", "B", 16)
     pdf.cell(0, 10, "Processing Parameters", new_x="LMARGIN", new_y="NEXT")
     pdf.ln(4)
 
-    _add_runtime_table(pdf, processing_parameters_dict)
+    _add_runtime_table(pdf, params)
     pdf.ln(6)
 
-    ref_dem = processing_parameters_dict.get("reference_dem", "")
+    ref_dem = params.get("reference_dem", "")
     if ref_dem:
         pdf.set_font("Helvetica", "B", 10)
         pdf.cell(0, 7, "Reference DEM:", new_x="LMARGIN", new_y="NEXT")
@@ -252,7 +465,7 @@ def compile_report(
         ("stereo", "Stereo"),
         ("point2dem", "point2dem"),
     ]:
-        cmd = processing_parameters_dict.get(key, "")
+        cmd = params.get(key, "")
         if cmd:
             pdf.set_font("Helvetica", "B", 10)
             pdf.cell(0, 7, f"{label} Command:", new_x="LMARGIN", new_y="NEXT")
@@ -269,8 +482,6 @@ def compile_report(
         pdf.multi_cell(0, 4, wrapped)
         pdf.ln(4)
 
-    pdf.output(report_pdf_path)
-
 
 def _add_metadata_table(pdf, metadata):
     """Add DEM metadata summary table to the PDF.

{asp_plot-1.12.1 → asp_plot-1.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "asp_plot"
-version = "1.12.1"
+version = "1.13.0"
 license = {text = "BSD-3-Clause"}
 authors = [
   { name="Ben Purinton", email="purinton@uw.edu" },