regionmask.Regions

class regionmask.Regions(outlines, numbers=None, names=None, abbrevs=None, name='unnamed', source=None, overlap=False)

class for plotting regions and creating region masks

Parameters:

outlines (iterable 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.
numbers (iterable of int, optional) – List of numerical indices for every region. Default: range(0, len(outlines))
names (iterable or dict of string, optional) – Long name of each region. Default: [“Region0”, .., “RegionN”]
abbrevs (iterable or dict of string, optional) – Abbreviations of each region. Default: [“r0”, …, “rN”]
name (string, optional) – Name of the collection of regions. Default: “unnamed”
source (string, optional) – Source of the region definitions. Default: “”.
overlap (bool, default: False) – Indicates if (some of) the regions overlap. If True mask_3D will ensure overlapping regions are correctly assigned to grid points while mask will error (because overlapping regions cannot be represented by a 2D mask).

If False (default) assumes non-overlapping regions. Grid points will silently be assigned to the region with the higher number (this may change in a future version of regionmask).

There is (currently) no automatic detection of overlapping regions.

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:  False

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:  False

Regions:
1 uSq1 Unit Square1
2 uSq2 Unit Square2

[2 regions]

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

Regions:
0 r0 Region0
1 r1 Region1

[2 regions]

__init__(outlines, numbers=None, names=None, abbrevs=None, name='unnamed', source=None, overlap=False)

Methods

`__init__`(outlines[, numbers, names, ...])
`combiner`(prop)	combines attributes from single regions
`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, lon_name, lat_name, ...])	create a 2D float mask of a set of regions for the given lat/ lon grid
`mask_3D`(lon_or_obj[, lat, drop, lon_name, ...])	create a 3D boolean mask of a set of regions for the given lat/ lon grid
`plot`(*[, ax, projection, add_label, label, ...])	plot map with with region outlines
`plot_regions`(*[, ax, add_label, label, ...])	plot map with with srex regions
`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