asp_plot.altimetry

Contents

asp_plot.altimetry#

Altimetry analysis coordinator.

Altimetry is a thin coordinator that composes three single-concern objects and exposes their behaviour under one notebook-friendly API:

The coordinator owns the cross-cutting state that describes the DEM under analysis (directory, dem_fn, aligned_dem_fn) and the pc_align orchestration + keep/discard decision shared by the Earth and planetary paths (#127). The source/plotter objects read that state through a back reference. Alignment and Raster are imported at module scope because the alignment methods reference them directly.

Attributes#

logger

Classes#

AlignmentResult

Outcome of Altimetry.align_and_evaluate().

Altimetry

Process and analyze ICESat-2 / planetary altimetry against ASP DEMs.

Module Contents#

class asp_plot.altimetry.AlignmentResult#

Outcome of 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.

status#
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.

Type:

str

alignment_report_df#

The alignment report table produced by Altimetry.alignment_report(). Empty for insufficient_points.

Type:

pandas.DataFrame

aligned_dem_fn#

Path to the aligned DEM on success; None otherwise (the file is cleaned up on non-success branches).

Type:

str or None

improvement_pct#

(p50_beg - p50_end) / p50_beg * 100 when computable, else None.

Type:

float or None

message#

Short human-readable summary suitable for a status line in the PDF report.

Type:

str

parameters_used#

The kwargs used for the alignment attempt (e.g. processing_level, minimum_points, improvement_threshold_pct). Echoed into the report.

Type:

dict

aligned_dem_fn: str | None = None#
alignment_report_df: pandas.DataFrame | None = None#
improvement_pct: float | None = None#
message: str = ''#
parameters_used: dict#
status: str#
class asp_plot.altimetry.Altimetry(directory, dem_fn, aligned_dem_fn=None, atl06sr_processing_levels=None, atl06sr_processing_levels_filtered=None, **kwargs)#

Process and analyze ICESat-2 / planetary altimetry against ASP DEMs.

Coordinates the ICESat-2 (Icesat2Source) and planetary (PlanetarySource, i.e. LolaSource / MolaSource) data sources and the plotting layer (AltimetryPlotter), exposing them under a single API. It can request and filter altimetry data, align a DEM to it, and visualize the results.

directory#

Root directory for outputs and analysis

Type:

str

dem_fn#

Path to the DEM file to analyze

Type:

str

aligned_dem_fn#

Path to the aligned DEM file if available

Type:

str or None

atl06sr_processing_levels#

Dictionary of ATL06-SR data for different processing levels

Type:

dict

atl06sr_processing_levels_filtered#

Dictionary of filtered ATL06-SR data for different processing levels

Type:

dict

planetary_points#

Loaded LOLA/MOLA altimetry points (planetary DEMs)

Type:

geopandas.GeoDataFrame or None

alignment_report_df#

DataFrame containing alignment reports when available

Type:

pandas.DataFrame or None

Examples

>>> altimetry = Altimetry('/path/to/directory', '/path/to/dem.tif')
>>> altimetry.request_atl06sr_multi_processing(save_to_parquet=True)
>>> altimetry.filter_esa_worldcover(filter_out="water")
>>> altimetry.alignment_report()
>>> altimetry.mapview_plot_atl06sr_to_dem()
align_and_evaluate(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 alignment_report() with a decision step so the aligned DEM is only retained when it represents a meaningful improvement. Returns an 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 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 alignment_report(). Default 0.1.

  • minimum_points (int, optional) – Forwarded to alignment_report(). Default 500.

  • agreement_threshold (float, optional) – Forwarded to alignment_report(). Default 0.25.

Return type:

AlignmentResult

align_and_evaluate_planetary(max_displacement=500, improvement_threshold_pct=5.0, min_translation_threshold=0.1, minimum_points=20)#

Run pc_align against MOLA/LOLA and evaluate whether to keep it.

Mirrors align_and_evaluate() (the ICESat-2 path) but for planetary altimetry. Requires load_planetary_csv() to have been called so self.planetary_points is populated.

Decision logic:

  1. If fewer than minimum_points valid planetary points are available, 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 or the translation magnitude is below min_translation_threshold × DEM GSD, delete the aligned DEM and return status="no_improvement".

  3. Otherwise re-run planetary_to_dem_dh() to populate altimetry_minus_aligned_dem and return status="success".

Parameters:

  • max_displacement (float, optional) – --max-displacement for pc_align, in meters. Default 500 (ASAP-Stereo’s CTX cookbook recommendation).

  • improvement_threshold_pct (float, optional) – Minimum p50 reduction (%) required to keep the aligned DEM.

  • min_translation_threshold (float, optional) – Minimum translation magnitude as a fraction of the DEM GSD.

  • minimum_points (int, optional) – Minimum number of valid altimetry points to attempt alignment. Planetary tracks are sparser than ICESat-2, so this defaults to a much smaller number than the Earth path.

Return type:

AlignmentResult

alignment_report(processing_level='ground', minimum_points=500, agreement_threshold=0.25, write_out_aligned_dem=False, min_translation_threshold=0.1, key_for_aligned_dem=None)#

Generate alignment reports and optionally align the DEM.

Runs pc_align between the DEM and filtered ATL06-SR data for all temporal variations of a given processing level, generates reports of the alignment results, and optionally creates an aligned DEM.

Parameters:

  • processing_level (str, optional) – Base processing level to use, default is “ground”

  • minimum_points (int, optional) – Minimum number of points required for alignment, default is 500

  • agreement_threshold (float, optional) – Threshold for agreement between different temporal alignments, as a fraction of the mean shift, default is 0.25

  • write_out_aligned_dem (bool, optional) – Whether to create an aligned DEM, default is False

  • min_translation_threshold (float, optional) – Minimum translation magnitude as a fraction of the DEM GSD to warrant creating an aligned DEM, default is 0.1

  • key_for_aligned_dem (str, optional) – Which temporal filter key to use for alignment if write_out_aligned_dem is True. Default is None, which uses the processing_level value.

Returns:

Sets self.alignment_report_df and optionally self.aligned_dem_fn

Return type:

None

Notes

This method performs both the pc_align operations and analysis of the alignment results. It checks for consistency across temporal filters and only creates an aligned DEM if the translation is significant enough and consistent across temporal windows.

atl06sr_to_dem_dh(n_sigma=3)#
filter_esa_worldcover(*args, **kwargs)#
filter_outliers(*args, **kwargs)#
generic_temporal_filter_atl06sr(*args, **kwargs)#
get_altimetry_selections(*args, **kwargs)#
histogram(key='all', title='Histogram', plot_aligned=False, save_dir=None, fig_fn=None)#
histogram_by_landcover(key='all', top_n=4, title='ICESat-2 ATL06-SR vs DEM', xlim=None, plot_aligned=False, save_dir=None, fig_fn=None)#
histogram_planetary_to_dem(save_dir=None, fig_fn=None, title=None, plot_aligned=False)#
load_atl06sr_from_parquet(*args, **kwargs)#
load_planetary_csv(*args, **kwargs)#
mapview_plot_atl06sr_to_dem(key='all', clim=None, plot_aligned=False, save_dir=None, fig_fn=None, map_crs=None, **ctx_kwargs)#
mapview_plot_planetary_to_dem(clim=None, save_dir=None, fig_fn=None, title=None, plot_aligned=False)#
planetary_to_dem_dh(*args, **kwargs)#
plot_atl06sr(key='all', **kwargs)#
plot_atl06sr_dem_profile(key='all', rgt=None, cycle=None, spot=None, segments=None, plot_aligned=False, save_dir=None, fig_fn=None)#
plot_atl06sr_time_stamps(key='all', **kwargs)#
plot_best_worst_segments(key='all', rgt=None, cycle=None, spot=None, segments=None, plot_aligned=False, save_dir=None, fig_fn=None)#
predefined_temporal_filter_atl06sr(*args, **kwargs)#
request_atl06sr_multi_processing(*args, **kwargs)#
sample_esa_worldcover(*args, **kwargs)#
to_csv_for_pc_align(*args, **kwargs)#
to_csv_for_pc_align_planetary(filename_prefix='planetary_for_pc_align')#
aligned_dem_fn = None#
property atl06sr_processing_levels#
property atl06sr_processing_levels_filtered#
dem_fn#
directory#
icesat2#
planetary#
property planetary_points#
plotter#
asp_plot.altimetry.logger#
Contents