/swmm-plot

name: swmm-plot
description: Nature-spec figures from a SWMM run: paired rainfall (inverted) + node/link flow hydrograph (plot_run), network layout map (map_run), study-area map. 89/183 mm columns, 5-7 pt sans-serif, ticks out, no gridlines, Wong colour-blind-safe palette, vector PDF + 450 dpi PNG twin, SI units, no title; optional focus-day / HH:MM window crop. Use whenever an agent needs a publication-ready figure from a run's .inp + .out.

SWMM Plot (Nature figure specification)

Part of [Agentic SWMM](https://github.com/Zhonghao1995/agentic-swmm-workflow): install the project first for the executable toolchain (aiswmm CLI, SWMM solver, MCP servers).

Every figure this skill renders follows the Nature journal figure specification, the project's standing figure standard. Source: <https://research-figure-guide.nature.com/figures/preparing-figures-our-specifications/>. The spec lives in exactly three places here, and the scripts hand-set nothing:

| File | Holds | |---|---| | [`assets/nature.mplstyle`](assets/nature.mplstyle) | the stylesheet (fonts, line weights, ticks, palette, TrueType text, constrained layout) | | [`scripts/plot_style.py`](scripts/plot_style.py) | `apply_style()`, `figsize()`, `map_figsize()`, `save_figure()`, `legend_outside()`, the `WONG` palette | | this file | the rules a figure must satisfy, and the tool contracts |

**Scope note:** these are print-publication rules for the data figures of a run. They are not meant for the HTML report chrome or the CLI itself.

Before calling plot: ask the user

When the user asks to plot, **always ask these questions first** before calling any plot tool:

1. **Which entity?** A specific node (junction / outfall), by name, or a specific link (conduit), by name?

• List 3-5 high-peak-flow candidates from the run's RPT `Link Flow Summary` so the user can pick.

2. **Which attribute?** Node options: `Total_inflow`, `Depth_above_invert`, `Volume_stored_ponded`, `Flow_lost_flooding`. Link options: `Flow_rate`, `Velocity`, `Depth`. 3. **Time window?** Default is the full simulation (24h). Offer to limit to a focus day or HH:MM-HH:MM window if peaks occur in a short period.

Do **not** silently pick defaults. The user needs control: different plots answer different questions (peak inspection vs continuity vs flooding).

What this skill renders

| Figure | Script | Reached via | Default output | |---|---|---|---| | Rainfall (top, inverted) + node/link flow (bottom) hydrograph | `scripts/plot_rain_runoff_si.py` | `plot_run` tool, `aiswmm plot`, MCP `plot_rain_runoff_si` | `08_plot/fig_<node>_<attr>.png` + `.pdf` | | Network layout map (subcatchments, conduits, junctions, storage, outfalls; sub-networks coloured per outfall) | `scripts/plot_network_layout.py` | `map_run` tool, `aiswmm map` | `08_plot/network_map.png` + `.pdf` | | Study-area map (DEM hillshade, subcatchments, conduits, outfalls, scale bar, north arrow, cartouche) | `scripts/plot_study_area.py` | SWMMCanada fetch (`aiswmm canada`), or the script directly | `00_raw/study_area.png` + `.pdf` |

Inputs: rainfall TIMESERIES from the `.inp` (inline, `FILE`, or `[RAINGAGES] FILE`), flow series from the `.out` binary (via `swmmtoolbox`), geometry from the INP text or the SWMManywhere / SWMMCanada upstream layers.

Non-negotiables

| Rule | Value | |---|---| | Width | **89 mm** single column (default). **183 mm** double column only for the hydrograph, via `--width double`, when the series needs the room | | Max height | **170 mm** (maps take their height from the network's own aspect ratio) | | Body text | **5 pt min, 7 pt max**, sans-serif (Arial, Helvetica, Nimbus Sans, DejaVu Sans fallbacks) | | Lines / strokes | **0.25-1 pt** (axes 0.5, hydrograph 0.75, conduits 0.6, polygon edges 0.3, scale bar 1.0) | | Colour space | **RGB** | | Palette | Wong colour-blind-safe set (below) | | Output | vector **PDF** (the submission file) + **PNG at 450 dpi** (preview) with the same stem, written together by `save_figure` | | Text in the PDF | live, TrueType-embedded (`pdf.fonttype 42`), never outlined | | Units | SI only; every axis labelled with units in parentheses | | Title | none; titles belong to the surrounding document | | Rainfall axis | inverted (depth grows downward) so it never overlaps the flow series |

Always do

• Start from `apply_style()`; size with `figsize("single" | "double")` or `map_figsize(bounds)`; save with `save_figure(fig, out_png)`. Never `plt.rcParams.update`, never `tight_layout()`, never `bbox_inches="tight"` (it silently changes the physical width and breaks the 89/183 mm rule).
• Axis lines and tick marks on every axis; **ticks point outward**; top/right spines off (the hydrograph's flow axis keeps its own right spine).
• Put the key **above the panel** (`legend_outside`), so it never sits on data.
• Label every axis with units: `Rainfall depth (mm/5 min)`, `Flow (m³/s)`, `Easting (m, EPSG:32610)`, `X (INP units)` when the INP's unit is unknown.
• Keep the figure about the run: the hydrograph draws only the rainfall inside the reported period (a 30-year 5-min climate file is 3M bars otherwise).
• Prefer 89 mm; reach for 183 mm only when the content needs it.

Never do

• Background gridlines
• Drop shadows, 3D effects, gradients as decoration
• Patterns/hatching to distinguish categories; use solid colours
• Coloured text (series are bound to axes by the key, not by tinted labels)
• Red/green pairings, rainbow/jet colourmaps
• Overlapping text, or text over busy backgrounds (the study-area cartouche sits on a white box)
• A title inside the figure
• A raster-only figure: an orphan PNG is what gets submitted by mistake

Wong colour-blind-safe palette

Black first, then in this order. Roles in this skill are fixed so the figures of one run read as one set:

| Name | Hex | Role here | |---|---|---| | Black | `#000000` | flow line; outfall markers (star, white edge) on both maps; conduits on the study-area map | | Orange | `#E69F00` |