A self-contained set of training notebooks for the Climate Rapid Evaluation Framework (REF).
The notebooks take you from what the REF is through to querying the public REF API and building a publication-ready figure. They are written for climate scientists, analysts, and newcomers with no prior REF knowledge is assumed.
Click the launch Binder badge above. Binder builds the environment and opens JupyterLab; no local setup is required.
This may take several minutes
Requires uv, a Python Package Manager to create a local virtual environment.
git clone https://github.com/Climate-REF/climate-ref-tutorials.git
cd climate-ref-tutorials
uv sync # create the environment
uv run bash scripts/generate_client.sh # generate the REF API client
uv run python -c "from ref_tutorials import fetch_sample_data; fetch_sample_data()" # pre-fetch sample data (notebook 04)
uv run jupyter lab notebooks # open the notebooksThe notebooks are designed to be read in order; later ones assume concepts introduced earlier.
| # | Notebook | What you will learn | Prerequisites |
|---|---|---|---|
| 01 | REF concepts | The core vocabulary: diagnostics, providers, executions, metrics, datasets | None |
| 02 | Querying the REF API | Set up the API client, list diagnostics, fetch metric values, inspect an execution | 01 |
| 03 | Figure generation | Build a polished multi-model metric comparison figure and save it | 01, 02 |
| 04 | Running a diagnostic locally | Define a custom diagnostic provider and run it locally on small sample data | 01 |
More notebooks will be added over time — see CONTRIBUTING.md.
- Notebooks 01–03 query the live public REF API at https://api.climate-ref.org. An internet connection is required; the notebooks fail clearly if the API is unreachable.
- The REF API client (
climate_ref_client) is generated from the API's OpenAPI schema byscripts/generate_client.sh, so it always matches the current API. It is not committed to this repository. - Notebook 04 fetches a small CMIP6 sample dataset via the REF CLI and runs a
custom diagnostic provider, defined in
src/ref_tutorials/provider.pylocally. - Shared logic lives in the
ref_tutorialshelper package (src/ref_tutorials), keeping the notebooks short and readable. - Notebook outputs are committed so the notebooks render fully on GitHub without being run.
Apache-2.0. See LICENCE.