Deprecate implicit isel(time=0) default in DataArray.plot()

[ecomodeller]

Problem

Calling da.plot() on a multi-timestep 2D-spatial DataArray (Grid2D, FM 2D, vertical profile, point spectrum) silently selects the first timestep. The behaviour has been part of mikeio since the beginning and is mentioned in the docstrings of DataArrayPlotterGrid2D, DataArrayPlotterFM, and DataArrayPlotterFMVerticalProfile ("the first step will be plotted"), but is undocumented in DataArrayPlotterPointSpectrum which silently does the same.

For a hydrodynamic simulation started from a cold start, the first timestep is the flat initial condition — the default plot is uninformative or actively misleading. There is no defensible global default: first is bad for spinup, last is bad for spinup-truncated files, mean hides extremes. The convenience of "show me anything" is real for a developer poking at a file, but actively unhelpful for the modellers who are mikeio's primary audience.

Prior art

Library	Behaviour with extra dims
xarray	Falls back to xarray.plot.hist() for ndim ∉ {1, 2}; offers row= / col= faceting for explicit time navigation
iris	Hard ValueError: "Cube must be N-dimensional. Got M dimensions."
xugrid (Deltares — closest analogue)	squeeze(), then ValueError("UgridDataArray contains non-topology dimensions")
uxarray (NCAR)	ValueError: "Expected data with a single dimension (other axes may be length 1)"
hvplot	Defaults to histogram for >2D; temporal navigation via explicit groupby='time'

The mikeio default is unique. xugrid — the closest analogue, operating on the same kind of unstructured-mesh-over-time data as mikeio's dfsu plotter — raises rather than silently slicing.

Recommendation

Deprecate the implicit isel(time=0) in two stages, mirroring the existing FutureWarning already in place for the analogous "implicitly selects surface layer" behaviour (_plot_FM_map):

1. Next minor release: emit FutureWarning from each affected plotter when n_timesteps > 1 and no time selection has been made. Message points users at da.isel(time=0).plot() (or time=-1, time=da.time.mean(), etc.).
2. Next major release: raise ValueError with the same suggestion. Update docstrings, examples, and user-guide notebooks.

Affected plotters: DataArrayPlotterGrid2D (contour, contourf, pcolormesh), DataArrayPlotterFM._plot_FM_map, DataArrayPlotterFMVerticalProfile._plot_transect, DataArrayPlotterPointSpectrum._plot_1dspectrum / _plot_2dspectrum. The Grid1D and FM-vertical-column plotters already use the time axis for the plot itself and are unaffected. The LineSpectrum / AreaSpectrum constructors already pre-reduce via da[0] and should be revisited at the same time for consistency.

Migration cost

Every notebook, example, and downstream user calling .plot() on a multi-step file will need to add an explicit time selection. The FutureWarning stage gives downstream users a release cycle to adapt before the hard error lands.

Related: #969 (inconsistent plotting API across geometries).

[ecomodeller]

Direct precedent: #901 introduced the FutureWarning for implicit surface-layer selection on 3D FM data. The same staged-deprecation playbook applies here.

[ecomodeller]

Worth grounding this in mikeio's existing read() semantics rather than treating it purely as a netCDF-comparison exercise.

Dfsu.read() and Dfs2.read() already accept keepdims: bool = False. When the user explicitly selects a single timestep via time=0, the time dim is dropped. When they read all data, the dim is preserved (even if the file has only one timestep). The read layer already encodes the rule: explicit single-step selection → squeeze; otherwise → preserve.

A first instinct was to mirror that with a length-1 auto-squeeze in plot(): silent on length-1, error on length>1. Rejected. mikeio scripts in advisory work are deliverables — they need to be QAable without running them. A reviewer should be able to read the script and assess correctness without executing it against the actual file. An API where da.plot() means "squeeze" or "error" depending on what is on disk fails that test by construction; pushing the data-dependence from `n>1` to `n==1` does not fix it.

The proposal is therefore strict: .plot() requires no time dim. The user makes the choice explicit in the script:

da = mikeio.read("snapshot.dfsu", time=0)["x"]   # explicit at read
da.plot()

# or
da = mikeio.read("snapshot.dfsu")["x"]
da.isel(time=0).plot()                            # explicit at plot

Cost: one `isel(time=0)` (or `time=0` at read) for snapshot files. Benefit: the script's behaviour is determinable from the code alone.

Implementation mirrors #901 — `FutureWarning` first, `ValueError` later. Affected plotters as listed in the issue body.