fusionlab.plot.evaluation.plot_metric_over_horizon¶

fusionlab.plot.evaluation.plot_metric_over_horizon(forecast_df, target_name='target', metrics='mae', quantiles=None, output_dim=1, actual_col_pattern='{target_name}_actual', pred_col_pattern_point='{target_name}_pred', pred_col_pattern_quantile='{target_name}_q{quantile_int}', group_by_cols=None, plot_kind='bar', figsize_per_subplot=(7, 4.5), max_cols_metrics=2, scaler=None, scaler_feature_names=None, target_idx_in_scaler=None, sharey_metrics=False, verbose=0, **plot_kwargs)[source]¶

Plot one or several error metrics as a function of forecast step.

Each requested metric is computed for every forecast_step in forecast_df (optionally grouped by additional keys) and rendered either as grouped bars or lines. Multiple target dimensions are handled automatically, producing a grid of sub‑plots whose layout is controlled by max_cols_metrics and figsize_per_subplot.

The helper accepts both point‑forecast and quantile‑forecast frames exported by fusionlab.nn.utils.format_predictions_to_dataframe().

Parameters:

forecast_df (pandas.DataFrame) – Long‑format table of predictions. Must contain 'sample_idx' and 'forecast_step' plus the prediction, {segment_col}, and actual columns (for instance
target_name (str, default :class:``”target”:class:``)
metrics (str or list, default 'mae') – One metric or a list of metrics to compute. Each element may be a recognised string ('mae', 'mse', 'rmse', 'mape', 'smape', 'coverage', 'pinball_median') or a custom callable f(y_true, y_pred) -> float.
quantiles (list[float], optional) – Quantiles included in forecast_df (e.g. [0.1, 0.5, 0.9]). If present and a generic metric is chosen the median (0.5 or nearest) prediction is employed as y_pred.
output_dim (int, default 1) – Number of target dimensions. A separate radar is generated
group_by_cols (list[str], optional) – Extra columns to group by before computing the metric (e.g. ['country', 'model_version']). When supplied, separate series are drawn for each group.
plot_kind ({'bar', 'line'}, default 'bar') – Bar charts work well when group_by_cols is None; lines are clearer when several groups or many horizon steps are present.
figsize_per_subplot (tuple, default (7, `:class:`4.5)) – Width × height (in inch) of every individual metric panel.
max_cols_metrics (int, default 2) – Maximum number of metric panels per row.
scaler (Any, optional) – Fitted scikit‑learn‑style transformer used to inverse‑scale data
scaler_feature_names (list[str], optional) – Full feature order that scaler was trained on.
target_idx_in_scaler (int, optional) – Position of target_name inside scaler_feature_names.
sharey_metrics (bool, default False) – If True, all panels in the same row share the y‑axis scale.
verbose (int, default 0)
**plot_kwargs (Any) – Extra arguments forwarded to the underlying Matplotlib ax.plot / ax.fill calls (e.g. color, linewidth,
actual_col_pattern (str)
pred_col_pattern_point (str)
pred_col_pattern_quantile (str)

Returns:

Generates Matplotlib figures and shows them.

Return type:

None

Raises:

ValueError – If mandatory columns are missing, an unknown metric string is supplied, or scaling information is incomplete.
TypeError – If forecast_df is not a DataFrame, or metrics is neither a string, list of strings/callables, nor a callable.

Notes

When quantiles are supplied a point‑style metric (e.g. 'mae') is computed on the median quantile. Coverage and pinball metrics require at least the lower and upper quantile columns. For grouped plots consider setting plot_kind=’line’ for readability.

Examples

>>> from fusionlab.nn.utils import format_predictions_to_dataframe
>>> from fusionlab.plot.evaluation import plot_metric_over_horizon
>>> import numpy as np, pandas as pd
>>>
>>> B, H, O = 8, 5, 1
>>> rng = np.random.default_rng(42)
>>> preds = rng.normal(size=(B, H, O))
>>> y_true = preds + rng.normal(scale=.3, size=(B, H, O))
>>> df_pred = format_predictions_to_dataframe(
...     preds, y_true, target_name="temp",
...     forecast_horizon=H, output_dim=O
... )
>>>
>>> # add a grouping column
>>> df_pred["city"] = rng.choice(["NY", "SF"], size=len(df_pred))
>>>
>>> plot_metric_over_horizon(
...     forecast_df=df_pred,
...     target_name="temp",
...     metrics=["mae", "rmse"],
...     group_by_cols=["city"],
...     plot_kind="line",
...     verbose=1
... )