kishorkukreja/awesome-supply-chain/seasonal-planning

import numpy as np
import pandas as pd
from scipy.optimize import minimize
from scipy import stats
class SeasonalBuyOptimizer:
    """
    Optimize seasonal buy quantities
    Balance:
    - Under-buying: Lost sales (stockouts)
    - Over-buying: Markdowns and excess inventory
    """
    def __init__(self, season_config):
        """
        Parameters:
        - season_config: Season parameters (length, targets, costs)
        """
        self.season = season_config
    def calculate_optimal_buy(self, sku_forecast, unit_cost, retail_price,
                             markdown_rate=0.50, stockout_cost_multiplier=1.5):
        """
        Calculate optimal buy quantity using newsvendor model
        Classic single-period inventory problem
        """
        # Expected demand
        mean_demand = sku_forecast['mean']
        std_demand = sku_forecast['std']
        # Profit margins
        full_price_margin = retail_price - unit_cost
        markdown_price = retail_price * (1 - markdown_rate)
        markdown_margin = markdown_price - unit_cost
        # Cost of under-stocking (lost profit + goodwill)
        cost_understocking = full_price_margin * stockout_cost_multiplier
        # Cost of over-stocking (forced markdown or liquidation)
        cost_overstocking = unit_cost - markdown_price
        # Critical ratio (newsvendor)
        critical_ratio = cost_understocking / (cost_understocking + cost_overstocking)
        # Optimal order quantity (quantile of demand distribution)
        optimal_quantity = stats.norm.ppf(critical_ratio, mean_demand, std_demand)
        # Calculate expected profit at optimal quantity
        expected_sales = self._expected_sales(optimal_quantity, mean_demand, std_demand)
        expected_markdowns = max(0, optimal_quantity - expected_sales)
        expected_revenue = (expected_sales * retail_price +
                           expected_markdowns * markdown_price)
        expected_cost = optimal_quantity * unit_cost
        expected_profit = expected_revenue - expected_cost
        # Service level (fill rate)
        service_level = stats.norm.cdf(optimal_quantity, mean_demand, std_demand)
        return {
            'optimal_buy_quantity': round(optimal_quantity, 0),
            'expected_demand': mean_demand,
            'demand_std': std_demand,
            'expected_sales': round(expected_sales, 0),
            'expected_markdowns': round(expected_markdowns, 0),
            'expected_profit': round(expected_profit, 2),
            'service_level': round(service_level * 100, 1),
            'markdown_rate': markdown_rate * 100,
            'critical_ratio': round(critical_ratio, 3)
        }
    def _expected_sales(self, quantity, mean, std):
        """
        Calculate expected sales given quantity
        Accounts for potential stockouts
        """
        # E[Sales] = E[min(Demand, Quantity)]
        # Using normal distribution approximation
        if std == 0:
            return min(quantity, mean)
        z = (quantity - mean) / std
        expected_sales = mean * stats.norm.cdf(z) + std * stats.norm.pdf(z)
        return min(expected_sales, quantity)
    def optimize_assortment_mix(self, product_options, total_budget,
                                category_constraints=None):
        """
        Optimize product mix within budget
        Select which products to buy and in what quantities
        """
        n_products = len(product_options)
        # Objective: Maximize total expected profit
        def objective(quantities):
            total_profit = 0
            for i, qty in enumerate(quantities):
                product = product_options.iloc[i]
                # Calculate profit for this quantity
                result = self.calculate_optimal_buy(
                    sku_forecast={'mean': product['forecast_mean'],
                                 'std': product['forecast_std']},
                    unit_cost=product['unit_cost'],
                    retail_price=product['retail_price']
                )
                # Adjust for actual quantity vs. optimal
                if qty > 0:
                    # Approximate profit at this quantity
                    profit_at_qty = result['expected_profit'] * (qty / result['optimal_buy_quantity'])
                    total_profit += profit_at_qty
            return -total_profit  # Negative for minimization
        # Constraints
        def budget_constraint(quantities):
            total_cost = sum(
                quantities[i] * product_options.iloc[i]['unit_cost']
                for i in range(n_products)
            )
            return total_budget - total_cost
        constraints = [{'type': 'ineq', 'fun': budget_constraint}]
        # Bounds (non-negative quantities)
        bounds = [(0, product_options.iloc[i]['max_quantity']) for i in range(n_products)]
        # Initial guess (proportional to forecast)
        x0 = np.array([
            min(product_options.iloc[i]['forecast_mean'],
                product_options.iloc[i]['max_quantity'])
            for i in range(n_products)
        ]) * 0.8  # Start conservative
        # Optimize
        result = minimize(objective, x0, method='SLSQP',
                         bounds=bounds, constraints=constraints)
        optimal_quantities = result.x
        # Build result dataframe
        results = []
        for i, qty in enumerate(optimal_quantities):
            product = product_options.iloc[i]
            if qty > 5:  # Only include products with meaningful quantity
                buy_analysis = self.calculate_optimal_buy(
                    sku_forecast={'mean': product['forecast_mean'],
                                 'std': product['forecast_std']},
                    unit_cost=product['unit_cost'],
                    retail_price=product['retail_price']
                )
                results.append({
                    'sku': product['sku'],
                    'category': product['category'],
                    'buy_quantity': round(qty, 0),
                    'unit_cost': product['unit_cost'],
                    'retail_price': product['retail_price'],
                    'total_cost': round(qty * product['unit_cost'], 2),
                    'expected_profit': buy_analysis['expected_profit'],
                    'expected_markdown_rate': buy_analysis['markdown_rate']
                })
        results_df = pd.DataFrame(results)
        return results_df, result
    def calculate_open_to_buy(self, sales_plan, beginning_inventory,
                              on_order, target_end_inventory,
                              markdown_receipts=0):
        """
        Calculate open-to-buy (OTB) budget
        OTB = Sales Plan + Target End Inv - Beginning Inv - On Order + Markdowns
        """
        otb = (
            sales_plan +
            target_end_inventory -
            beginning_inventory -
            on_order +
            markdown_receipts
        )
        return {
            'sales_plan': sales_plan,
            'beginning_inventory': beginning_inventory,
            'on_order': on_order,
            'target_end_inventory': target_end_inventory,
            'markdown_receipts': markdown_receipts,
            'open_to_buy': otb,
            'otb_pct_of_sales': (otb / sales_plan * 100) if sales_plan > 0 else 0
        }
# Example usage
season_config = {
    'season_name': 'Fall 2024',
    'start_date': '2024-08-01',
    'end_date': '2024-11-30',
    'weeks': 16
}
optimizer = SeasonalBuyOptimizer(season_config)
# Single SKU optimization
sku_forecast = {'mean': 500, 'std': 150}
buy_decision = optimizer.calculate_optimal_buy(
    sku_forecast=sku_forecast,
    unit_cost=25,
    retail_price=60,
    markdown_rate=0.50
)
print("Optimal Buy Analysis:")
print(f"  Optimal quantity: {buy_decision['optimal_buy_quantity']}")
print(f"  Expected sales: {buy_decision['expected_sales']}")
print(f"  Expected markdowns: {buy_decision['expected_markdowns']}")
print(f"  Expected profit: ${buy_decision['expected_profit']:,.2f}")
print(f"  Service level: {buy_decision['service_level']:.1f}%")
# Assortment optimization
product_options = pd.DataFrame({
    'sku': [f'SKU{i:03d}' for i in range(1, 21)],
    'category': np.random.choice(['Tops', 'Bottoms', 'Dresses'], 20),
    'forecast_mean': np.random.uniform(200, 800, 20),
    'forecast_std': np.random.uniform(50, 200, 20),
    'unit_cost': np.random.uniform(15, 40, 20),
    'retail_price': np.random.uniform(40, 100, 20),
    'max_quantity': 1000
})
assortment, optimization_result = optimizer.optimize_assortment_mix(
    product_options,
    total_budget=150000
)
print(f"\nOptimized Assortment (Budget: $150K):")
print(f"Products selected: {len(assortment)}")
print(f"Total cost: ${assortment['total_cost'].sum():,.0f}")
print(f"Expected total profit: ${assortment['expected_profit'].sum():,.0f}")

class SeasonalDemandForecaster:
    """
    Forecast seasonal demand patterns
    Accounts for:
    - Historical seasonal trends
    - Year-over-year growth
    - Fashion trends and newness
    - Weather impacts
    """
    def __init__(self, historical_data):
        """
        Parameters:
        - historical_data: Historical sales by week/season
          columns: ['season', 'year', 'week', 'sales', 'category']
        """
        self.history = historical_data
    def forecast_seasonal_curve(self, season, category):
        """
        Create seasonal sales curve
        Shows expected % of season sales by week
        """
        # Get historical data for this season
        season_history = self.history[
            (self.history['season'] == season) &
            (self.history['category'] == category)
        ]