Forecast Projection Algorithm

Last Updated: Jan 22, 2026

---

Executive Summary

This algorithm executes a Hybrid Demand Forecasting Model. It combines a “Naive” historical average with a customized Holt’s Linear Trend method. The model de-seasonalizes historical data to identify underlying trends, projects those trends forward, and then re-applies seasonality, marketing events, and growth factors to generate a daily demand schedule for the next Lead Time + Coverage window.

INFO

Type: Deterministic / Time-Series Forecast
Core Method: Holt’s Linear Exponential Smoothing (with Damped Trend)

---

Inputs & Configuration

The algorithm requires a strict operational context to function.

Operational Data

• History: Array of daily sales units (ordered by date).
• StartDate: The anchor date for the simulation.

Configuration Object (options)

Parameter	Default	Description
leadTimeDays	90	Days to wait before stock arrives (Gap Analysis start).
coverageDays	60	Target days of stock to hold after arrival.
seasonalityProfile	{}	Key-Value map of Month Index (0-11) to Weight (e.g., 1.2 = +20%).
accelerationPercent	0.1	Weight given to the “Algo” vs “Naive” forecast.
skuGrowthRateWeekly	0	Compounding weekly growth factor.

---

Core Logic: The “Gap Analysis”

The function calculateGapInventoryTarget performs the heavy lifting. It transforms raw history into a future purchase recommendation through five distinct mathematical phases.

flowchart TD
    Raw[Raw Daily History] --> Aggregate[Aggregate to Weekly]
    Aggregate --> Deseason[De-seasonalize Data]
    Deseason --> Holts[Holt's Linear Smoothing]
    Holts --> Clamp[Safety Clamp Trend]
    Clamp --> Project[Project Future Days]
    Project --> Factors{Apply Factors}
    
    Factors --> |Seasonality| Reseason[Re-seasonalized]
    Factors --> |Marketing| Marketing[Lift Multiplier]
    Factors --> |Growth| Growth[Compounding Growth]
    
    Reseason --> Sum[Sum 'Gap' Demand]
    Marketing --> Sum
    Growth --> Sum
    
    Sum --> Blend[Blend w/ Naive Avg]
    Blend --> Final[Final Stock Target]

Phase 1: Aggregation & De-seasonalization

Daily data is too noisy for trend detection. We first aggregate daily units into Weekly Buckets (working backwards from the most recent date).

To isolate the “true” organic trend, we must remove known seasonality effects.
If December usually has 2x sales (weight = 2.0), a raw sale of 100 units is treated as a “normalized” sale of 50 units.

${\text{CleanValue}}_t=\frac{{\text{ActualWeeklySales}}_t}{\text{SeasonalityWeight}({\text{Month}}_t)}$

Phase 2: Holt’s Linear Smoothing (The Training Phase)

We use a double exponential smoothing method to track two components:

1. Level ($L$): The baseline volume of sales at time.
2. Trend ($T$): The direction and magnitude of change (slope) at time.

Hyperparameters

• Alpha (α): The Level Smoothing Factor.
  A lower value makes the level less reactive to short-term spikes.
• Beta (β): The Trend Smoothing Factor.
  A very low value ensures we only react to sustained, long-term shifts in direction.
• Phi (φ): The Damping Factor.
  This decays the trend over time, preventing the model from projecting infinite linear growth forever.

Recursive Equations

For each week in the history:

1. Update Level: $L_t=\alpha \cdot \text{Actual}\ast t+(1-\alpha )(L\ast t-1+\varphi \cdot T_{t-1})$
   Logic: The new level is a blend of the actual data we just saw ($L_t$) and our previous prediction ($L_{t-1}$).
2. Update Trend: $T_t=\beta (L_t-L_{t-1})+(1-\beta )\cdot \varphi \cdot T_{t-1}$
   Logic: The new trend is a blend of the recent change ($T_t$) and the previous trend ($T_{t-1}$).

Phase 3: The Safety Clamp

Before projecting the future, we strictly limit the (Final Trend) to prevent “hallucinations” caused by recent outliers.

We calculate the Implied Weekly Growth Rate: $\text{GrowthRate}=\frac{T_{final}}{L_{final}}$

We then apply hard limits:

• Max Growth: +5% per week.
• Min Growth: -10% per week.

If the rate exceeds these bounds, the trend is forcibly overwritten: $T_{safe}=L_{final}\cdot \text{Limit}$

Phase 4: Daily Projection Loop

The algorithm iterates through every day of the future horizon ($\text{now}$ to $\text{leadTimeDays}+\text{coverageDays}$).

1. Trend Damping

The trend does not stay constant; it decays daily (applied weekly in code) to represent uncertainty.
$T_{projected}=T_{safe}\cdot {\varphi }^{\lfloor d/7\rfloor }$ $L_{projected}=L_{final}+\sum (T_{projected})$

2. Base Daily Value

We convert the weekly projected level back to a daily average. $\text{DailyBase}=\frac{\max (0,L_{projected})}{7}$

3. Factor Application

We now re-apply the external factors to generating the Final Daily Demand.

${\text{Demand}}_d=\text{DailyBase}\times {\text{Seasonality}}_m\times {\text{GrowthFactor}}_d\times \text{MarketingLift}$

• Seasonality: The weight for the projected month.
• Compounding Growth: $(1+\text{WeeklyGrowth}{)}^{d/7}$
• Marketing Lift: Iterates through marketingEvents. If date falls in window:
  $\text{Multiplier}=\text{Multiplier}\times (1+\text{EventGrowth}\%)$

Phase 5: The “Gap” Summation

We only care about demand that occurs after the lead time (when the stock arrives) and before the coverage period ends.

$\text{AlgoGapDemand}={\sum }_{d=\text{LeadTime}}^{\text{LeadTime}+\text{Coverage}}{\text{Demand}}_d$

The sum expected demand for each day, starting from day $LeadTime$, until $day$ reaches $LeadTime+Coverage$

Phase 6: Confidence Blending

To mitigate risk for new products with sparse data, we blend the complex “Algo” forecast with a simple “Naive” average.

Confidence Score ($C$):
$C=\min \left(1,\frac{\text{WeeksHistory}}{26}\right)$
Interpretation: It takes 26 weeks (6 months) to reach 100% confidence in the Algo.

Weighting: $W_{algo}=\text{AccelerationPercent}\times C$ $W_{naive}=1-W_{algo}$

Final Target: $\text{FinalTarget}=(\text{AlgoGapDemand}\cdot W_{algo})+(\text{NaiveGapDemand}\cdot W_{naive})+\text{SafetyStock}$

---

Weeks of Supply Calculation

*Function: calculateWeeksOfSupply*

This is a deterministic depletion simulator. It answers: “Given inventory, on what specific date do I run out?”

The Algorithm

1. Initialize Remaining = Inventory.
2. Iterate through the DailyProjections array (generated in Phase 4).
3. For each day with demand :

• If : $Remaining=Remaining-D_i$ $\text{DaysCovered}=\text{DaysCovered}+1$
• If (Stockout): We calculate the partial day covered: $\text{DaysCovered}=\text{DaysCovered}+\left(\frac{Remaining}{D_i}\right)$ $Remaining=0$ BREAK Loop.

4. Final Output: $\text{WeeksSupply}=\frac{\text{DaysCovered}}{7}$

---

Related Implementations

• Usage: Used in the Generate Forecast Per SKU workflow.
• Source: calculateGapInventoryTarget function in the “Run Forecast Algorithm” node.