What’s New

v0.6.0 (30.07.2020)

Warning

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:

• 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