regionmask.Regions

class regionmask.Regions(outlines, numbers=None, names=None, abbrevs=None, name: str = 'unnamed', source: str | None = None, overlap: bool | None = None)

class for plotting regions and creating region masks

Parameters:

outlinesiterable or dict of: Nx2 array of vertices, Polygon or MultiPolygon

List of the coordinates of the vertices (outline) of the region as shapely Polygon/ MultiPolygon or list.

numbersiterable of int, optional

List of numerical indices for every region. Default: range(0, len(outlines))

namesiterable or dict of string, optional

Long name of each region. Default: [“Region0”, .., “RegionN”]

abbrevsiterable or dict of string, optional

Abbreviations of each region. Default: [“r0”, …, “rN”]

namestring, optional

Name of the collection of regions. Default: “unnamed”

sourcestring, optional

Source of the region definitions. Default: “”.

overlapbool | None, default: None

Indicates if (some of) the regions overlap and determines the behaviour of the mask methods.

If True Regions.mask_3D ensures overlapping regions are correctly assigned to grid points, while Regions.mask raises an Error (because overlapping regions cannot be represented by a 2D 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 Regions.mask_3D correctly assigns them and Regions.mask raises an Error.

Examples

Create your own Regions:

>>> from regionmask import Regions

>>> name = 'Example'
>>> numbers = [0, 1]
>>> names = ['Unit Square1', 'Unit Square2']
>>> abbrevs = ['uSq1', 'uSq2']

>>> outl1 = ((0, 0), (0, 1), (1, 1.), (1, 0))
>>> outl2 = ((0, 1), (0, 2), (1, 2.), (1, 1))
>>> outlines = [outl1, outl2]

>>> r = Regions(outlines, numbers, names, abbrevs, name)
>>> r
<regionmask.Regions 'Example'>
overlap:  None

Regions:
0 uSq1 Unit Square1
1 uSq2 Unit Square2

[2 regions]

It’s also possible to pass shapely Poylgons:

>>> from shapely.geometry import Polygon

>>> numbers = [1, 2]
>>> names = {1:'Unit Square1', 2: 'Unit Square2'}
>>> abbrevs = {1:'uSq1', 2:'uSq2'}
>>> poly = {1: Polygon(outl1), 2: Polygon(outl2)}

>>> r = Regions(outlines, numbers, names, abbrevs, name)
>>> r
<regionmask.Regions 'Example'>
overlap:  None

Regions:
1 uSq1 Unit Square1
2 uSq2 Unit Square2

[2 regions]

>>> # arguments are now optional
>>> r = Regions(outlines)
>>> r
<regionmask.Regions 'unnamed'>
overlap:  None

Regions:
0 r0 Region0
1 r1 Region1

[2 regions]

__init__(outlines, numbers=None, names=None, abbrevs=None, name: str = 'unnamed', source: str | None = None, overlap: bool | None = None) → None

Methods

`__init__`(outlines[, numbers, names, ...])
`from_geodataframe`(df, *[, name, source, overlap])	Convert a `geopandas.GeoDataFrame` created with `to_geodataframe` back to `regionmask.Region` (round trip)
`map_keys`(key)	map from names and abbrevs of the regions to numbers
`mask`(lon_or_obj[, lat, method, wrap_lon, ...])	create a 2D float mask of a set of regions for the given lat/ lon grid
`mask_3D`(lon_or_obj[, lat, drop, method, ...])	create a 3D boolean mask of a set of regions for the given lat/ lon grid
`mask_3D_frac_approx`(lon_or_obj[, lat, drop, ...])	create a 3D fractional mask of a set of regions for the given lat/ lon grid
`plot`(*[, ax, projection, add_label, label, ...])	plot region on cartopy axes
`plot_regions`(*[, ax, add_label, label, ...])	plot regions on regular axes
`to_dataframe`()	Convert this region into a pandas.DataFrame, excluding polygons.
`to_geodataframe`()	Convert this region into a geopandas.GeoDataFrame.
`to_geoseries`()	Convert this region into a geopandas.GeoSeries.

Attributes

`abbrevs`	list of abbreviations of the regions
`bounds`	list of the bounds of the regions (min_lon, min_lat, max_lon, max_lat)
`bounds_global`	global bounds over all regions (min_lon, min_lat, max_lon, max_lat)
`centroids`	list of the center of mass of the regions
`coords`	list of coordinates of the region vertices as numpy array
`lon_180`	if the regions extend from -180 to 180
`lon_360`	if the regions extend from 0 to 360
`names`	list of names of the regions
`numbers`	list of the numbers of the regions
`polygons`	list of shapely Polygon/ MultiPolygon of the regions
`region_ids`	dictionary that maps all names and abbrevs to the region number