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.13.0

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

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

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...

xarray.DataArray

'mask'

• lat: 90
• lon: 360

• nan nan nan nan nan nan nan nan ... nan nan nan nan nan nan nan nan

  array([[nan, nan, nan, ..., nan, nan, nan],
         [nan, nan, nan, ..., nan, nan, nan],
         [nan, nan, nan, ..., nan, nan, nan],
         ...,
         [21., 21., 21., ..., 21., 21., 21.],
         [nan, 21., 21., ..., nan, nan, nan],
         [nan, nan, nan, ..., nan, nan, nan]])

• Coordinates: (2)
  • lat
    (lat)
    int64
    90 89 88 87 86 85 ... 6 5 4 3 2 1

    array([90, 89, 88, 87, 86, 85, 84, 83, 82, 81, 80, 79, 78,
           77, 76, 75, 74, 73, 72, 71, 70, 69, 68, 67, 66, 65,
           64, 63, 62, 61, 60, 59, 58, 57, 56, 55, 54, 53, 52,
           51, 50, 49, 48, 47, 46, 45, 44, 43, 42, 41, 40, 39,
           38, 37, 36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26,
           25, 24, 23, 22, 21, 20, 19, 18, 17, 16, 15, 14, 13,
           12, 11, 10,  9,  8,  7,  6,  5,  4,  3,  2,  1])

  • lon
    (lon)
    int64
    0 1 2 3 4 5 ... 355 356 357 358 359

    array([  0,   1,   2, ..., 357, 358, 359])

• Indexes: (2)
  • lat
    PandasIndex

    PandasIndex(Index([90, 89, 88, 87, 86, 85, 84, 83, 82, 81, 80, 79, 78, 77, 76, 75, 74, 73,
           72, 71, 70, 69, 68, 67, 66, 65, 64, 63, 62, 61, 60, 59, 58, 57, 56, 55,
           54, 53, 52, 51, 50, 49, 48, 47, 46, 45, 44, 43, 42, 41, 40, 39, 38, 37,
           36, 35, 34, 33, 32, 31, 30, 29, 28, 27, 26, 25, 24, 23, 22, 21, 20, 19,
           18, 17, 16, 15, 14, 13, 12, 11, 10,  9,  8,  7,  6,  5,  4,  3,  2,  1],
          dtype='int64', name='lat'))

  • lon
    PandasIndex

    PandasIndex(Index([  0,   1,   2,   3,   4,   5,   6,   7,   8,   9,
           ...
           350, 351, 352, 353, 354, 355, 356, 357, 358, 359],
          dtype='int64', name='lon', length=360))

• Attributes: (3)

  standard_name :

  region

  flag_values :

  [ 0 1 2 3 4 5 6 7 8 9 10 16 17 18 19 20 21 22 23 24 28 29 30 31 32 33 34 35 36 37 38]

  flag_meanings :

  GIC NWN NEN WNA CNA ENA NCA SCA CAR NWS NSA NEU WCE EEU MED SAH WAF CAF NEAF SEAF RAR WSB ESB RFE WCA ECA TIB EAS ARP SAS SEA

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

xarray.DataArray

'mask'

• region: 19
• y: 205
• x: 275

• False False False False False False ... False False False False False

  array([[[False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          ...,
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False]],
  
         [[False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          ...,
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False]],
  
         [[False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          ...,
  ...
          ...,
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False]],
  
         [[False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          ...,
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False]],
  
         [[False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          [False, False, False, ..., False, False, False],
          ...,
          [ True,  True,  True, ..., False, False, False],
          [ True,  True,  True, ..., False, False, False],
          [ True,  True,  True, ..., False, False, False]]])

• Coordinates: (5)
  • xc
    (y, x)
    float64
    189.2 189.4 189.6 ... 17.15 16.91

    long_name :

    longitude of grid cell center

    units :

    degrees_east

    array([[189.22293223, 189.38990916, 189.55836619, ..., 293.77906088,
            294.0279241 , 294.27439931],
           [188.96836986, 189.13470591, 189.30253733, ..., 294.05584005,
            294.30444387, 294.55065969],
           [188.71234264, 188.87800731, 189.04515208, ..., 294.335053  ,
            294.58337453, 294.8292928 ],
           ...,
           [124.04724025, 123.88362026, 123.71852016, ...,  16.83171831,
             16.58436953,  16.33949649],
           [123.78686428, 123.62254238, 123.45672512, ...,  17.11814486,
             16.87043749,  16.62518298],
           [123.52798366, 123.36295986, 123.1964407 , ...,  17.40209947,
             17.1540526 ,  16.90845095]])

  • yc
    (y, x)
    float64
    16.53 16.78 17.02 ... 27.76 27.51

    long_name :

    latitude of grid cell center

    units :

    degrees_north

    array([[16.53498637, 16.7784556 , 17.02222429, ..., 27.36301592,
            27.11811045, 26.87289026],
           [16.69397341, 16.93865381, 17.18364512, ..., 27.5847719 ,
            27.33821848, 27.0913656 ],
           [16.85219179, 17.09808909, 17.34430872, ..., 27.80584314,
            27.55764558, 27.30915621],
           ...,
           [17.31179033, 17.56124674, 17.81104646, ..., 28.4502485 ,
            28.19718339, 27.94384744],
           [17.15589701, 17.40414034, 17.65272318, ..., 28.23129632,
            27.97989251, 27.72821596],
           [16.99919497, 17.24622904, 17.49358736, ..., 28.01160028,
            27.76185586, 27.51182726]])

  • region
    (region)
    int64
    0 1 2 3 4 5 ... 30 31 32 33 35 38

    array([ 0,  1,  2,  3,  4,  5, 16, 17, 18, 19, 20, 28, 29,
           30, 31, 32, 33, 35, 38])

  • abbrevs
    (region)
    <U3
    'GIC' 'NWN' 'NEN' ... 'EAS' 'SEA'

    array(['GIC', 'NWN', 'NEN', 'WNA', 'CNA', 'ENA', 'NEU', 'WCE', 'EEU',
           'MED', 'SAH', 'RAR', 'WSB', 'ESB', 'RFE', 'WCA', 'ECA', 'EAS',
           'SEA'], dtype='<U3')

  • names
    (region)
    <U19
    'Greenland/Iceland' ... 'S.E.Asia'

    array(['Greenland/Iceland', 'N.W.North-America', 'N.E.North-America',
           'W.North-America', 'C.North-America', 'E.North-America',
           'N.Europe', 'West&Central-Europe', 'E.Europe', 'Mediterranean',
           'Sahara', 'Russian-Arctic', 'W.Siberia', 'E.Siberia',
           'Russian-Far-East', 'W.C.Asia', 'E.C.Asia', 'E.Asia', 'S.E.Asia'],
          dtype='<U19')

• Indexes: (1)
  • region
    PandasIndex

    PandasIndex(Index([0, 1, 2, 3, 4, 5, 16, 17, 18, 19, 20, 28, 29, 30, 31, 32, 33, 35, 38], dtype='int64', name='region'))

• Attributes: (1)

  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