asp_plot.icesat2_source

asp_plot.icesat2_source#

ICESat-2 ATL06-SR altimetry source.

Owns the Earth/ICESat-2 side of asp_plot.altimetry.Altimetry: requesting ATL06-SR points from SlideRule (with parquet caching), sampling ESA WorldCover, temporal and outlier filtering, differencing against the ASP DEM, and selecting the best track / best-worst 1 km segments used by the profile plots and reproducibility (#121).

The class holds its own data (atl06sr_processing_levels / atl06sr_processing_levels_filtered and the resolved request time range) and reads the cross-cutting dem_fn / directory / aligned_dem_fn from the coordinating Altimetry instance passed at construction.

Attributes#

ICESAT2_MISSION_START

logger

Classes#

Icesat2Source

Request, cache, filter and difference ICESat-2 ATL06-SR points.

Module Contents#

class asp_plot.icesat2_source.Icesat2Source(alt, atl06sr_processing_levels=None, atl06sr_processing_levels_filtered=None)#

Request, cache, filter and difference ICESat-2 ATL06-SR points.

Parameters:

  • alt (Altimetry) – The coordinating asp_plot.altimetry.Altimetry instance. Cross-cutting paths (dem_fn, directory, aligned_dem_fn) are read from it so a single source of truth describes the DEM under analysis.

  • atl06sr_processing_levels (dict, optional) – Pre-loaded ATL06-SR data for different processing levels.

  • atl06sr_processing_levels_filtered (dict, optional) – Pre-loaded filtered ATL06-SR data.

atl06sr_to_dem_dh(n_sigma=3)#

Calculate height differences between ATL06-SR data and DEMs.

Interpolates DEM heights at ATL06-SR point locations and calculates the difference between ICESat-2 heights and DEM heights. If an aligned DEM is available, also calculates differences against it. Outliers beyond n_sigma × NMAD from the median are removed by default.

Parameters:

n_sigma (float or None, optional) – Remove dh outliers beyond this many NMAD from the median. Default 3. Pass None to skip outlier filtering.

Returns:

Adds columns to the filtered ATL06-SR data: - dem_height: Interpolated height from the original DEM - icesat_minus_dem: Height difference (ICESat-2 - DEM) - aligned_dem_height: Interpolated height from aligned DEM (if available) - icesat_minus_aligned_dem: Height difference with aligned DEM (if available)

Return type:

None

Notes

This method performs bilinear interpolation of DEM values at ATL06-SR point locations using xarray and rioxarray. It handles coordinate system conversions automatically.

filter_esa_worldcover(filter_out='water', retain_only=None)#

Filter ATL06-SR data based on ESA WorldCover land cover classes.

Filters the data points based on ESA WorldCover classification, either by removing specific land cover types or retaining only specific types.

Parameters:

  • filter_out (str, optional) – Land cover group to filter out, default is “water”. Options: “water”, “snow_ice”, “trees”, “low_vegetation”, “built_up”

  • retain_only (str or None, optional) – If specified, retain only points matching this land cover group, default is None. Same options as filter_out.

Returns:

Results are stored in the class attributes

Return type:

None

Notes

This method uses the ESA WorldCover land cover classification (see WORLDCOVER_NAMES), which was sampled when requesting the ATL06-SR data.

filter_outliers(column='icesat_minus_dem', n_sigma=3)#

Remove dh outliers beyond n_sigma × standard deviation from the mean.

Parameters:

  • column (str, optional) – Column to filter on, default "icesat_minus_dem".

  • n_sigma (float, optional) – Number of standard deviations to allow, default 3.

generic_temporal_filter_atl06sr(select_years=None, select_months=None, select_days=None)#

Apply custom temporal filters to ATL06-SR data.

Filters the data based on specific years, months, or days, allowing for custom temporal filtering not covered by the predefined filters.

Parameters:

  • select_years (list or None, optional) – Years to keep (e.g., [2019, 2020]), default is None

  • select_months (list or None, optional) – Months to keep (1-12), default is None

  • select_days (list or None, optional) – Days of month to keep (1-31), default is None

Returns:

Results are filtered in-place in the class attributes

Return type:

None

Notes

This method modifies the existing filtered data rather than creating new entries with different keys. At least one of the filter parameters should be provided for the method to have any effect.

get_altimetry_selections(key='all')#

Report the ICESat-2 selections a run made, for reproducibility (#121).

Bundles the request settings, the parquet cache locations (the exact points used), the auto-selected profile track, and the best/worst segment extents so they can be written to a figure-selections file and replayed on a later run.

Parameters:

key (str, optional) – Processing level key, default is “all”.

Returns:

{"request": {..}, "parquet_cache": {key: path}, "profile_track": {"rgt", "cycle", "spot"}, "segments": {"best": {..}, "worst": {..}}}. Keys are omitted when the corresponding selection is unavailable.

Return type:

dict

load_atl06sr_from_parquet(parquet_paths, h_sigma_quantile=1.0)#

Load ATL06-SR points directly from saved parquet caches.

Replays the exact points a prior run used (issue #121), bypassing the SlideRule request entirely so a re-processed scene compares against an identical ICESat-2 sample. Runs the same normalization + quality filter as a fresh request via _ingest_atl06sr.

Parameters:

  • parquet_paths (dict) – Mapping of processing-level key -> parquet path (e.g. {"all": ".../atl06sr_all.parquet"}).

  • h_sigma_quantile (float, optional) – Quantile of h_sigma above which fits are discarded, default 1.0.

Returns:

True if at least one parquet was loaded, False otherwise.

Return type:

bool

predefined_temporal_filter_atl06sr(date=None)#

Apply predefined temporal filters to ATL06-SR data.

Creates multiple temporally filtered versions of the ATL06-SR data based on a reference date, including: - 15-day window around the date - 45-day window around the date - 91-day window around the date - Seasonal filter (same season as the reference date)

Parameters:

date (datetime or None, optional) – Reference date for filtering. If None, extracts date from stereopair metadata, default is None

Returns:

Results are stored in the class attributes with new keys indicating the temporal filter applied

Return type:

None

Notes

This method is particularly useful for DEM validation and alignment, as it provides multiple temporal windows to analyze the stability of the terrain and to identify optimal temporal windows for alignment.

request_atl06sr_multi_processing(processing_levels=['all', 'ground', 'canopy', 'top_of_canopy'], res=20, len=40, ats=20, cnt=10, maxi=6, h_sigma_quantile=1.0, save_to_parquet=False, filename='atl06sr', region=None, time_range='all', scene_date=None, time_buffer_days=365, t0=None, t1=None)#

Request ICESat-2 ATL06-SR data for multiple processing levels.

Downloads ATL06-SR data from the SlideRule API for specified processing levels (surface types), with options to filter and save the results. Each processing level targets different surface types like ground, canopy, etc.

Parameters:

  • processing_levels (list, optional) – List of processing levels to request, default is [“all”, “ground”, “canopy”, “top_of_canopy”]

  • res (int, optional) – ATL06-SR segment resolution in meters, default is 20

  • len (int, optional) – ATL06-SR segment length in meters, default is 40

  • ats (int, optional) – Along-track sigma, default is 20

  • cnt (int, optional) – Minimum number of photons for segment, default is 10

  • maxi (int, optional) – Maximum iterations for surface fit, default is 6

  • h_sigma_quantile (float, optional) – Quantile for filtering by h_sigma, default is 1.0

  • save_to_parquet (bool, optional) – Whether to save results to parquet files, default is False

  • filename (str, optional) – Base filename for saved data, default is “atl06sr”

  • region (list or None, optional) – Region bounds as [minx, miny, maxx, maxy] in lat/lon, default is None (derived from DEM)

  • time_range (str, optional) – "all" (default) requests all ICESat-2 data from mission start to present. "buffered" activates time filtering via the cascade: t0/t1 > scene_date ± time_buffer_days > XML metadata ± time_buffer_days > fall back to all.

  • scene_date (str or datetime-like, optional) – Scene acquisition date, used when time_range="buffered". If None, auto-detected from stereopair XML metadata.

  • time_buffer_days (int, optional) – Days before/after scene_date defining the time window, default is 365

  • t0 (str or datetime-like, optional) – Explicit start date (e.g. “2020-01-01”), used when time_range="buffered". Overrides scene_date.

  • t1 (str or datetime-like, optional) – Explicit end date (e.g. “2024-12-31”). Defaults to present if only t0 is provided.

Returns:

Results are stored in the class attributes

Return type:

None

Notes

This method makes SlideRule API calls which require internet connectivity. It also samples ESA WorldCover data for land cover classification of the ICESat-2 data points. The method includes filtering to improve data quality by removing points with high uncertainty and from early mission cycles.

sample_esa_worldcover()#

Sample ESA WorldCover 10m values into every filtered processing level that doesn’t already have them.

Normally not needed when data is requested via request_atl06sr_multi_processing, which samples WorldCover automatically before caching. Use this when working with manually-loaded data.

to_csv_for_pc_align(key='ground', filename_prefix='atl06sr_for_pc_align')#

Export ATL06-SR data to CSV format for use with pc_align.

Creates a CSV file from the filtered ATL06-SR data that is formatted for use with the ASP pc_align tool, containing longitude, latitude, and height above datum.

Parameters:

  • key (str, optional) – Processing level to export, default is “ground”

  • filename_prefix (str, optional) – Prefix for the output CSV file, default is “atl06sr_for_pc_align”

Returns:

Path to the created CSV file

Return type:

str

Notes

The ASP pc_align tool requires input data in a specific format. This method converts the ATL06-SR GeoDataFrame to the required CSV format with columns for longitude, latitude, and height.

alt#
atl06sr_processing_levels#
atl06sr_processing_levels_filtered#
asp_plot.icesat2_source.ICESAT2_MISSION_START#
asp_plot.icesat2_source.logger#