Plots

Plots#

Hydrological_model_validator.Plotting.Plots.efficiency_plot(total_value, monthly_values, **kwargs)[source]#

Plot efficiency metric (e.g., NSE) for each month with color-coded markers.

Parameters:

  • total_value (float) – The efficiency value computed over the full time period (used as reference line).

  • monthly_values (list of float) – Efficiency values for each month (12 total).

Keyword Arguments:

  • output_path (str or Path) – Required. Directory where the figure is saved.

  • metric_name (str) – Required. Used for the filename (e.g., “NSE”).

  • title (str, optional) – Title of the plot (e.g., “Nash-Sutcliffe Efficiency”).

  • y_label (str, optional) – LaTeX-formatted y-axis label (e.g., “$E_{rel}$”).

  • figsize (tuple of float, optional) – Size of the figure in inches.

  • dpi (int, optional) – Resolution of the plot.

  • line_color (str, optional) – Color of the line connecting monthly points.

  • line_width (float, optional) – Width of the connecting line.

  • marker_size (float, optional) – Size of circular markers.

  • marker_edge_color (str, optional) – Color of marker edge.

  • marker_edge_width (float, optional) – Width of marker edge.

  • xtick_rotation (int, optional) – Degree of x-tick label rotation.

  • tick_width (float, optional) – Width of axis ticks.

  • spine_width (float, optional) – Width of axis spines.

  • legend_loc (str, optional) – Location of the legend.

  • grid_style (str, optional) – Style of grid lines (e.g., “–”, “:”).

  • zero_line (dict, optional) –

    Zero reference line options, keys:

    • show (bool)

    • style (str)

    • width (float)

    • color (str)

    • label (str)

  • overall_line (dict, optional) –

    Overall mean line options, keys:

    • style (str)

    • width (float)

    • color (str)

    • label (str)

Returns:

Saves the efficiency metric plot to the specified output directory.

Return type:

None

Example

>>> plot_efficiency_metric(
...     total_value=0.75,
...     monthly_values=[0.6, 0.7, 0.8, 0.7, 0.75, 0.76, 0.77, 0.78, 0.74, 0.72, 0.7, 0.69],
...     output_path='figures/',
...     metric_name='NSE',
...     title='Nash-Sutcliffe Efficiency',
...     y_label='$E_{rel}$',
...     figsize=(10, 6)
... )
Hydrological_model_validator.Plotting.Plots.error_components_timeseries(stats_df, output_path, cloud_cover=None, variable_name='', **kwargs)[source]#

Plot time series of error components and optional cloud cover.

Generates a multi-panel plot showing:

  • Mean Bias

  • Unbiased RMSE

  • Standard Deviation of Error

  • Correlation

  • (Optional) Cloud Cover with smoothed version

Parameters:

  • stats_df (pd.DataFrame) – DataFrame with time series of statistical error components. Must include columns: [‘mean_bias’, ‘unbiased_rmse’, ‘std_error’, ‘correlation’].

  • output_path (str or Path) – Directory path where the figure will be saved.

  • cloud_cover (pd.Series, optional) – Time series of cloud cover (%) data. Adds extra subplot if provided.

  • variable_name (str, optional) – Variable name (e.g., “SST”, “Chlorophyll”) used for labeling.

Keyword Arguments:

  • fig_width (float, optional) – Width of the full figure.

  • fig_height_per_plot (float, optional) – Height allocated per subplot.

  • sharex (bool, optional) – If True, subplots share the x-axis.

  • title_fontsize (int, optional) – Font size of the figure title.

  • title_fontweight (str, optional) – Font weight of the figure title.

  • label_fontsize (int, optional) – Font size of y-axis labels.

  • grid_color (str, optional) – Grid line color.

  • grid_linestyle (str, optional) – Grid line style (e.g., ‘–‘).

  • grid_alpha (float, optional) – Transparency of grid lines.

  • mean_bias_color (str, optional) – Line color for Mean Bias subplot.

  • unbiased_rmse_color (str, optional) – Line color for Unbiased RMSE subplot.

  • std_error_color (str, optional) – Line color for Std Error subplot.

  • correlation_color (str, optional) – Line color for Correlation subplot.

  • cloud_cover_color (str, optional) – Line color for raw Cloud Cover.

  • cloud_cover_smoothed_color (str, optional) – Line color for smoothed Cloud Cover.

  • cloud_cover_rolling_window (int, optional) – Window size for rolling smoothing of cloud cover.

  • spine_linewidth (float, optional) – Width of axes spines.

  • spine_edgecolor (str, optional) – Color of axes spines.

  • filename_template (str, optional) – Template for saved filename (e.g., ‘{}_errors.png’).

Returns:

Saves the multi-panel error component plot to the output path.

Return type:

None

Example

>>> error_components_timeseries(
...     stats_df=error_df,
...     cloud_cover=cloud_series,
...     output_path="figures/",
...     variable_name="SST"
... )

Notes

  • Uses Seaborn and Matplotlib styling.

  • Default styles and colors controlled by default_error_timeseries_options.

Hydrological_model_validator.Plotting.Plots.plot_spatial_efficiency(data_array, geo_coords, output_path, title_prefix, **kwargs)[source]#

Plot spatial efficiency metric maps (e.g., correlation, NSE) by month or year with Cartopy projection.

Generates a grid of spatial maps showing the spatial distribution of a performance metric (e.g., correlation, NSE) between model and satellite data for each month or year. Supports extensive customization via keyword arguments and a centralized defaults dictionary.

Parameters:

  • data_array (xarray.DataArray) – 3D data with shape (month/year, lat, lon). Must contain either a ‘month’ or ‘year’ dimension.

  • geo_coords (dict) –

    Dictionary containing geographic info:

    • latp (2D array): Latitude grid.

    • lonp (2D array): Longitude grid.

    • MinLambda, MaxLambda (float): Longitude bounds.

    • MinPhi, MaxPhi (float): Latitude bounds.

    • Epsilon (float, optional): Spatial padding offset for label adjustment.

  • output_path (str or Path) – Directory where the figure will be saved.

  • title_prefix (str) – Title prefix for colorbar and subplot titles (e.g., “Correlation”).

Keyword Arguments:

  • cmap (str or Colormap, optional) – Colormap to use (default: “coolwarm”).

  • vmin (float, optional) – Minimum value for colorbar.

  • vmax (float, optional) – Maximum value for colorbar.

  • suffix (str, optional) – Suffix for plot title and filename.

  • suptitle_fontsize (int, optional) – Font size of the super title (reduced by 6 if only one column).

  • suptitle_fontweight (str, optional) – Font weight of the super title.

  • suptitle_y (float, optional) – Vertical position of the super title.

  • title_fontsize (int, optional) – Font size of subplot titles.

  • title_fontweight (str, optional) – Font weight of subplot titles.

  • cbar_labelsize (int, optional) – Font size of colorbar tick labels.

  • cbar_labelpad (int, optional) – Padding between colorbar and label.

  • cbar_shrink (float, optional) – Shrink factor for horizontal colorbar.

  • cbar_ticks (int, optional) – Number of colorbar ticks.

  • figsize_per_plot (tuple, optional) – Size (width, height) per subplot.

  • max_cols (int, optional) – Maximum number of columns in subplot grid.

  • epsilon (float, optional) – Padding fallback if not in geo_coords.

  • lat_offset_base (float, optional) – Extra latitude offset if needed.

  • gridline_color (str, optional) – Color of gridlines.

  • gridline_style (str, optional) – Line style of gridlines (e.g., “–“).

  • gridline_alpha (float, optional) – Transparency of gridlines.

  • gridline_dms (bool, optional) – Format labels in degrees-minutes-seconds.

  • gridline_labels_top (bool, optional) – Show gridline labels on top axis.

  • gridline_labels_right (bool, optional) – Show gridline labels on right axis.

  • projection (str, optional) – Cartopy projection class name.

  • resolution (str, optional) – Resolution of coastlines (e.g., “10m”).

  • land_color (str, optional) – Color for landmasses.

  • show (bool, optional) – Display the plot interactively.

  • block (bool, optional) – Block execution on plt.show().

  • dpi (int, optional) – Resolution of the output figure.

Raises:

ValueError – If the data_array does not contain a ‘month’ or ‘year’ dimension.

Returns:

Saves the spatial efficiency maps to the specified output directory.

Return type:

None

Examples

>>> plot_spatial_efficiency(
...     data_array, geo_coords, "figures", "Correlation",
...     cmap="coolwarm", vmax=1.0, vmin=-1.0, show=True
... )
Hydrological_model_validator.Plotting.Plots.plot_spectral(data=None, plot_type='PSD', freqs=None, fft_components=None, error_comp=None, cloud_covers=None, output_path=None, variable_name=None, fs=1.0, nperseg=256, **kwargs)[source]#

Plot spectral analysis of time series data using either PSD or CSD.

Parameters:

  • data (pd.Series or dict, optional) – Optional time series input (not used directly in current implementation).

  • plot_type (str) – Type of spectral plot to generate: ‘PSD’ (Power Spectral Density) or ‘CSD’ (Cross Spectral Density).

  • freqs (array-like, optional) – Frequency values used for PSD plotting.

  • fft_components (dict of arrays, optional) – Dictionary mapping labels to FFT-transformed series for PSD plotting.

  • error_comp (pd.DataFrame or dict, optional) – Error component data used in CSD plotting.

  • cloud_covers (list of (pd.Series, str), optional) – List of tuples with cloud cover time series and their labels (used in CSD).

  • output_path (str or Path) – Path to save the resulting spectral plot.

  • variable_name (str) – Short code name of the variable, used in output filename.

  • fs (float, optional) – Sampling frequency (default: 1.0).

  • nperseg (int, optional) – Segment length for computing CSD (default: 256).

Keyword Arguments:

  • figsize (tuple, optional) – Figure size (e.g., (12, 6)).

  • xlabel_fontsize (int, optional) – Font size of the x-axis label.

  • ylabel_fontsize (int, optional) – Font size of the y-axis label.

  • title_fontsize (int, optional) – Font size of the plot title.

  • title_fontweight (str, optional) – Font weight of the plot title (e.g., ‘bold’).

  • tick_labelsize (int, optional) – Font size of tick labels.

  • grid_color (str, optional) – Grid line color.

  • grid_alpha (float, optional) – Grid line transparency.

  • grid_linestyle (str, optional) – Grid line style (e.g., ‘–‘).

  • freq_xlim (tuple, optional) – Frequency axis limits (e.g., (0.0, 0.5)).

  • additional_linestyles (list, optional) – Linestyles for multiple cloud cover series (e.g., [’–’, ‘-.’, ‘:’]).

  • spine_linewidth (float, optional) – Width of plot spines.

  • spine_edgecolor (str, optional) – Color of plot spines.

Raises:

ValueError – If required inputs are missing or an unknown plot_type is provided.

Hydrological_model_validator.Plotting.Plots.scatter_plot(data_dict: Dict[str, Series | list], **kwargs: Any) → None[source]#

Generate a scatter plot comparing daily mean values between model and satellite datasets.

This function creates a single scatter plot showing the relationship between model outputs and satellite observations. It also includes an identity line (y = x) for reference, allowing visual evaluation of model accuracy.

Parameters:

data_dict (Dict[str, Union[pd.Series, list]]) – Dictionary containing model and satellite data. Keys should correspond to model and satellite dataset names. Values must be 1D arrays or pandas Series.

Keyword Arguments:

  • output_path (str or Path) – Required. Directory to save figures.

  • variable_name (str) – Required. Variable code (e.g., ‘SST’).

  • BA (bool, optional) – Whether to append “(Basin Average)” to titles.

  • figsize (tuple of float, optional) – Figure size (width, height).

  • dpi (int, optional) – Figure resolution.

  • color (str, optional) – Scatter point color.

  • season_colors (dict, optional) – Map of season names to colors (for seasonal plots).

  • alpha (float, optional) – Transparency of scatter points.

  • marker_size (int, optional) – Size of scatter markers.

  • title_fontsize (int, optional) – Font size for plot titles.

  • label_fontsize (int, optional) – Font size for axis labels.

  • tick_labelsize (int, optional) – Size of tick labels.

  • line_width (float, optional) – Width of lines (identity, fits, axes).

  • legend_fontsize (int, optional) – Size of legend text.

  • variable (str, optional) – Long name of variable (used in title).

  • unit (str, optional) – Unit of variable (used in labels).

Example

>>> scatter_plot(
...     data_dict={'model': model_series, 'satellite': sat_series},
...     variable_name='SST',
...     output_path='figures/',
...     BA=True
... )
Hydrological_model_validator.Plotting.Plots.seasonal_scatter_plot(daily_means_dict: Dict[str, ndarray | Series], **kwargs: Any) → None[source]#

Generate seasonal scatter plots (DJF, MAM, JJA, SON) and a combined plot comparing model vs satellite daily mean values.

Each seasonal subplot shows:

  • Scatter comparison of model and satellite values.

  • Identity line (y = x).

  • Robust linear regression fit (Huber).

  • Nonparametric LOWESS fit.

The final composite plot displays all seasons together, color-coded with a shared legend.

Parameters:

daily_means_dict (Dict[str, Union[np.ndarray, pd.Series]]) – Dictionary with keys typically “mod” and “sat”, each containing 1D arrays or pandas Series of daily mean values. Assumes data starts from 2000-01-01 and is daily.

Keyword Arguments:

  • output_path (str or Path) – Required. Directory to save figures.

  • variable_name (str) – Required. Variable code (e.g., ‘SST’).

  • BA (bool, optional) – Whether to append “(Basin Average)” to titles.

  • figsize (tuple of int, optional) – Figure size (width, height).

  • dpi (int, optional) – Figure resolution.

  • season_colors (dict, optional) – Map of season names to colors. Default covers DJF, MAM, JJA, SON.

  • alpha (float, optional) – Transparency of scatter points.

  • marker_size (int, optional) – Size of scatter markers.

  • title_fontsize (int, optional) – Font size for plot titles.

  • label_fontsize (int, optional) – Font size for axis labels.

  • line_width (int, optional) – Width of lines (identity, fits, axes).

  • tick_labelsize (int, optional) – Size of tick labels.

  • legend_fontsize (int, optional) – Size of legend text.

  • variable (str, optional) – Long name of variable (used in titles).

  • unit (str, optional) – Unit of variable (used in labels).

Returns:

Saves each seasonal plot and one combined plot to the output path.

Return type:

None

Notes

  • Assumes data is continuous and aligned from 2000-01-01 onward.

  • Handles NaNs automatically during fitting and plotting.

  • Useful for visualizing seasonal agreement in long-term model or climate datasets.

Example

>>> seasonal_scatter_plot(
...     daily_means_dict={'mod': model_series, 'sat': sat_series},
...     variable_name='SST',
...     output_path='figures/',
...     BA=True
... )
Hydrological_model_validator.Plotting.Plots.timeseries(data_dict: Dict[str, Series | list], BIAS: Series | list | None, **kwargs: Any) → None[source]#

Plot time series of daily mean values from multiple datasets along with BIAS.

This function generates a two-panel time series plot:

  1. The upper subplot displays daily mean values of each dataset (typically model and satellite data).

  2. The lower subplot shows the BIAS (model - satellite) as a time series.

The figure is saved to a specified output directory as a PNG file and displayed using matplotlib.

Parameters:

  • data_dict (Dict[str, Union[pd.Series, list]]) – Dictionary containing daily mean values for different sources (e.g., model and satellite). Keys are strings identifying the data source. Values should be pandas.Series with datetime indices or lists convertible to Series.

  • BIAS (Union[pd.Series, list]) – Series (or list) representing the BIAS time series (typically model - satellite). Should be time-aligned with the values in data_dict.

Keyword Arguments:

  • output_path (str or Path) – Required. Path where the figure should be saved.

  • variable_name (str) – Required. Variable code name used to infer full name and unit.

  • variable (str, optional) – Full variable name (e.g., “Chlorophyll”). Used in titles and axis.

  • unit (str, optional) – Unit of measurement (e.g., “mg Chl/m³”). Displayed on axis.

  • BA (bool, optional) – If True, appends “ (Basin Average)” to the title.

  • figsize (tuple of float, optional) – Size of figure in inches (default typically (12, 8)).

  • dpi (int, optional) – Resolution of the figure (default 100).

  • color_palette (iterator, optional) – Iterator of colors (e.g., itertools.cycle(sns.color_palette(“tab10”))).

  • line_width (float, optional) – Width of plotted lines (default 2.0).

  • title_fontsize (int, optional) – Font size of the main title.

  • bias_title_fontsize (int, optional) – Font size of the BIAS subplot title.

  • label_fontsize (int, optional) – Font size of axis labels.

  • legend_fontsize (int, optional) – Font size of the legend.

  • savefig_kwargs (dict, optional) – Additional args for plt.savefig(), e.g., bbox_inches, transparent.

Example

>>> timeseries(
...     data_dict={'model': model_series, 'satellite': sat_series},
...     BIAS=model_series - sat_series,
...     variable_name='Chl',
...     output_path='figures/',
...     BA=True
... )

Notes

  • If variable or unit is not provided, the function attempts to resolve them using get_variable_label_unit(variable_name).

  • The data series are auto-converted to pandas.Series if passed as lists.

  • The order and coloring of plotted datasets depend on the order in data_dict and color_palette.

Hydrological_model_validator.Plotting.Plots.violinplot(data_dict, **kwargs)[source]#

Plot a violin plot comparing monthly model and satellite values.

Parameters:

data_dict (dict) – Dictionary containing model and satellite data indexed by datetime.

Keyword Arguments:

  • output_path (str or Path) – Required. Directory where the figure is saved.

  • variable_name (str) – Short name used to infer full variable name and unit.

  • variable (str, optional) – Full variable name (e.g., “Chlorophyll”). Used in the title.

  • unit (str, optional) – Unit of measurement (e.g., “mg Chl/m³”). Shown on the y-axis.

  • figsize (tuple of float, optional) – Size of the figure in inches.

  • dpi (int, optional) – Resolution of the plot.

  • palette (list or dict, optional) – Colors for the violin plots.

  • cut (float, optional) – Defines how far the violin extends past extreme datapoints.

  • title_fontsize (int, optional) – Font size of the title.

  • title_fontweight (str or int, optional) – Font weight of the title (e.g., ‘bold’).

  • ylabel_fontsize (int, optional) – Font size of the y-axis label.

  • xlabel_fontsize (int, optional) – Font size of the x-axis label.

  • xtick_rotation (int, optional) – Degree of x-tick label rotation.

  • tick_width (float, optional) – Width of axis ticks.

  • spine_linewidth (float, optional) – Line width for axis spines.

  • grid_alpha (float, optional) – Transparency of grid lines.

Returns:

Saves the violin plot figure to the specified output directory.

Return type:

None

Example

>>> violinplot(
...     data_dict={'model': model_series, 'satellite': sat_series},
...     variable_name='SST',
...     output_path='figures/',
...     figsize=(12, 6)
... )
Hydrological_model_validator.Plotting.Plots.whiskerbox(data_dict, **kwargs)[source]#

Create a boxplot comparing monthly values of model and satellite data.

This function plots side-by-side boxplots for each month, showing model vs satellite distributions. It’s useful for visualizing variability and central tendency over time.

Parameters:

data_dict (dict) – Dictionary containing time-series data for model and satellite. Keys must distinguish between model and satellite (e.g., ‘model’, ‘satellite’).

Keyword Arguments:

  • output_path (str or Path) – Required. Directory to save the resulting PNG plot.

  • variable_name (str) – Required. Variable short name (e.g., ‘SST’).

  • variable (str, optional) – Full variable name (e.g., ‘Sea Surface Temperature’).

  • unit (str, optional) – Unit of the variable (e.g., ‘°C’).

  • figsize (tuple of float, optional) – Figure size in inches, e.g., (14, 8).

  • dpi (int, optional) – Plot resolution in dots per inch.

  • palette (str or list, optional) – Seaborn-compatible color palette.

  • showfliers (bool, optional) – Whether to show outlier points in the boxplot.

  • title_fontsize (int, optional) – Font size of the plot title.

  • title_fontweight (str, optional) – Font weight of the plot title (e.g., ‘bold’).

  • ylabel_fontsize (int, optional) – Font size of the y-axis label.

  • xlabel (str, optional) – Label for the x-axis (default: ‘’).

  • grid_alpha (float, optional) – Transparency for grid lines.

  • xtick_rotation (int or float, optional) – Rotation angle for x-axis tick labels.

  • tick_width (float, optional) – Width of axis ticks.

Returns:

Saves the boxplot figure as a PNG file to the specified output directory.

Return type:

None

Example

>>> whiskerbox(
...     data_dict={'model': model_series, 'satellite': sat_series},
...     variable_name='Chl',
...     output_path='figures/',
...     figsize=(14, 8),
...     palette='Set2',
...     showfliers=False
... )
Contents