This tutorial was generated from an IPython 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"]



Import regionmask and check the version:

import regionmask


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 0x7fd90e177800>

Get data for examples

# example region
region =

# 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,
<matplotlib.collections.QuadMesh at 0x7fd8fc501fd0>

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)
<xarray.DataArray 'mask' (lat: 90, lon: 360)> Size: 259kB
nan nan nan nan nan nan nan ... nan nan nan nan nan nan nan
  * 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
    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...
    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)

<xarray.DataArray 'mask' (region: 19, y: 205, x: 275)> Size: 1MB
False False False False False ... False False False False
    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
    standard_name:  region


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