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
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!
Removed support for Python 3.6 (PR288).
defined_regions.natural_earthused 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_v5_0_0instead (GH306, PR311).
The mask no longer has dimension coordinates when 2D numpy arrays are passed as lat and lon coords (PR294).
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.
Add methods to convert
Regionsto (geo)pandas objects, namely
Regions.to_dataframe()). The geopandas.GeoDataFrame can be converted back (round-tripped) using
The plotting methods (
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
tolerancekeyword of the plotting methods. The
subsamplekeyword is deprecated (GH109, PR292).
Went over the documentation, improved some sections, unpinned some packages, modernized some aspects (PR313).
Fix compatibility with shapely 1.8 (PR291).
Refactor test_mask - make use of
xr.testing.assert_equaland simplify some elements (PR297).
Add python 3.10 to list of supported versions (PR330).
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.
Deprecated all positional arguments (keyword arguments only).
regionskeyword was deprecated. Subset regions before plotting, i.e. use
r.plot(regions=regions). This will allow to remove a argument from the methods.
lw=0to the default
land_kwsto avoid overlap with the coastlines.
projectionfor consistency with cartopy.
add_coastlinesfor consistency with other keywords (e.g.
Can now create masks for regions with arbitrary coordinates e.g. for coordinate reference systems that are not lat/ lon based by setting
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_loncorrectly for more cases (GH213).
Fixed a bug that could silently lead to a wrong mask in certain cases. Three conditions are required:
The longitude coordinates are not ordered (note that wrapping the longitudes can also lead to unordered coordinates).
Rearranging the coordinates makes them equally spaced.
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).
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).
Updated setup configuration and automated version numbering:
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).
pd.Series.str.replacedue to an upcoming change in pandas (PR262).
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.
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):
matpoltlib and cartopy are now optional dependencies. Note that cartopy is also required to download and access the natural earth shapefiles (GH169).
create_mask_containsfunction (deprecated in v0.5.0). Use
regionmask.Regions(coords).mask(lon, lat)instead (PR181).
xarraykeyword to all
maskfunctions. This was deprecated in version 0.5.0. To obtain a numpy mask use
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
ci/min_deps_check.pyto the newest version on xarray (PR218).
Add a test environment for python 3.9 (GH215).
Regionsis 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
There were some last updates to the AR6 regions (
If you use the AR6 regions please update the package. There were no functional changes.
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.
Regions.plotcan 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
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
Polygonswith z-coordinates work correctly (GH36).
_maybe_get_columnfrom 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).
matplotlib-basefor testing instead of
matplotlibfor tests, seems a bit faster (GH112).
if ...: ValueErroroutside 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).
sphinx.ext.napoleonwhich fixes the look of the API docs. Also some small adjustments to the docs (PR125).
mpl.rcParams["savefig.bbox"] = "tight"in
docs/defined_*.rstto avoid spurious borders in the map plots (GH112).
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.
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.land110region and also for some countries in
Regionsand changed its call signature. This allows to make all arguments except
regionmask.create_mask_contains()is deprecated and will be removed in a future version. Use
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 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).
Regions.plot_regions()method that only plots the region borders and not a map, as
Regions.plot_regions()method can be used to plot the regions on a existing
cartopymap or a regular axes (closes GH31).
Add possibility to create an example dataset containing lon, lat and their bounds (closes GH66).
Added code coverage with pytest-cov and codecov.
Regions were missing a line when the coords were not closed and
For a region defined via
MultiPolygon: use the centroid of the largest
Polygonto 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
np.all(np.equal(mask.lon, lon)), instead of
"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.3.1 (4 October 2016)
This is a bugfix/ cleanup release.
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
isinstance(np.int32, int)is False (GH11).
In python 3
zipis an iterator (and not a
list), thus it failed on
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