dycove.utils.plotting.ModelPlotter

class dycove.utils.plotting.ModelPlotter(simdir, quantity, plot_times, plot_separate_species=True, plot_method='interp', plot_interp_vars: dict[str, int] | None = None, plot_specs: dict[str, Any] | None = None, cmap_lims: dict[str, tuple[float, float]] | None = None, cmaps: dict[str, Colormap] | None = None, quantity_units: dict[str, tuple[str, int | float]] | None = None, plot_vectors=False, vector_props: dict[str, Any] | None = None, show_title=True, show_topo_cbar=False, show_axis_ticks=False, scalebar=False, scalebar_props: dict[str, Any] | None = None, mask_bndy_file: Path | str | None = None, extents: tuple[float, float, float, float] | None = None, animate=False, delete_static_imgs=False, save_grids=False)[source]

Plot hydrodynamic and vegetation quantities from DYCOVE model runs (ANUGA or DFM).

This class handles loading, interpolating, and plotting 2-D spatial quantities (e.g., depth, velocity, vegetation fractions, mortality, etc.) from DYCOVE simulations.

Parameters:

  • simdir (str or Path) – Path to the root simulation directory containing either a dflowfm/ directory (DFM) or a .sww model file (ANUGA).

  • quantity (str) – Quantity to plot. Must be one of the supported quantities listed below.

  • plot_times (dict[str, int]) –

    Dictionary of plot timing parameters with the following keys:

    • 'plotHR_0': Sim. hour to start plotting

    • 'plotHR_f': Sim. hour to end plotting

    • 'mapHR_int': Sim. hours between hydrodynamic model outputs

    • 'plotHR_int': Sim. hours between consecutive plots, cannot be less than map_output, unused if plotting vegetation.

  • plot_separate_species (bool, optional) – If True, vegetation quantities are plotted separately for each species (multi-species only). Vegetation fractions are plotted by species, rather than by cohort.

  • plot_method (str, optional) – 'interp' (default) for nearest-neighbor interpolation to a regular grid, or 'exact' for plotting on the original mesh nodes/cells (must be regular grid). NOT WORKING CURRENTLY.

  • plot_interp_vars (dict, optional) – Options for interpolating to 2D grid, see keys and details under __init__ below.

  • plot_specs (dict, optional) – Plot appearance options, e.g., see keys and details under __init__ below.

  • cmap_lims (dict, optional) – Colorbar limits for each quantity, see keys and details under __init__ below.

  • cmaps (dict, optional) – Colormaps for each quantity. Accepts Matplotlib Colormap objects. See keys and details under __init__ below.

  • quantity_units (dict, optional) – Unit labels, scaling factors, and minimum plotting thresholds for each quantity, see keys and details under __init__ below.

  • plot_vectors (bool, optional) – If True, plots normalized velocity vectors (quantity==”Velocity” only).

  • vector_props (dict, optional) – Scaling and spacing options for velocity vectors, used if quantity == “Velocity”, see keys and details under __init__ below.

  • show_title (bool, optional) – If True, include auto-generated plot title at top of plot.

  • show_topo_cbar (bool, optional) – If True, include elevation color bar on the left-hand side.

  • show_axis_ticks (bool, optional) – If True, axis ticks will be shown on left and bottom sides of image, in data units.

  • scalebar (bool, optional) – If True, include a scalebar object on the plot.

  • scalebar_props (dict, optional) – Scalebar properties, e.g., see keys and details under __init__ below.

  • mask_bndy_file (str or Path, optional) – Path to polygon CSV file for masking interpolation outside the domain. Probably required if model domain is not rectangular.

  • extents (tuple[float, float, float, float], optional) – Geographic extents for interpolation (xmin, xmax, ymin, ymax). Useful for zooming in on a particular location. NOTE: ymin and ymax are in MODEL coordinates, not numpy coordinates.

  • animate (bool, optional) – If True, creates an animated GIF after generating all plots. Requires imageio library.

  • delete_static_imgs (bool, optional) – If True, deletes individual PNGs after animation is built.

  • save_grids (bool, optional) – If True, saves interpolated grids (.npz) alongside figures. Can be helpful for external plotting of, say, difference maps, which are not supported here (yet).

  • names) (Supported Quantities (use exact)

  • -------------------------------------

  • quantities (DYCOVE)

  • 'Bathymetry' (-)

  • 'WSE' (-)

  • 'Depth' (-)

  • 'Velocity' (-)

  • Stress' (- 'Max Shear)

  • quantities

  • Height' (- 'Stem)

  • Diameter' (- 'Stem)

  • Density' (- 'Stem)

  • 'Fractions' (-)

  • Flooding' (- 'Mortality --)

  • Desiccation' (- 'Mortality --)

  • Uprooting' (- 'Mortality --)

  • Burial' (- 'Mortality --)

  • Scour' (- 'Mortality --)

  • Flooding'

  • Desiccation'

  • Uprooting'

  • Burial'

  • Scour'

  • Total' (- 'Mortality --)

Notes

  • All optional arguments have default values, but some dictionary arguments will almost definitely need to be changed or provided by the user, such as cmap_lims, for which appropriate values will depend on model data.

  • The class automatically detects the model type ('DFM' or 'ANUGA') based on directory contents.

  • Uses DFMMapLoader or ANUGAMapLoader for reading model-specific outputs.

  • Vegetation quantities (e.g. fractions, stem attributes, mortality) are handled differently than hydrodynamic quantities, using the ecofac time scaling factor.

  • Quantities that include 'Mortality' may be plotted either as potential (model-estimated stress exposure) or applied (post-threshold mortality) fields. See VegCohort documentation and mortality* methods of VegetationSpecies for details.

__init__(simdir, quantity, plot_times, plot_separate_species=True, plot_method='interp', plot_interp_vars: dict[str, int] | None = None, plot_specs: dict[str, Any] | None = None, cmap_lims: dict[str, tuple[float, float]] | None = None, cmaps: dict[str, Colormap] | None = None, quantity_units: dict[str, tuple[str, int | float]] | None = None, plot_vectors=False, vector_props: dict[str, Any] | None = None, show_title=True, show_topo_cbar=False, show_axis_ticks=False, scalebar=False, scalebar_props: dict[str, Any] | None = None, mask_bndy_file: Path | str | None = None, extents: tuple[float, float, float, float] | None = None, animate=False, delete_static_imgs=False, save_grids=False)[source]

Methods

__init__(simdir, quantity, plot_times[, ...])

check_inputs()

check_quantity_input()

check_time_inputs()

compute_stem_quantity_grid(frac, q)

create_gif()

create_grid(var)

create_interp_func(map_vars)

create_timestrings(i)

format_fname_time(time_parts)

format_title_time(time_parts)

get_eco_loop_indices()

get_eco_quantity_grids(map_vars)

get_eco_times(i)

get_exact_grid_idx(map_vars)

get_grid_coords(grid)

Return meshgrid coordinates in the same space as imshow extent

get_hydro_loop_indices()

get_hydro_quantity_grids(map_vars)

get_loop_indices()

get_map_indices(i)

get_model_name()

get_model_type()

get_modeldir()

get_quantity_grids(map_vars)

get_time_breakdown(i)

Returns a dict time components for formatting titles and filenames

imshow(ax, grid, cmap, vlims)

make_quiver(ax, grid)

make_scalebar(ax)

plot_quantity(base_grid, main_grid)

plot_single_quantity(base_grid, main_grid, ...)

read_assign_eco_vars()

run()

setup_model_loaders()

get_grid_coords(grid)[source]

Return meshgrid coordinates in the same space as imshow extent

get_time_breakdown(i)[source]

Returns a dict time components for formatting titles and filenames