cryoswath.l3 module#

Aggregate L2 point elevations into regular spatio-temporal L3 grids.

cryoswath.l3.build_dataset(region_of_interest, start_datetime, end_datetime, *, l2_type='swath', buffer_region_by=None, max_elev_diff=150, timestep_months=1, window_ntimesteps=3, spatial_res_meter=500, agg_func_and_meta=(<function _med_iqr_cnt>, {'_count': 'i8', '_iqr': 'f8', '_median': 'f8'}), cache_filename=None, cache_filename_extra=None, outfilepath=None, crs=None, reprocess=False, **l2_from_id_kwargs)[source]#

Build a gridded dataset of elevation estimates.

This function aggregates Level-2 (L2) elevation data into a regular grid using a rolling window approach. The resulting dataset is stored in a Zarr format for efficient access and analysis.

Parameters:

  • region_of_interest (str | shapely.Polygon) – The region to process, specified as a RGI region ID (string) or a custom shapely Polygon.

  • start_datetime (str | pd.Timestamp) – The start date for the dataset.

  • end_datetime (str | pd.Timestamp) – The end date for the dataset.

  • l2_type (str, optional) – Type of L2 data to process (“swath”, “poca”, or “both”). Defaults to “swath”.

  • buffer_region_by (float, optional) – Buffer distance (in meters) to expand the region of interest. Defaults to 30,000 meters if not provided.

  • max_elev_diff (float, optional) – Maximum elevation difference to filter the data. Defaults to 150 meters.

  • timestep_months (int, optional) – Time step in months. Defaults to 1 month.

  • window_ntimesteps (int, optional) – Number of time steps for the rolling window data aggregation. Must be an odd number. Defaults to 3.

  • spatial_res_meter (float, optional) – Spatial resolution of the output grid in meters. Defaults to 500 meters.

  • agg_func_and_meta (tuple[callable, dict], optional) – Aggregation function and metadata for the output variables. Defaults to calculating the median, interquartile range, and data count.

  • cache_filename (str, optional) – Custom filename for the cached L2 data. Defaults to a name derived from the region ID.

  • cache_filename_extra (str, optional) – Additional string to append to the cache filename. Defaults to None.

  • outfilepath (str | Path, optional) – Output zarr path. If omitted, it is inferred from the region and grid settings.

  • crs (CRS | int, optional) – Coordinate reference system for the data. If None, a planar CRS is determined automatically. Defaults to None.

  • reprocess (bool, optional) – Whether to reprocess existing data. Defaults to False.

  • **l2_from_id_kwargs – Additional keyword arguments passed to the cryoswath.l2.from_id() function.

Returns:

The gridded dataset of elevation estimates.

Return type:

xarray.Dataset

Raises:

  • Warning – If the window_ntimesteps is not an odd number, it is adjusted and a warning is issued.

  • Exception – If joined swath and poca aggregation is requested (not implemented).

Notes

  • The function requires significant amounts of working memory.

  • Intermediate results are saved to ensure progress is not lost in case of interruptions.

cryoswath.l3.cache_l2_data(region_of_interest, start_datetime, end_datetime, *, buffer_region_by=None, max_elev_diff=150, timestep_months=1, window_ntimesteps=3, cache_filename=None, cache_filename_extra=None, crs=None, reprocess=False, **l2_from_id_kwargs)[source]#

Cache Level-2 (L2) data for a specified region and time period.

This function processes and stores essential L2 data in an HDF5 file, downloading and processing Level-1b (L1b) files if they are not available. It supports buffering the region and time period to ensure no data is missed.

Parameters:

  • region_of_interest (str | shapely.Polygon) – The region to process, specified as a RGI region ID (string) or a custom shapely Polygon.

  • start_datetime (str | pd.Timestamp) – The start date for the data to be cached.

  • end_datetime (str | pd.Timestamp) – The end date for the data to be cached.

  • buffer_region_by (float, optional) – Buffer distance (in meters) to expand the region of interest. Defaults to 30,000 meters if not provided.

  • max_elev_diff (float, optional) – Maximum elevation difference to filter the data. Defaults to 150 meters.

  • timestep_months (int, optional) – Time step in months. Defaults to 1 month.

  • window_ntimesteps (int, optional) – Number of time steps for the rolling window data aggregation. Must be an odd number. Defaults to 3.

  • cache_filename (str, optional) – Custom filename for the cached data. Defaults to a name derived from the region ID.

  • cache_filename_extra (str, optional) – Additional string to append to the cache filename. Defaults to None.

  • crs (CRS | int, optional) – Coordinate reference system for the data. If None, a planar CRS is determined automatically. Defaults to None.

  • reprocess (bool, optional) – Whether to reprocess existing data. Defaults to False.

  • **l2_from_id_kwargs – Additional keyword arguments passed to the cryoswath.l2.from_id() function.

Returns:

The function saves the processed data to an HDF5 file and does not return any value.

Return type:

None

Raises:

Warning – If the window_ntimesteps is not an odd number, it is adjusted and a warning is issued.

cryoswath.l3.extend_dataset(dataset_or_path, end_datetime, *, recompute_start_datetime=None, output_path=None, overlap_time_steps=2, overlap_policy='keep_original', overlap_rtol=1e-05, overlap_atol=1e-08, region_of_interest=None, l2_type='swath', buffer_region_by=None, max_elev_diff=150, timestep_months=None, window_ntimesteps=None, spatial_res_meter=None, agg_func_and_meta=(<function _med_iqr_cnt>, {'_count': 'i8', '_iqr': 'f8', '_median': 'f8'}), cache_filename=None, cache_filename_extra=None, crs=None, overwrite=False, reprocess=True, **l2_from_id_kwargs)[source]#

Extend an existing L3 dataset by recomputing a tail segment.

Parameters:

  • dataset_or_path (Dataset | str | Path)

  • end_datetime (str | Timestamp)

  • recompute_start_datetime (str | Timestamp)

  • output_path (str | Path)

  • overlap_time_steps (int)

  • overlap_policy (str)

  • overlap_rtol (float)

  • overlap_atol (float)

  • region_of_interest (str | Polygon)

  • l2_type (str)

  • buffer_region_by (float)

  • max_elev_diff (float)

  • timestep_months (int)

  • window_ntimesteps (int)

  • spatial_res_meter (float)

  • agg_func_and_meta (tuple[callable, dict])

  • cache_filename (str)

  • cache_filename_extra (str)

  • crs (CRS | int)

  • overwrite (bool)

  • reprocess (bool)