Introduce cset_gallery functionality

docs/source/conf.py

@@ -4,6 +4,8 @@
 https://www.sphinx-doc.org/en/master/usage/configuration.html
 """
 
+from sphinx_gallery.sorting import ExplicitOrder
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -20,6 +22,7 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
+    "sphinx_gallery.gen_gallery",
 ]
 
 # -- Options for HTML output -------------------------------------------------
@@ -61,3 +64,28 @@
     # Met Office internal webserver.
     r"https://wwwspice/.+",
 ]
+
+# -- Sphinx gallery config ----------------------------------------------------
+
+sphinx_gallery_conf = {
+    "plot_gallery": True,
+    "examples_dirs": "reference/cset_gallery/examples",  # input scripts
+    "gallery_dirs": "reference/cset_gallery/generated",  # output pages
+    "filename_pattern": r"\.py$",
+    "image_scrapers": ("matplotlib",),
+    "thumbnail_size": (800, 600),
+    "capture_repr": (),  # disable capture of printed / returned output
+    "nested_sections": False,
+    "subsection_order": ExplicitOrder(
+        [
+            "reference/cset_gallery/examples/spatial",
+            "reference/cset_gallery/examples/line",
+            "reference/cset_gallery/examples/custom",
+        ]
+    ),
+}
+
+suppress_warnings = [
+    "toc.not_included",
+    "toc.excluded",
+]

docs/source/index.rst

@@ -26,6 +26,9 @@ Useful links
 
 `Source Code`_ | `Issue Tracker`_ | Releases_ | `Discussion Forum`_
 
+
+For examples of CSET outputs, see :doc:`reference/cset_gallery/index`.
+
 For information on how to use CSET, see :doc:`getting-started/index`.
 
 For information on getting involved as a developer, see

docs/source/reference/cli.rst

@@ -1,5 +1,5 @@
-CLI Usage
-=========
+Command Line Usage (CLI)
+========================
 
 .. _cset-bake-command:
 

docs/source/reference/cset_gallery/examples/README.rst

@@ -0,0 +1 @@
+.. orphan

docs/source/reference/cset_gallery/examples/custom/README.rst

@@ -0,0 +1,2 @@
+Customising CSET outputs
+========================

docs/source/reference/cset_gallery/examples/custom/plot_surface_spatial_cutout.py

@@ -0,0 +1,69 @@
+"""
+Trim edge gridcells
+===================
+
+Generate spatial map of a 2D field over selected sub-region of data with domain edges trimmed.
+
+Spatial maps are generated using either CSET operators :py:mod:`CSET.operators.plot.spatial_pcolormesh_plot` or :py:mod:`CSET.operators.plot.spatial_contour_plot`.
+
+General functionality is provided using :doc:`CSET recipe </usage/operator-recipes>` ``generic_surface_spatial_plot_sequence.yaml``
+
+
+A) Using *cset bake* on the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- See :doc:`/reference/cset_gallery/generated/spatial/plot_surface_spatial` for general settings.
+- Set ``SUBAREA_TYPE`` and ``SUBAREA_EXTENT`` to select trim widths, and use ``SUBAREA_NAME`` to control labelling.
+- Example to generate spatial maps for selected sub-area of ``VARNAME`` for all output times:
+
+.. code-block::
+
+    cset cookbook generic_surface_spatial_plot_sequence
+    cset bake -i "input_data_path" -o "my_output_path"
+              -r generic_surface_spatial_plot_sequence
+              --VARNAME="temperature_at_screen_level"
+              --MODEL_NAME="my_model_label"
+              --METHOD=""
+              --SUBAREA_TYPE='gridcells' --SUBAREA_EXTENT=[3, 2, 3, 1] --SUBAREA_NAME=''
+              [-s STYLE_FILE] [--plot-resolution PLOT_RESOLUTION] [--skip-write]
+
+
+B) Configuring the *cset_workflow*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Update workflow configuration settings via ``rose edit`` GUI or in ``rose-suite.conf`` file.
+- Complete ``General setup options`` and ``Cycling and Model options`` details - see :doc:`/usage/workflow-configure`.
+- Set ``SELECT_SUBAREA`` to ``True``, set ``SUBAREA_TYPE`` to ``gridcells`` and set ``SUBAREA_EXTENT``.
+- Set other required configuration options on ``Diagnostics / Surface (2D) fields`` panel.
+
+::
+
+    SELECT_SUBAREA = True
+    SPATIAL_SURFACE_FIELD = True
+    SUBAREA_TYPE = 'gridcells'
+    SUBAREA_EXTENT = [3, 2, 3, 1]
+    SUBAREA_NAME = ''
+    SURFACE_FIELDS = ['temperature_at_screen_level', <other_variable_of_interest>, ...]
+
+
+C) Example python code
+^^^^^^^^^^^^^^^^^^^^^^
+"""
+
+import CSET.operators.plot as cset_plot
+import CSET.operators.read as cset_read
+
+# Set path to input data
+file_path = "../../../../../../tests/test_data/air_temp.nc"
+
+# Read selected variable(s) of interest.
+# Use read_cube parameters to control edge trim selection.
+cube = cset_read.read_cubes(
+    file_path,
+    ["temperature_at_screen_level"],
+    subarea_type="gridcells",
+    subarea_extent=[3, 2, 3, 1],
+)[0]
+
+# Plot single example frame using spatial_contour_plot
+cset_plot.spatial_contour_plot(cube[-1])

docs/source/reference/cset_gallery/examples/custom/plot_surface_spatial_global_cutout.py

@@ -0,0 +1,69 @@
+"""
+Select lat-lon subarea
+======================
+
+Generate spatial map of a 2D field over selected sub-region of data.
+
+Spatial maps are generated using either CSET operators :py:mod:`CSET.operators.plot.spatial_pcolormesh_plot` or :py:mod:`CSET.operators.plot.spatial_contour_plot`.
+
+General functionality is provided using :doc:`CSET recipe </usage/operator-recipes>` ``generic_surface_spatial_plot_sequence.yaml``
+
+
+A) Using *cset bake* on the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- See :doc:`/reference/cset_gallery/generated/spatial/plot_surface_spatial_global` for general settings.
+- Set ``SUBAREA_TYPE`` and ``SUBAREA_EXTENT`` to select sub-region, and use ``SUBAREA_NAME`` to control labelling.
+- Example to generate spatial maps for selected sub-area of ``VARNAME`` for all output times:
+
+.. code-block::
+
+    cset cookbook generic_surface_spatial_plot_sequence
+    cset bake -i "input_data_path" -o "my_output_path"
+              -r generic_surface_spatial_plot_sequence
+              --VARNAME="temperature_at_screen_level"
+              --MODEL_NAME="my_model_label"
+              --METHOD=""
+              --SUBAREA_TYPE='realworld' --SUBAREA_EXTENT=[-40.0, 40.0, -20.0, 55.0] --SUBAREA_NAME='Africa'
+              [-s STYLE_FILE] [--plot-resolution PLOT_RESOLUTION] [--skip-write]
+
+
+B) Configuring the *cset_workflow*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Update workflow configuration settings via ``rose edit`` GUI or in ``rose-suite.conf`` file.
+- Complete ``General setup options`` and ``Cycling and Model options`` details - see :doc:`/usage/workflow-configure`.
+- Set ``SELECT_SUBAREA`` to ``True``, choose ``SUBAREA_TYPE`` and set ``SUBAREA_EXTENT`` and ``SUBAREA_NAME``.
+- Set other required configuration options on ``Diagnostics / Surface (2D) fields`` panel.
+
+::
+
+    SELECT_SUBAREA = True
+    SPATIAL_SURFACE_FIELD = True
+    SUBAREA_TYPE = 'realworld'
+    SUBAREA_EXTENT = [-40.0, 40.0, -20.0, 55.0]
+    SUBAREA_NAME = 'Africa'
+    SURFACE_FIELDS = ['temperature_at_screen_level', <other_variable_of_interest>, ...]
+
+
+C) Example python code
+^^^^^^^^^^^^^^^^^^^^^^
+"""
+
+import CSET.operators.plot as cset_plot
+import CSET.operators.read as cset_read
+
+# Set path to input data
+file_path = "../../../../../../tests/test_data/air_temperature_global.nc"
+
+# Read selected variable(s) of interest.
+# Use read_cube parameters to control subarea selection.
+cube = cset_read.read_cube(
+    file_path,
+    ["temperature_at_screen_level"],
+    subarea_type="realworld",
+    subarea_extent=[-40.0, 40.0, -20.0, 55.0],
+)
+
+# Plot single example frame using spatial_pcolormesh_plot
+cset_plot.spatial_pcolormesh_plot(cube)

docs/source/reference/cset_gallery/examples/line/README.rst

@@ -0,0 +1,4 @@
+.. orphan
+
+Line plots
+==========

docs/source/reference/cset_gallery/examples/line/plot_line_histogram.py

@@ -0,0 +1,65 @@
+"""
+Histogram plot
+==============
+
+Generate histogram of region-averaged field.
+
+Line are generated using either CSET operators :py:mod:`CSET.operators.plot.plot_histogram_series`.
+
+General functionality is provided using :doc:`CSET recipe </usage/operator-recipes>` ``generic_surface_histogram_series.yaml``
+
+
+A) Using *cset bake* on the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Access recipe file using ``cset cookbook``.
+- Set required recipe inputs on command-line (or as environment variables for greater flexibility).
+- Use ``SEQUENCE="realization"`` to generate one histogram for all times.
+- Use ``SEQUENCE="time"`` for a histogram at each output time.
+- Example to generate full domain histogram of ``VARNAME`` for all output times:
+
+.. code-block::
+
+    cset cookbook generic_surface_histogram_series
+    cset bake -i "input_data_path" ["input_data_path2" "input_data_path3" "..."] -o "my_output_path"
+              -r generic_surface_histogram_series.yaml
+              --VARNAME="temperature_at_screen_level"
+              --MODEL_NAME="my_model_label" "my_model_label2" "my_model_label3" "..."
+              --SEQUENCE="realization"
+              --SUBAREA_TYPE='None' --SUBAREA_EXTENT='None' --SUBAREA_NAME='None'
+              [-s STYLE_FILE] [--plot-resolution PLOT_RESOLUTION] [--skip-write]
+
+
+
+B) Configuring the *cset_workflow*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Update workflow configuration settings via ``rose edit`` GUI or in ``rose-suite.conf`` file.
+- Complete ``General setup options`` and ``Cycling and Model options`` details - see :doc:`/usage/workflow-configure`.
+- Set required configuration options on ``Diagnostics / Surface (2D) fields`` panel.
+- Set ``HISTOGRAM_SURFACE_FIELD_SEQUENCE=False`` to generate one histogram for all times.
+- Set ``HISTOGRAM_SURFACE_FIELD_SEQUENCE=True`` for a histogram at each output time.
+
+::
+
+    SURFACE_FIELDS = ['temperature_at_screen_level', <other_variable_of_interest>, ...]
+    HISTOGRAM_SURFACE_FIELD = True
+    HISTOGRAM_SURFACE_FIELD_SEQUENCE = False
+
+
+
+C) Example python code
+^^^^^^^^^^^^^^^^^^^^^^
+"""
+
+import CSET.operators.plot as cset_plot
+import CSET.operators.read as cset_read
+
+# Set path to input data
+file_paths = "../../../../../../tests/test_data/air_temperature_global.nc"
+
+# Read selected variable(s) of interest
+cubes = cset_read.read_cubes(file_paths, ["temperature_at_screen_level"])
+
+# Plot domain histogram
+cset_plot.plot_histogram_series(cubes, sequence_coordinate="realization")

docs/source/reference/cset_gallery/examples/line/plot_line_power_spectra.py

@@ -0,0 +1,69 @@
+"""
+Power spectra plot
+==================
+
+Generate power spectra of region-averaged field.
+
+Line are generated using either CSET operators :py:mod:`CSET.operators.plot.plot_line_series`.
+
+General functionality is provided using :doc:`CSET recipe </usage/operator-recipes>` ``generic_surface_power_spectrum_series.yaml``
+
+
+A) Using *cset bake* on the command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Access recipe file using ``cset cookbook``.
+- Set required recipe inputs on command-line (or as environment variables for greater flexibility).
+- Use ``SINGLE_PLOT=True`` to generate one plot for all times.
+- Use ``SINGLE_PLOT=False`` for a plot at each output time.
+- Example to generate full-domain power spectra of ``VARNAME`` for all output times:
+
+.. code-block::
+
+    cset cookbook generic_surface_domain_mean_time_series
+    cset bake -i "input_data_path" ["input_data_path2" "input_data_path3" "..."] -o "my_output_path"
+              -r generic_surface_domain_mean_time_series
+              --VARNAME="temperature_at_screen_level"
+              --MODEL_NAME="my_model_label" "my_model_label2" "my_model_label3" "..."
+              --SINGLE_PLOT="True"
+              --SUBAREA_TYPE='None' --SUBAREA_EXTENT='None' --SUBAREA_NAME='None'
+              [-s STYLE_FILE] [--plot-resolution PLOT_RESOLUTION] [--skip-write]
+
+
+B) Configuring the *cset_workflow*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Update workflow configuration settings via ``rose edit`` GUI or in ``rose-suite.conf`` file.
+- Complete ``General setup options`` and ``Cycling and Model options`` details - see :doc:`/usage/workflow-configure`.
+- Set required configuration options on ``Diagnostics / Surface (2D) fields`` panel.
+- Set ``SPECTRUM_SURFACE_FIELD_SEQUENCE=False`` to generate spectrum for all times.
+- Set ``SPECTRUM_SURFACE_FIELD_SEQUENCE=True`` for spectrum at each output time.
+
+::
+
+    SURFACE_FIELDS = ['temperature_at_screen_level', <other_variable_of_interest>, ...]
+    SPECTRUM_SURFACE_FIELD = True
+    SPECTRUM_SURFACE_FIELD_SEQUENCE = False
+
+
+C) Example python code
+^^^^^^^^^^^^^^^^^^^^^^
+"""
+
+import CSET.operators.plot as cset_plot
+import CSET.operators.power_spectrum as cset_spectra
+import CSET.operators.read as cset_read
+
+# Set path to input data
+file_paths = "../../../../../../tests/test_data/air_temperature_global.nc"
+
+# Read selected variable(s) of interest
+cubes = cset_read.read_cubes(file_paths, ["temperature_at_screen_level"])
+
+# Compute domain power spectrum
+spectra = cset_spectra.calculate_power_spectrum(cubes)
+
+# Plot power spectrum as line plot
+cset_plot.plot_line_series(
+    spectra, series_coordinate="physical_wavenumber", single_plot=True
+)