Changelog

v0.12.1 (21.03.2024)

Fix some metadata to allow releasing.

v0.12.0 (21.03.2024)

regionmask v0.12.0 adds a new approximate fractional overlap mask, fixes a number of issues with certain natural earth regions and restores compatibility with the upcoming xarray release.

Breaking Changes

Deprecated Regions.coords because they are no longer used (#486).
Removed support for Python 3.8 (#465).
Removed the regionmask.defined_regions.natural_earth regions which were deprecated in v0.9.0, (#479)
Removed the deprecated subsample keyword from the plotting methods (#468).
Removed the deprecated _ar6_pre_revisions regions (#466).

Enhancements

Added a new approximate fractional overlap mask that allows to estimate which portion of a grid point is covered by each region (#38, #498).
Add python 3.12 to list of supported versions (#494).

New regions

Added newest version of natural earth regions: natural_earth_v5_1_2 - see also bug fixes (#357, #488).

Bug Fixes

Ensure correct masks are created for float32 coordinates (#489, #493).
Fixed the default value of overlap of from_geopandas() to None (#453, #470).
Fixed some numerical issues for natural earth regions for natural_earth_v5_1_2:
- ocean_basins_50 not extending to 180°E (#410, #488).
- countries_50 and land_50 not extending to -90° N (#487, #488).
  
  Warning
  
  The three regions (ocean_basins_50, countries_50, and land_50) are not corrected for natural_earth_v4_0_0 and natural_earth_v5_0_0. It is therefore recommended to use natural_earth_v5_1_2 for these regions.

Docs

Updated the “Using regionmask with intake” example (#477).
Fixed the url to the MEOW dataset in the intake example (#474 and #477).
Fixed the docstring for overlap of from_geopandas() and Regions (#453, #470).

Internal Changes

Restore compatibility with upcoming xarray release (probably v2023.04 or v2024.04, ##512).
Small optimizations for Regions (##478).

v0.11.0 (22.09.2023)

regionmask v0.11.0 checks if regions are overlapping per default. It also fixes some minor bugs and bumps the supported versions.

Breaking Changes

Removed support for Python 3.7 (#424).

The minimum versions of some dependencies were changed (#424):

Package	Old	New
cartopy*	0.17	0.20
cf_xarray*	0.6	0.7
geopandas	0.7	0.10
matplotlib*	3.2	3.5
numpy	1.17	1.21
pandas	1.2	1.3
pooch	1.2	1.4
rasterio	1.1	1.2
shapely	1.7	1.8
xarray	0.15	0.20

Finalize the deprecations for the plot methods from v0.8.0 (#429).

Enhancements

regionmask now checks if regions are overlapping (unless overlap=False is explicitly set) - check the documentation on overlapping regions for details (#439).

Bug Fixes

Fixed two bugs, which would raise an error when creating a mask for overlapping regions if:
- the coordinates were unstructured (#438) or
- there were more than 32 regions and equally-spaced coordinates (#453).
Can now pass the use_cf parameter to mask_geopandas() and mask_3D_geopandas(). Previously these two functions could not control the behavior of finding the coords (#427).
Fix the detection of edge points at -180°E or 0°E if longitude values contain NA values (#426).
Fix the wrapping of longitudes that contain NA values and simplify the _wrapAngle function. Note the wrapping does not depend on the longitude coordinates since #271 and thus this bug did not affect users since v0.8.0 (#425).

Docs

Rename docs/whats_new.rst to CHANGELOG.rst (#457).

Internal Changes

The target url of the remote resources now uses the version (#431).
Better error message when trying to create 2D overlapping mask (#432).
Update the signature of the internal mask functions. No longer require bounds as input (#434).
Add upstream-dev CI check to ensure regionmask works with the developmen version of its dependencies (#444).

v0.10.0 (31.05.2023)

regionmask v0.10.0 brings support for cf_xarray, which allows to auto-detect coordinate names using and handling of region names in 2D masks. It also supports shapely 2.0 and creating overlapping 3D masks has become faster.

Breaking Changes

Made more arguments keyword-only for several functions and methods, e.g., for Regions.mask() (#368).
Passing lon_name and lat_name to the masking methods and functions (e.g. Regions.mask()) is deprecated. Please pass the lon and lat coordinates directly, e.g., mask*(ds[lon_name], ds[lat_name]) (#293 and #371).
Marked the method keyword to the masking methods and functions (e.g. Regions.mask()) as internal and flagged it for removal in a future version. Passing this argument should only be necessary for testing (#417).

Enhancements

Can now autodetect longitude and latitude coordinates from cf metadata if the optional dependency cf_xarray is installed (#393, #364).
2D masks (e.g. Regions.mask()) now contain flag_values and flag_meanings as attributes (attrs). Together with cf_xarray these can be leveraged to select single (mask.cf == "CNA") or multiple (mask.cf.isin) regions (#361, #346).
Added flatten_3D_mask() - a helper function to flatten 3D masks to 2D masks (#399).
The masking functions (e.g. Regions.mask()) now warn if the units of the coordinates(lat.attrs["units"] ) are given as “radians” (#279).
Better error when passing a single region without wrapping it into a list or tuple (#372).
Added set_options to regionmask which can, currently, be used to control the number of displayed rows of Regions (#376).
Create faster masks with shapely 2.0, which replaces pygeos (#349).
Allow setting the cache location manually: regionmask.set_options(cache_dir="~/.rmask"). The default location is given by pooch.os_cache("regionmask"), i.e. ~/.cache/regionmask/ on unix-like operating systems (#403).
Add python 3.11 to list of supported versions (#390).
Added pyogrio as optional dependency. Natural earth data shapefiles are now loaded faster, if pyogrio is installed (#406).

New regions

Added natural_earth.countries_10 regions from natural earth (#396).

Docs

The version number should now be displayed correctly again on readthedocs. Formerly regionmask was installed from a dirty and shallow git archive, thus setuptools_scm did not report the correct version number (#348, #421 see also readthedocs/readthedocs.org#8201).

Internal Changes

Directly create 3D masks, relevant for overlapping regions as part of #228:
- using shapely, pygeos (#343), and rasterio (#345)
- in the function to determine points at exactly -180°E (or 0°E) and -90°N (#341)
Use importlib.metadata if available (i.e. for python > 3.7) - should lead to a faster import time for regionmask (#369).
Small changes to the repr of Regions (#378).
Reduce the memory requirements of core.utils.unpackbits() (#379:).
Speed up loading of us_states_10 and us_states_50 by defining a bbox which only needs to load a subset of the data (#405).

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 (#288).
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 (#318).
The minimum versions of some dependencies were changed (#311, #312):

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 (#306, #311).
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 (#294).
The mask no longer has dimension coordinates when 2D numpy arrays are passed as lat and lon coords (#294).

Enhancements

regionmask does now correctly treat overlapping regions if overlap=True is set in the constructor (#228, #318).

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:
- ICON
- FESOM
- MPAS
with 1-dimensional coordinates of the form lon(cell) and lat(cell). Note that only xarray arrays can be detected as unstructured grids. (#278, #280). 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() (#50, #298).
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 (#109, #292).
The download of the natural_earth regions is now done in regionmask (using pooch) and no longer relies on cartopy (#306, #311).

Deprecations

The regionmask.defined_regions._ar6_pre_revisions regions are deprecated. The regionmask.defined_regions.ar6 regions should be used instead (#314, #320).

New regions

Added prudence regions for Europe from Christensen and Christensen, 2007, (#283). By Ruth Lorenz.

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) (#129, #294).
Ensure Regions.plot() uses the current axes (plt.gca()) if possible and error if a non-cartopy GeoAxes is passed (#316, #321).

Docs

Went over the documentation, improved some sections, unpinned some packages, modernized some aspects (#313).

Internal Changes

Fix compatibility with shapely 1.8 (#291).
Fix downloading naturalearth regions part 2 (see #261): Monkeypatch the correct download URL and catch all URLError, not only timeouts (#289).
Rewrote the function to create the mask DataArray (#168, #294).
Follow up to #294 - fix wrong dimension order for certain conditions (#295).
Refactor test_mask - make use of xr.testing.assert_equal and simplify some elements (#297).
Add packaging as a dependency (#324, #328).
Add python 3.10 to list of supported versions (#330).

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 (#151).
Updates to Regions.plot() and Regions.plot_regions() (#246):
- 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() (#246):
- 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 (#123).
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 (#151).
The extent of the longitude coordinates is no longer checked to determine the wrap, now only the extent of the mask is considered (#249). This should allow to infer wrap_lon correctly for more cases (#213).

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] (#266).
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 #48 (#151).
Raise a ValueError if the input coordinates (lat and lon) have wrong number of dimensions or shape (#245, #242).

Docs

Updated the plotting tutorial (#246).
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 (#248).
Pin cartopy to version 0.19 and matplotlib to version 3.4 and use a (temporary) fix for #165. 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 (#269).

Internal Changes

Updated setup configuration and automated version numbering:
- Moved contents of setup.py to setup.cfg (#240).
- Use pyproject.toml to define the installation requirements (#240, #247).
- Use setuptools-scm for automatic versioning (#240).
- Allow installing from git archives (#240).
Refactor test_defined_region and test_mask_equal_defined_regions - globally define a list of all available defined_regions (#256).
In the tests: downloading naturalearth regions could run forever. Make sure this does not happen and turn the timeout Error into a warning (#261).
Set regex=True in pd.Series.str.replace due to an upcoming change in pandas (#262).

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 (#220):

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 (#204 and #224).
matpoltlib and cartopy are now optional dependencies. Note that cartopy is also required to download and access the natural earth shapefiles (#169).

Deprecations

Removed Regions_cls and Region_cls (deprecated in v0.5.0). Use Regions instead (#182).
Removed the create_mask_contains function (deprecated in v0.5.0). Use regionmask.Regions(coords).mask(lon, lat) instead (#181).
Removed the xarray keyword to all mask functions. This was deprecated in version 0.5.0. To obtain a numpy mask use mask.values (#179).
Removed the "legacy"-masking deprecated in v0.5.0 (#69, #183).

Enhancements

Regions.plot() and Regions.plot_regions() now take the label_multipolygon keyword to add text labels to all Polygons of MultiPolygons (#185).
Regions.plot() and Regions.plot_regions() now warn on unused arguments, e.g. plot(add_land=False, land_kws=dict(color="g")) (#192).

New regions

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

Bug Fixes

Text labels outside of the map area should now be correctly clipped in most cases (#157).
Move _flatten_polygons to utils and raise an error when something else than a Polygon or MultiPolygon is passed (#211).
Fix incompatibility with xarray >=0.19.0 (#234). By Julius Busecke.

Docs

Unified the docstrings of all mask functions (#173).
Mentioned how to calculate regional medians (#170).
Mentioned how to open regions specified in a yaml file using intake and fsspec (#93, #205). By Aaron Spring.
Fixed the docstrings using velin (#231).

Internal Changes

Moved the CI from azure to github actions (after moving to the regionmask organisation) (#232).
Update the CI: use mamba for faster installation, merge code coverage from all runs, don’t check the coverage of the tests (#197).
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 (#218).
Add a test environment for python 3.9 (#215).
Enforce minimum versions in requirements.txt and clean up required dependencies (#199 and #219).

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() (#200).

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:

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 (#159).
Regions.plot() no longer colors the ocean per default. Use Regions.plot(add_ocean=True) to restore the previous behavior (#58).
Changed the default style of the coastlines in Regions.plot(). To restore the previous behavior use Regions.plot(coastline_kws=dict()) (#146).

Enhancements

Create 3D boolean masks using Regions.mask_3D() and mask_3D_geopandas() - see the tutorial on 3D masks (#4, #73).
Create regions from geopandas/ shapefiles from_geopandas (#101 by Aaron Spring).
Directly mask geopandas GeoDataFrame and GeoSeries mask_geopandas (#103).
Added a convenience function to plot flattened 3D masks: plot_3D_mask() (#161).
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 (#56 and #107).
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 (#140).
Split longitude if this leads to two equally-spaced parts. This can considerably speed up creating a mask. See #127 for details.
Added test to ensure Polygons with z-coordinates work correctly (#36).
Better repr for Regions (#108).
Towards enabling the download of region definitions using pooch (#61).

New regions

Added the AR6 reference regions described in Iturbide et al., (2000) (#61).
New marine regions from natural earth added as natural_earth.ocean_basins_50 (#91 by Julius Busecke).

Bug Fixes

The natural earth shapefiles are now loaded with encoding="utf8" (#95).
Explicitly check that the numbers are numeric and raise an informative error (#130).
Do not subset coords with more than 10 vertices when plotting regions as this can be slow (#153).

Internal Changes

Decouple _maybe_get_column from its usage for naturalearth - so it can be used to read columns from geodataframes (#117).
Switch to azure pipelines for testing (#110).
Enable codecov on azure (#115).
Install matplotlib-base for testing instead of matplotlib for tests, seems a bit faster (#112).
Replaced all assertion with if ...: ValueError outside of tests (#142).
Raise consistent warnings on empty mask (#141).
Use a context manager for the plotting tests (#145).

Docs

Combine the masking tutorials (xarray, numpy, and multidimensional coordinates) into one (#120).
Use sphinx.ext.napoleon which fixes the look of the API docs. Also some small adjustments to the docs (#125).
Set mpl.rcParams["savefig.bbox"] = "tight" in docs/defined_*.rst to avoid spurious borders in the map plots (#112).

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 (#63). Previously the edge behaviour was not well defined and depended on the orientation of the outline (clockwise vs. counter clockwise; #69 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 #22).

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 (#51).

xarray is now a hard dependency (#64).

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 #22 and #24).

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 #22 and #62).

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

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

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

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

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

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

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

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

Added code coverage with pytest-cov and codecov.

Bug Fixes

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

Fix a regression introduced by #47: when plotting regions containing multipolygons _draw_poly closed the region again and introduced a spurious line (closes #54).

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

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

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

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

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

Fix wrong figure in docs: countries showed landmask (#39).

v0.4.0 (02.03.2018)

Enhancements

Add landmask/ land 110m from Natural Earth (#21).
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’) (#25).
Links to github issues not working, due to missing sphinx.ext.extlinks (#26).
Docs: mask_xarray.ipynb: mask no longer needs a name (as of #5).

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 (#14).
natural_earth was not properly imported (#10).
A numpy scalar of dtype integer is not int - i.e. isinstance(np.int32, int) is False (#11).
In python 3 zip is an iterator (and not a list), thus it failed on mask (#15).
Removed unnecessary files (ne_downloader.py and naturalearth.py).
Resolved conflicting region outlines in the Giorgi regions (#17).

v0.3.0 (20 September 2016)

Allow passing 2 dimensional latitude and longitude grids (#8).

v0.2.0 (5 September 2016)

Add name for xarray mask (#3).
overhaul of the documentation
move rtd / matplotlib handling to background

v0.1.0 (15 August 2016)

first release on pypi