asp-plot 3.2.0__py3-none-any.whl → 3.4.0__py3-none-any.whl

asp_plot/alignment.py

@@ -386,7 +386,7 @@ class Alignment:
 
         return report
 
-    def apply_dem_translation(self, output_prefix="pc_align/pc_align"):
+    def apply_dem_translation(self, output_prefix="pc_align/pc_align", output_fn=None):
         """
         Apply the pc_align translation to the DEM.
 
@@ -398,6 +398,13 @@ class Alignment:
         ----------
         output_prefix : str, optional
             Prefix for pc_align output files, default is "pc_align/pc_align"
+        output_fn : str, optional
+            Where to write the translated DEM. Default is None, which writes
+            ``<dem_fn without .tif>_pc_align_translated.tif`` next to the
+            source DEM (the report convention). Pass an explicit path to
+            keep the translated copy elsewhere, e.g. when many candidate
+            DEMs are aligned side by side and their folders should stay
+            untouched (:class:`asp_plot.dem_benchmark.DEMBenchmark`).
 
         Returns
         -------
@@ -479,7 +486,11 @@ class Alignment:
         t_srs.ImportFromWkt(src.ds.crs.to_wkt())
         proj_shift = self.get_proj_shift(src_c, src_shift, s_srs, t_srs, inv_trans=True)
 
-        aligned_dem_fn = self.dem_fn.replace(".tif", "_pc_align_translated.tif")
+        if output_fn is None:
+            aligned_dem_fn = self.dem_fn.replace(".tif", "_pc_align_translated.tif")
+        else:
+            aligned_dem_fn = output_fn
+            os.makedirs(os.path.dirname(os.path.abspath(aligned_dem_fn)), exist_ok=True)
         print(f"\nWriting out: {aligned_dem_fn}\n")
 
         gdal_opt = ["COMPRESS=LZW", "TILED=YES", "PREDICTOR=3", "BIGTIFF=IF_SAFER"]

asp_plot/altimetry_source.py

@@ -20,6 +20,11 @@ import numpy as np
 import rioxarray
 import xarray as xr
 
+# A residual this many NMADs from the median is not a DEM error but a blunder in
+# the altimetry (cloud returns, a bad fit); dropped before the n_sigma × std cut
+# so that a large cluster of them cannot inflate the std and defeat it.
+GROSS_OUTLIER_NMAD = 30
+
 
 class AltimetrySource:
     """Base for ICESat-2 and planetary altimetry sources.
@@ -66,13 +71,26 @@ class AltimetrySource:
         return rioxarray.open_rasterio(dem_fn, masked=True).squeeze()
 
     @staticmethod
-    def _std_outlier_mask(dh, n_sigma):
-        """Boolean mask keeping dh values within ``n_sigma`` × std of the mean.
+    def _outlier_mask(dh, n_sigma):
+        """Boolean mask keeping dh values within ``n_sigma`` × std of the mean,
+        after dropping gross outliers.
+
+        Two cuts. First, anything farther than ``GROSS_OUTLIER_NMAD`` (30)
+        normalized median absolute deviations from the median is dropped: no
+        DEM error puts a point 30 NMADs out, but a cloud return does — one
+        ICESat-2 pass of marine-layer cloud 150–200 m above the ground was a
+        fifth of the sample over a coastal site, and a plain mean/std cut,
+        its std inflated to ~70 m by that cluster, removed nothing and left
+        every DEM with an RMSE near 85 m. Then the usual ``n_sigma`` × std cut
+        about the mean of what survives, which is the cut every report has
+        always applied and, absent gross contamination, gives the same result
+        as before (the gross cut touches at most a few dozen points of the
+        ~7000 over Atlanta).
 
         Rows whose ``dh`` is NaN are kept (they carry no difference yet and
         must not be dropped). Returns ``None`` — signalling that no filtering
         should occur — when there are no finite values or the spread is
-        degenerate (zero or non-finite std).
+        degenerate (zero or non-finite scale).
 
         Parameters
         ----------
@@ -84,11 +102,17 @@ class AltimetrySource:
         valid = dh.dropna().values
         if valid.size == 0:
             return None
-        mean_val = np.mean(valid)
-        std_val = np.std(valid)
+        median_val = np.median(valid)
+        nmad_val = 1.4826 * np.median(np.abs(valid - median_val))
+        if nmad_val == 0 or np.isnan(nmad_val):
+            return None
+        gross = (dh - median_val).abs() <= GROSS_OUTLIER_NMAD * nmad_val
+        core = dh[gross].dropna().values
+        mean_val = np.mean(core)
+        std_val = np.std(core)
         if std_val == 0 or np.isnan(std_val):
             return None
-        mask = (dh - mean_val).abs() <= n_sigma * std_val
+        mask = gross & ((dh - mean_val).abs() <= n_sigma * std_val)
         return mask | dh.isna()
 
     def _write_csv_to_directory(self, df, filename):

asp_plot/cli/asp_report.py

@@ -1,5 +1,6 @@
 import click
 
+from asp_plot.report import FIGURE_MAX_DPI
 from asp_plot.report_pipeline import ReportConfig, run_report
 
 
@@ -128,6 +129,14 @@ def _reconstruct_command():
     default=None,
     help="Title for the report. Default: Directory name of ASP processing.",
 )
+@click.option(
+    "--figure-max-dpi",
+    prompt=False,
+    default=FIGURE_MAX_DPI,
+    show_default=True,
+    type=int,
+    help="Resolution ceiling for figures embedded in the PDF, applied at the size each figure is placed on the page. Figures are plotted at 220 dpi and then scaled down to the page, so wide multi-panel figures otherwise land at 400+ effective dpi and inflate the file for detail no screen or printer shows. Pass 0 to embed the full-resolution figures.",
+)
 def main(
     directory,
     bundle_adjust_prefix,
@@ -146,6 +155,7 @@ def main(
     reuse_selections,
     report_filename,
     report_title,
+    figure_max_dpi,
 ):
     """
     Generate a comprehensive report of ASP processing results.
@@ -172,6 +182,7 @@ def main(
         reuse_selections=reuse_selections,
         report_filename=report_filename,
         report_title=report_title,
+        figure_max_dpi=figure_max_dpi,
         report_command=_reconstruct_command(),
     )
     run_report(config)

asp_plot/cli/dem_benchmark.py

@@ -0,0 +1,181 @@
+import os
+
+import click
+
+from asp_plot.dem_benchmark import DEMBenchmark
+from asp_plot.icesat2_source import WORLDCOVER_GROUPS
+
+
+@click.command()
+@click.argument("dems", nargs=-1, required=True)
+@click.option(
+    "--parquet",
+    prompt=False,
+    default=None,
+    help="ICESat-2 ATL06-SR parquet cache to score Earth DEMs against (the "
+    "atl06sr_all.parquet a previous asp_report run wrote next to its report, "
+    "or from Altimetry.request_atl06sr_multi_processing(save_to_parquet=True)). "
+    "The same points are replayed for every DEM; no SlideRule request is made.",
+)
+@click.option(
+    "--altimetry-csv",
+    prompt=False,
+    default=None,
+    help="LOLA/MOLA CSV to score Moon/Mars DEMs against (see "
+    "request_planetary_altimetry). Use instead of --parquet for planetary DEMs.",
+)
+@click.option(
+    "--directory",
+    prompt=False,
+    default="./",
+    help="Working directory. pc_align products and the translated DEM copies go "
+    "under <directory>/dem_benchmark/<label>/, never into the DEMs' own folders. "
+    "Default: current directory.",
+)
+@click.option(
+    "--reference",
+    prompt=False,
+    default=None,
+    help="Label of one of the DEMs to difference the others against (vs_ref "
+    "columns of the stats table). Default: none.",
+)
+@click.option(
+    "--no-pc-align",
+    is_flag=True,
+    default=False,
+    help="Skip the per-DEM pc_align translation; report pre-alignment residuals only.",
+)
+@click.option(
+    "--own-extent",
+    is_flag=True,
+    default=False,
+    help="Compute coverage and triangulation-error statistics over each DEM's "
+    "own extent instead of the intersection of all DEM footprints.",
+)
+@click.option(
+    "--filter-out",
+    prompt=False,
+    multiple=True,
+    default=("water",),
+    type=click.Choice(sorted(WORLDCOVER_GROUPS) + ["none"]),
+    help="ESA WorldCover group to drop from the ICESat-2 points before "
+    "differencing; repeat the option for several. Giving the option replaces "
+    "the default, so name water as well to keep dropping it: '--filter-out "
+    "water --filter-out trees' is the stable-terrain choice when years "
+    "separate the imagery from the ICESat-2 passes. 'none' keeps every return "
+    "and cannot be combined with a group. Earth DEMs only. Default: water.",
+)
+@click.option(
+    "--n-bootstrap",
+    prompt=False,
+    default=1000,
+    type=int,
+    help="Replicates of the paired block bootstrap that puts 95 % intervals on "
+    "the shared-point median and NMAD of every DEM and on its NMAD difference "
+    "to the best DEM (whole ICESat-2 beam tracks, or MOLA orbits, are "
+    "resampled). 0 skips it. Default: 1000.",
+)
+@click.option(
+    "--title",
+    prompt=False,
+    default=None,
+    help="Figure title. Default: none.",
+)
+@click.option(
+    "--output-directory",
+    prompt=False,
+    default=None,
+    help="Directory for the figure and stats CSV. Default: --directory.",
+)
+@click.option(
+    "--output-filename",
+    prompt=False,
+    default="dem_benchmark.png",
+    help="Figure filename; the stats CSV takes the same name with a .csv "
+    "extension, and the residual histogram figure a _histogram suffix. "
+    "Default: dem_benchmark.png.",
+)
+def main(
+    dems,
+    parquet,
+    altimetry_csv,
+    directory,
+    reference,
+    no_pc_align,
+    own_extent,
+    filter_out,
+    n_bootstrap,
+    title,
+    output_directory,
+    output_filename,
+):
+    """
+    Score many DEMs against one altimetry sample.
+
+    DEMS are paths, optionally labelled as LABEL=PATH (e.g.
+    "MVS=stereo_mvs3/run-DEM.tif"); an unlabelled ASP run-DEM.tif is labelled
+    by its folder. Every DEM gets: coverage inside the common footprint, the
+    median triangulation error from its IntersectionErr raster when present
+    (table only; it is a consistency check, not a quality ranking), and the
+    altimetry-minus-DEM median / NMAD / RMSE before and (unless
+    --no-pc-align) after a pc_align translation, on its own points and on the
+    points valid in every DEM, with bootstrap intervals on the latter. Writes
+    a one-row-per-DEM summary figure, an overlaid residual histogram, and the
+    stats table as CSV.
+    """
+    if "none" in filter_out and len(set(filter_out)) > 1:
+        raise click.UsageError(
+            "--filter-out none keeps every return and cannot be combined with "
+            "a land-cover group."
+        )
+    directory = os.path.expanduser(directory)
+    if output_directory is None:
+        output_directory = directory
+    output_directory = os.path.expanduser(output_directory)
+
+    bench = DEMBenchmark(
+        directory=directory,
+        dems=list(dems),
+        parquet=parquet,
+        altimetry_csv=altimetry_csv,
+        reference=reference,
+        aoi=None if own_extent else "intersection",
+        filter_out=[g for g in filter_out if g != "none"] or None,
+        n_bootstrap=n_bootstrap,
+        title=title,
+    )
+    stats = bench.run(pc_align=not no_pc_align)
+
+    stem = os.path.splitext(output_filename)[0]
+    csv_fn = bench.save_stats(os.path.join(output_directory, f"{stem}.csv"))
+    bench.summary_plot(save_dir=output_directory, fig_fn=output_filename)
+    bench.histogram_plot(save_dir=output_directory, fig_fn=f"{stem}_histogram.png")
+
+    # The headline columns; the CSV has every column of STATS_COLUMNS.
+    shown = stats[
+        [
+            "label",
+            "valid_pct",
+            "ie_median_m",
+            "n_points",
+            "n_shared",
+            "dh_shared_median_m",
+            "dh_shared_nmad_m",
+            "dh_aligned_shared_median_m",
+            "dh_aligned_shared_nmad_m",
+            "nmad_ci_low_m",
+            "nmad_ci_high_m",
+            "p_best",
+        ]
+    ]
+    shown = shown.dropna(axis=1, how="all")
+    print("\n" + shown.to_string(index=False, float_format=lambda v: f"{v:.2f}"))
+    print(
+        f"\nSummary figure: {os.path.join(output_directory, output_filename)}"
+        f"\nHistogram:      {os.path.join(output_directory, stem + '_histogram.png')}"
+        f"\nStats table:    {csv_fn}\n"
+    )
+
+
+if __name__ == "__main__":
+    main()