pcmdi_metrics.io.region_subset

pcmdi_metrics.io.region_subset(ds, region, data_var=None, regions_specs=None, debug=False)[source]

Subset a dataset or data array based on a specified region.

This function subsets an xarray Dataset or DataArray according to latitude and longitude boundaries defined in a specified region. It automatically handles different longitude conventions (0 to 360 vs -180 to 180) and can provide debug information.

Parameters:

  • ds (Union[xr.Dataset, xr.DataArray]) – The input dataset or data array to be subsetted.

  • region (str) – The name of the region to subset the data to. This should match a key in the regions_specs dictionary.

  • data_var (str, optional) – The name of the data variable if ds is a DataArray. If None, the DataArray is named “variable” if it has no name, by default None.

  • regions_specs (dict, optional) – A dictionary containing specifications for different regions. If None, defaults are loaded, by default None.

  • debug (bool, optional) – If True, prints debug information during the subsetting process, by default False.

Returns:

Union[xr.Dataset, xr.DataArray] – The subsetted dataset or data array, with the type matching the input.

Notes

This function first converts DataArrays to Datasets for processing and converts back if needed. It supports both latitude and longitude subsetting based on the region specifications, with compatibility for different longitude conventions.

See also

load_regions_specs

The underlying function used to load default regions_specs for pre-defined region names.

Examples

Basic usage of region_subset:

>>> import xarray as xr
>>> from pcmdi_metrics.io import region_subset
>>> ds = xr.tutorial.open_dataset("air_temperature")  # https://docs.xarray.dev/en/stable/generated/xarray.tutorial.open_dataset.html
>>> regions_specs = {
...     "CONUS": {
...         "domain": {
...             "latitude": (33, 49),
...             "longitude": (225, 300)
...         }
...     }
... }
>>> subset = region_subset(ds, region="CONUS", regions_specs=regions_specs)
>>> subset
<xarray.Dataset>
Dimensions: ...
Data variables:
    ...

With debug information enabled:

>>> subset = region_subset(ds, region="CONUS", regions_specs=regions_specs, debug=True)
Converting latitude and longitude to specified region...
region_subset, latitude subsetted, ds: <latitude_subset_output>
region_subset, longitude subsetted, ds: <longitude_subset_output>