Visualizing Forecasts with K-Diagram

fusionlab-learn focuses on generating robust time series forecasts. To gain deeper insights into these forecasts, especially regarding uncertainty and model behavior over time or across different segments, the k-diagram library offers a suite of specialized polar visualizations.

This guide demonstrates how to use k-diagram (accessed via fusionlab.kdiagram if installed as an extra) with the outputs generated by fusionlab-learn models. Predictions are typically formatted into a pandas DataFrame using utilities like format_predictions_to_dataframe().

Prerequisites:

Ensure fusionlab-learn is installed with the kdiagram extra, which will also install the k-diagram package and matplotlib:

pip install fusionlab-learn[k-diagram]

If you have fusionlab-learn already and only need k-diagram:

pip install k-diagram matplotlib

Preparing Forecast Data for K-Diagram

Most k-diagram plotting functions expect a pandas DataFrame. After training a fusionlab-learn model (e.g., XTFT or TemporalFusionTransformer) and generating predictions, you would typically use format_predictions_to_dataframe() to structure your forecasts.

Let’s assume you have a forecast_df from this utility. For point forecasts, it might have columns like sample_idx, forecast_step, my_target_actual, my_target_pred. For quantile forecasts, it might have my_target_q10, my_target_q50, my_target_q90, in addition to actuals.

The following examples will simulate such DataFrames and then use fusionlab.kdiagram for visualization.

Example 1: Actual vs. Predicted Plot

The plot_actual_vs_predicted() function provides a polar scatter plot comparing actual values against model predictions. This can help identify systematic biases or how prediction errors are distributed.

Scenario: Imagine you have point forecasts from a fusionlab-learn model.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import os

# Import kdiagram via fusionlab's proxy
import fusionlab.kdiagram as fkd
# If kdiagram was installed separately, you could also do:
# import kdiagram as kd

# Ensure output directory for images exists relative to where script is run
# For Sphinx, paths in .. figure:: are relative to the .rst file
output_image_dir = "docs/source/images" # Adjust if script runs from project root
os.makedirs(output_image_dir, exist_ok=True)

# --- Simulate a forecast_df from fusionlab ---
np.random.seed(42)
num_forecast_points = 150
actual_values = 50 + 10 * np.sin(
    np.linspace(0, 5 * np.pi, num_forecast_points)
    ) + np.random.normal(0, 5, num_forecast_points)
predicted_values = actual_values * 0.9 + \
                   np.random.normal(0, 4, num_forecast_points) + 5

forecast_eval_df = pd.DataFrame({
    'sales_actual': actual_values,
    'sales_pred': predicted_values,
    'time_index': np.arange(num_forecast_points)
})
print("Sample of DataFrame for Actual vs. Predicted plot:")
print(forecast_eval_df.head())

# --- Plotting with fusionlab.kdiagram ---
# Note: kdiagram functions are accessed via fusionlab.kdiagram
# if the proxy is set up correctly and k-diagram is installed.
try:
    kd.plot.plot_actual_vs_predicted(
        df=forecast_eval_df,
        actual_col='sales_actual',
        pred_col='sales_pred',
        title='FusionLab & K-Diagram: Actual vs. Predicted Sales',
        line=False,  # Use dots for this example
        r_label="Sales Value",
        actual_props={
            'marker': '.', 's': 50, 'alpha': 0.7,
            'color': '#007acc'     # Blue
        },
        pred_props={
            'marker': '+', 's': 60, 'alpha': 0.8,
            'color': '#e85e00'     # Valid orange hex
        },
        savefig=os.path.join(
            output_image_dir,
            "fusionlab_kdiag_actual_vs_pred.png"
        )
    )
    #plt.close()
    print(
        f"Plot saved to "
        f"{output_image_dir}/fusionlab_kdiag_actual_vs_pred.png"
    )
except ImportError as e:
    print(f"K-Diagram not available through fusionlab.kdiagram: {e}")
except Exception as e:
    print(f"An error occurred during plotting: {e}")

Expected Output & Plot 1:

Sample of DataFrame for Actual vs. Predicted plot:
   sales_actual  sales_pred  time_index
0     52.483571   53.237185           0
1     50.360953   51.710650           1
2     55.331307   52.078077           2
3     60.725365   60.581843           3
4     52.922266   53.802329           4
...
Plot saved to docs/source/images/fusionlab_kdiag_actual_vs_pred.png

Polar plot comparing actual sales to FusionLab model predictions, visualized using k-diagram via fusionlab.kdiagram.

Example 2: Coverage Diagnostic Plot

For quantile forecasts, plot_coverage_diagnostic() visualizes whether the actual values fall within the predicted uncertainty intervals.

Scenario: You have quantile forecasts (e.g., q10, q50, q90) from a fusionlab-learn model.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import os
import fusionlab.kdiagram as fkd

# output_image_dir defined in previous cell

# --- Simulate a forecast_df with quantiles ---
np.random.seed(88)
num_forecast_points = 200
actual_values_q = np.random.normal(loc=30, scale=5, size=num_forecast_points)
q10_values = actual_values_q - np.random.uniform(2, 6, num_forecast_points)
q50_values = actual_values_q + np.random.normal(0, 1, num_forecast_points)
q90_values = actual_values_q + np.random.uniform(2, 6, num_forecast_points)
actual_values_q[::20] = q90_values[::20] + 2
actual_values_q[::25] = q10_values[::25] - 2

forecast_quant_df = pd.DataFrame({
    'demand_actual': actual_values_q,
    'demand_q10': q10_values,
    'demand_q50': q50_values,
    'demand_q90': q90_values
})
print("\nSample of DataFrame for Coverage Diagnostic plot:")
print(forecast_quant_df.head())

# --- Plotting with fusionlab.kdiagram ---
try:
    fkd.plot.plot_coverage_diagnostic(
        df=forecast_quant_df,
        actual_col='demand_actual',
        q_cols=['demand_q10', 'demand_q90'],
        title='FusionLab & K-Diagram: Interval Coverage (Q10-Q90)',
        as_bars=True, # Use bars for this example
        fill_gradient=True,
        coverage_line_color='purple', # Changed color
        bar_props={'alpha': 0.7},
        verbose=0,
        savefig=os.path.join(output_image_dir, "fusionlab_kdiag_coverage.png")
    )
    plt.close()
    print(f"Plot saved to {output_image_dir}/fusionlab_kdiag_coverage.png")
except ImportError as e:
    print(f"K-Diagram not available through fusionlab.kdiagram: {e}")
except Exception as e:
    print(f"An error occurred during plotting: {e}")

Expected Output & Plot 2:

Sample of DataFrame for Coverage Diagnostic plot:
   demand_actual  demand_q10  demand_q50  demand_q90
0      33.003098   29.332539   32.480096   35.169899
1      26.928811   23.406621   27.742191   28.759837
...
Plot saved to docs/source/images/fusionlab_kdiag_coverage.png

Point-wise coverage diagnostic for FusionLab quantile forecasts, visualized using k-diagram via fusionlab.kdiagram.

Example 3: Model Drift Plot

plot_model_drift() helps visualize if prediction interval characteristics change across different forecast horizons or segments.

Scenario: Data is in a wide format where each horizon’s quantiles are columns.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import os
import fusionlab.kdiagram as fkd

# output_image_dir defined previously

np.random.seed(0)
horizons_labels = ['H_Step1', 'H_Step2', 'H_Step3', 'H_Step4']
num_samples_drift = 50
df_drift = pd.DataFrame()
q10_cols_drift, q90_cols_drift = [], []

for i, hor_label in enumerate(horizons_labels):
    q10_colname = f'pred_{hor_label}_q10'
    q90_colname = f'pred_{hor_label}_q90'
    q10_cols_drift.append(q10_colname)
    q90_cols_drift.append(q90_colname)
    q10_vals = np.random.rand(num_samples_drift) * 5 + i * 0.7
    q90_vals = q10_vals + np.random.rand(num_samples_drift) * 2.5 + 1.5 + i * 1.0
    df_drift[q10_colname] = q10_vals
    df_drift[q90_colname] = q90_vals

print("\nSample of DataFrame for Model Drift plot:")
print(df_drift.head(2))

try:
    fkd.plot.plot_model_drift(
        df=df_drift,
        q10_cols=q10_cols_drift,
        q90_cols=q90_cols_drift,
        horizons=horizons_labels,
        acov='semi_circle', # Changed angular coverage
        title='FusionLab & K-Diagram: Interval Drift',
        cmap='plasma', # Changed colormap
        savefig=os.path.join(output_image_dir, "fusionlab_kdiag_model_drift.png")
    )
    plt.close()
    print(f"Plot saved to {output_image_dir}/fusionlab_kdiag_model_drift.png")
except ImportError as e:
    print(f"K-Diagram not available through fusionlab.kdiagram: {e}")
except Exception as e:
    print(f"An error occurred during plotting: {e}")

Expected Output & Plot 3:

Sample of DataFrame for Model Drift plot:
   pred_H_Step1_q10  pred_H_Step1_q90  pred_H_Step2_q10  pred_H_Step2_q90
0          2.744068          6.988482          3.907212          9.010952
1          3.575947          6.010909          4.975008          8.061101
Plot saved to docs/source/images/fusionlab_kdiag_model_drift.png

Visualization of prediction interval drift across forecast horizons, using k-diagram via fusionlab.kdiagram.

Example 4: Prediction Velocity Plot

plot_velocity() visualizes the rate and direction of change in predictions across consecutive horizons.

Scenario: Data is wide, with median forecasts for different horizons as columns.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import os
import fusionlab.kdiagram as fkd

# output_image_dir defined previously

np.random.seed(123)
num_points_vel = 100
horizon_labels_vel = ['Forecast_H1', 'Forecast_H2', 'Forecast_H3', 'Forecast_H4']
df_velocity = pd.DataFrame({'sample_id': range(num_points_vel)})
base_value_vel = np.random.rand(num_points_vel) * 20
trend_vel = np.linspace(0, 3, num_points_vel)

for i, hor_label in enumerate(horizon_labels_vel):
    noise_vel = np.random.randn(num_points_vel) * 0.8
    df_velocity[hor_label] = base_value_vel + trend_vel * (i + 1) + noise_vel
print("\nSample of DataFrame for Velocity plot:")
print(df_velocity.head(2))

try:
    fkd.plot.plot_velocity(
        df=df_velocity,
        q50_cols=horizon_labels_vel, # List of median forecast columns
        title='FusionLab & K-Diagram: Prediction Velocity',
        use_abs_color=True, # Color by magnitude
        normalize=True,
        cmap='magma', # Changed colormap
        cbar=True,
        s=35, # Marker size
        savefig=os.path.join(output_image_dir, "fusionlab_kdiag_velocity.png")
    )
    plt.close()
    print(f"Plot saved to {output_image_dir}/fusionlab_kdiag_velocity.png")
except ImportError as e:
    print(f"K-Diagram not available through fusionlab.kdiagram: {e}")
except Exception as e:
    print(f"An error occurred during plotting: {e}")

Expected Output & Plot 4:

Sample of DataFrame for Velocity plot:
   sample_id  Forecast_H1  Forecast_H2  Forecast_H3  Forecast_H4
0          0     0.592269     1.467803     2.614264     2.931038
1          1     8.900599     9.887309     9.900808     9.969413
Plot saved to docs/source/images/fusionlab_kdiag_velocity.png

Visualization of prediction velocity using k-diagram via fusionlab.kdiagram.

Example 5: Taylor Diagram for Model Comparison

plot_taylor_diagram_in() summarizes model performance against reference values.

Scenario: Comparing point predictions from two fusionlab-learn models.

import numpy as np
import matplotlib.pyplot as plt
import os
# Import directly from fusionlab.kdiagram.plot.evaluation
from fusionlab.kdiagram.plot import evaluation as fl_kde

# output_image_dir defined previously

np.random.seed(42)
reference_actuals = np.random.normal(10, 2, 100)
preds_model_A = reference_actuals * 0.85 + np.random.normal(0, 0.8, 100)
preds_model_B = reference_actuals * 0.6 + np.random.normal(0, 1.5, 100) + 1
model_names = ['FusionLab_Model_A', 'FusionLab_Model_B']

try:
    fl_kde.plot_taylor_diagram_in(
        preds_model_A, preds_model_B,
        reference=reference_actuals,
        names=model_names,
        acov='half_circle', # Changed angular coverage
        zero_location='N',
        direction=1,
        fig_size=(7.5, 7.5), # Slightly different size
        cmap='RdYlBu', # Different colormap
        radial_strategy='rmse', # Color by RMSE
        title='FusionLab & K-Diagram: Taylor Diagram Comparison',
        savefig=os.path.join(output_image_dir, "fusionlab_kdiag_taylor.png")
    )
    plt.close()
    print(f"\nPlot saved to {output_image_dir}/fusionlab_kdiag_taylor.png")
except ImportError as e:
    print(f"K-Diagram (or its submodule) not available through fusionlab.kdiagram: {e}")
except Exception as e:
    print(f"An error occurred during plotting: {e}")

Expected Output & Plot 5:

Plot saved to docs/source/images/fusionlab_kdiag_taylor.png

Taylor diagram comparing FusionLab models, visualized using k-diagram via fusionlab.kdiagram.

This guide provides a starting point for using k-diagram with fusionlab-learn. Explore the k-diagram documentation for more customization options and advanced features to further enhance your forecast evaluation and communication.