Docs update

Author: mx-moth

continuous-integration/docs.yaml

@@ -3,8 +3,8 @@ channels:
 
 dependencies:
   - geos ~=3.12.2
-  - python =3.12
+  - python =3.14
   - wheel
   - pip:
-    - -r ./requirements-3.12.txt
+    - -r ./requirements-3.14.txt
     - -e ..[docs]

docs/_static/images/animated-plot.mp4

@@ -15,28 +15,33 @@ the :class:`~emsarray.conventions.Convention` interface.
 .. autofunction:: emsarray.open_dataset
 .. autofunction:: emsarray.get_dataset_convention
 
-.. autoclass:: emsarray.conventions.Convention
-   :members:
+Convention
+==========
 
-.. autoclass:: emsarray.conventions.DimensionConvention
+All dataset conventions have the following methods:
 
-   .. autoattribute:: grid_dimensions
+.. autoclass:: emsarray.conventions.Convention
+   :members:
 
 .. autoclass:: emsarray.conventions.Grid
    :members:
 
-.. autoclass:: emsarray.conventions.DimensionGrid
-   :members: dimensions
+Concepts
+========
 
 .. type:: GridKind
 
-    Some type that can enumerate the different :ref:`grid types <grids>`
-    present in a dataset.
-    This can be an :class:`enum.Enum` listing each different kind of grid.
+    All datasets define variables on one or more  :ref:`grid<grids>`.
+    :type:`GridKind` enumerates all the available grids for a specific convention,
+    while :class:`Grid` provides methods for introspecting a particular grid.
+
+    The :type:`GridKind` for a dataset is usually an :class:`enum.Enum` listing each different kind of grid.
+
+    .. rubric:: Notes
 
     :type:`Index` values will be included in the feature properties
     of exported geometry from :mod:`emsarray.operations.geometry`.
-    If the index type includes the grid kind,
+    As the native index for a convention usually includes the grid kind,
     the grid kind needs to be JSON serializable.
     The easiest way to achieve this is to make your GridKind type subclass :class:`str`:
 
@@ -60,6 +65,20 @@ the :class:`~emsarray.conventions.Convention` interface.
     this should be a tuple whos first element is :type:`.GridKind`.
     For conventions with a single grid, :type:`.GridKind` is not required.
 
+Dimension conventions
+=====================
+
+Most dataset conventions have grids that are uniquely identifiable by their dimensions.
+For these conventions the DimensionConvention subclass provides many default implementations.
+These details are most relevant for developers implementing new Convention subclasses.
+
+.. autoclass:: emsarray.conventions.DimensionConvention
+
+   .. autoattribute:: grid_dimensions
+
+.. autoclass:: emsarray.conventions.DimensionGrid
+   :members: dimensions
+
 .. autoclass:: emsarray.conventions.Specificity
    :members:
    :undoc-members:

docs/_static/images/animated-plot.png

@@ -14,6 +14,15 @@ and have limited customisation options.
 Consult the :ref:`examples gallery <examples>`
 for demonstrations on making more customised plots.
 
+The :ref:`examples <examples>` section contains many worked examples on how to generate plots.
+:ref:`example-plot-with-clim` is a good place to start.
+
+Shortcuts
+=========
+
+These functions will generate an entire plot,
+but have limited customisation options.
+
 .. autofunction:: plot_on_figure
 .. autofunction:: animate_on_figure
 

docs/_static/images/plot-set-extent.png

@@ -39,6 +39,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'sphinxcontrib.video',
     'roles'
 ]
 
@@ -56,6 +57,7 @@
 # a list of builtin themes.
 #
 html_theme = 'sphinx_book_theme'
+html_theme_options = {'show_toc_level': 2}
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

docs/_static/images/plot-with-clim.png

@@ -0,0 +1,90 @@
+import cartopy.crs
+import datetime
+import emsarray
+import emsarray.plot
+import numpy
+from cartopy.feature import GSHHSFeature
+from emsarray.utils import datetime_from_np_time
+from matplotlib import pyplot
+from matplotlib.artist import Artist
+from matplotlib.animation import FuncAnimation, FFMpegWriter
+
+# Open the dataset
+ds = emsarray.tutorial.open_dataset('kgari')
+
+# Select just the surface water and get the current vectors
+surface = ds.isel(k=-1)
+u, v = surface['u'], surface['v']
+# Compute the magnitude of the current vectors
+magnitude = numpy.sqrt(u ** 2 + v ** 2)
+
+
+# The dataset is in Australian Eastern Standard Time, UTC +10
+aest_timezone = datetime.timezone(datetime.timedelta(hours=10))
+
+
+# Make a figure
+figure = pyplot.figure(figsize=(8, 8), layout='constrained')
+axes = figure.add_subplot(projection=cartopy.crs.PlateCarree())
+axes.set_aspect('equal', adjustable='datalim')
+coast = GSHHSFeature(scale='intermediate')
+axes.add_feature(coast, facecolor='mistyrose', edgecolor='darkgrey', linewidth=0.5)
+axes.set_facecolor('aliceblue')
+
+
+# Make an artist to plot magnitude, selecting the first time step of data.
+# When making an animation it is important to keep the artist in a variable
+# so you can update the data frame by frame.
+magnitude_artist = ds.ems.make_artist(
+    axes, magnitude.isel(time=0),
+    add_colorbar=False,
+    clim=(0, 1), edgecolor='face', cmap='Oranges',
+)
+figure.colorbar(magnitude_artist, ax=axes, location='right', label="metres per second")
+
+# Make an artist to plot the current vectors
+uv_artist = ds.ems.make_artist(
+    axes, (u.isel(time=0), v.isel(time=0)),
+    scale=40)
+
+
+# Finish setting up the plot
+axes.autoscale()
+
+
+def update_plot(frame: int) -> list[Artist]:
+    # This function is called every frame and should update the plot with new data.
+
+    # Disable the matplotlib layout engine after the first frame
+    # else the plot has a tendency to jiggle around on later frames.
+    if frame > 0:
+        figure.set_layout_engine('none')
+
+    # Update the plot title to display the frame time
+    frame_time = datetime_from_np_time(ds['time'].isel(time=frame).values)
+    frame_time = frame_time.astimezone(aest_timezone)
+    axes.set_title(f"Surface water currents\n{frame_time:%Y-%m-%d %H:%M %Z}")
+
+    # Update the data being plotted by the artists
+    magnitude_artist.set_data_array(magnitude.isel(time=frame))
+    uv_artist.set_data_array((u.isel(time=frame), v.isel(time=frame)))
+
+    # Return every artist that has been updated this frame
+    return [axes.title, magnitude_artist, uv_artist]
+
+
+animation = FuncAnimation(
+    figure,  # The figure to animate
+    update_plot,  # The function to call to update the plot data
+    frames=ds.sizes['time'],  # How many frames of animation to render
+)
+
+# Draw and save the first frame of the animation for a thumbnail
+update_plot(0)
+figure.savefig('animated-plot.png')
+
+# Save the animation
+ffmpeg_writer = FFMpegWriter(fps=5, bitrate=1800)
+animation.save('animated-plot.mp4', writer=ffmpeg_writer)
+
+pyplot.show(block=True)

docs/api/conventions/interface.rst

@@ -0,0 +1,35 @@
+.. _example-animated-plot:
+
+=============
+Animated plot
+=============
+
+Animated plots are possible with emsarray by using :class:`matplotlib.animation.FuncAnimation`
+and calling :meth:`.GridArtist.set_data_array()` each frame.
+A :class:`~matplotlib.animation.FuncAnimation` will call a function every frame where you can update the plot.
+Each artist returned by :meth:`.Convention.make_artist()` has a :meth:`~.GridArtist.set_data_array()` method
+which can be used to update the data in the plot.
+In combination this makes animations in emsarray about as straight forward as making a static plot:
+
+.. video:: /_static/images/animated-plot.mp4
+   :poster: /_static/images/animated-plot.png
+   :alt: A video of surface water currents around K'gari.
+   :loop:
+   :muted:
+   :width: 100%
+
+Code
+====
+
+Saving a video to a file requires `ffmpeg <https://www.ffmpeg.org/>`_
+which can be installed using conda:
+
+.. code-block:: shell
+
+    $ conda install ffmpeg
+
+:download:`Download animated-plot.py example <animated-plot.py>`.
+
+.. literalinclude:: animated-plot.py
+   :language: python
+