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

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__()

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)

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, optional) – Whether to invert the y-axis when computing affine transformation, by default True.

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

  • 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 or 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) – OGGM dataset a geospatial CRS to extract extent from.

  • self (DatacubeCryotempoEolis)

Returns:

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

Return type:

shapely.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:

GeoDataFrame containing the glacier mask polygon(s) in the specified CRS.

Return type:

gpd.GeoDataFrame

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 with NaNs.

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

  • **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) – Column name holding elevation change values.

  • elevation_change_sigma_var_name (str) – Column name holding uncertainty values.

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

  • 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, optional) – Whether to return all metadata from the first product without parsing, by default True.

  • 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 (shapely.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, optional) – Optional minimum timestamp to filter results, by default None. If not set then the minimum timestamp of the dataset in specklia will be used.

  • max_timestamp (int, optional) – Optional maximum timestamp to filter results, by default None. 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