What’s New¶
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()
andRegions.plot_regions()
(PR246):Deprecated all positional arguments (keword arguments only).
The
regions
keyword was deprecated. Subset regions before plotting, i.e. user[regions].plot()
instead ofr.plot(regions=regions)
. This will allow to remove a argument from the methods.
Updates to
Regions.plot()
(PR246):Added
lw=0
to the defaultocean_kws
andland_kws
to avoid overlap with the coastlines.Renamed the
proj
keyword toprojection
for consistency with cartopy.Renamed the
coastlines
keyword toadd_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:
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).Regions.mask()
(and all othermask
methods and functions) no longer raise an error for regions that exceed 360° latitude ifwrap_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 (temorary) fix for GH165. This allows to make use of conda-forge/cartopy-feedstock#116 such that natural_earth shapefiles can be donwloaded again. Also added some other minor doc updates (PR269).
Internal Changes¶
Updated setup configuration and automated version numbering:
Refactor
test_defined_region
andtest_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
inpd.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
andRegion_cls
(deprecated in v0.5.0). UseRegions
instead (PR182).Removed the
create_mask_contains
function (deprecated in v0.5.0). Useregionmask.Regions(coords).mask(lon, lat)
instead (PR181).Removed the
xarray
keyword to allmask
functions. This was deprecated in version 0.5.0. To obtain a numpy mask usemask.values
(GH179).Removed the
"legacy"
-masking deprecated in v0.5.0 (GH69, PR183).
Enhancements¶
Regions.plot()
andRegions.plot_regions()
now take thelabel_multipolygon
keyword to add text labels to all Polygons of MultiPolygons (GH185).Regions.plot()
andRegions.plot_regions()
now warn on unused arguments, e.g.plot(add_land=False, land_kws=dict(color="g"))
(GH192).
New regions¶
Added
natural_earth.land_10
andnatural_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
toutils
and raise an error when something else than aPolygon
orMultiPolygon
is passed (PR211).Fix incompatibility with xarray >=0.19.0 (PR234). By Julius Busecke.
Docs¶
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 nowtemplate-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 forRegions.mask_3D()
andmask_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. UseRegions.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 useRegions.plot(coastline_kws=dict())
(PR146).
Enhancements¶
Create 3D boolean masks using
Regions.mask_3D()
andmask_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
andRegions.plot_regions
now also displays region interiors. All lines are now added at once using aLineCollection
which is faster than a loop andplt.plot
(GH56 and GH107).Regions.plot
can now fill land areas withadd_land
. Further, there is more control over the appearance over the land and ocean features as well as the coastlines using thecoastline_kws
,ocean_kws
, andland_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).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¶
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 ofmatplotlib
for tests, seems a bit faster (GH112).Replaced all
assertion
withif ...: 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"
indocs/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 thenaturalearth.land110
region and also for some countries innaturalearth.countries_50
(closes GH22).Renamed
Regions_cls
toRegions
and changed its call signature. This allows to make all arguments exceptoutlines
optional.Renamed
Region_cls
to_OneRegion
for clarity.The function
regionmask.create_mask_contains()
is deprecated and will be removed in a future version. Useregionmask.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 (exceptoutlines
) 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 typedict
(closes GH43).Added a
Regions.plot_regions()
method that only plots the region borders and not a map, asRegions.plot()
. TheRegions.plot_regions()
method can be used to plot the regions on a existingcartopy
map or a regular axes (closes GH31).Added
Regions.bounds
andRegions.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 largestPolygon
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
andmask.lat
; testnp.all(np.equal(mask.lon, lon))
, instead ofnp.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.
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 alist
), thus it failed onmask
(GH15).Removed unnecessary files (ne_downloader.py and naturalearth.py).
Resolved conflicting region outlines in the Giorgi regions (GH17).
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