gaussian_random_field.grf_module.geo_zarr_utils

Utility functions for working with GeoZarr data within the GRF module.

Functions

prepare_cf_data_variable_arrays(ds)

Assign CF grid-mapping and fill-value metadata to dataset variables.

prepare_cf_spatial_data_array(...)

Assign the required GeoZarr attributes to a spatial coordinate.

prepare_cf_time_data_array(time_data_array)

Convert a time coordinate to numeric epoch seconds with legacy CF metadata.

save_geo_zarr(ds, zarr_path[, target_chunk_size])

Save dataset to GeoZarr adhering to CF conventions (https://cfconventions.org/).

sparse_grid_to_point_cloud(ds)

Convert a sparse grid dataset to a point cloud format.

trim_to_mesh(ds, mesh)

Drop points that fall outside the mesh.

prepare_cf_data_variable_arrays(ds: Dataset) → Dataset

Assign CF grid-mapping and fill-value metadata to dataset variables.

prepare_cf_spatial_data_array(spatial_data_array: DataArray, name: str, axis: str) → DataArray

Assign the required GeoZarr attributes to a spatial coordinate.

prepare_cf_time_data_array(time_data_array: DataArray) → DataArray

Convert a time coordinate to numeric epoch seconds with legacy CF metadata.

save_geo_zarr(ds: Dataset, zarr_path: Path | str, target_chunk_size: str = '1024MB') → None

Save dataset to GeoZarr adhering to CF conventions (https://cfconventions.org/).

Parameters:
  • ds (xr.Dataset) – The xarray dataset to save. This must follow the GeoZarr format, including having a spatial_ref attribute with a valid CRS.

  • zarr_path (Path | str) – Full path of the output .zarr file to be created.

  • target_chunk_size (str, optional) – The target chunk size for the GeoZarr dataset, by default “1024MB”.

sparse_grid_to_point_cloud(ds: Dataset) → Dataset

Convert a sparse grid dataset to a point cloud format.

This function removes NaN cells in the grid, and returns the resulting cells as a flattened point cloud.

Data already stored as a point cloud is accepted too. Some sources are not on a regular grid in the target CRS - RACMO’s native run is on a rotated pole, so its cells do not fall on x/y axes once reprojected - and those datasets carry a single dimension of positions instead. They are passed through with the dimension renamed, rather than being gridded first.

Parameters:

ds (xr.Dataset) –

The input GeoZarr dataset, in one of two forms.

A sparse grid, with at least the following dimensions:
  • time (must be of length 1)

  • x (or old name: ‘projection_x_coordinate’)

  • y (or old name: ‘projection_y_coordinate’)

Or a point cloud, with:
  • time (must be of length 1)

  • point (or ‘point_id’), with x and y giving each position

Returns:

A dataset where the spatial X and Y dimensions have been stacked into a single ‘point_id’ dimension, and points where all variables are NaN across all timesteps have been removed.

Return type:

xr.Dataset

Raises:

ValueError – If the dataset does not have exactly one time step, or has neither a pair of spatial dimensions nor a point dimension carrying x and y.

trim_to_mesh(ds: Dataset, mesh: SpdeMesh) → Dataset

Drop points that fall outside the mesh.

The published input datasets cover a buffer around the catchment, while a mesh covers the catchment alone, so a dataset normally carries points the mesh cannot represent. Those points give an all-zero row in the projector matrix and INLA refuses the fit, so they are removed before fitting rather than left to fail.

Parameters:
Returns:

The same dataset with only the points the mesh covers.

Return type:

xr.Dataset

Raises:

ValueError – If no point falls on the mesh at all, which means the data and the mesh do not describe the same place.