---
id: 3e9b5c41-6a27-4f7c-b0d8-9d2e6f1a8c73
name: Incorporate seasonality, trends, and special events
kind: ForecastEnhancement
cron: 0 0 6 * * *
analysis_window: 90d
comparison_periods: [7d, 28d]
---

Incorporate **seasonality, long-term trends, and special events** into sales forecasting to improve prediction accuracy and better reflect real-world demand fluctuations.

Process should analyze historical order behavior and adjust baseline forecasts to reflect **predictable seasonal patterns, demand trends, and event-driven demand changes**.

Output must contain **adjusted forecast data only**, without explanations or descriptions of methodology.

## Known Tables & Columns

### `curated.pos_orders`
- `created_at` (timestamp) - local order timestamp for time-based patterns
- `created_at_utc` (timestamp) - UTC timestamp when normalization is needed
- `business_date` (date) - business trading date
- `total` (decimal) - order revenue
- `service_channel` (varchar) - dine-in, pickup, delivery, or similar channel label when populated
- `fulfillment_channel` (varchar) - downstream fulfillment grouping when populated

### `curated.pos_order_items` (optional demand-mix enrichment)
- `order_id` (varchar) - join key to `curated.pos_orders.order_id`
- `item_id` (integer) - menu item identifier
- `quantity` (integer) - sold quantity
- `unit_price` (decimal) - observed sold unit price
- `category_name` (varchar) - sold item category when populated

### `curated.pos_menu_items` (optional metadata enrichment)
- `item_id` (integer) - menu item identifier
- `category_name` (varchar) - configured category

## Analysis Approach

1. Extract historical sales data from last **90 days** using `curated.pos_orders`.

2. Identify **seasonal demand patterns**, including:
   - weekday vs weekend behavior
   - recurring weekly cycles
   - recurring monthly demand patterns.

3. Detect **long-term sales trends**, such as:
   - gradual growth in revenue
   - gradual decline in demand
   - sustained shifts in purchasing behavior.

4. Detect **recent anomalies** within historical window such as:
   - unusual spikes or drops in sales
   - short-term effects caused by promotions or special events.

5. Use `business_date` as primary date dimension. Use `created_at` or `created_at_utc` when hourly or intraday alignment is needed.

6. Use `curated.pos_order_items` and `curated.pos_menu_items` only when item or category mix materially explains seasonality changes that are not visible from order totals alone.

7. Enrich dataset using **external signals**, including:
   - holidays and public events
   - seasonal periods
   - local events such as sports games or festivals.

8. Retrieve short-term contextual signals using `get_weather_forecast` to determine whether upcoming demand may deviate from historical baselines.

9. Evaluate how **past holidays and events affected demand**, identifying whether they caused:
   - revenue spikes
   - revenue drops
   - demand shifts between days or channels.

10. Adjust **baseline forecast values** to account for:
    - seasonal demand patterns
    - detected growth or decline trends
    - upcoming holidays or events
    - contextual signals such as weather.

11. Ensure adjustments remain **stable and realistic**, avoiding overfitting to short-term anomalies.

12. Output constraints:
    - return **adjusted forecast data only**
    - **do not include explanations, reasoning, or methodology**.

13. Minimize database usage:
    - prefer aggregated summaries
    - avoid requesting more than **3 queries** unless necessary.

## Output Format

Return **adjusted forecast values** reflecting seasonality, trends, and special-event demand effects.

No explanations or narrative text should be included in output.