regionmask.mask_3D_geopandas(geodataframe, lon_or_obj, lat=None, *, drop=True, lon_name=None, lat_name=None, numbers=None, method=None, wrap_lon=None, use_cf=None, overlap=None)

create a 3D boolean mask of a set of regions for the given lat/ lon grid

geodataframeGeoDataFrame or GeoSeries

Object providing the region definitions (polygons).

lon_or_objobject or array_like

Can either be a longitude array and then lat needs to be given. Or an object where the longitude and latitude can be retrieved from, either using cf_xarray or by the names “lon” and “lat”. See also use_cf.

latarray_like, optional

If lon_or_obj is a longitude array, the latitude needs to be passed.

dropboolean, default: True

If True (default) drops slices where all elements are False (i.e no gridpoints are contained in a region). If False returns one slice per region.

numbersstr, optional

Name of the column to use for numbering the regions. This column must not have duplicates. If None (default), takes geodataframe.index.values.

wrap_lonNone | bool | 180 | 360, default: None

Whether to wrap the longitude around, inferred automatically. If the regions and the provided longitude do not have the same base (i.e. one is -180..180 and the other 0..360) one of them must be wrapped. This can be achieved with wrap_lon:

  • None: autodetects whether the longitude needs to be wrapped

  • False: nothing is done. This is useful when working with coordinates that are not in lat/ lon format.

  • True: longitude data is wrapped to [0, 360[ if its minimum is smaller than 0 and wrapped to [-180, 180[ if its maximum is larger than 180.

  • 180: Wraps longitude coordinates to [-180, 180[

  • 360: Wraps longitude coordinates to [0, 360[

overlapbool | None, default: None

Indicates if (some of) the regions overlap.

  • If True mask_3D_geopandas ensures overlapping regions are correctly assigned to grid points, while mask_geopandas raises an Error (because overlapping regions cannot be represented by a 2 dimensional mask).

  • If False assumes non-overlapping regions. Grid points are silently assigned to the region with the higher number.

  • If None (default) checks if any gridpoint belongs to more than one region. If this is the case mask_3D_geopandas correctly assigns them and mask_geopandas raises an Error.

use_cfbool, default: None

Whether to use cf_xarray to infer the names of the x and y coordinates. If None uses cf_xarray if the coord names are unambiguous. If True requires cf_xarray if False does not use cf_xarray.

mask_3Dboolean xarray.DataArray

See also

Regions.mask, Regions.mask_3D_frac_approx