Skip to content

Commit

Permalink
Bundle recipes and example data into documentation
Browse files Browse the repository at this point in the history
This prevents needing to rely on external hosts for these. I did need to drop
the example commands to fetch the resources via curl, but they were probably
confusing anyway.
  • Loading branch information
jfrost-mo committed Sep 17, 2024
1 parent b565a04 commit f50ddfe
Show file tree
Hide file tree
Showing 5 changed files with 49 additions and 22 deletions.
Binary file added docs/source/getting-started/air_temp.nc
Binary file not shown.
39 changes: 39 additions & 0 deletions docs/source/getting-started/air_temperature_spatial_plot.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Name of the recipe.
title: Surface air temperature spatial plot
# Category of recipe, used to group together multiple recipes in output.
category: Quick look
# Description will be displayed alongside output.
description: |
Extended description that can go across multiple lines. It is written in
[Markdown](https://commonmark.org/help/) and can thus contain links and
_formatting_.
# Sequence of steps to run.
steps:
# Specify the operator to run in each step.
- operator: read.read_cubes
# Specify the name of the argument, and its value.
filename_pattern: "*.nc"

- operator: filters.filter_cubes
# Can specify extra keyword arguments as sub-maps.
constraint:
operator: constraints.combine_constraints
var_constraint:
# Can nest in another operator to use its output as an argument,
# multiple levels deep if needed.
operator: constraints.generate_var_constraint
# Input implicitly taken from the previous step, but can be overridden
# by using the appropriate keyword argument.
varname: m01s03i236
cell_method_constraint:
operator: constraints.generate_cell_methods_constraint
# Values can be more than just strings, such as this empty list.
cell_methods: []

# Save a sequence of plots, one per time.
- operator: plot.spatial_pcolormesh_plot

# Save a single cube with all the processed data.
- operator: write.write_cube_to_nc
overwrite: True
10 changes: 4 additions & 6 deletions docs/source/getting-started/create-first-recipe.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ We will now create a recipe from scratch. This recipe will plot a specific
timestamp of the example air temperature data.

Start by opening a new file in your favourite text editor, and save it somewhere
accessible as ``single_timestep_surface_air_temperature_spatial_plot.yaml``.
accessible as ``surface_air_temperature_spatial_plot.yaml``.

Recipe Metadata
---------------
Expand Down Expand Up @@ -179,16 +179,14 @@ After following this far your recipe should look like this:
Running the Recipe
------------------

We can run this recipe using `the same data`_ as was used for the
:doc:`run-recipe` tutorial.

.. _the same data: https://github.com/MetOffice/CSET/raw/main/tests/test_data/air_temp.nc
We can run this recipe using the same data as was used for the
:doc:`run-recipe` tutorial: :download:`air_temp.nc`

Use ``cset bake`` to run your newly created recipe.

.. code-block:: bash
cset bake -i air_temp.nc -o output/ -r single_timestep_surface_air_temperature_spatial_plot.yaml
cset bake -i air_temp.nc -o output/ -r surface_air_temperature_spatial_plot.yaml
You can investigate the created plot and data file in the specified ``output``
directory.
Expand Down
17 changes: 4 additions & 13 deletions docs/source/getting-started/run-recipe.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,11 @@ this tutorial you will use CSET to plot the mean surface air temperature of a
forecast.

We will create a basic spatial plot of the mean surface air temperature, using a
pre-existing recipe. You can `download the recipe file here`_.
pre-existing recipe. Download the following recipe:
:download:`air_temperature_spatial_plot.yaml`

Now you need to find some data to process. You can `download an example file
here`_, or with the following command.

.. code-block:: bash
# Download recipe file.
curl -LO https://gist.githubusercontent.com/jfrost-mo/6e539d5be20bfa28342bf4ff82f24dea/raw/air_temperature_spatial_plot.yaml
# Download example data.
curl -LO https://github.com/MetOffice/CSET/raw/main/tests/test_data/air_temp.nc
Now you need to find some data to process. Download the following example file:
:download:`air_temp.nc`

Now we are ready to run our recipe. This is where we use the ``cset bake``
command. This takes the input data file, an output path and the recipe file. The
Expand All @@ -34,6 +28,3 @@ You can look at the visualised output with ``xdg-open output/index.html``.

You've now successfully run CSET with a pre-existing recipe. In the next
tutorial we will see what is going on inside.

.. _download the recipe file here: https://gist.githubusercontent.com/jfrost-mo/6e539d5be20bfa28342bf4ff82f24dea/raw/air_temperature_spatial_plot.yaml
.. _download an example file here: https://github.com/MetOffice/CSET/raw/main/tests/test_data/air_temp.nc
5 changes: 2 additions & 3 deletions docs/source/getting-started/visualise-recipe.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ Visualising a recipe graphically
In this tutorial we will investigate what is going on inside of a recipe, and
visualise the *operators* inside.

As in the previous tutorial `download this example recipe file`_.
As in the previous tutorial we can download this example recipe file:
:download:`air_temperature_spatial_plot.yaml`

We will now visualise the steps inside the recipe using the ``cset graph``
command.
Expand Down Expand Up @@ -52,5 +53,3 @@ Afterwards the cube passes to the ``plot.spatial_contour_plot`` and

You now know how to visualise a recipe, and a little about the operators it is
made up of. In the next tutorial you will learn to make your own recipe.

.. _download this example recipe file: https://gist.githubusercontent.com/jfrost-mo/6e539d5be20bfa28342bf4ff82f24dea/raw/air_temperature_spatial_plot.yaml

0 comments on commit f50ddfe

Please sign in to comment.