heiplanet_data.regrid module

heiplanet_data.regrid

Spatial resolution resampling (downsampling and upsampling) of datasets.

This module changes the grid resolution of a dataset:

• downsampling (coarser grid) with one of three backends: downsample_resolution_with_xarray (coarsen/reduce), downsample_resolution_with_xesmf (regridding via xESMF), and downsample_resolution_with_cdo (remapping via the CDO binary),
• upsampling (finer grid) via interpolation (upsample_resolution),
• the dispatching entry point resample_resolution, configured through the ResolutionConfig and GridConfig dataclasses, which picks the backend and direction based on the requested resolution.

This is the only module that imports the heavy optional dependencies xesmf/esmpy and cdo; both require the conda environment to be activated so that the underlying binaries are on PATH.

Classes:

• GridConfig –

  Configuration for grid specification for resampling.

• ResolutionConfig –

  Configuration for resolution resampling.

Functions:

• align_lon_lat_with_popu_data –

  Align longitude and latitude coordinates with population data of the same resolution.

• check_agg_funcs –

  Check if aggregation functions are valid.

• check_downsample_condition –

  Check if downsampling conditions are met.

• downsample_resolution_with_cdo –

  Downsample the resolution of a dataset using CDO.

• downsample_resolution_with_xarray –

  Downsample the resolution of a dataset.

• downsample_resolution_with_xesmf –

  Downsample the resolution of a dataset using xESMF.

• resample_resolution –

  Resample the grid of a dataset to a new resolution.

• upsample_resolution –

  Upsample the resolution of a dataset using xarray.interp.

Attributes:

• warn_positive_resolution –

warn_positive_resolution module-attribute

warn_positive_resolution = 'New resolution must be a positive number.'

GridConfig dataclass

GridConfig(expected_longitude_max_xarray=float64(179.75), new_min_lat=None, new_max_lat=None, new_min_lon=None, new_max_lon=None, new_lat_size=None, new_lon_size=None, gridtype='lonlat')

Configuration for grid specification for resampling.

Attributes:

• expected_longitude_max_xarray (float64) –

  Expected maximum longitude. Default is np.float64(179.75). This is used to adjust the grid after resampling with xarray, e.g. to align with population data.

• new_min_lat (float | None) –

  Minimum latitude of the new grid. Default is None. This is used for resampling with xESMF and CDO.

• new_max_lat (float | None) –

  Maximum latitude of the new grid. Default is None. This is used for resampling with xESMF.

• new_min_lon (float | None) –

  Minimum longitude of the new grid. Default is None. This is used for resampling with xESMF and CDO.

• new_max_lon (float | None) –

  Maximum longitude of the new grid. Default is None. This is used for resampling with xESMF.

• new_lat_size (int | None) –

  Size of latitude of the new grid. Default is None. This is used for resampling with CDO.

• new_lon_size (int | None) –

  Size of longitude of the new grid. Default is None. This is used for resampling with CDO.

• gridtype (Literal['gaussian', 'lonlat', 'curvilinear', 'unstructured']) –

  Type of the grid. Default is "lonlat". This is used for resampling with CDO.

expected_longitude_max_xarray class-attribute instance-attribute

expected_longitude_max_xarray = float64(179.75)

gridtype class-attribute instance-attribute

gridtype = 'lonlat'

new_lat_size class-attribute instance-attribute

new_lat_size = None

new_lon_size class-attribute instance-attribute

new_lon_size = None

new_max_lat class-attribute instance-attribute

new_max_lat = None

new_max_lon class-attribute instance-attribute

new_max_lon = None

new_min_lat class-attribute instance-attribute

new_min_lat = None

new_min_lon class-attribute instance-attribute

new_min_lon = None

ResolutionConfig dataclass

ResolutionConfig(new_resolution=0.5, lat_name='latitude', lon_name='longitude', downsample_lib='xesmf', downsample_agg_funcs=None, upsample_method_map=None)

Configuration for resolution resampling.

Attributes:

• new_resolution (float) –

  New resolution in degrees. Default is 0.5.

• lat_name (str) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str) –

  Name of the longitude coordinate. Default is "longitude".

• downsample_lib (Literal['xarray', 'xesmf', 'cdo']) –

  Library to use for downsampling. Options are "xarray", "xesmf", or "cdo". Default is "xesmf".

• downsample_agg_funcs (Dict[str, str] | None) –

  Aggregation function for each variable. If None, default aggregation of corresponding library is used. Default is None.

• upsample_method_map (Dict[str, str] | None) –

  Mapping of variable names to interpolation methods. If None, linear interpolation is used. Default is None.

downsample_agg_funcs class-attribute instance-attribute

downsample_agg_funcs = None

downsample_lib class-attribute instance-attribute

downsample_lib = 'xesmf'

lat_name class-attribute instance-attribute

lat_name = 'latitude'

lon_name class-attribute instance-attribute

lon_name = 'longitude'

new_resolution class-attribute instance-attribute

new_resolution = 0.5

upsample_method_map class-attribute instance-attribute

upsample_method_map = None

align_lon_lat_with_popu_data

align_lon_lat_with_popu_data(dataset, expected_longitude_max=float64(179.75), lat_name='latitude', lon_name='longitude')

Align longitude and latitude coordinates with population data of the same resolution. This function is specifically designed to ensure that the longitude and latitude coordinates in the dataset match the expected values used in population data, which are: - Longitude: -179.75 to 179.75, 720 points - Latitude: 89.75 to -89.75, 360 points

Parameters:

• dataset (Dataset) –

  Dataset with longitude and latitude coordinates.

• expected_longitude_max (float64, default: float64(179.75) ) –

  Expected maximum longitude after adjustment. Default is np.float64(179.75).

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

Returns:

• Dataset –

  xr.Dataset: Dataset with adjusted longitude and latitude coordinates.

check_agg_funcs

check_agg_funcs(agg_funcs, valid_agg_funcs)

Check if aggregation functions are valid.

Parameters:

• agg_funcs (Dict[str, str]) –

  Aggregation functions for each variable.

• valid_agg_funcs (set) –

  Set of valid aggregation function names.

Raises:

• ValueError –

  If any aggregation function is not valid or agg_funcs is not a dictionary.

check_downsample_condition

check_downsample_condition(dataset, new_resolution, lat_name='latitude', lon_name='longitude', agg_funcs=None)

Check if downsampling conditions are met.

Parameters:

• dataset (Dataset) –

  Dataset to check downsampling conditions.

• new_resolution (float) –

  Desired new resolution in degrees.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

• agg_funcs (Dict[str, str] | None, default: None ) –

  Aggregation functions for each variable.

Raises:

• ValueError –

  If coordinate names are incorrect, new resolution is non-positive, new resolution is not greater than old resolution, or agg_funcs is not None and not a dictionary.

Returns:

• float ( float ) –

  Old resolution in degrees.

downsample_resolution_with_cdo

downsample_resolution_with_cdo(dataset, new_resolution=0.5, new_min_lat=None, new_lat_size=None, new_min_lon=None, new_lon_size=None, lat_name='latitude', lon_name='longitude', agg_funcs=None, gridtype='lonlat')

Downsample the resolution of a dataset using CDO.

Parameters:

• dataset (Dataset) –

  Dataset to change resolution.

• new_resolution (float, default: 0.5 ) –

  New resolution in degrees. Default is 0.5.

• new_min_lat (float, default: None ) –

  Minimum latitude of the new grid. Default is None.

• new_lat_size (int, default: None ) –

  Size of latitude of the new grid. Default is None.

• new_min_lon (float, default: None ) –

  Minimum longitude of the new grid. Default is None.

• new_lon_size (int, default: None ) –

  Size of longitude of the new grid. Default is None.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

• agg_funcs (Dict[str, str] | None, default: None ) –

  Aggregation functions for each variable. If None, default aggregation is used, i.e. bil (bilinear). Default is None. Possible keys are: * nn (nearest neighbor), * bil (bilinear), * bic (bicubic), * con (conservative), * con2 (conservative 2^nd order).

• gridtype (Literal['gaussian', 'lonlat', 'curvilinear', 'unstructured'], default: 'lonlat' ) –

  Type of the grid. Default is "lonlat".

Returns:

• Dataset –

  xr.Dataset: Dataset with changed resolution.

downsample_resolution_with_xarray

downsample_resolution_with_xarray(dataset, new_resolution=0.5, lat_name='latitude', lon_name='longitude', agg_funcs=None)

Downsample the resolution of a dataset.

Parameters:

• dataset (Dataset) –

  Dataset to change resolution.

• new_resolution (float, default: 0.5 ) –

  New resolution in degrees. Default is 0.5.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

• agg_funcs (Dict[str, str] | None, default: None ) –

  Aggregation functions for each variable. If None, default aggregation (i.e. mean) is used. Default is None. Possible keys are: * mean * sum * max * min

Returns:

• Dataset –

  xr.Dataset: Dataset with changed resolution.

downsample_resolution_with_xesmf

downsample_resolution_with_xesmf(dataset, new_resolution=0.5, new_min_lat=None, new_max_lat=None, new_min_lon=None, new_max_lon=None, lat_name='latitude', lon_name='longitude', agg_funcs=None)

Downsample the resolution of a dataset using xESMF. Ref: https://xesmf.readthedocs.io/en/stable/notebooks/Rectilinear_grid.html

Parameters:

• dataset (Dataset) –

  Dataset to change resolution.

• new_resolution (float, default: 0.5 ) –

  New resolution in degrees. Default is 0.5.

• new_min_lat (float, default: None ) –

  Minimum latitude of the new grid. Default is None.

• new_max_lat (float, default: None ) –

  Maximum latitude of the new grid. Default is None.

• new_min_lon (float, default: None ) –

  Minimum longitude of the new grid. Default is None.

• new_max_lon (float, default: None ) –

  Maximum longitude of the new grid. Default is None.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

• agg_funcs (Dict[str, str] | None, default: None ) –

  Aggregation functions for each variable. If None, default aggregation is used, i.e. bilinear for all variables. Possible keys are: * bilinear * conservative, need grid corner information * conservative_normed, need grid corner information * patch * nearest_s2d * nearest_d2s

Returns:

• Dataset –

  xr.Dataset: Dataset with changed resolution.

resample_resolution

resample_resolution(dataset, resolution_config=ResolutionConfig(), grid_config=GridConfig())

Resample the grid of a dataset to a new resolution.

Parameters:

• dataset (Dataset) –

  Dataset to resample.

• resolution_config (ResolutionConfig, default: ResolutionConfig() ) –

  Configuration for resolution resampling.

• grid_config (GridConfig, default: GridConfig() ) –

  Configuration for grid specification.

Returns:

• Dataset –

  xr.Dataset: Resampled dataset with changed resolution.

upsample_resolution

upsample_resolution(dataset, new_resolution=0.1, lat_name='latitude', lon_name='longitude', method_map=None)

Upsample the resolution of a dataset using xarray.interp.

Parameters:

• dataset (Dataset) –

  Dataset to change resolution.

• new_resolution (float, default: 0.1 ) –

  New resolution in degrees. Default is 0.1.

• lat_name (str, default: 'latitude' ) –

  Name of the latitude coordinate. Default is "latitude".

• lon_name (str, default: 'longitude' ) –

  Name of the longitude coordinate. Default is "longitude".

• method_map (Dict[str, str] | None, default: None ) –

  Mapping of variable names to interpolation methods. If None, linear interpolation is used. Default is None.

Returns:

• Dataset –

  xr.Dataset: Dataset with changed resolution.