Regionmask

--------------------

Breaking Changes
~~~~~~~~~~~~~~~~

Enhancements
~~~~~~~~~~~~

Deprecations
~~~~~~~~~~~~

New regions
~~~~~~~~~~~

Bug Fixes
~~~~~~~~~

Docs
~~~~

Internal Changes
~~~~~~~~~~~~~~~~


.. _changelog.0.12.1:

--------------------

Fix some metadata to allow releasing.

.. _changelog.0.12.0:

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
~~~~

- Updated the "Using regionmask with intake" example (:pull:`477`).
- Fixed the url to the MEOW dataset in the intake example (:pull:`474` and :pull:`477`).
- Fixed the docstring for ``overlap`` of :py:func:`from_geopandas` and :py:class:`Regions` (:issue:`453`, :pull:`470`).

Internal Changes
~~~~~~~~~~~~~~~~

- Restore compatibility with upcoming xarray release (probably v2023.04 or v2024.04, :pull:`512`).
- Small optimizations for :py:class:`Regions` (:pull:`478`).

.. _changelog.0.11.0:

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
~~~~~~~~~~~~

- regionmask now checks if regions are overlapping (unless ``overlap=False`` is explicitly set) - check
the documentation on :doc:`overlapping regions<notebooks/overlap>` for details (:pull:`439`).

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

.. _changelog.0.10.0:

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
~~~~~~~~~~~~

- Can now autodetect longitude and latitude coordinates from `cf metadata <http://cfconventions.org/>`__
if the optional dependency `cf_xarray <https://cf-xarray.readthedocs.io/en/latest/coord_axes.html>`__
is installed (:pull:`393`, :issue:`364`).
- 2D masks (e.g. :py:meth:`Regions.mask`) now contain `flag_values` and `flag_meanings` as
attributes (`attrs`). Together with `cf_xarray <https://cf-xarray.readthedocs.io/en/latest/flags.html>`__
these can be leveraged to select single (``mask.cf == "CNA"``) or multiple (``mask.cf.isin``)
regions (:pull:`361`, :issue:`346`).
- Added :py:func:`flatten_3D_mask` - a helper function to flatten 3D masks to 2D masks
(:issue:`399`).
- The masking functions (e.g. :py:meth:`Regions.mask`) now warn if the `units` of the
coordinates(``lat.attrs["units"]`` ) are given as "radians" (:issue:`279`).
- Better error when passing a single region without wrapping it into a list or tuple (:issue:`372`).
- Added :py:class:`set_options` to regionmask which can, currently, be used to control
the number of displayed rows of :py:class:`Regions` (:issue:`376`).
- Create faster masks with shapely 2.0, which replaces pygeos (:pull:`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 (:pull:`403`).
- Add python 3.11 to list of supported versions (:pull:`390`).
- Added `pyogrio <https://pyogrio.readthedocs.io>`__ as optional dependency. Natural earth
data shapefiles are now loaded faster, if pyogrio is installed (:pull:`406`).

New regions
~~~~~~~~~~~

- Added :py:attr:`natural_earth.countries_10` regions from natural earth (:pull:`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 (:pull:`348`, :pull:`421` see also `readthedocs/readthedocs.org8201
<https://github.com/readthedocs/readthedocs.org/issues/8201>`_).

Internal Changes
~~~~~~~~~~~~~~~~

- Directly create 3D masks, relevant for overlapping regions as part of :issue:`228`:

- using shapely, pygeos (:pull:`343`), and rasterio (:pull:`345`)
- in the function to determine points at *exactly* -180°E (or 0°E) and -90°N (:pull:`341`)
- Use importlib.metadata if available (i.e. for python > 3.7) - should lead to a faster
import time for regionmask (:pull:`369`).
- Small changes to the repr of :py:class:`Regions` (:pull:`378`).
- Reduce the memory requirements of :py:func:`core.utils.unpackbits` (:issue:`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 (:pull:`405`).

.. _whats-new.0.9.0:

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
~~~~~~~~~~~~

- regionmask does now correctly treat overlapping regions if ``overlap=True`` is set in
the constructor (:issue:`228`, :pull:`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.

- :py:meth:`Regions.mask` and :py:meth:`Regions.mask_3D` now work with unstructured 1D
grids such as:

- `ICON <https://code.mpimet.mpg.de/projects/iconpublic>`_
- `FESOM <https://fesom.de/>`_
- `MPAS <https://mpas-dev.github.io/>`_

with 1-dimensional coordinates of the form ``lon(cell)`` and ``lat(cell)``.
Note that only xarray arrays can be detected as unstructured grids.
(:issue:`278`, :pull:`280`). By `Aaron Spring <https://github.com/aaronspring>`_.

- Add methods to convert :py:class:`Regions` to (geo)pandas objects, namely :py:meth:`Regions.to_geodataframe`,
:py:meth:`Regions.to_geoseries`, :py:meth:`Regions.to_dataframe`). The geopandas.GeoDataFrame
can be converted back (round-tripped) using :py:meth:`Regions.from_geodataframe`
(:issue:`50`, :pull:`298`).

- The plotting methods (:py:meth:`Regions.plot` and :py:meth:`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 (:issue:`109`, :pull:`292`).
- The download of the natural_earth regions is now done in regionmask (using pooch) and no
longer relies on cartopy (:issue:`306`, :pull:`311`).

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
~~~~~~~~~~~

- Added :py:attr:`prudence` regions for Europe from `Christensen and Christensen, 2007,
<https://link.springer.com/article/10.1007/s10584-006-9210-7>`_ (:pull:`283`).
By `Ruth Lorenz <https://github.com/ruthlorenz>`_.

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

Docs
~~~~

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

Internal Changes
~~~~~~~~~~~~~~~~

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

.. _whats-new.0.8.0: