8. Spatial/temporal post-processing (vflood-analyze)

Once you have a bundled simulation.nc (§7), vflood-analyze answers questions about it a raw grid or a single plotted frame can't: how does a variable vary by sub-basin, is the flooded area spatially clustered or scattered, and what does the hydrograph look like at a specific gauge point. Four subcommands:

vflood-rri RRI_Input.txt                                              # 1. run the simulation
vflood-netcdf RRI_Input.txt                                       # 2. bundle to NetCDF
vflood-analyze zonal simulation.nc --variable hs \
    --zones das_boundaries.geojson --id-field kode_das --out zonal_stats.csv
vflood-analyze moran simulation.nc --variable hs --out moran_timeseries.csv
vflood-analyze hydrograph simulation.nc --variable qr \
    --locations location.txt --outdir hydrograph/ --acf --plot

• zonal — per-zone mean/min/max/std/sum/count at every timestep, from any GeoJSON/shapefile with one or more named polygons (e.g. DAS/watershed boundaries — the same file shape basin-atlas's own gee-scripts/output/ produces, or any user-supplied ROI). --id-field picks which feature property becomes each zone's name in the output CSV; without it, zones are just numbered zone_0, zone_1, etc. Output is long-format CSV (one row per zone per timestep) — reshape/pivot it in whatever tool you plot with. CSV-only, no chart rendering.

• moran — global Moran's I (spatial autocorrelation) for one variable at every timestep: positive means the variable is spatially clustered (a coherent flood extent), near zero means spatially random, negative means a checkerboard-like dispersed pattern. --contiguity queen (default, includes diagonal neighbors) or rook (orthogonal only). NaN cells (outside the domain) are excluded from the statistic, not treated as zero; a completely uniform frame (zero variance, e.g. a dry grid before rain arrives) also comes back as NaN rather than a misleading 0. CSV-only, no chart rendering.

• hydrograph — time series and summary stats (peak value/time, time-to-peak, rising/recession duration at a 10%-of-peak threshold, volume) at named grid points, reading location.txt in the exact name row col (1-indexed) format RRI_Input.txt's own location_file/hydro_switch fields already use. This is the piece the original RRI pipeline's calcHydro.exe utility provided that was never ported here — a real gap this closes, not just a convenience wrapper. --acf also writes a temporal autocorrelation CSV per location (--max-lag controls how many lags — data only, no chart). --plot renders PNG charts of the hydrograph itself: one per-location chart plus a comparison chart overlaying every location's series on one plot (hydrograph_comparison.png) — the single most useful chart for "how did discharge differ across my gauges."

• combined — the presentation figure: rainfall + river discharge (Q) + river depth + slope (overland) depth, one figure per location.txt point, in either of two layouts (--layout):

  # timeseries (default): all 4 as stacked time-series panels
  vflood-analyze combined simulation.nc --rain rain/rain.dat \
      --locations location.txt --outdir combined/ --gif
   
  # spatial: 3 spatial maps (rain/river-depth/slope-depth) + 1 hydrograph panel (Q)
  vflood-analyze combined simulation.nc --layout spatial --project RRI_Input.txt \
      --locations location.txt --outdir combined/ --gif

  --layout timeseries (default) stacks all 4 as time-series panels sharing one time axis. The rainfall panel is basin-average (postprocess.basin_average_rainfall — spatial mean of rain.dat's own grid at each output timestep, via the exact same right-continuous per-timestep lookup the engine itself uses to sample rain.dat, so the panel is reading rain.dat the same way the simulation actually did) drawn as bars with an inverted y-axis — rain "hangs" from the top, the standard hydrology hyetograph-over-hydrograph convention, so wet periods read naturally above the flow response building up beneath them instead of competing for the same space.

  --layout spatial is a 2x2 dashboard instead: 3 full-basin raster maps (rainfall intensity, river depth, slope depth, each at one instant) + 1 hydrograph panel (discharge Q growing over time at the gauge). Needs --project RRI_Input.txt instead of --rain — the spatial rainfall panel is a true remap of rain.dat's own grid onto the model's (lat, lon) grid (postprocess.remap_rainfall_to_grid_series), which needs RRI_Input.txt's xllcorner_rain/yllcorner_rain/cellsize_rain_x/cellsize_rain_y — georeferencing rain.dat's own block format doesn't carry by itself, unlike a plain basin-average which only needs the raw file. Color scales are computed once from the whole series, not per-frame, for the same "don't rescale frame to frame" reason the time-series layout's fixed y-limits use.

  Either layout's --gif additionally renders an animated version per location (<name>_combined.gif / <name>_spatial.gif) — one frame per output timestep, growing/updating in sync with the run's own time, with a dashed "now" marker — plays frame-for-frame alongside vflood-export --formats gif's spatial flood-extent animation (§6) for a side-by-side "watch the map flood and the hydrograph build up together" pair. --gif-duration-ms controls playback speed (default 200ms/frame). Needs qr, hr, and hs all bundled into the input NetCDF (vflood-netcdf's own default --variables hs,hr,qr already includes all three).

• plot — re-renders a PNG hydrograph chart from an existing <location>.csv standalone: vflood-analyze plot hydrograph/Down.csv --out hydrograph/Down.png. Charting is scoped to the hydrograph and the combined figure (the model's own direct output); zonal/moran/ACF are deliberately CSV-only, no chart-rendering path for those.

All CSV output is plain, long-format CSV — no new conventions, so it drops straight into Excel/pandas/R/whatever you already use. Hydrograph and combined charts follow this project's dataviz-skill palette (fixed-order categorical colors — the same location/variable always gets the same color across every chart — thin lines, light gridlines, a legend whenever there's more than one series). All five subcommands read the bundled NetCDF directly via netCDF4.Dataset (same library choice as vflood-netcdf's own writer, not xarray).