fusionlab.plot.forecast.visualize_forecasts¶

fusionlab.plot.forecast.visualize_forecasts(forecast_df, dt_col, tname, test_data=None, eval_periods=None, mode='quantile', kind='spatial', actual_name=None, x=None, y=None, cmap='coolwarm', max_cols=3, axis='on', s=2, show_grid=True, grid_props=None, savefig=None, save_fmts=None, verbose=1, **kw)[source]¶

Visualize forecast results and actual test data for one or more evaluation periods.

The function plots a grid of scatter plots comparing actual values with forecasted predictions. Each evaluation period yields two plots: one for actual values and one for predicted values. If multiple evaluation periods are provided, the grid layout wraps after max_cols columns.

\[\hat{y}_{t+i} = f\Bigl( X_{\text{static}},\;X_{\text{dynamic}},\; X_{\text{future}}\Bigr)\]

for \(i = 1, \dots, N\), where \(N\) is the forecast horizon.

Parameters:

forecast_df (pandas.DataFrame) – DataFrame containing forecast results with a time column, spatial coordinates, and prediction columns.
dt_col (str) – Name of the time column used to filter forecast results (e.g. "year").
tname (str) – Target variable name used to construct forecast columns (e.g. "subsidence"). This argument is required.

eval_periodsscalar or list, optional: Evaluation period(s) used to select forecast results. If set to None, the function selects up to three unique periods from test_data[dt_col].
modestr, optional: Forecast mode. Must be either "quantile" or "point". Default is "quantile".
kindstr, optional: Type of visualization. If "spatial", spatial columns are required; otherwise, the provided x and y columns are used.
xstr, optional: Column name for the x-axis. For non-spatial plots, this must be provided or will be inferred via assert_xy_in.
ystr, optional: Column name for the y-axis. For non-spatial plots, this must be provided or will be inferred via assert_xy_in.
cmapstr, optional: Colormap used for scatter plots. Default is "coolwarm".
max_colsint, optional: Maximum number of evaluation periods to plot per row. If the number of periods exceeds max_cols, a new row is started.
axis: str, optional,: Wether to keep the axis of set it to False.
show_grid: bool, default=True,: Visualize the grid
grid_props: dict, optional: Grid properties for visualizations. If none the properties is infered as {"linestyle":":", 'alpha':0.7}.
verboseint, optional: Verbosity level. Controls the amount of output printed.

Returns:: The function displays the visualization plot.
Return type:: None

Examples

Example 1: Spatial Visualization

In this example, we visualize the forecasted and actual values of the subsidence target variable, using longitude and latitude for the spatial coordinates. We visualize the results for two evaluation periods (2023 and 2024), using quantile mode for the forecast.

>>> from fusionlab.plot.forecast import visualize_forecasts
>>> forecast_results = pd.DataFrame({
>>>     'longitude': [-103.808151, -103.808151, -103.808151],
>>>     'latitude': [0.473152, 0.473152, 0.473152],
>>>     'subsidence_q50': [0.3, 0.4, 0.5],
>>>     'subsidence': [0.35, 0.42, 0.49],
>>>     'date': ['2023-01-01', '2023-01-02', '2023-01-03']
>>> })
>>> test_data = pd.DataFrame({
>>>     'longitude': [-103.808151, -103.808151, -103.808151],
>>>     'latitude': [0.473152, 0.473152, 0.473152],
>>>     'subsidence': [0.35, 0.41, 0.49],
>>>     'date': ['2023-01-01', '2023-01-02', '2023-01-03']
>>> })
>>> visualize_forecasts(
>>>     forecast_df=forecast_results,
>>>     test_data=test_data,
>>>     dt_col="date",
>>>     tname="subsidence",
>>>     eval_periods=[2023, 2024],
>>>     mode="quantile",
>>>     kind="spatial",
>>>     cmap="coolwarm",
>>>     max_cols=2,
>>>     verbose=1
>>> )

Example 2: Non-Spatial Visualization

In this example, we visualize the forecasted and actual values of the subsidence target variable in a non-spatial context. The columns longitude and latitude are still provided but used for non-spatial x and y axes. Evaluation is for 2023.

>>> from fusionlab.plot.forecast import visualize_forecasts
>>> forecast_results = pd.DataFrame({
>>>     'longitude': [-103.808151, -103.808151, -103.808151],
>>>     'latitude': [0.473152, 0.473152, 0.473152],
>>>     'subsidence_pred': [0.35, 0.41, 0.48],
>>>     'subsidence': [0.36, 0.43, 0.49],
>>>     'date': ['2023-01-01', '2023-01-02', '2023-01-03']
>>> })
>>> test_data = pd.DataFrame({
>>>     'longitude': [-103.808151, -103.808151, -103.808151],
>>>     'latitude': [0.473152, 0.473152, 0.473152],
>>>     'subsidence': [0.36, 0.42, 0.50],
>>>     'date': ['2023-01-01', '2023-01-02', '2023-01-03']
>>> })
>>> forecast_df_point = visualize_forecasts(
>>>     forecast_df=forecast_results,
>>>     test_data=test_data,
>>>     dt_col="date",
>>>     tname="subsidence",
>>>     eval_periods=[2023],
>>>     mode="point",
>>>     kind="non-spatial",
>>>     x="longitude",
>>>     y="latitude",
>>>     cmap="viridis",
>>>     max_cols=1,
>>>     axis="off",
>>>     show_grid=True,
>>>     grid_props={"linestyle": "--", "alpha": 0.5},
>>>     verbose=2
>>> )

Notes

In quantile mode, the function uses the column <tname>_q50 for visualization.
In point mode, the column <tname>_pred is used.
For spatial visualizations, if x and y are not provided, they default to "longitude" and "latitude".
The evaluation period(s) are determined by filtering forecast_df[dt_col] == <eval_period>.
Use assert_xy_in to validate that the x and y columns exist in the provided DataFrames.