What’s New

v0.6.0 (30.07.2020)


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

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).


New regions

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).


  • 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.


  • 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)


  • 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