===== 1.0.0 ===== Released on 2026-05-19 Improved support for multiple grids =================================== In previous releases emsarray made the assumption that variables were primarily defined on some grid of polygons. This is true for rectilinear grids, curvilinear grids, spherical multiple cell grids, and unstructured grids from `COMPAS `_ models. This is not true for the unstructured grids from `SCHISM `_ models however which define many variables on the vertices of the polygons, not the polygons themselves. This assumption of polygons was limiting the datasets that emsarray could support. With this update each grid kind is treated equally with no assumptions around face grids. Each dataset can have multiple grid kinds, and each of these grid kinds is represented by a :class:`.Grid` instance. The set of grids for a dataset is available at :attr:`.Convention.grids`, and the grid for a variable can be found using :meth:`.Convention.get_grid`. The externally facing API is mostly backwards compatible although many methods have been deprecated in favour of methods on the :class:`.Grid` class. These methods will continue to be supported for this release at least. `Convention.get_index_for_point` and `SpatialIndexItem` have been dropped instead of deprecated. These methods were little used and backwards compatibility was complicated. To make the transition smoother the assumption of a default polygon grid has been maintained, however this default may be removed in future releases. .. _ugrid: https://ugrid-conventions.github.io/ugrid-conventions/ .. _compas: https://research.csiro.au/cem/software/ems/hydro/unstructured-compas/ .. _schism: https://ccrm.vims.edu/schismweb/ Improved plotting API ===================== The plotting API has been improved to achieve the goals: * The ability to plot variables defined on non-polygonal grids, * Make customisation of artist properties easier, such as colour maps and data limits, * Provide a consistent API for updating the data for an artist, to make animated plots simpler, * Support plotting on multiple axes in a figure, and * Support more kinds of artists, such as contour plots over polygonal grids. A new method :meth:`.Convention.make_artist` has been added which will pick the correct matplotlib :class:`~matplotlib.artist.Artist` to plot a given variable. This method will pass any kwargs on to the underlying artist allowing for easy customisation (see :ref:`sphx_glr_examples_plot-with-clim.py`). This method takes an :class:`~matplotlib.axes.Axes` instance allowing for multiple axes on one figure (see :ref:`sphx_glr_examples_plot-two-subplots.py`). It will return a :class:`~.plot.artists.GridArtist` instance which has a :meth:`.GridArtist.set_data_array` method. Users can call this method to update the data being plotted in an animation without the artist-specific handling previously required in :func:`~.plot.animate_on_figure` (see :ref:`sphx_glr_examples_plot-animation.py`). :ref:`More examples ` are being added over time to demonstrate how to make more customised plots. Changelog ========= * Reduce memory allocations when constructing polygons. This should allow opening even larger datasets (:pr:`200`, :pr:`207`). * Add support for Python 3.14 and drop support for Python 3.11, following `SPEC-0 `_. (:pr:`201`). * Drop all previously deprecated functionality: support for shapely versions older than 2.0, support for cartopy versions older than 0.23.0, the ``emsarray.Format`` and ``emsarray.get_file_format()`` aliases, the renamed Convention methods ``_get_data_array()``, ``get_time_name()``, ``get_depth_name()``, ``get_all_depth_names()``, ``unravel_index()``, ``make_linear()``, ``make_patch_collection()``, ``spatial_index()``, ``get_grid_kind_and_size()``, and ``NonIntersectingPoints.indices`` (:pr:`202`). * Use `PEP 695 `_ style type parameters. This drops the `Index` and `GridKind` type variables which were exported in `emsarray.conventions`, which is a backwards incompatible change but is difficult to add meaningful backwards compatible support (:issue:`109`, :pr:`204`) * Use default matplotlib colour map when plotting instead of "jet". In practice this will usually be "viridis" unless the user has changed their local defaults (:pr:`206`). * Split the :mod:`emsarray.plot` module in to multiple files. It was getting unruly in size and was about to become larger again. The documentation has been updated to match the conceptual divisions. The new layout makes it easier to support matplotlib as an optional dependency (:pr:`208`). * The handling of multiple grid kinds was rewritten from the ground up to properly support conventions like `unstructured grids `_ using the new :meth:`.Convention.grids` property (:pr:`205`, also :issue:`189`). * A new method :meth:`Convention.make_artist()` improves the plotting capabilities, supporting plotting variables on all grids supported by the convention (:pr:`205`, :pr:`210`, :pr:`211`, :issue:`175`, :issue:`121`, and :pr:`187`). * Add `sphinx-gallery `_ to the docs to render the example gallery (:pr:`210`). * Update `emsarray-data `_ to version 1.0.0, which includes the `SCHISM-WWMIII hydrological and wave model hindcast for Vanuatu `_ dataset (:pr:`212`). * Add example showing :ref:`multiple ways of plotting vector data ` (:pr:`213`, :pr:`215`). * Add :attr:`.Grid.centroid_coordinates` attribute (:pr:`214`). * Stop using pytz. The Python datetime module now has sufficient functionality, the external dependency is no longer required. pytz was included as a dependency of pandas, and pandas recently dropped pytz which broke things. (:pr:`219`). * Defer ShocSimple coordinate detection to the CFGrid2D base class (:issue:`217`, :pr:`218`). * Split `tests.utils` in to multiple `tests.helpers` submodules (:pr:`220`). * Split `tests.test_utils` in to multiple `tests.utils.test_component` submodules (:pr:`220`). * Add :func:`emsarray.utils.estimate_bounds_1d` function (:pr:`221`). * Bounds variables are now included in :meth:`Convention.get_all_geometry_names()` (:pr:`222`). * Allow transecting two-dimensional variables, such as sea surface height (:issue:`197`, :pr:`216`). * Add :meth:`.Transect.make_artist()` method and the related :class:`.CrossSectionArtist` and :class:`.TransectStepArtist` artists (:issue:`175`, :pr:`216`). * Monkeypatch the cartopy GSHHS downloader to use the new URL from the University of Hawaii (:pr:`225`, :pr:`SciTools/cartopy#2659`). * Silence all warnings in CI (:pr:`227`). * Manage dependencies, lock files, and installing in CI using poetry (:pr:`228`).