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:
Passing the coordinates explicitly:
region.mask(longitude, latitude)
Pass an xarray
DataArray
orDataset
:region.mask(ds)
in which case the coordinates are either auto-detected using cf_xarray or determined asds["lon"]
andds["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>
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:
Passing the coordinates directly (
region.mask(lon, lat)
) takes precedence.If cf_xarray is not installed regionmask will use
ds["lon"]
andds["lat"]
or raise aKeyError
.If cf_xarray is installed the behavior is determined via the
use_cf
keyword of themask
andmask_3D
methods:use_cf=None
(default): use the cf metadata to determine the coordinates or useds["lon"]
andds["lat"]
(raises aValueError
if ambiguous).use_cf=True
: use the cf metadata to determine the coordinatesuse_cf=False
: useds["lon"]
andds["lat"]
as coordinates