regionmask.mask_3D_geopandas

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

Parameters:

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.

Returns:

mask_3Dboolean xarray.DataArray