fusionlab.plot.forecast.forecast_view

fusionlab.plot.forecast.forecast_view(forecast_df, value_prefixes=None, kind='dual', view_quantiles=None, view_years=None, spatial_cols=None, time_col='coord_t', max_cols='auto', cmap='viridis', cbar='uniform', axis_off=False, show_grid=True, grid_props=None, figsize=None, savefig=None, save_fmts='.png', dt_col=None, show=True, cumulative=False, _logger=None, stop_check=None, verbose=1, **kws)[source]

Generates and displays spatial forecast visualizations.

This function creates a grid of scatter plots to visualize spatio-temporal forecast data. It can handle both long-format and wide-format DataFrames, automatically arranging plots by year and metric (e.g., different quantiles).

Parameters:

  • forecast_df (pd.DataFrame) – Input DataFrame containing forecast data. The function auto-detects if the format is long or wide.

  • value_prefixes (list of str, optional) – The base names of the metrics to plot (e.g., ['subsidence', 'GWL']). If None, the function will attempt to automatically infer these from the DataFrame’s column names. A separate figure is generated for each prefix.

  • kind ({'dual', 'pred_only'}, default 'dual') –

    Determines what to plot: - 'dual': Plots both actual values and predictions

    side-by-side for comparison, if actuals are available.

    • 'pred_only': Plots only the predicted values.

  • view_quantiles (list of str or float, optional) – A list to filter which quantiles are displayed. Values can be floats (e.g., [0.1, 0.5]) or strings (e.g., ['q10', 'q50']). If None, all detected quantiles are plotted.

  • view_years (list of str or int, optional) – A list of years to display. If None, all detected years in the forecast are plotted.

  • spatial_cols (tuple of str, default (``’coord_x’, ``'coord_y')) – A tuple containing the names of the columns to be used for the x and y axes of the scatter plots.

  • time_col (str, default 'coord_t') –

    The name of the column representing the time dimension in a long-format DataFrame. Used by the internal format detector.

    ..note::

    ’time_col’ and ‘dt_col’ can be used interchangeability.

  • max_cols (int or 'auto', default 'auto') –

    Controls the number of subplots per row. - If 'auto', the number of columns is automatically set

    to the number of quantiles being plotted (plus one if kind=’dual’).

    • If an integer, sets a fixed number of columns for the prediction plots. If kind=’dual’, an additional column for the actuals is added, potentially exceeding this number.

  • cmap (str, default 'viridis') – The Matplotlib colormap to use for the scatter plots.

  • cbar ({'uniform', 'individual'}, default 'uniform') –

    Controls the color bar scaling: - 'uniform': All subplots in a figure share a single,

    uniform color scale, determined by the global min/max of all plotted data. A single color bar is displayed for the entire figure.

    • 'individual': Each subplot has its own color bar scaled to its own data range. (Note: Current implementation defaults to uniform; individual color bars would be a future enhancement).

  • axis_off (bool, default False) – If True, turns off the axes (ticks, labels, spines) for all subplots.

  • show_grid (bool, default True) – If True and axis_off is False, a grid is displayed on the subplots.

  • grid_props (dict, optional) – A dictionary of properties to pass to ax.grid() (e.g., {'linestyle': ':', 'alpha': 0.7}).

  • figsize (tuple of (float, float), optional) – The size of the figure for each value_prefix. If None, the size is automatically calculated based on the number of rows and columns.

  • savefig (str, optional) – If a file path is provided (e.g., ‘my_forecast.png’), the figure(s) will be saved. The prefix name will be appended to the filename (e.g., ‘my_forecast_subsidence.png’).

  • save_fmts (str or list of str, default '.png') – The format(s) to save the figure in (e.g., ['.png', '.pdf']).

  • verbose (int, default 1) – Controls the verbosity of logging messages. 0 is silent, 1 provides basic info, and higher values provide more detail.

  • kws (dict,) – Keywords arguments for feature extensions.

  • dt_col (str | None)

  • show (bool)

  • cumulative (bool | str)

  • _logger (Logger | Callable[[str], None] | None)

  • stop_check (Callable[[], bool])

Returns:

This function does not return any value. It displays and/or saves Matplotlib figures directly.

Return type:

None

See also

format_forecast_dataframe

The utility used to detect and pivot the input DataFrame.

get_value_prefixes

The utility used to auto-detect metric prefixes.

Notes

  • The function creates a grid where each row corresponds to a year from view_years, and columns correspond to the actuals (if kind=’dual’) and each of the selected quantiles.

  • If an actual value for a specific year is not available, the function will attempt to fill that plot using the most recent known ‘actual’ value to facilitate comparison across the row.

  • Currently, a separate figure is generated for each prefix in value_prefixes.