Merge pull request #110 from csiro-coasts/transect

Add `emsarray.transect` module

continuous-integration/environment.yaml

@@ -3,3 +3,4 @@ channels:
 
 dependencies:
   - geos ~=3.10.2
+  - udunits2 >=2.2.25

continuous-integration/requirements.txt

@@ -28,7 +28,11 @@ certifi==2023.7.22
     #   pyproj
     #   requests
 cftime==1.6.2
-    # via netcdf4
+    # via
+    #   cfunits
+    #   netcdf4
+cfunits==3.3.6
+    # via emsarray (setup.cfg)
 chardet==5.2.0
     # via tox
 charset-normalizer==3.2.0
@@ -127,6 +131,7 @@ numpy==1.25.2
     #   bottleneck
     #   cartopy
     #   cftime
+    #   cfunits
     #   contourpy
     #   dask
     #   emsarray (setup.cfg)
@@ -142,6 +147,7 @@ packaging==23.1
     # via
     #   bokeh
     #   cartopy
+    #   cfunits
     #   dask
     #   distributed
     #   emsarray (setup.cfg)

docs/api/index.rst

@@ -19,5 +19,6 @@ API reference
     utils.rst
     tutorial.rst
     plot.rst
+    transect.rst
     types.rst
     exceptions.rst

docs/api/transect.rst

@@ -0,0 +1,30 @@
+.. module:: emsarray.transect
+
+=================
+emsarray.transect
+=================
+
+.. currentmodule:: emsarray.transect
+
+Plot transects through your dataset.
+Transects are vertical slices along some path through your dataset.
+
+Examples
+--------
+
+.. list-table::
+
+   * - :ref:`example-kgari-transect`
+
+       .. image:: /_static/images/kgari-transect.png
+          :width: 200
+          :class: no-scaled-link
+
+.. autofunction:: plot
+
+.. autoclass:: Transect
+   :members:
+
+.. autoclass:: TransectPoint
+
+.. autoclass:: TransectSegment

docs/examples.rst → docs/examples/index.rst

@@ -12,3 +12,21 @@ To explore these notebooks interactively on the web you can launch a
 If you would prefer to download the examples and explore them locally,
 they are available on Github at
 `csiro-coasts/emsarray-notebooks <https://github.com/csiro-coasts/emsarray-notebooks>`_.
+
+Gallery
+=======
+
+.. toctree::
+   :glob:
+   :hidden:
+
+   *
+
+.. list-table::
+
+   * - :ref:`example-kgari-transect`
+
+       .. image:: /_static/images/kgari-transect.png
+          :width: 200
+          :class: no-scaled-link
+

docs/examples/kgari-transect.py

@@ -0,0 +1,55 @@
+import emsarray
+import shapely
+from emsarray import plot, transect
+from matplotlib import pyplot
+
+dataset_url = 'https://dapds00.nci.org.au/thredds/dodsC/fx3/model_data/gbr4_bgc_GBR4_H2p0_B2p0_Chyd_Dcrt.ncml'
+dataset = emsarray.open_dataset(dataset_url).isel(time=-1)
+dataset = dataset.ems.select_variables(['botz', 'temp'])
+
+line = shapely.LineString([
+    [152.9768944, -25.4827962],
+    [152.9701996, -25.4420345],
+    [152.9727745, -25.3967620],
+    [152.9623032, -25.3517828],
+    [152.9401588, -25.3103560],
+    [152.9173279, -25.2538563],
+    [152.8962135, -25.1942238],
+    [152.8692627, -25.0706729],
+    [152.8623962, -24.9698750],
+    [152.8472900, -24.8415806],
+    [152.8308105, -24.6470172],
+    [152.7607727, -24.3521012],
+    [152.6392365, -24.1906056],
+    [152.4792480, -24.0615124],
+])
+landmarks = [
+    ('Round Island', shapely.Point(152.9262543, -25.2878719)),
+    ('Lady Elliot Island', shapely.Point(152.7145958, -24.1129146)),
+]
+
+# Plot the transect
+figure = transect.plot(
+    dataset, line, dataset['temp'],
+    figsize=(7.9, 3),
+    bathymetry=dataset['botz'],
+    landmarks=landmarks)
+figure.savefig('kgari-transect.png')
+
+# Plot the path of the transect
+figure = pyplot.figure(figsize=(5, 5), dpi=100)
+axes = figure.add_subplot(projection=dataset.ems.data_crs)
+axes.set_aspect(aspect='equal', adjustable='datalim')
+axes.set_title('Transect path')
+axes.add_collection(dataset.ems.make_poly_collection(
+    dataset['botz'], cmap='Blues_r', edgecolor='face',
+    linewidth=0.5, zorder=0))
+plot.add_coast(axes, zorder=1)
+plot.add_gridlines(axes)
+plot.add_landmarks(axes, landmarks)
+axes = figure.axes[0]
+axes.set_extent(plot.bounds_to_extent(line.envelope.buffer(0.2).bounds))
+axes.plot(*line.coords.xy, zorder=2)
+figure.savefig('kgari-path.png')
+
+pyplot.show(block=True)

docs/examples/kgari-transect.rst

@@ -0,0 +1,29 @@
+.. _example-kgari-transect:
+
+====================
+K'gari transect plot
+====================
+
+The following is a :mod:`transect <emsarray.transect>` path
+starting in the Great Sandy Strait near K'gari,
+heading roughly North out to deeper waters:
+
+.. image:: /_static/images/kgari-path.png
+   :alt: Transect of GBR1 dataset along Great Sandy Strait and past K'gari
+         showing the water temperature.
+   :align: center
+
+The temperature along this transect can be plotted:
+
+.. image:: /_static/images/kgari-transect.png
+   :alt: Transect of GBR1 dataset along Great Sandy Strait and past K'gari
+         showing the water temperature.
+
+Code
+====
+
+:download:`Download kgari-transect.py example <kgari-transect.py>`.
+
+.. literalinclude:: kgari-transect.py
+   :language: python
+

docs/getting-started/installing.rst

@@ -33,21 +33,28 @@ You can install these by :ref:`choosing some extras at install time <extras>`.
 Dependencies
 ============
 
-``emsarray`` depends on
-`cartopy <https://scitools.org.uk/cartopy/docs/latest/installing.html>`_
-for plotting.
-This depends on the non-Python ``geos`` library.
+Most of the dependencies of ``emsarray`` are installable via pip,
+however some dependencies require non-Python components
+that must be installed using some other method.
+``emsarray`` uses the following libraries that can not be installed via pip:
+
+* ``geos``, via
+  `cartopy <https://scitools.org.uk/cartopy/docs/latest/installing.html>`_.
+  This is used for plotting
+* ``udunits2``, via
+* `cfunits <https://ncas-cms.github.io/cfunits/installation.html>`.
+  This is used for plotting.
 
 These can be installed via your package manager or via ``conda``.
 Installing from ``conda`` is the recommended approach
 as these packages are often more up-to-date than the system packages
-and it guarantees that compatible versions of ``geos`` is installed.
+and it guarantees that compatible versions are installed.
 
 .. code-block:: shell-session
 
    $ conda create -n my-env
    $ conda activate my-env
-   $ conda install cartopy
+   $ conda install cartopy cfunits
 
 If ``geos`` is installed using your system package manager,
 and ``cartopy`` is installed via pip,

docs/index.rst

@@ -44,7 +44,7 @@ Contents
 
     getting-started/index.rst
     concepts/index.rst
-    examples.rst
+    examples/index.rst
     api/index.rst
     cli.rst
     developing/index.rst

docs/releases/development.rst

@@ -27,3 +27,7 @@ Next release (in development)
   This is a breaking change if you previously relied
   on the default value of `True` for these parameters.
   (:pr:`108`).
+* Add new module :mod:`emsarray.transect` for making transect plots.
+  This feature is considered experimental
+  and may change significantly in future releases.
+  (:pr:`110`).

pyproject.toml

@@ -33,6 +33,7 @@ mypy_path = "$MYPY_CONFIG_FILE_DIR/src"
 module = [
 	"cartopy.*",
 	"cftime.*",
+	"cfunits.*",
 	"cryptography.*",
 	"geojson.*",
 	"importlib_metadata.*",

setup.cfg

@@ -44,6 +44,7 @@ plot =
 	cartopy >=0.21.1
 	matplotlib >=3.5.2
 	pykdtree >=1.3.5
+	cfunits >= 3.3.5
 
 tutorial =
 	pooch >=1.3.0
@@ -85,4 +86,4 @@ emsarray.conventions =
 
 [flake8]
 extend-select = E,W
-extend-ignore = E501,W503
+extend-ignore = E501,W503,E731