Skip to content

Latest commit

 

History

History
850 lines (652 loc) · 34.9 KB

CHANGELOG.rst

File metadata and controls

850 lines (652 loc) · 34.9 KB
.. currentmodule:: regionmask

Changelog

.. ipython:: python
   :suppress:

    import regionmask

v0.13.0 (unreleased)

Breaking Changes

  • Drop support for pygeos, which was replaced by shapely v2.0 (:pull:`519`).

  • Require shapely v2.0+ (:pull:`521`).

  • Removed support for Python 3.9 (:pull:`555`).

  • Bumped minimum rasterio version to v1.3 (:issue:`347`).

  • Finalized the deprecation of positional arguments (:pull:`552`).

  • Remove lon_name and lat_name keyword arguments of the mask functions deprecated in v0.10.0 (:pull:`557`).

  • The minimum versions of some dependencies were changed (:pull:`541`, :pull:`546`, :pull:`521`, and :pull:`547`):

    Package

    Old

    New

    cartopy*

    0.20

    0.22

    cf_xarray*

    0.7

    0.8

    geopandas

    0.10

    0.13

    matplotlib*

    3.5

    3.7

    numpy

    1.21

    1.24

    pandas

    1.3

    2.0

    pygrio*

    0.3

    0.6

    pooch

    1.4

    1.7

    rasterio

    1.2

    1.3

    shapely

    1.8

    2.0

    xarray

    0.20

    2023.07

Enhancements

Deprecations

New regions

Bug Fixes

Docs

Internal Changes

  • Get upstream-dev CI to run with numpy 2.0 (:pull:`522`) and fix accrued upstream failures for rasterio (:pull:`524`), cartopy (:pull:`525`), and matplotlib (:pull:`527`).
  • Avoid usage of shapely.vectorized which might be removed in a future version of shapely (:pull:`554`).
  • Made Regions.region_ids private (:pull:`560`).
  • Use pre-commit-ci to ensure formatting conventions are enforced (:pull:`559`).

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 (:pull:`486`).
  • Removed support for Python 3.8 (:pull:`465`).
  • Removed the regionmask.defined_regions.natural_earth regions which were deprecated in v0.9.0, (:pull:`479`)
  • Removed the deprecated subsample keyword from the plotting methods (:pull:`468`).
  • Removed the deprecated _ar6_pre_revisions regions (:pull:`466`).

Enhancements

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

New regions

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

Bug Fixes

  • Ensure correct masks are created for float32 coordinates (:issue:`489`, :pull:`493`).

  • Fixed the default value of overlap of :py:func:`from_geopandas` to None (:issue:`453`, :pull:`470`).

  • Fixed some numerical issues for natural earth regions for natural_earth_v5_1_2:

    • ocean_basins_50 not extending to 180°E (:issue:`410`, :pull:`488`).

    • countries_50 and land_50 not extending to -90° N (:issue:`487`, :pull:`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

Internal Changes

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 (:pull:`424`).

  • The minimum versions of some dependencies were changed (:pull:`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 (:pull:`429`).

Enhancements

Bug Fixes

  • Fixed two bugs, which would raise an error when creating a mask for overlapping regions if:
    • the coordinates were unstructured (:issue:`438`) or
    • there were more than 32 regions and equally-spaced coordinates (:issue:`453`).
  • Can now pass the use_cf parameter to :py:func:`mask_geopandas` and :py:func:`mask_3D_geopandas`. Previously these two functions could not control the behavior of finding the coords (:pull:`427`).
  • Fix the detection of edge points at -180°E or 0°E if longitude values contain NA values (:issue:`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 :pull:`271` and thus this bug did not affect users since v0.8.0 (:pull:`425`).

Docs

  • Rename docs/whats_new.rst to CHANGELOG.rst (:pull:`457`).

Internal Changes

  • The target url of the remote resources now uses the version (:pull:`431`).
  • Better error message when trying to create 2D overlapping mask (:issue:`432`).
  • Update the signature of the internal mask functions. No longer require bounds as input (:issue:`434`).
  • Add upstream-dev CI check to ensure regionmask works with the developmen version of its dependencies (:pull:`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 :py:meth:`Regions.mask` (:pull:`368`).
  • Passing lon_name and lat_name to the masking methods and functions (e.g. :py:meth:`Regions.mask`) is deprecated. Please pass the lon and lat coordinates directly, e.g., mask*(ds[lon_name], ds[lat_name]) (:issue:`293` and :pull:`371`).
  • Marked the method keyword to the masking methods and functions (e.g. :py:meth:`Regions.mask`) as internal and flagged it for removal in a future version. Passing this argument should only be necessary for testing (:pull:`417`).

Enhancements

New regions

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 (:pull:`348`, :pull:`421` see also readthedocs/readthedocs.org#8201).

Internal Changes

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, :py:class:`Regions` can now be round-tripped to :py:class:`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 (:pull:`288`).

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

  • The minimum versions of some dependencies were changed (:pull:`311`, :pull:`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 (:issue:`306`, :pull:`311`).

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

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

Enhancements

Deprecations

  • The regionmask.defined_regions._ar6_pre_revisions regions are deprecated. The regionmask.defined_regions.ar6 regions should be used instead (:issue:`314`, :pull:`320`).

New regions

Bug Fixes

Docs

  • Went over the documentation, improved some sections, unpinned some packages, modernized some aspects (:pull:`313`).

Internal Changes

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 :doc:`methods<notebooks/method>` for details (:issue:`151`).
  • Updates to :py:meth:`Regions.plot` and :py:meth:`Regions.plot_regions` (:pull:`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 :py:meth:`Regions.plot` (:pull:`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 (:issue:`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 (:issue:`151`).
  • The extent of the longitude coordinates is no longer checked to determine the wrap, now only the extent of the mask is considered (:issue:`249`). This should allow to infer wrap_lon correctly for more cases (:issue:`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] (:issue:`266`).

  • :py:meth:`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 :pull:`48` (:issue:`151`).

  • Raise a ValueError if the input coordinates (lat and lon) have wrong number of dimensions or shape (:pull:`245`, :issue:`242`).

Docs

  • Updated the plotting tutorial (:pull:`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 (:pull:`248`).
  • Pin cartopy to version 0.19 and matplotlib to version 3.4 and use a (temporary) fix for :issue:`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 (:pull:`269`).

Internal Changes

  • Updated setup configuration and automated version numbering:
  • Refactor test_defined_region and test_mask_equal_defined_regions - globally define a list of all available defined_regions (:issue:`256`).
  • In the tests: downloading naturalearth regions could run forever. Make sure this does not happen and turn the timeout Error into a warning (:pull:`261`).
  • Set regex=True in pd.Series.str.replace due to an upcoming change in pandas (:pull:`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 (:pull:`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 (:issue:`204` and :pull:`224`).

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

Deprecations

  • Removed Regions_cls and Region_cls (deprecated in v0.5.0). Use :py:class:`Regions` instead (:pull:`182`).
  • Removed the create_mask_contains function (deprecated in v0.5.0). Use regionmask.Regions(coords).mask(lon, lat) instead (:pull:`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 (:issue:`179`).
  • Removed the "legacy"-masking deprecated in v0.5.0 (:issue:`69`, :pull:`183`).

Enhancements

New regions

Bug Fixes

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

Docs

Internal Changes

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

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

Enhancements

New regions

Bug Fixes

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

Internal Changes

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

Docs

  • Combine the masking tutorials (xarray, numpy, and multidimensional coordinates) into one (:issue:`120`).
  • Use sphinx.ext.napoleon which fixes the look of the API docs. Also some small adjustments to the docs (:pull:`125`).
  • Set mpl.rcParams["savefig.bbox"] = "tight" in docs/defined_*.rst to avoid spurious borders in the map plots (:issue:`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 :doc:`methods<notebooks/method>` and the details below.

Breaking Changes

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 :issue:`22` and :issue:`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 :issue:`22` and :issue:`62`).
    • Added a :doc:`methods page<notebooks/method>` to the documentation, illustrating the algorithms, the edge behavior and treatment of holes (closes :issue:`16`).
    • Added a test to ensure that the two new algorithms ("rasterize", "shapely") yield the same result. Currently for 1° and 2° grid spacing (:issue:`74`).
  • Automatically detect whether the longitude of the grid needs to be wrapped, depending on the extent of the grid and the regions (closes :issue:`34`).
  • Make all arguments to :py:class:`Regions` optional (except outlines) this should make it easier to create your own region definitions (closes :issue:`37`).
  • Allow to pass arbitrary iterables to :py:class:`Regions` - previously these had to be of type dict (closes :issue:`43`).
  • Added a :py:meth:`Regions.plot_regions` method that only plots the region borders and not a map, as :py:meth:`Regions.plot`. The :py:meth:`Regions.plot_regions` method can be used to plot the regions on a existing cartopy map or a regular axes (closes :issue:`31`).
  • Added :py:attr:`Regions.bounds` and :py:attr:`Regions.bounds_global` indicating the minimum bounding region of each and all regions, respectively. Added :py:attr:`_OneRegion.bounds` (closes :issue:`33`).
  • Add possibility to create an example dataset containing lon, lat and their bounds (closes :issue:`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 (:issue:`46`).
  • Fix a regression introduced by :pull:`47`: when plotting regions containing multipolygons _draw_poly closed the region again and introduced a spurious line (closes :issue:`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 :issue:`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 :issue:`78`).
  • Rasterizing with "rasterize" and "shapely" was not equal when gridpoints exactly fall on a 45° border outline (:issue:`80`).
  • Conda channel mixing breaks travis tests. Only use conda-forge, add strict channel priority (:issue:`27`).
  • Fix documentation compilation on readthedocs (aborted, did not display figures).
  • Fix wrong figure in docs: countries showed landmask (:issue:`39`).

v0.4.0 (02.03.2018)

Enhancements

  • Add landmask/ land 110m from Natural Earth (:issue:`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') (:issue:`25`).
  • Links to github issues not working, due to missing sphinx.ext.extlinks (:issue:`26`).
  • Docs: mask_xarray.ipynb: mask no longer needs a name (as of :pull:`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 (:issue:`14`).
  • natural_earth was not properly imported (:issue:`10`).
  • A numpy scalar of dtype integer is not int - i.e. isinstance(np.int32, int) is False (:issue:`11`).
  • In python 3 zip is an iterator (and not a list), thus it failed on mask (:issue:`15`).
  • Removed unnecessary files (ne_downloader.py and naturalearth.py).
  • Resolved conflicting region outlines in the Giorgi regions (:issue:`17`).

v0.3.0 (20 September 2016)

  • Allow passing 2 dimensional latitude and longitude grids (:issue:`8`).

v0.2.0 (5 September 2016)

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

v0.1.0 (15 August 2016)

  • first release on pypi