Inventory Forecasting - Synthefy Docs

What is inventory forecasting? How does it help?

Problem: Retailers struggle to predict demand accurately, especially when external factors like weather dramatically impact sales. Traditional forecasting methods may ignore these contextual signals, leading to stockouts during high-demand periods or excess inventory during low-demand periods. Our approach: Incorporate weather data as context, and demonstrate conditional forecasting to discover which items sell together. Outcome: Our models achieve significantly lower error rates by incorporating weather data, and further analysis reveals which products move together, which can enable strategic decisions like complementary product placement and targeted promotions.

Prerequisites

First, install the required libraries:

pip install synthefy matplotlib numpy pandas swarm-visualizer

1. Load and Prepare Data

We’ll use a real-world dataset from a Chicago store that tracks sales for multiple products along with daily weather conditions. This rich dataset allows us to compare simple time-series forecasting against forecasts that incorporate weather data.

import os
from typing import Dict, Any

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import swarm_visualizer
from swarm_visualizer.utility import set_axis_infos
from synthefy import SynthefyAPIClient

# Configuration
TIMESTAMP_COL = "date"
GROUP_COL = "item_name"
TARGET_COL = "sales"
METADATA_COLS = [
    "temperature",
    "humidity",
    "wind_speed",
    "cloud_cover",
    "precipitation",
]

# Initialize API client
API_CLIENT = SynthefyAPIClient(api_key="YOUR_API_KEY")

# Load the Chicago store sales dataset
data_df = pd.read_csv(
    "https://drive.google.com/uc?export=download&id=1YcAFpFzcZgX0elekB_vdWrzTzEMbGzuD"
)

# Convert date column to datetime
data_df[TIMESTAMP_COL] = pd.to_datetime(data_df[TIMESTAMP_COL])

# Sort by date
data_df = data_df.sort_values(TIMESTAMP_COL).reset_index(drop=True)


# ============================================================================
# HELPER FUNCTIONS
# ============================================================================

def format_item_name(item_name: str) -> str:
    """Format item name professionally by replacing underscores with spaces and applying title case."""
    return item_name.replace("_", " ").title()

2. Visualize Historical Sales Patterns

Before running forecasts, let’s visualize the historical sales data to understand patterns and seasonality for each product. We’ll create time series plots showing how sales vary over time.

Show plotting code for historical sales

def plot_historical_sales(data_df: pd.DataFrame) -> None:
    """Create separate subplots for each item's sales over time using swarm-visualizer."""
    items = data_df[GROUP_COL].unique()


    # Create subplots - 4x1 vertical layout for 4 items
    fig, axes = plt.subplots(4, 1, figsize=(14, 16))
    axes = axes.flatten()  # Flatten to 1D array for easier indexing

    # Plot each item in its own subplot
    for idx, item in enumerate(items):
        if idx >= 4:  # Only plot first 4 items
            break

        ax = axes[idx]

        # Filter data for this item
        item_data = data_df[data_df[GROUP_COL] == item].sort_values(TIMESTAMP_COL)

        # Plot only last 50% of history
        history_cutoff = len(item_data) // 2
        item_data_subset = item_data.iloc[history_cutoff:]

        # Prepare data for swarm-visualizer
        normalized_dict = {
            f"{format_item_name(item)} Sales": {
                "x": item_data_subset[TIMESTAMP_COL][::2],
                "y": item_data_subset[TARGET_COL][::2],
                "lw": 2.5,
                "linestyle": "-",
                "color": "black",
                "alpha": 0.8,
            }
        }

        # Use swarm-visualizer plot_overlaid_lineplot
        swarm_visualizer.plot_overlaid_lineplot(
            ax=ax,
            normalized_dict=normalized_dict,
            title_str=f"{format_item_name(item)} Daily Sales",
            ylabel="Sales",
            xlabel="Date",
            legend_present=False,
        )

        # Use swarm-visualizer set_axis_infos for consistent styling
        set_axis_infos(
            ax=ax,
            xlabel="Date",
            ylabel="Sales",
            title_str=f"{format_item_name(item)} Daily Sales",
            grid=True,
        )
        plt.setp(ax.get_xticklabels(), rotation=45, ha="right")

    # Hide unused subplots if there are fewer than 4 items
    for idx in range(len(items), 4):
        axes[idx].set_visible(False)

    # Overall title
    fig.suptitle(
        "Historical Daily Sales by Product",
        fontsize=24,
        fontweight="bold",
        y=0.99,
    )

    plt.tight_layout()
    # Create directory if it doesn't exist
    os.makedirs("inventory_forecasting_plots", exist_ok=True)
    filepath = os.path.abspath(
        "inventory_forecasting_plots/historical_sales_overview.png"
    )
    plt.savefig(filepath, dpi=300, bbox_inches="tight")
    plt.close()
    print(f"✓ Saved: {filepath}")


def plot_sales_with_weather(data_df: pd.DataFrame) -> None:
    """Create separate subplots for each item's sales with temperature overlay using swarm-visualizer."""
    items = data_df[GROUP_COL].unique()

    # Create subplots - 4x1 vertical layout for 4 items
    fig, axes = plt.subplots(4, 1, figsize=(14, 16))
    axes = axes.flatten()  # Flatten to 1D array for easier indexing

    # Get overall temperature (from unique timestamps) - last 50% only
    weather_data = data_df.drop_duplicates(TIMESTAMP_COL).sort_values(TIMESTAMP_COL)
    weather_cutoff = len(weather_data) // 2
    weather_data = weather_data.iloc[weather_cutoff:]

    # Plot each item in its own subplot with temperature
    for idx, item in enumerate(items):
        if idx >= 4:  # Only plot first 4 items
            break

        ax = axes[idx]

        # Filter data for this item
        item_data = data_df[data_df[GROUP_COL] == item].sort_values(TIMESTAMP_COL)

        # Plot only last 50% of history
        history_cutoff = len(item_data) // 2
        item_data_subset = item_data.iloc[history_cutoff:]

        # Prepare data for swarm-visualizer with both sales and temperature
        normalized_dict = {
            f"{format_item_name(item)} Sales": {
                "x": item_data_subset[TIMESTAMP_COL][::2],
                "y": item_data_subset[TARGET_COL][::2],
                "lw": 2.5,
                "linestyle": "-",
                "color": "black",
                "alpha": 0.8,
            },
            "Temperature": {
                "x": weather_data[TIMESTAMP_COL][::2],
                "y": weather_data["temperature"][::2],
                "lw": 2,
                "linestyle": "--",
                "color": "black",
                "alpha": 0.5,
            }
        }

        # Use swarm-visualizer plot_overlaid_lineplot
        swarm_visualizer.plot_overlaid_lineplot(
            ax=ax,
            normalized_dict=normalized_dict,
            title_str=f"{format_item_name(item)} Daily Sales and Temperature",
            ylabel="Sales / Temperature (°F)",
            xlabel="Date",
            legend_present=True,
        )

        # Move legend to the right side
        ax.legend(loc="center left", bbox_to_anchor=(1, 0.5))

        # Use swarm-visualizer set_axis_infos for consistent styling
        set_axis_infos(
            ax=ax,
            xlabel="Date",
            ylabel="Sales / Temperature (°F)",
            title_str=f"{format_item_name(item)} Daily Sales and Temperature",
            grid=True,
        )
        plt.setp(ax.get_xticklabels(), rotation=45, ha="right")

    # Hide unused subplots if there are fewer than 4 items
    for idx in range(len(items), 4):
        axes[idx].set_visible(False)

    # Overall title
    fig.suptitle(
        "Daily Sales and Temperature by Product",
        fontsize=24,
        fontweight="bold",
        y=0.99,
    )

    plt.tight_layout()
    # Create directory if it doesn't exist
    os.makedirs("inventory_forecasting_plots", exist_ok=True)
    filepath = os.path.abspath(
        "inventory_forecasting_plots/sales_and_weather.png"
    )
    plt.savefig(filepath, dpi=300, bbox_inches="tight")
    plt.close()
    print(f"✓ Saved: {filepath}")


# Generate the visualizations
plot_historical_sales(data_df)
plot_sales_with_weather(data_df)

These visualizations help you understand:

Sales trends: Are there seasonal patterns or trends over time?
Weather impact: How does temperature correlate with sales?
Product differences: Do different products show different sensitivities to temperature?

Historical Sales Overview

Historical Sales and Temperature

This dual-axis plot reveals the relationship between sales and temperature:

Solid colored lines: Sales for each product
Dashed red line: Temperature overlay to show how weather affects demand

3. Split Data and Run Forecasts

We’ll split the data and forecast the last 20% of the data to compare univariate vs multivariate forecasting approaches.

def forecast_item(data_df: pd.DataFrame, item_name: str, history_ratio: float = 0.8) -> Dict[str, Any]:
    """Compare univariate vs multivariate forecasting for a single item."""
    # Split data
    item_data = data_df[data_df[GROUP_COL] == item_name].sort_values(TIMESTAMP_COL)
    split_idx = int(len(item_data) * history_ratio)
    history_df = item_data.iloc[:split_idx].copy()
    target_df = item_data.iloc[split_idx:].copy()

    # Univariate forecast (time series only)
    univariate_forecast = API_CLIENT.forecast_dfs(
        history_dfs=[history_df],
        target_dfs=[target_df],
        target_col=TARGET_COL,
        timestamp_col=TIMESTAMP_COL,
        metadata_cols=[],
        leak_cols=[],
        model="Migas-1.0",
    )

    # Multivariate forecast (time series + weather)
    multivariate_forecast = API_CLIENT.forecast_dfs(
        history_dfs=[history_df],
        target_dfs=[target_df],
        target_col=TARGET_COL,
        timestamp_col=TIMESTAMP_COL,
        metadata_cols=METADATA_COLS,
        leak_cols=METADATA_COLS,
        model="Migas-1.0",
    )

    return {
        'item_name': item_name,
        'history_df': history_df,
        'target_df': target_df,
        'univariate_predictions': univariate_forecast[0][TARGET_COL].values,
        'multivariate_predictions': multivariate_forecast[0][TARGET_COL].values,
    }


# Run forecasts for Soup and Tea
soup_results = forecast_item(data_df, 'soup')
tea_results = forecast_item(data_df, 'tea')

4. Visualize Forecast Results

Create visualizations to compare the forecasting approaches:

Show plotting code for forecast comparison

def plot_forecast_comparison(results: Dict[str, Any]) -> None:
    """Create time series plot with forecasts and MAPE values in legend labels."""
    item_name: str = results['item_name']
    history_df: pd.DataFrame = results['history_df']
    target_df: pd.DataFrame = results['target_df']
    univariate_preds: np.ndarray = results['univariate_predictions']
    multivariate_preds: np.ndarray = results['multivariate_predictions']

    # Calculate MAPE
    actual = target_df[TARGET_COL].values
    univariate_mape = np.mean(np.abs((actual - univariate_preds) / actual)) * 100
    multivariate_mape = np.mean(np.abs((actual - multivariate_preds) / actual)) * 100

    colors = {
        "univariate": "#fea333",  # Orange
        "multivariate": "#1E90FF",  # Blue
        "groundtruth": "black",
        "cross_item": "#2ECC71",  # Green
    }

    # Create time series plot with forecasts
    fig, ax = plt.subplots(1, 1, figsize=(16, 7))

    # Plot only last 50% of history
    history_cutoff = len(history_df) // 2
    history_subset = history_df.iloc[history_cutoff:]

    # Prepare data for swarm-visualizer
    # Combine historical and test data for actual values
    actual_x = pd.concat([history_subset[TIMESTAMP_COL], target_df[TIMESTAMP_COL]])
    actual_y = pd.concat([history_subset[TARGET_COL], target_df[TARGET_COL]])

    normalized_dict = {
        "Actual": {
            "x": actual_x,
            "y": actual_y,
            "lw": 2,
            "linestyle": "-",
            "color": colors["groundtruth"],
            "alpha": 0.8,
            "zorder": 1,
        },
        f"Univariate Forecast (MAPE: {univariate_mape:.2f}%)": {
            "x": target_df[TIMESTAMP_COL],
            "y": univariate_preds,
            "lw": 1.5,
            "linestyle": "-",
            "color": colors["univariate"],
            "alpha": 0.7,
            "zorder": 2,
        },
        f"Multivariate Forecast (MAPE: {multivariate_mape:.2f}%)": {
            "x": target_df[TIMESTAMP_COL],
            "y": multivariate_preds,
            "lw": 1.5,
            "linestyle": "-",
            "color": colors["multivariate"],
            "alpha": 0.7,
            "zorder": 3,
        }
    }

    # Use swarm-visualizer plot_overlaid_lineplot
    swarm_visualizer.plot_overlaid_lineplot(
        ax=ax,
        normalized_dict=normalized_dict,
        title_str=f"Forecast {format_item_name(item_name)}",
        ylabel="Sales",
        xlabel="Date",
        legend_present=True,
    )

    # Add vertical line at split
    split_date = target_df[TIMESTAMP_COL].iloc[0]
    ax.axvline(
        x=split_date,
        color="red",
        linestyle="--",
        linewidth=2,
        alpha=0.7,
        label="Train/Test Split",
        zorder=1,
    )

    # Move legend inside the plot area with default font size
    ax.legend(loc="upper right", frameon=True)

    # Use swarm-visualizer set_axis_infos for consistent styling
    set_axis_infos(
        ax=ax,
        xlabel="Date",
        ylabel="Sales",
        title_str=f"Forecast {format_item_name(item_name)}",
        grid=True,
    )
    plt.setp(ax.get_xticklabels(), rotation=45, ha="right")

    plt.tight_layout()
    plt.savefig(f'forecast_time_series_{item_name.lower()}.png', dpi=300, bbox_inches='tight')
    plt.close()


# Create forecast comparison plots
plot_forecast_comparison(soup_results)
plot_forecast_comparison(tea_results)

Example Output: Soup Forecast Comparison

Analysis: The multivariate forecast (blue) dramatically outperforms the univariate approach (orange) by capturing weather-related demand fluctuations:

Time series plot: The multivariate forecast closely tracks actual sales through various weather conditions, while univariate struggles with sudden changes. The red vertical line marks the train/test split.
MAPE values in legend: The legend shows the quantitative improvement - multivariate forecasting achieves significantly lower error rates (MAPE values are displayed directly in the legend labels).

The weather-aware model identifies patterns like increased soup sales during cold, rainy days - insights impossible with time-series-only forecasting.

Note that there seem to be peaks of sales before the weather dips! You can experiment with adding new features like (num_days_before_temp_dip)

Example Output: Tea Forecast Comparison

Key Insight: The multivariate approach doesn’t just forecast better - it reveals why demand changes. By incorporating weather and temporal features, you gain actionable insights: stock more hot beverages before cold fronts, and optimize inventory based on weather forecasts rather than just historical patterns.

5. Easily Find Products that Sell Together

Beyond weather, products in a store often influence each other’s sales. For instance, if coffee sales spike, tea sales might also increase, or soup and bread might move together. We can discover these relationships by using one product’s sales data to help forecast another product’s sales. Knowing this, store owners can introduce promotions or package deals to increase revenue.

What is Cross-Item Analysis

The key insight: if knowing Product A’s sales helps predict Product B’s sales more accurately, then these products are correlated. We measure this by comparing forecast accuracy (MAPE) - lower MAPE means stronger correlation.

What is “Leaking” in Cross-Item Analysis?

In this context, “leaking” refers to conditioning our forecast on another product’s sales data. Think of it as asking: “If I know how much tea was sold today, how does that change my forecast for soup sales?” Example: When we “leak” tea sales data into our soup forecast, we’re essentially asking:

Without tea data: “Based on historical soup sales and weather, what will soup sales look like?”
With tea data: “Given that tea sales were X units today, and considering historical soup sales and weather, what will soup sales look like?”

def calculate_mape(y_true, y_pred, epsilon=1e-10):
    """Calculate Mean Absolute Percentage Error."""
    y_true = np.array(y_true)
    y_pred = np.array(y_pred)

    mask = np.abs(y_true) > epsilon
    if not np.any(mask):
        return np.inf

    mape = float(np.mean(np.abs((y_true[mask] - y_pred[mask]) / y_true[mask])) * 100)
    return mape


def analyze_cross_item_correlations(data_df: pd.DataFrame, history_ratio: float = 0.8):
    """Analyze how well each item's sales can predict other items' sales."""
    item_ids = data_df[GROUP_COL].unique()
    cross_item_results = {}

    for target_item in item_ids:
        print(f"\n[Target: {target_item}]")
        item_results = {}

        for leaked_item in item_ids:
            if target_item == leaked_item:
                continue

            # Get data for both items
            target_data = data_df[data_df[GROUP_COL] == target_item].sort_values(TIMESTAMP_COL)
            leaked_data = data_df[data_df[GROUP_COL] == leaked_item].sort_values(TIMESTAMP_COL)

            # Split target item's data
            split_idx = int(len(target_data) * history_ratio)
            split_timestamp = target_data.iloc[split_idx][TIMESTAMP_COL]

            hist_target = target_data[target_data[TIMESTAMP_COL] < split_timestamp]
            future_target = target_data[target_data[TIMESTAMP_COL] >= split_timestamp]

            # Align leaked item's data with target item's timestamps
            hist_leaked = leaked_data[leaked_data[TIMESTAMP_COL] < split_timestamp]
            future_leaked = leaked_data[leaked_data[TIMESTAMP_COL] >= split_timestamp]

            # Create leaked column
            leaked_col_name = f"{TARGET_COL}_leaked"
            hist_leaked_vals = hist_leaked[[TIMESTAMP_COL, TARGET_COL]].rename(
                columns={TARGET_COL: leaked_col_name}
            )
            future_leaked_vals = future_leaked[[TIMESTAMP_COL, TARGET_COL]].rename(
                columns={TARGET_COL: leaked_col_name}
            )

            # Merge
            hist_with_leak = hist_target.merge(hist_leaked_vals, on=TIMESTAMP_COL, how='inner')
            future_with_leak = future_target.merge(future_leaked_vals, on=TIMESTAMP_COL, how='inner')

            # Forecast with leaked item data + weather
            forecast_dfs = API_CLIENT.forecast_dfs(
                history_dfs=[hist_with_leak],
                target_dfs=[future_with_leak],
                target_col=TARGET_COL,
                timestamp_col=TIMESTAMP_COL,
                metadata_cols=METADATA_COLS + [leaked_col_name],
                leak_cols=METADATA_COLS + [leaked_col_name],
                model="Migas-1.0",
            )

            predictions = forecast_dfs[0][TARGET_COL].values
            ground_truth = future_with_leak[TARGET_COL].values

            mape = calculate_mape(ground_truth, predictions)
            item_results[leaked_item] = float(mape)
            print(f"  {leaked_item:15s} -> MAPE: {mape:6.2f}%")

        cross_item_results[target_item] = item_results

    return cross_item_results


# Run cross-item correlation analysis
cross_item_results = analyze_cross_item_correlations(data_df)

How It Works

For each target product (e.g., soup), we forecast its sales using three approaches:
- Univariate: Time series only
- Multivariate: Time series + weather
- Cross-item: Time series + weather + another product’s sales
We test each product as the “leaked” feature to see which one helps most
Lower MAPE = stronger correlation between the products

Visualizing Cross-Item Relationships

Create comprehensive visualizations showing the progressive improvement from univariate to cross-item forecasting:

Show plotting code for cross-item analysis

def plot_cross_item_analysis(data_df: pd.DataFrame, cross_item_results: Dict[str, Dict[str, float]],
                              forecast_results: Dict[str, Dict[str, Any]] = None):
    """
    Create visualization comparing 3 forecasting approaches:
    1. Univariate (time series only)
    2. Multivariate (time series + weather)
    3. Multivariate + best cross-item leak
    """
    history_ratio = 0.8

    for target_item, results in cross_item_results.items():
        # Find best correlated item
        valid_results = {k: v for k, v in results.items() if not np.isnan(v) and v != np.inf}
        if not valid_results:
            continue

        best_item = min(valid_results.items(), key=lambda x: x[1])[0]

        # Get target item data
        target_data = data_df[data_df[GROUP_COL] == target_item].sort_values(TIMESTAMP_COL)
        split_idx = int(len(target_data) * history_ratio)
        split_timestamp = target_data.iloc[split_idx][TIMESTAMP_COL]

        hist_target = target_data[target_data[TIMESTAMP_COL] < split_timestamp]
        future_target = target_data[target_data[TIMESTAMP_COL] >= split_timestamp]

        # Check if we can reuse existing results (from soup/tea forecasts)
        if forecast_results and target_item in forecast_results:
            print(f"Reusing existing forecast results for {target_item}...")
            univariate_preds = forecast_results[target_item]['univariate_predictions']
            multivariate_preds = forecast_results[target_item]['multivariate_predictions']
        else:
            # Compute fresh forecasts
            univariate_forecast = API_CLIENT.forecast_dfs(
                history_dfs=[hist_target], target_dfs=[future_target],
                target_col=TARGET_COL, timestamp_col=TIMESTAMP_COL,
                metadata_cols=[], leak_cols=[], model="Migas-1.0")
            univariate_preds = univariate_forecast[0][TARGET_COL].values

            multivariate_forecast = API_CLIENT.forecast_dfs(
                history_dfs=[hist_target], target_dfs=[future_target],
                target_col=TARGET_COL, timestamp_col=TIMESTAMP_COL,
                metadata_cols=METADATA_COLS, leak_cols=METADATA_COLS, model="Migas-1.0")
            multivariate_preds = multivariate_forecast[0][TARGET_COL].values

        # Compute MAPEs
        univariate_mape = calculate_mape(future_target[TARGET_COL].values, univariate_preds)
        multivariate_mape = calculate_mape(future_target[TARGET_COL].values, multivariate_preds)

        # Get cross-item forecast (already computed in analyze_cross_item_correlations)
        cross_item_mape = results[best_item]

        # Create figure with 2 subplots
        fig, axes = plt.subplots(2, 1, figsize=(14, 10))
        fig.suptitle(f'Cross-Item Forecast Comparison: {target_item}',
                     fontsize=24, fontweight='bold', y=0.995)

        # Subplot 1: Full time series with all forecasts
        ax1 = axes[0]

        # Plot only last 50% of history
        history_cutoff = len(hist_target) // 2
        hist_target_subset = hist_target.iloc[history_cutoff:]

        colors = {
            "univariate": "#fea333",  # Orange
            "multivariate": "#1E90FF",  # Blue
            "groundtruth": "black",
            "cross_item": "#2ECC71",  # Green
        }

        # Prepare data for swarm-visualizer
        # Combine historical and test data for actual values
        actual_x = pd.concat([hist_target_subset[TIMESTAMP_COL], future_target[TIMESTAMP_COL]])
        actual_y = pd.concat([hist_target_subset[TARGET_COL], future_target[TARGET_COL]])

        cross_item_dict = {
            "Actual Sales": {
                "x": actual_x,
                "y": actual_y,
                "lw": 2,
                "linestyle": "-",
                "color": colors["groundtruth"],
                "alpha": 0.8,
                "zorder": 1,
            },
            f"Univariate (MAPE: {univariate_mape:.2f}%)": {
                "x": future_target[TIMESTAMP_COL],
                "y": univariate_preds,
                "lw": 1.5,
                "linestyle": "-",
                "color": colors["univariate"],
                "alpha": 0.7,
                "zorder": 2,
            },
            f"Multivariate + Weather (MAPE: {multivariate_mape:.2f}%)": {
                "x": future_target[TIMESTAMP_COL],
                "y": multivariate_preds,
                "lw": 1.5,
                "linestyle": "-",
                "color": colors["multivariate"],
                "alpha": 0.7,
                "zorder": 3,
            },
            f"Multivariate + Weather + {format_item_name(best_item)} (MAPE: {cross_item_mape:.2f}%)": {
                "x": future_with_leak[TIMESTAMP_COL],
                "y": cross_item_preds,
                "lw": 1.5,
                "linestyle": "-",
                "color": colors["cross_item"],
                "alpha": 0.7,
                "zorder": 4,
            }
        }

        # Use swarm-visualizer plot_overlaid_lineplot
        swarm_visualizer.plot_overlaid_lineplot(
            ax=ax1,
            normalized_dict=cross_item_dict,
            title_str="Full Time Series with All Forecasts",
            ylabel="Sales",
            xlabel="Date",
            legend_present=True,
        )

        # Move legend to the right side
        ax1.legend(loc="center left", bbox_to_anchor=(1, 0.5))

        # Add vertical line at split
        ax1.axvline(
            x=split_timestamp,
            color="red",
            linestyle="--",
            linewidth=2,
            alpha=0.7,
            label="Train/Test Split",
            zorder=1,
        )

        # Use swarm-visualizer set_axis_infos for consistent styling
        set_axis_infos(
            ax=ax1,
            xlabel="Date",
            ylabel="Sales",
            title_str="Full Time Series with All Forecasts",
            grid=True,
        )
        plt.setp(ax1.get_xticklabels(), rotation=45, ha='right')

        # Subplot 2: Zoom in on forecast period
        ax2 = axes[1]

        # Prepare data for swarm-visualizer for forecast period detail
        forecast_detail_dict = {
            "Actual Sales": {
                "x": future_target[TIMESTAMP_COL],
                "y": future_target[TARGET_COL],
                "lw": 2,
                "linestyle": "-",
                "color": colors["groundtruth"],
                "alpha": 1.0,
                "zorder": 3,
            },
            f"Univariate (MAPE: {univariate_mape:.2f}%)": {
                "x": future_target[TIMESTAMP_COL],
                "y": univariate_preds,
                "lw": 1.5,
                "linestyle": "-",
                "color": colors["univariate"],
                "alpha": 0.7,
                "zorder": 2,
            },
            f"Multivariate (MAPE: {multivariate_mape:.2f}%)": {
                "x": future_target[TIMESTAMP_COL],
                "y": multivariate_preds,
                "lw": 1.5,
                "linestyle": "-",
                "color": colors["multivariate"],
                "alpha": 0.7,
                "zorder": 2,
            },
            f"+ {format_item_name(best_item)} (MAPE: {cross_item_mape:.2f}%)": {
                "x": future_with_leak[TIMESTAMP_COL],
                "y": cross_item_preds,
                "lw": 1.5,
                "linestyle": "-",
                "color": colors["cross_item"],
                "alpha": 0.7,
                "zorder": 2,
            }
        }

        # Use swarm-visualizer plot_overlaid_lineplot
        swarm_visualizer.plot_overlaid_lineplot(
            ax=ax2,
            normalized_dict=forecast_detail_dict,
            title_str="Forecast Period Detail",
            ylabel="Sales",
            xlabel="Date",
            legend_present=True,
        )

        # Move legend to the right side
        ax2.legend(loc="center left", bbox_to_anchor=(1, 0.5))

        # Use swarm-visualizer set_axis_infos for consistent styling
        set_axis_infos(
            ax=ax2,
            xlabel="Date",
            ylabel="Sales",
            title_str="Forecast Period Detail",
            grid=True,
        )
        plt.setp(ax2.get_xticklabels(), rotation=45, ha='right')

        plt.tight_layout()
        plt.savefig(f'cross_item_analysis_{target_item.lower()}.png', dpi=300, bbox_inches='tight')
        plt.show()
        plt.close()


# Create cross-item analysis plots (reusing soup/tea results)
forecast_results_dict = {'soup': soup_results, 'tea': tea_results}
plot_cross_item_analysis(data_df, cross_item_results, forecast_results_dict)

Example Output: Cross-Item Analysis for Soup

Understanding the Analysis:

Top panel: Shows the full timeline with historical data and all three forecast approaches. The vertical line marks the train/test split.
Bottom panel: Zoomed view of the forecast period showing how each approach performs. Notice the progressive improvement from univariate to multivariate to cross-item forecasting.

Visualizing Cross-Item Prediction Accuracy

Create a comprehensive 2x2 grid showing which items are most helpful for predicting each target item:

Show plotting code for cross-item MAPE comparison

def plot_cross_item_mape_comparison(cross_item_results: Dict[str, Dict[str, float]]) -> None:
    """
    Create a 2x2 grid of bar charts showing MAPE values for cross-item predictions.
    Each subplot shows one target item with bars for each predictor item.
    """
    # Create 2x2 subplot grid
    fig, axes = plt.subplots(2, 2, figsize=(16, 12))
    axes = axes.flatten()  # Flatten to 1D array for easier indexing

    # Define colors for predictor items matching the main color scheme
    predictor_colors = {
        "soup": "#FF8C00",  # Orange
        "tea": "#1E90FF",  # Blue
        "ice_cream": "#2ECC71",  # Green
        "bread": "#A23B72",  # Purple
    }

    # Get all predictor items (should be consistent across targets)
    all_predictors = set()
    for predictions in cross_item_results.values():
        all_predictors.update(predictions.keys())
    all_predictors = sorted(list(all_predictors))

    # Create a subplot for each target item
    for idx, (target_item, predictions) in enumerate(
        cross_item_results.items()
    ):
        ax = axes[idx]

        # Prepare data for this target - sort by MAPE (smallest first)
        predictor_data = []
        for predictor in all_predictors:
            if predictor in predictions:
                predictor_data.append(
                    {
                        "name": format_item_name(predictor),
                        "mape": predictions[predictor],
                        "color": predictor_colors[predictor],
                    }
                )

        # Sort by MAPE (smallest first)
        predictor_data.sort(key=lambda x: x["mape"])

        predictor_names = [item["name"] for item in predictor_data]
        mape_values = [item["mape"] for item in predictor_data]
        colors = [item["color"] for item in predictor_data]

        # Create bars
        bars = ax.bar(predictor_names, mape_values, color=colors, alpha=0.8)

        # Add value labels on top of bars
        for bar, value in zip(bars, mape_values):
            height = bar.get_height()
            ax.text(
                bar.get_x() + bar.get_width() / 2.0,
                height + 0.1,
                f"{value:.1f}%",
                ha="center",
                va="bottom",
                fontweight="bold",
            )

        # Set y-axis to start from 0
        ax.set_ylim(0, max(mape_values) * 1.2)

        # Use swarm-visualizer set_axis_infos for consistent styling
        set_axis_infos(
            ax=ax,
            xlabel="Predictor Item",
            ylabel="MAPE (%)",
            title_str=f"MAPE for forecasting {format_item_name(target_item)}\n(Lower MAPE = Better)",
            grid=True,
        )

        # Rotate x-axis labels if needed
        plt.setp(ax.get_xticklabels(), rotation=45, ha="right")

    # Overall title
    fig.suptitle(
        "Cross-Item Prediction Accuracy by Target Item",
        fontsize=24,
        fontweight="bold",
        y=0.99,
    )

    plt.tight_layout()
    plt.subplots_adjust(
        top=0.85
    )  # Add more space between main title and subplot titles

    # Save the plot
    os.makedirs("inventory_forecasting_plots", exist_ok=True)
    filepath = os.path.abspath(
        "inventory_forecasting_plots/cross_item_mape_comparison.png"
    )
    plt.savefig(filepath, dpi=300, bbox_inches="tight")
    plt.close()

    print(f"✓ Saved cross-item MAPE comparison: {filepath}")

    # Print summary statistics
    print("\n" + "=" * 60)
    print("CROSS-ITEM PREDICTION SUMMARY")
    print("=" * 60)

    for target_item, predictions in cross_item_results.items():
        sorted_predictors = sorted(predictions.items(), key=lambda x: x[1])
        print(f"\n{target_item.upper()} - Best to Worst Predictors:")
        for predictor, mape in sorted_predictors:
            print(f"  {format_item_name(predictor):12s}: {mape:6.2f}% MAPE")

# Overall best predictors
print("\nOVERALL BEST PREDICTORS:")
for target_item, predictions in cross_item_results.items():
    best_predictor, best_mape = min(predictions.items(), key=lambda x: x[1])
    print(
        f"  {format_item_name(target_item):12s} → best predicted by {format_item_name(best_predictor):12s} ({best_mape:.2f}% MAPE)"
    )


# Create cross-item MAPE comparison chart
plot_cross_item_mape_comparison(cross_item_results)

Example Output: Cross-Item MAPE Comparison

This visualization clearly shows which items are most helpful for predicting each target item:

Hot beverages show strong correlations - Tea and Soup are highly correlated

Variable Improvement Across Products: Notice that soup and tea show much larger improvements from cross-item forecasting compared to their baseline univariate/multivariate forecasts. This is because hot beverages and comfort foods have strong weather-driven correlations. In contrast, products like bread may show less dramatic improvement since bread sales are more stable and less influenced by weather patterns. Focus your cross-item forecasting efforts on products that show strong seasonal or weather-related correlations.

Business Applications:

Inventory Optimization: If tea and soup are highly correlated, use tea sales trends to improve soup inventory forecasts
Shelf Placement: Position correlated products near each other to increase cross-sales
Demand Forecasting: When you see unusual tea sales, prepare for corresponding soup demand changes

​What is inventory forecasting? How does it help?

​Prerequisites

​1. Load and Prepare Data

​2. Visualize Historical Sales Patterns

​Historical Sales Overview

​Historical Sales and Temperature

​3. Split Data and Run Forecasts

​4. Visualize Forecast Results

​Example Output: Soup Forecast Comparison

​Example Output: Tea Forecast Comparison

​5. Easily Find Products that Sell Together

​What is Cross-Item Analysis

​What is “Leaking” in Cross-Item Analysis?

​How It Works

​Visualizing Cross-Item Relationships

​Example Output: Cross-Item Analysis for Soup

​Visualizing Cross-Item Prediction Accuracy

​Example Output: Cross-Item MAPE Comparison

What is inventory forecasting? How does it help?

Prerequisites

1. Load and Prepare Data

2. Visualize Historical Sales Patterns

Historical Sales Overview

Historical Sales and Temperature

3. Split Data and Run Forecasts

4. Visualize Forecast Results

Example Output: Soup Forecast Comparison

Example Output: Tea Forecast Comparison

5. Easily Find Products that Sell Together

What is Cross-Item Analysis

What is “Leaking” in Cross-Item Analysis?

How It Works

Visualizing Cross-Item Relationships

Example Output: Cross-Item Analysis for Soup

Visualizing Cross-Item Prediction Accuracy

Example Output: Cross-Item MAPE Comparison