What’s New

v0.9.0 (02.03.2022)

Version 0.9.0 contains some exiting improvements: overlapping regions and unstructured grids can now be masked correctly. Further, Regions can now be round-tripped to geopandas.GeoDataFrame objects. The new version also adds PRUDENCE regions and a more stable handling of naturalearth regions.

Many thanks to the contributors to the v0.9.0 release: Aaron Spring, Mathias Hauser, and Ruth Lorenz!

Breaking Changes

  • Removed support for Python 3.6 (PR288).

  • The xarray.DataArray mask returned by all masking functions (e.g. Regions.mask()) was renamed from region to mask. The former was ambiguous with respect to the region dimension of 3D masks (PR318).

  • The minimum versions of some dependencies were changed (PR311, PR312):

    Package

    Old

    New

    geopandas

    0.6

    0.7

    matplotlib

    3.1

    3.2

    pooch

    1.0

    1.2

    rasterio

    1.0

    1.1

    shapely

    1.6

    1.7

  • regionmask.defined_regions.natural_earth is deprecated. defined_regions.natural_earth used cartopy to download natural_earth data and it was unclear which version of the regions is available. This is problematic because some regions change between the versions. Please use defined_regions.natural_earth_v4_1_0 or defined_regions.natural_earth_v5_0_0 instead (GH306, PR311).

  • Passing coordinates with different type to Regions.mask() and Regions.mask_3D() is no longer supported, i.e. can no longer pass lon as numpy array and lat as DataArray (PR294).

  • The mask no longer has dimension coordinates when 2D numpy arrays are passed as lat and lon coords (PR294).

Enhancements

  • regionmask does now correctly treat overlapping regions if overlap=True is set in the constructor (GH228, PR318).

    Per default regionmask assumes non-overlapping regions. In this case grid points of overlapping polygons will silently be assigned to the region with the higher number. This may change in a future version.

  • Regions.mask() and Regions.mask_3D() now work with unstructured 1D grids such as:

    with 1-dimensional coordinates of the form lon(cell) and lat(cell). Note that only xarray arrays can be detected as unstructured grids. (GH278, PR280). By Aaron Spring.

  • Add methods to convert Regions to (geo)pandas objects, namely Regions.to_geodataframe(), Regions.to_geoseries(), Regions.to_dataframe()). The geopandas.GeoDataFrame can be converted back (round-tripped) using Regions.from_geodataframe() (GH50, PR298).

  • The plotting methods (Regions.plot() and Regions.plot_regions()) now use a more sophisticated logic to subsample lines on GeoAxes plots. The new method is based on the euclidean distance of each segment. Per default the maximum distance of each segment is 1 for lat/ lon coords - see the tolerance keyword of the plotting methods. The subsample keyword is deprecated (GH109, PR292).

  • The download of the natural_earth regions is now done in regionmask (using pooch) and no longer relies on cartopy (GH306, PR311).

Deprecations

  • The regionmask.defined_regions._ar6_pre_revisions regions are deprecated. The regionmask.defined_regions.ar6 regions should be used instead (GH314, PR320).

New regions

Bug Fixes

  • The name of lon and lat coordinates when passed as single elements is now respected when creating masks i.e. for region.mask(ds.longitude, ds.longitude) (GH129, PR294).

  • Ensure Regions.plot() uses the current axes (plt.gca()) if possible and error if a non-cartopy GeoAxes is passed (GH316, PR321).

Docs

  • Went over the documentation, improved some sections, unpinned some packages, modernized some aspects (PR313).

Internal Changes

  • Fix compatibility with shapely 1.8 (PR291).

  • Fix downloading naturalearth regions part 2 (see PR261): Monkeypatch the correct download URL and catch all URLError, not only timeouts (PR289).

  • Rewrote the function to create the mask DataArray (GH168, PR294).

  • Follow up to PR294 - fix wrong dimension order for certain conditions (GH295).

  • Refactor test_mask - make use of xr.testing.assert_equal and simplify some elements (PR297).

  • Add packaging as a dependency (GH324, PR328).

  • Add python 3.10 to list of supported versions (PR330).

v0.8.0 (08.09.2021)

Version 0.8.0 contains an important bugfix, improves the handling of wrapped longitudes, can create masks for coordinates and regions that do not have a lat/ lon coordinate reference system and masks for irregular and 2D grids are created faster if the optional dependency pygeos is installed.

Breaking Changes

  • Points at exactly -180°E (or 0°E) and -90°N are no longer special cased if wrap_lon=False when creating a mask - see methods for details (GH151).

  • Updates to Regions.plot() and Regions.plot_regions() (PR246):

    • Deprecated all positional arguments (keyword arguments only).

    • The regions keyword was deprecated. Subset regions before plotting, i.e. use r[regions].plot() instead of r.plot(regions=regions). This will allow to remove a argument from the methods.

  • Updates to Regions.plot() (PR246):

    • Added lw=0 to the default ocean_kws and land_kws to avoid overlap with the coastlines.

    • Renamed the proj keyword to projection for consistency with cartopy.

    • Renamed the coastlines keyword to add_coastlines for consistency with other keywords (e.g. add_land).

Enhancements

  • Creating masks for irregular and 2D grids can be speed up considerably by installing pygeos. pygeos is an optional dependency (GH123).

  • Can now create masks for regions with arbitrary coordinates e.g. for coordinate reference systems that are not lat/ lon based by setting wrap_lon=False (GH151).

  • The extent of the longitude coordinates is no longer checked to determine the wrap, now only the extent of the mask is considered (GH249). This should allow to infer wrap_lon correctly for more cases (GH213).

Bug Fixes

  • Fixed a bug that could silently lead to a wrong mask in certain cases. Three conditions are required:

    1. The longitude coordinates are not ordered (note that wrapping the longitudes can also lead to unordered coordinates).

    2. Rearranging the coordinates makes them equally spaced.

    3. The split point is not in the middle of the array.

    Thus, the issue would happen for the following example longitude coordinates: [3, 4, 5, 1, 2] (but not for [3, 4, 1, 2]). Before the bugfix the mask would incorrectly be rearranged in the following order [4, 5, 1, 2, 3] (GH266).

  • Regions.mask() (and all other mask methods and functions) no longer raise an error for regions that exceed 360° latitude if wrap_lon=False. This was most likely a regression from PR48 (GH151).

  • Raise a ValueError if the input coordinates (lat and lon) have wrong number of dimensions or shape (PR245, GH242).

Docs

  • Updated the plotting tutorial (PR246).

  • Install regionmask via ci/requirements/docs.yml on RTD using pip and update the packages: don’t require jupyter (but ipykernel, which leads to a smaller environment), use new versions of sphinx and sphinx_rtd_theme (PR248).

  • Pin cartopy to version 0.19 and matplotlib to version 3.4 and use a (temporary) fix for GH165. This allows to make use of conda-forge/cartopy-feedstock#116 such that natural_earth shapefiles can be downloaded again. Also added some other minor doc updates (PR269).

Internal Changes

  • Updated setup configuration and automated version numbering:

    • Moved contents of setup.py to setup.cfg (PR240).

    • Use pyproject.toml to define the installation requirements (PR240, PR247).

    • Use setuptools-scm for automatic versioning (PR240).

    • Allow installing from git archives (PR240).

  • Refactor test_defined_region and test_mask_equal_defined_regions - globally define a list of all available defined_regions (GH256).

  • In the tests: downloading naturalearth regions could run forever. Make sure this does not happen and turn the timeout Error into a warning (PR261).

  • Set regex=True in pd.Series.str.replace due to an upcoming change in pandas (PR262).

v0.7.0 (28.07.2021)

Version 0.7.0 is mostly a maintenance version. It drops python 2.7 support, accompanies the move of the repo to the regionmask organisation (regionmask/regionmask), finalizes a number of deprecations, and restores compatibility with xarray 0.19.

Breaking Changes

  • Removed support for Python 2. This is the first version of regionmask that is Python 3 only!

  • The minimum versions of some dependencies were changed (PR220):

    Package

    Old

    New

    numpy

    1.15

    1.17

    xarray

    0.13

    0.15

  • Moved regionmask to its own organisation on github. It can now be found under regionmask/regionmask (GH204 and PR224).

  • matpoltlib and cartopy are now optional dependencies. Note that cartopy is also required to download and access the natural earth shapefiles (GH169).

Deprecations

  • Removed Regions_cls and Region_cls (deprecated in v0.5.0). Use Regions instead (PR182).

  • Removed the create_mask_contains function (deprecated in v0.5.0). Use regionmask.Regions(coords).mask(lon, lat) instead (PR181).

  • Removed the xarray keyword to all mask functions. This was deprecated in version 0.5.0. To obtain a numpy mask use mask.values (GH179).

  • Removed the "legacy"-masking deprecated in v0.5.0 (GH69, PR183).

Enhancements

New regions

  • Added natural_earth.land_10 and natural_earth.land_50 regions from natural earth (PR195) by Martin van Driel.

Bug Fixes

  • Text labels outside of the map area should now be correctly clipped in most cases (GH157).

  • Move _flatten_polygons to utils and raise an error when something else than a Polygon or MultiPolygon is passed (PR211).

  • Fix incompatibility with xarray >=0.19.0 (PR234). By Julius Busecke.

Docs

  • Unified the docstrings of all mask functions (GH173).

  • Mentioned how to calculate regional medians (GH170).

  • Mentioned how to open regions specified in a yaml file using intake and fsspec (GH93, PR205). By Aaron Spring.

  • Fixed the docstrings using velin (PR231).

Internal Changes

  • Moved the CI from azure to github actions (after moving to the regionmask organisation) (PR232).

  • Update the CI: use mamba for faster installation, merge code coverage from all runs, don’t check the coverage of the tests (PR197).

  • Fix doc creation for newest version of jupyter nbconvert (template is now template-file).

  • Update ci/min_deps_check.py to the newest version on xarray (PR218).

  • Add a test environment for python 3.9 (GH215).

  • Enforce minimum versions in requirements.txt and clean up required dependencies (GH199 and PR219).

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

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

Enhancements

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

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