What’s New

v0.6.2 (19.01.2021)

This is a minor bugfix release that corrects a problem occurring only in python 2.7 which could lead to wrong coordinates of 3D masks derived with Regions.mask_3D and mask_3D_geopandas.

Bug Fixes

• Make sure Regions is sorted by the number of the individual regions. This was previously not always the case. Either when creating regions with unsorted numbers in python 3.6 and higher (e.g. Regions([poly2, poly1], [2, 1])) or when indexing regions in python 2.7 (e.g. regionmask.defined_regions.ar6.land[[30, 31, 32]] sorts the regions as 32, 30, 31). This can lead to problems for Regions.mask_3D and mask_3D_geopandas (GH200).

v0.6.1 (19.08.2020)

There were some last updates to the AR6 regions (regionmask.defined_regions.ar6). If you use the AR6 regions please update the package. There were no functional changes.

v0.6.0 (30.07.2020)

Warning

Version 0.6 is the last release of regionmask that will support Python 2.7. Future releases will be Python 3 only, but older versions of regionmask will always be available for Python 2.7 users. For the more details, see:

• Python 3 Statement

Version 0.6.0 offers better support for shapefiles (via geopandas) and can directly create 3D boolean masks which play nicely with xarray’s weighted.mean(...) function. It also includes a number of optimizations and bug fixes.

Breaking Changes

• Points at exactly -180°E (or 0°E) and -90°N are now treated separately; such that a global mask includes all gridpoints - see methods for details (GH159).

• Regions.plot() no longer colors the ocean per default. Use Regions.plot(add_ocean=True) to restore the previous behavior (GH58).

• Changed the default style of the coastlines in Regions.plot(). To restore the previous behavior use Regions.plot(coastline_kws=dict()) (PR146).

Enhancements

• Create 3D boolean masks using Regions.mask_3D and mask_3D_geopandas - see the tutorial on 3D masks (GH4, GH73).

• Create regions from geopandas/ shapefiles from_geopandas (PR101 by Aaron Spring).

• Directly mask geopandas GeoDataFrame and GeoSeries mask_geopandas (PR103).

• Added a convenience function to plot flattened 3D masks: plot_3D_mask() (GH161).

• Regions.plot and Regions.plot_regions now also displays region interiors. All lines are now added at once using a LineCollection which is faster than a loop and plt.plot (GH56 and GH107).

• Regions.plot can now fill land areas with add_land. Further, there is more control over the appearance over the land and ocean features as well as the coastlines using the coastline_kws, ocean_kws, and land_kws arguments (GH140).

• Split longitude if this leads to two equally-spaced parts. This can considerably speed up creating a mask. See GH127 for details.

• Added test to ensure Polygons with z-coordinates work correctly (GH36).

• Better repr for Regions (GH108).

• Towards enabling the download of region definitions using pooch (PR61).

New regions

• Added the AR6 reference regions described in Iturbide et al., (2000) (PR61).

• New marine regions from natural earth added as natural_earth.ocean_basins_50 (PR63 by Julius Busecke).

Bug Fixes

• The natural earth shapefiles are now loaded with encoding="utf8" (GH95).

• Explicitly check that the numbers are numeric and raise an informative error (GH130).

• Do not subset coords with more than 10 vertices when plotting regions as this can be slow (GH153).

Internal Changes

• Decouple _maybe_get_column from its usage for naturalearth - so it can be used to read columns from geodataframes (GH117).

• Switch to azure pipelines for testing (PR110).

• Enable codecov on azure (PR115).

• Install matplotlib-base for testing instead of matplotlib for tests, seems a bit faster (GH112).

• Replaced all assertion with if ...: ValueError outside of tests (GH142).

• Raise consistent warnings on empty mask (GH141).

• Use a context manager for the plotting tests (GH145).

Docs

• Combine the masking tutorials (xarray, numpy, and multidimensional coordinates) into one (GH120).

• Use sphinx.ext.napoleon which fixes the look of the API docs. Also some small adjustments to the docs (PR125).

• Set mpl.rcParams["savefig.bbox"] = "tight" in docs/defined_*.rst to avoid spurious borders in the map plots (GH112).

v0.5.0 (19.12.2019)

Version 0.5.0 offers a better performance, a consistent point-on-border behavior, and also unmasks region interiors (holes). It also introduces a number of deprecations. Please check the notebook on methods and the details below.

Breaking Changes

• New behavior for ‘point-on-border’ and region interiors:

  • New ‘edge behaviour’: points that fall on the border of a region are now treated consistently (PR63). Previously the edge behaviour was not well defined and depended on the orientation of the outline (clockwise vs. counter clockwise; GH69 and matplotlib/matplotlib#9704).

  • Holes in regions are now excluded from the mask; previously they were included. For the defined_regions, this is relevant for the Caspian Sea in the naturalearth.land110 region and also for some countries in naturalearth.countries_50 (closes GH22).

• Renamed Regions_cls to Regions and changed its call signature. This allows to make all arguments except outlines optional.

• Renamed Region_cls to _OneRegion for clarity.

• Deprecated the centroids keyword for Regions (GH51).

• xarray is now a hard dependency (GH64).

• The function regionmask.create_mask_contains() is deprecated and will be removed in a future version. Use regionmask.Regions(coords).mask(lon, lat) instead.

Enhancements

• New faster and consistent methods to rasterize regions:

  • New algorithm to rasterize regions for equally-spaced longitude/ latitude grids. Uses rasterio.features.rasterize: this offers a 50x to 100x speedup compared to the old method, and also has consistent edge behavior (closes GH22 and GH24).

  • New algorithm to rasterize regions for grids that are not equally-spaced. Uses shapely.vectorized.contains: this offers a 2x to 50x speedup compared to the old method. To achieve the same edge-behavior a tiny (10 ** -9) offset is subtracted from lon and lat (closes GH22 and GH62).

  • Added a methods page to the documentation, illustrating the algorithms, the edge behavior and treatment of holes (closes GH16).

  • Added a test to ensure that the two new algorithms (“rasterize”, “shapely”) yield the same result. Currently for 1° and 2° grid spacing (GH74).

• Automatically detect whether the longitude of the grid needs to be wrapped, depending on the extent of the grid and the regions (closes GH34).

• Make all arguments to Regions optional (except outlines) this should make it easier to create your own region definitions (closes GH37).

• Allow to pass arbitrary iterables to Regions - previously these had to be of type dict (closes GH43).

• Added a Regions.plot_regions() method that only plots the region borders and not a map, as Regions.plot(). The Regions.plot_regions() method can be used to plot the regions on a existing cartopy map or a regular axes (closes GH31).

• Added Regions.bounds and Regions.bounds_global indicating the minimum bounding region of each and all regions, respectively. Added _OneRegion.bounds (closes GH33).

• Add possibility to create an example dataset containing lon, lat and their bounds (closes GH66).

• Added code coverage with pytest-cov and codecov.

Bug Fixes

• Regions were missing a line when the coords were not closed and subsample=False (GH46).

• Fix a regression introduced by PR47: when plotting regions containing multipolygons _draw_poly closed the region again and introduced a spurious line (closes GH54).

• For a region defined via MultiPolygon: use the centroid of the largest Polygon to add the label on a map. Previously the label could be placed outside of the region (closes GH59).

• Fix regression: the offset was subtracted in mask.lon and mask.lat; test np.all(np.equal(mask.lon, lon)), instead of np.allclose (closes GH78).

• Rasterizing with "rasterize" and "shapely" was not equal when gridpoints exactly fall on a 45° border outline (GH80).

• Conda channel mixing breaks travis tests. Only use conda-forge, add strict channel priority (GH27).

• Fix documentation compilation on readthedocs (aborted, did not display figures).

• Fix wrong figure in docs: countries showed landmask (GH39).

v0.4.0 (02.03.2018)

Enhancements

• Add landmask/ land 110m from Natural Earth (GH21).

• Moved some imports to functions, so import regionmask is faster.

• Adapted docs for python 3.6.

Bug Fixes

• Columns of geodataframes can be in lower (‘name’) or upper case (‘NAME’) (GH25).

• Links to github issues not working, due to missing sphinx.ext.extlinks (GH26).

• Docs: mask_xarray.ipynb: mask no longer needs a name (as of PR5).

v0.3.1 (4 October 2016)

This is a bugfix/ cleanup release.

Bug Fixes

• travis was configured wrong - it always tested on python 2.7, thus some python3 issues went unnoticed (GH14).

• natural_earth was not properly imported (GH10).

• A numpy scalar of dtype integer is not int - i.e. isinstance(np.int32, int) is False (GH11).

• In python 3 zip is an iterator (and not a list), thus it failed on mask (GH15).

• Removed unnecessary files (ne_downloader.py and naturalearth.py).

• Resolved conflicting region outlines in the Giorgi regions (GH17).

v0.3.0 (20 September 2016)

• Allow passing 2 dimensional latitude and longitude grids (GH8).

v0.2.0 (5 September 2016)

• Add name for xarray mask (GH3).

• overhaul of the documentation

• move rtd / matplotlib handling to background

v0.1.0 (15 August 2016)

• first release on pypi