DatacubeCryotempoEolis#

class dtcg.datacube.cryotempo_eolis.DatacubeCryotempoEolis[source]#

Bases: object

Functionality for adding EOLIS data to a OGGM datacube.

SPECKLIA_DATASET_NAME_EOLIS_ELEVATION_CHANGE#

Name of the dataset in Specklia to add to the OGGM datacube.

Type:

str

MINIMUM_REQUIRED_EOLIS_COVERAGE_FRACTION#

Minimum required fraction of EOLIS data coverage over glacier area for data to be considered valid.

Type:

float

MINIMUM_REQUIRED_GLACIER_AREA_KM2#

Minimum required glacier area in square kilometers for data to be considered valid.

Type:

float

EOLIS_STATIC_KEYS#

EOLIS metadata keys that are static across product files.

Type:

list[str]

EOLIS_PRODUCT_KEYS#

EOLIS metadata keys that are unique for each product.

Type:

list[str]

Methods

__init__()

add_data(datacube, gdir)

Add gridded EOLIS data from a glacier directory to a datacube.

augment_dataset_with_1d_timeseries(...)

Generate and attach 1D time series of elevation change and uncertainty to an OGGM dataset.

convert_gridded_dataframe_to_array(...[, ...])

Resolve arrays from sparse gridded data stored in a dataframe.

create_query_polygon(oggm_ds)

Create a WGS84-aligned polygon bounding box from the spatial extent of an OGGM dataset.

create_vector_glacier_mask(oggm_ds, target_crs)

Vectorise the glacier mask of an OGGM dataset into polygon(s).

gaussian_filter_fill(arr[, sigma])

Fill NaN regions in an array using Gaussian filter.

generate_1d_timeseries(eolis_gridded_data, ...)

Compute a 1D elevation change time series with propagated uncertainties.

prepare_eolis_metadata(specklia_source_data)

Extract metadata from Specklia dataset source information.

retrieve_data_from_specklia(query_polygon, ...)

Query and retrieve data from the Specklia API for a given spatial and temporal extent.

retrieve_prepare_eolis_gridded_data(oggm_ds, ...)

Retrieve EOLIS gridded elevation change data and resample it to the given OGGM grid.
__init__()[source]#
Parameters:

self (DatacubeCryotempoEolis)

add_data(datacube, gdir)[source]#

Add gridded EOLIS data from a glacier directory to a datacube.

Every datacube must support this method. It should be able to add data to the provided datacube and returns the final datacube.

Parameters:
Return type:

xr.Dataset

augment_dataset_with_1d_timeseries(
eolis_gridded_data,
oggm_ds,
elevation_change_var_name,
elevation_change_sigma_var_name,
)[source]#

Generate and attach 1D time series of elevation change and uncertainty to an OGGM dataset.

This method masks gridded EOLIS data to the glacier extent, computes mean elevation change and propagated uncertainties per timestamp, and appends them to the input OGGM dataset as new time series variables.

Parameters:

  • eolis_gridded_data (geopandas.GeoDataFrame) – EOLIS gridded data containing x/y locations, timestamps, and elevation change values.

  • oggm_ds (xr.Dataset) – OGGM dataset to which new time series variables will be added.

  • elevation_change_var_name (str) – Name of the column holding elevation change values in the input data.

  • elevation_change_sigma_var_name (str) – Name of the column holding uncertainty values in the input data.

  • self (DatacubeCryotempoEolis)

Returns:

The input dataset is modified in place with new 1D time series variables.

Return type:

None

convert_gridded_dataframe_to_array(
gridded_df,
value_column_names,
x_coordinate_column,
y_coordinate_column,
spatial_resolution,
xy_projection,
y_affine_negative=True,
t_coordinate_column=None,
)[source]#

Resolve arrays from sparse gridded data stored in a dataframe.

For each column name specified, an array (either 2d, or 3d if a time coordinate is supplied) is created using the x and y extent in the gridded dataframe and the provided resolution, and is populated with the sparse gridded data from the dataframe.

Parameters:

  • gridded_df (pd.DataFrame) – DataFrame containing sparse gridded data, including coordinate columns and value columns.

  • value_column_names (list[str]) – List of column names whose values are to be gridded.

  • x_coordinate_column (str) – Name of the column containing x coordinates.

  • y_coordinate_column (str) – Name of the column containing y coordinates.

  • spatial_resolution (float) – Resolution to use when constructing the regular grid.

  • xy_projection (Proj) – PyProj projection object representing the spatial reference system.

  • y_affine_negative (bool, default True) – Whether to invert the y-axis when computing affine transformation.

  • t_coordinate_column (str, default None) – Optional name of time coordinate column to create a 3D array.

  • self (DatacubeCryotempoEolis)

Returns:

  • Dictionary of gridded arrays keyed by column name

  • Salem Grid object describing the spatial extent

  • Optional array of sorted time coordinates (if time is used)

Return type:

tuple[dict[str, np.ndarray], Grid, np.ndarray | None]

create_query_polygon(oggm_ds)[source]#

Create a WGS84-aligned polygon bounding box from the spatial extent of an OGGM dataset.

Parameters:

  • oggm_ds (xr.Dataset) – The OGGM dataset from which to extract the geospatial CRS extent.

  • self (DatacubeCryotempoEolis)

Returns:

Polygon in EPSG:4326 (lat/lon) describing the outer bounds of the OGGM dataset.

Return type:

Polygon

create_vector_glacier_mask(
oggm_ds,
target_crs,
)[source]#

Vectorise the glacier mask of an OGGM dataset into polygon(s).

The raster glacier mask is converted to shapely polygons using rasterio.features.shapes, dissolved into a single geometry, and reprojected to the target CRS.

Parameters:

  • oggm_ds (xr.Dataset) – OGGM dataset containing a glacier_mask DataArray and CRS.

  • target_crs (CRS) – Target coordinate reference system for the output polygons.

  • self (DatacubeCryotempoEolis)

Returns:

Glacier mask polygon in the specified CRS.

Return type:

Polygon

gaussian_filter_fill(
arr,
sigma=3.0,
**kwargs,
)[source]#

Fill NaN regions in an array using Gaussian filter.

The data and a validity mask are filtered separately and combined so that only NaNs are replaced, while original values remain unchanged.

Parameters:

  • arr (np.ndarray) – Input array containing NaNs.

  • sigma (float | tuple[float], default 3.0) – Standard deviation(s) for the Gaussian kernel.

  • **kwargs (dict) – Additional arguments passed to scipy.ndimage.gaussian_filter.

  • self (DatacubeCryotempoEolis)

Returns:

Copy of arr with NaNs filled by Gaussian-smoothed neighbors.

Return type:

np.ndarray

generate_1d_timeseries(
eolis_gridded_data,
elevation_change_var_name,
elevation_change_sigma_var_name,
length_scale=6000.0,
)[source]#

Compute a 1D elevation change time series with propagated uncertainties.

For each timestamp in the gridded dataset, the function calculates the mean elevation change across all valid pixels and estimates the uncertainty of the mean by building a covariance matrix that accounts for spatial correlation between points.

Parameters:

  • eolis_gridded_data (gpd.GeoDataFrame) – EOLIS gridded data containing x/y locations, timestamps, and elevation change values.

  • elevation_change_var_name (str) – Name of the column holding elevation change values.

  • elevation_change_sigma_var_name (str) – Name of the column holding uncertainty values.

  • length_scale (int | float, default 6e3) – Spatial correlation length scale in eolis_gridded_data geometry crs units used to construct the exponential decay kernel.

  • self (DatacubeCryotempoEolis)

Returns:

Two lists with the same length as the number of unique timestamps:

  • Mean elevation change per timestamp.

  • Propagated uncertainty per timestamp.

Return type:

tuple[list[float], list[float]]

prepare_eolis_metadata(
specklia_source_data,
preliminary_dataset=True,
)[source]#

Extract metadata from Specklia dataset source information.

Parameters:

  • specklia_source_data (list[dict]) – List of source information dictionaries returned by Specklia.

  • preliminary_dataset (bool, default True) – Whether to return all metadata from the first product without parsing.

  • self (DatacubeCryotempoEolis)

Returns:

Dictionary of static metadata and product-specific attributes, grouped by filename.

Return type:

dict

retrieve_data_from_specklia(
query_polygon,
specklia_data_set_name,
specklia_api_key,
min_timestamp=None,
max_timestamp=None,
)[source]#

Query and retrieve data from the Specklia API for a given spatial and temporal extent.

Parameters:

  • query_polygon (Polygon) – WGS84 polygon representing the spatial area to query.

  • specklia_data_set_name (str) – Name of the dataset to query from Specklia.

  • specklia_api_key (str) – API key used to authenticate with the Specklia service.

  • min_timestamp (int, default None) – Optional minimum timestamp to filter results. If not set then the minimum timestamp of the dataset in specklia will be used.

  • max_timestamp (int, default None) – Optional maximum timestamp to filter results. If not set then the maximum timestamp of the dataset in specklia will be used.

  • self (DatacubeCryotempoEolis)

Returns:

  • GeoDataFrame of geospatial data queried from Specklia

  • List of metadata dicts for all data in the retrieved geodataframe

  • Dataset-level metadata for the Specklia dataset queried

Return type:

tuple[gpd.GeoDataFrame, list[dict], pd.Series]

retrieve_prepare_eolis_gridded_data(
oggm_ds,
grid,
)[source]#

Retrieve EOLIS gridded elevation change data and resample it to the given OGGM grid.

Parameters:

  • oggm_ds (xr.Dataset) – OGGM xarray dataset to which EOLIS data will be added.

  • grid (Grid) – Grid object representing the OGGM grid projection and extent.

  • self (DatacubeCryotempoEolis)

Returns:

Modified OGGM dataset including resampled EOLIS elevation change and uncertainty arrays.

Return type:

xr.Dataset