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 whilemask
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 withto_geodataframe
back toregionmask.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
Convert this region into a pandas.DataFrame, excluding polygons.
Convert this region into a geopandas.GeoDataFrame.
Convert this region into a geopandas.GeoSeries.
Attributes
list of abbreviations of the regions
list of the bounds of the regions (min_lon, min_lat, max_lon, max_lat)
global bounds over all regions (min_lon, min_lat, max_lon, max_lat)
list of the center of mass of the regions
list of coordinates of the region vertices as numpy array
if the regions extend from -180 to 180
if the regions extend from 0 to 360
list of names of the regions
list of the numbers of the regions
list of shapely Polygon/ MultiPolygon of the regions
dictionary that maps all names and abbrevs to the region number