TC hunt vol. 4

recipes/tc_tracking/README.md

@@ -43,13 +43,12 @@ process.
    - [2.1 Generate Ensemble](#21-generate-ensemble)
    - [2.2 Reproduce Individual Ensemble Members](#22-reproduce-individual-ensemble-members)
    - [2.3 Extract Reference Tracks from ERA5](#23-extract-reference-tracks-from-era5)
-3. [Visualisation](#3-visualisation) *(coming soon)*
+3. [Visualisation](#3-visualisation)
 4. [TempestExtremes Integration](#4-tempestextremes-integration)
 5. [Example Workflow](#5-example-workflow)
    - [5.1 Extract Baseline](#51-extract-baseline-optional)
    - [5.2 Produce Ensemble Forecasts](#52-produce-ensemble-forecasts)
    - [5.3 Analyse Tracks](#53-analyse-tracks)
-     *(coming soon)*
    - [5.4 Reproduce Interesting Members](#54-reproduce-interesting-members-to-extract-fields)
 
 ## 1. Setting up the Environment
@@ -570,29 +569,36 @@ and a warning is logged.
 
 ## 3. Visualisation
 
-> [!Note]
-> Visualisation tools will be available in a future update.
-
-<!-- markdownlint-disable MD033 -->
-<details>
-<summary>Preview</summary>
-
-Two Jupyter notebooks are provided in `./plotting` for
-analysing and visualising tropical cyclone tracking results:
+Two [JupyText](https://jupytext.readthedocs.io/) notebook scripts are
+provided in `./plotting` for analysing and visualising tropical cyclone
+tracking results:
 
-- **`tracks_slayground.ipynb`**: Ensemble track analysis
+- **`tracks_slayground_notebook.py`**: Ensemble track analysis
   including spaghetti plots (trajectory visualisation),
   absolute and relative intensity metrics (wind speed,
   MSLP), comparisons against ERA5 reference tracks and
   IBTrACS observations, extreme value statistics, and
   error moment analysis over lead time.
 
-- **`plot_tracks_n_fields.ipynb`**: Create animated
+- **`plot_tracks_n_fields_notebook.py`**: Create animated
   visualisations of storm tracks overlaid on atmospheric
   field data.
 
-</details>
-<!-- markdownlint-enable MD033 -->
+Both scripts can be run as plain Python files or converted to Jupyter
+notebooks via JupyText. From the recipe root:
+
+```bash
+cd plotting
+jupytext --to notebook tracks_slayground_notebook.py
+jupytext --to notebook plot_tracks_n_fields_notebook.py
+jupyter notebook tracks_slayground.ipynb
+```
+
+`./plotting/` must be the working directory because the notebooks import
+their helpers (`analyse_n_plot`, `plotting_helpers`, `data_handling`) by
+bare module name. See `./plotting/README.md` for the full layout, including
+the `analyse_n_plot.py` batch entry point for running the analysis across
+many storms at once.
 
 ## 4. TempestExtremes Integration
 
@@ -708,13 +714,6 @@ trajectories.
 
 ### 5.3 Analyse Tracks
 
-> [!Note]
-> Visualisation tools will be available in a future update.
-
-<!-- markdownlint-disable MD033 -->
-<details>
-<summary>Preview</summary>
-
 Visualise the results using the notebook
 `plotting/tracks_slayground.ipynb`.
 
@@ -739,9 +738,6 @@ tru_track_dir = '/path/to/outputs_reference_tracks'
 # tru_track_dir = '/path/to/test/aux_data'
 ```
 
-</details>
-<!-- markdownlint-enable MD033 -->
-
 ### 5.4 Reproduce Interesting Members to Extract Fields
 
 Suppose that after conducting the above analysis you want

recipes/tc_tracking/plotting/.gitignore

@@ -0,0 +1,2 @@
+plots/
+*.ipynb

recipes/tc_tracking/plotting/README.md

@@ -0,0 +1,50 @@
+# Analysing and Plotting TC Tracks
+
+## Notebooks
+
+- **`plot_tracks_n_fields_notebook.py`** – Plotting tracks and fields for
+  individual ensemble members
+- **`tracks_slayground_notebook.py`** – Analysing and plotting complete
+  tracks from a full ensemble run for a case study on a given storm
+
+Both scripts are [JupyText](https://jupytext.readthedocs.io/) Python files
+that can be run directly or converted to Jupyter notebooks:
+
+```bash
+# Convert to a Jupyter notebook
+jupytext --to notebook plot_tracks_n_fields_notebook.py
+jupytext --to notebook tracks_slayground_notebook.py
+```
+
+> [!Note]
+> The notebooks and the modules in this directory use bare module names
+> (`from analyse_n_plot import ...`, `from plotting_helpers import ...`).
+> Run them with `plotting/` as the working directory so Python can resolve
+> those imports:
+>
+> ```bash
+> cd recipes/tc_tracking/plotting
+> jupyter notebook tracks_slayground.ipynb
+> ```
+
+## Scripts and Library Modules
+
+- **`analyse_n_plot.py`** – Batch entry point. Drives
+  `analyse_individual_storms` (one plot set per storm) and
+  `analyse_ensemble_of_storms` (error metrics aggregated across many
+  storms). Run with `python analyse_n_plot.py` after editing the storm
+  selection and paths near the bottom of the file.
+- **`data_handling.py`** – Library: track ingestion, matching against the
+  reference, ensemble averaging on the sphere, and lead-time error
+  metrics. Imported by the notebooks; not intended to be run directly.
+- **`plotting_helpers.py`** – Library: the individual plotting routines
+  (spaghetti, intensities over time, histograms, error metrics). Also
+  imported by the notebooks; not intended to be run directly.
+
+## Additional Information
+
+- Each notebook specifies at the beginning what data is required and how to
+  produce it using the TC tracking pipeline.
+- All plotting and analysis routines take a `time_step` keyword argument
+  defaulting to 6 h, matching the stock FCN3 and AIFS-ENS configurations.
+  Override it if you run the upstream pipeline at a different cadence.