cryoswath.l4 module#

Higher-level post-processing for L3 products (gap filling and trends).

cryoswath.l4.add_meta_to_default_finalized_l3(outdir, your_name='unkown', your_institution='n/a', all_double=False)[source]#

Adds meta data to and changes variable names of L3 dataset

This function expects that pathlib.Path().stat().st_mtime() returns seconds since Unix epoch and only makes sense if you ran:

cryoswath.l3.build_dataset(region_id)
cryoswath.l4.fill_l3_voids(region_id)

If you deviated from default values in the processing, verify the output of this function.

Parameters:

  • outdir (str | Path) – Path to output directory.

  • your_name (str, optional) – Your name. Defaults to “n/a”.

  • your_institution (str, optional) – Your institution. Defaults to “n/a”.

  • all_double (bool)

cryoswath.l4.append_basin_group(ds, basin_gdf=None)[source]#

Append per-cell basin-group identifier for grouped interpolation.

Parameters:

  • ds (DataArray | Dataset)

  • basin_gdf (GeoDataFrame)

Return type:

Dataset

cryoswath.l4.append_basin_id(ds, basin_gdf=None)[source]#

Append per-cell basin identifier derived from glacier polygons.

Parameters:

  • ds (DataArray | Dataset)

  • basin_gdf (GeoDataFrame)

Return type:

Dataset

cryoswath.l4.append_elevation_reference(geospatial_ds, ref_elev_name='ref_elev', dem_file_name_or_path=None)[source]#

Append DEM-based elevation reference resampled to dataset grid.

Parameters:

  • geospatial_ds (Dataset | DataArray)

  • ref_elev_name (str)

  • dem_file_name_or_path (str)

Return type:

Dataset

cryoswath.l4.difference_to_reference_dem(l3_data, save_to_disk=True, basin_shapes=None)[source]#

Fill L3 gaps and return elevation differences relative to DEM.

Parameters:

  • l3_data (Dataset)

  • save_to_disk (str | bool)

  • basin_shapes (GeoDataFrame)

Return type:

Dataset

cryoswath.l4.elevation_trend_raster_from_l3(region_id, *, only_intermediate=False, diagnostic_hook=None)[source]#

Calculate elevation trend for each cell of L3 dataset

This is a convenience function that currently takes opinionated choices that cannot be modified. More capabilities are planned to be implemented in future.

Next to returning the elevation trends, these are, also, written to disk. If the result files are present, these will be read instead of repeating the calculation.

Parameters:

  • region_id (str) – Region identifier that was used in the L3 Zarr store names.

  • only_intermediate (bool, optional) – If true, returns after calculating the trends where sufficient data is available and skips filling voids. Defaults to False.

  • diagnostic_hook (Callable, optional) – Opt-in hook called with diagnostic event names and payloads.

Returns:

Dataset of elevation trends and other parameters, depending on the usage.

Return type:

xr.Dataset

cryoswath.l4.fill_l3_voids(o2region)[source]#

Fills data gaps in L3 datasets

This is a convenience function that currently takes opinionated choices that cannot be modified. More capabilities are planned to be implemented in future.

This function, also, writes the results to disk. If a file is present at the corresponding location, it is read instead of being recalculated.

Parameters:

o2region (str) – The RGI second order region identifier.

Returns:

Filled dataset.

Return type:

xr.Dataset

cryoswath.l4.fill_voids(ds, main_var, error, *, elev='ref_elev', per=('basin', 'basin_group'), basin_shapes=None, discard_deglaciated=True, outlier_limit=5, outlier_replace=False, outlier_iterations=1, fit_sanity_check=None, filled_flag=None, diagnostic_hook=None)[source]#

Fill spatial/temporal gaps using hierarchical hypsometric strategies.

The routine fills by basin, then basin group, then region-wide, with temporal interpolation for short and edge gaps when time is present. It loads basin outlines if needed, restores missing coordinates and reference elevation, and can record fill provenance in filled_flag.

This is memory intensive: regrouping, unstacking, and reindexing can temporarily require roughly 5-10x the input L3 dataset size.

Parameters:

  • ds (Dataset)

  • main_var (str)

  • error (str)

  • elev (str)

  • per (tuple[str])

  • basin_shapes (GeoDataFrame)

  • discard_deglaciated (bool)

  • outlier_limit (float)

  • outlier_replace (bool)

  • outlier_iterations (int)

  • fit_sanity_check (dict)

  • filled_flag (str)

  • diagnostic_hook (Callable[[str, dict[str, Any]], Any] | None)

Return type:

Dataset

cryoswath.l4.fit_trend(data, *, pivot=<DateOffset: months=0>, timestep_months=12, return_raw=False)[source]#

Fit linear trend (and uncertainty) for regularly sampled time series.

Parameters:

  • data (Dataset)

  • pivot (DateOffset)

  • timestep_months (int)

  • return_raw (bool)

Return type:

Dataset

cryoswath.l4.fit_trend__seasons_removed(l3_ds)[source]#

Fit a trend-plus-season model after masking low-quality cells.

Parameters:

l3_ds (Dataset)

Return type:

Dataset

cryoswath.l4.timeseries_from_gridded(ds, void_err_type='prediction', diagnostic_hook=None)[source]#

Calculates uncertainties of average elevation

This function returns a two-column DataFrame of elevation averages and the associated uncertaities. Computing the uncertainties is not trivial and will be reasoned in an upcoming paper.

The void filling flags are essential. Currently they are hard-coded and have the following meaning: -2: filling failed -1/nan: no data 0: no filling 1: filled based on trend_with_season() fit per cell 2: misc.interpolate_hypsometrically() per basin 3: misc.interpolate_hypsometrically() per group of basins 4: linear temporal interpolation for gaps shorter than one year 5: second order region wide misc.interpolate_hypsometrically() 6: filling with temporally closest value per cell

Select void_err_type depending on whether prediction or confidence intervals were assigned. Note that in any case the errors are expected to be on the scale of interquartile ranges, i.e., the errors will be multiplied by a scaling factor.

Parameters:

  • ds (xr.Dataset) – Void-filled L3 dataset. Needs variables “_median”, “_iqr”, “basin_id”, “group_id, “filled_flag”, “x”, “y”, and “time”.

  • void_err_type (Literal["prediction", "confidence"]) – Type of errors for filled voids. Defaults to “prediction”.

  • diagnostic_hook (Callable, optional) – Opt-in hook called with diagnostic event names and payloads.

Returns:

DataFrame with columns “elevation” and

”uncertainty”, and time stamps on the index.

Return type:

pd.DataFrame

cryoswath.l4.trend_with_seasons(t_ns, trend, offset, amp_yearly, phase_yearly, amp_semiyr, phase_semiyr)[source]#

Linear trend plus annual and semi-annual harmonic components.