regionmask.Regions
- class regionmask.Regions(outlines, numbers=None, names=None, abbrevs=None, name='unnamed', source=None, overlap=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, whileRegions.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 andRegions.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='unnamed', source=None, overlap=None)
Methods
__init__
(outlines[, numbers, names, ...])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
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
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
coords
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