What’s New

v0.6.0 (unreleased)

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:

Breaking Changes

Enhancements

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

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

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

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

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

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

  • Combine the masking tutorials (xarray, numpy, and multidimensional coordinates) into one tutorial (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 v0.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 What’s New.

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