Note

This page was generated from an Jupyter notebook that can be accessed from github.

Detecting coordinates

To create masks regionmask needs to know the x and y (longitude and latitude) coordinates of the grid. There are two ways to pass these to the mask and mask_3D methods:

  1. Passing the coordinates explicitly: region.mask(longitude, latitude)

  2. Pass an xarray DataArray or Dataset: region.mask(ds) in which case the coordinates are either auto-detected using cf_xarray or determined as ds["lon"] and ds["lat"]

Illustration

Preparation

Import regionmask and check the version:

import regionmask

print(regionmask.__version__)
0.12.1.post1.dev41+g4d9e3f1

Other imports

import numpy as np
import xarray as xr

xr.set_options(display_width=60, display_expand_data=False)
<xarray.core.options.set_options at 0x7f96a62ea480>

Get data for examples

# example region
region = regionmask.defined_regions.ar6.land

# dataset with coordinates named "lon" and "lat", without cf metadata
ds = xr.Dataset(coords={"lon": np.arange(0, 360), "lat": np.arange(90, 0, -1)})

# dataset with coordinates not named "lon" and "lat," with cf metadata
rasm = xr.tutorial.open_dataset("rasm")

1. Passing coordinates directly

The coordinates can be passed individually - these must be “array-like” (typically numpy arrays or xarray DataArrays):

mask = region.mask(ds.lon, ds.lat)
mask.plot()
<matplotlib.collections.QuadMesh at 0x7f967ff4fdd0>
../_images/dddd75b67fc53ea3e0f9a6158e8d069db8c98ea4e6bd75abd51a6c2ee472295d.png

2. Not using cf_xarray

If cf_xarray is not installed, the passed dataset does not have any cf metadata/ attributes, or use_cf=False is set, regionmask tries to read the coordinates from ds["lon"] and ds["lat"] and raises an error otherwise:

mask = region.mask(ds)
mask
<xarray.DataArray 'mask' (lat: 90, lon: 360)> Size: 259kB
nan nan nan nan nan nan nan ... nan nan nan nan nan nan nan
Coordinates:
  * lat      (lat) int64 720B 90 89 88 87 86 ... 5 4 3 2 1
  * lon      (lon) int64 3kB 0 1 2 3 4 ... 356 357 358 359
Attributes:
    standard_name:  region
    flag_values:    [ 0  1  2  3  4  5  6  7  8  9 10 16 ...
    flag_meanings:  GIC NWN NEN WNA CNA ENA NCA SCA CAR N...
try:
    region.mask(rasm, use_cf=False)
except KeyError:
    print("Error raised")
Error raised

Using cf_xarray

cf_xarray uses cf metadata saved in the attributes to determine coordinates (see coordinate-criteria). For this the cf_xarray needs to be installed but importing it is not necessary.

mask = region.mask_3D(rasm)

mask
<xarray.DataArray 'mask' (region: 19, y: 205, x: 275)> Size: 1MB
False False False False False ... False False False False
Coordinates:
    xc       (y, x) float64 451kB 189.2 189.4 ... 16.91
    yc       (y, x) float64 451kB 16.53 16.78 ... 27.51
  * region   (region) int64 152B 0 1 2 3 4 ... 32 33 35 38
    abbrevs  (region) <U3 228B 'GIC' 'NWN' ... 'EAS' 'SEA'
    names    (region) <U19 1kB 'Greenland/Iceland' ... 'S...
Dimensions without coordinates: y, x
Attributes:
    standard_name:  region

Details

regionmask uses the following logic to determine the coordinates:

  1. Passing the coordinates directly (region.mask(lon, lat)) takes precedence.

  2. If cf_xarray is not installed regionmask will use ds["lon"] and ds["lat"] or raise a KeyError.

  3. If cf_xarray is installed the behavior is determined via the use_cf keyword of the mask and mask_3D methods:

    • use_cf=None (default): use the cf metadata to determine the coordinates or use ds["lon"] and ds["lat"] (raises a ValueError if ambiguous).

    • use_cf=True : use the cf metadata to determine the coordinates

    • use_cf=False: use ds["lon"] and ds["lat"] as coordinates