ForecastAllocation

Versions

1.0.0

v1.0.0

Basic Information

Class Name: ForecastAllocation

Title: Forecast Allocation

Version: 1.0.0

Author: Connor Stabnick

Organization: OneStream

Creation Date: 2024-02-28

Default Routine Memory Capacity: 2.0 GB

Description

Short Description

Distributes aggregate forecasts to more granular levels using historical patterns.

Long Description

Distributes summary-level forecasts to finer-grain allocation columns using historical patterns. Use when your forecast is at a higher level such as region, store, or category, but you need to drill down within that level (e.g. product/department/location).

Methods:

Simple spread — equal split when history is thin or you want an unweighted distribution.
Historical average allocation — each category's historical share when the mix is stable.
Lag-adjusted historical spread — uses recent, seasonally aligned history when the mix changes over time.

Add optional date groupings (Day Of Week, Month Of Year) to refine percentages. Simple spread and historical average support fallback groupings when a pattern is missing; lag-adjusted historical spread does not — those rows will have blank allocated values.

How long the routine takes depends on how much detail you need — not just the number of forecast categories you start with (pre-allocation), but also allocation columns and forecast periods. For example, 5,000 weekly forecast categories with 8 allocation columns over 26 weeks produces about 1 million result rows after allocation, not 5,000.

Sizes below refer to pre-allocation forecast categories (your input). This routine comfortably handles around 5,000 categories at weekly, daily, or monthly frequency with all three methods — including multi-year histories, forecast horizons up to a year, and up to roughly 100 allocation columns. Simple spread and historical average allocation scale the furthest, handling very large inputs of tens of thousands of categories (over 100 million result rows after allocation). Lag Adjusted Historical Spread is best for small-to-moderate datasets and is not recommended for the very largest daily workloads. For large or daily datasets, start with simple spread or historical average allocation. Note: yearly data must include at least three forecast periods.

Use Cases

1. Products Within Stores

Your forecast predicts total store sales, but planners need product-level estimates even though products were never forecast directly. Forecast Allocation breaks each store forecast into product-level values using how products historically contributed to store totals.

Setup: set historical dimension columns to match forecast dimensions (e.g., Store). Set allocation columns to the finer grain (e.g., Product). Match dimension columns between historical and forecast tables. Use Historical Average Allocation when product mix is stable; use Simple Spread for a quick equal split when history is thin. Add date allocation groupings (e.g., Month Of Year) when seasonality affects product mix.

2. Stores Within Regions By Month

Regional sales forecasts must be distributed to individual stores, and store performance varies by season. Forecast Allocation uses historical store share within each region — optionally refined by month — to produce store-level forecasts from regional totals.

Setup: dimension columns include Region (and any shared forecast dimensions). Allocation columns are Store. Add Month Of Year as a date allocation grouping when store mix shifts seasonally. Prefer Historical Average Allocation for stable mixes or Lag Adjusted Historical Spread when recent patterns matter more than long-run averages.

3. Sparse History, Cold Start, or Store Closures

Some forecast periods have no matching historical pattern — new stores, temporary closures, sparse date-grouping combinations, or missing dimension values. For Simple Spread and Historical Average Allocation, configure fallback date allocation groupings (e.g., fall back from Week Of Month + Week Of Year to Week Of Month only, then to dimension-only). The output Notes column records which fallback was applied. When all fallbacks fail, allocated values are null and Notes explains why. Lag Adjusted Historical Spread does not support fallbacks; use Simple Spread or Historical Average Allocation when sparse history is expected.

Routine Methods

1. Historical Average Allocation (Method)

Method: historical_average_allocation
- Type: Method
- Memory Capacity: 2.0 GB
- Allow In-Memory Execution: No
- Read Only: Yes
- Method Limits: This method has been tested up to ~24K pre-allocation targets / ~108M output rows (daily stress) at 15 GB memory. Output rows = targets × allocation columns × forecast periods. Weekly baseline (5,000 targets, 8 allocatables, 52/26 weeks) at 3 GB; 100 allocatables (~13M rows) at 3 GB. Default memory capacity 4 GB; increase for large daily workloads.
- Outputs Dynamic Artifacts: No
- Short Description:
  - Uses historical data to calculate average percentages for allocation columns.
- Detailed Description:
  - Choose this method when historical mix proportions are stable over your lookback window and you want each allocation column's share of historical totals applied to the forecast. Groups historical data by dimensions and allocation columns, sums values, and computes each allocation column's percentage of the dimension total. Multiplies forecast values by these percentages. Supports fallback date allocation groupings when primary patterns are missing; fallback usage is recorded in the output Notes column.
- Inputs:
  - Required Input
    - Data Definition: The base parameters for the allocation routine.
      - Name: allocation_base
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: AllocationParameters
    - Date Range Lookback Unit: Unit for the historical lookback window (Days, Weeks, Months, or Years). See step label for examples.
      - Name: date_range_lookback_unit
      - Tooltip:
        
        Detail:
        
        Calendar unit for the lookback window — independent of Data Frequency. For simple_spread and historical_average_allocation you may choose a different unit than your dataset granularity (e.g., Weekly data with Days × 364 for ~one year of history). The window filters by calendar dates, not row count. Lag Adjusted Historical Spread does not use this field; it uses Lookback Window and Lag in data periods instead.
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: DateRangeUnits_
    - Date Range Lookback Steps: Number of lookback units before the earliest forecast date.
      - Name: date_range_lookback_steps
      - Tooltip:
        
        Detail:
        
        How many Lookback Units to go back from the earliest forecast date. Only historical rows on or after that start date and before the forecast period are used. Example: Unit = Months, Steps = 12, earliest forecast = 2024-01-01 → history from 2023-01-01 through 2023-12-31.
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
- Artifacts:
  - Allocation Output: The dataset with the selected allocation having been applied.
    - Qualified Key Annotation: output_data
    - Aggregate Artifact: False
    - In-Memory Json Accessible: False
    - File Annotations:
      - artifacts_/@output_data/data_/data_<int>.parquet
        
        A partitioned set of parquet files where each file will have no more than 1000000 rows.

2. Lag Adjusted Historical Spread (Method)

Method: lag_adjusted_historical_spread
- Type: Method
- Memory Capacity: 2.0 GB
- Allow In-Memory Execution: No
- Read Only: Yes
- Method Limits: This method has been tested up to a weekly baseline (5,000 targets, 8 allocation columns) at 3–4 GB; extended to weekly (104/52 weeks) at 10 GB; daily (5,000 targets) at 15 GB. Daily stress (~24K targets, ~108M output rows) timed out — use Simple Spread or Historical Average Allocation at that scale. Default memory capacity 8 GB.
- Outputs Dynamic Artifacts: No
- Short Description:
  - Historical average allocation method with forecast lag adjustment.
- Detailed Description:
  - Choose this method when allocation mix drifts over time and you need seasonally aligned, recent rolling-window patterns matched to each forecast date's lag (best for moderate-sized datasets). For each forecast date, looks back by the configured lag and computes rolling sums over the lookback window. Calculates each allocation column's share within dimensions (optionally filtered by date allocation groupings). Multiplies forecast values by the resulting percentages. Important: Fallback date allocation groupings are NOT supported — unmatched forecast rows will have null Allocated Percent and Allocated Value. This method is significantly more memory- and CPU-intensive than the other methods.
- Inputs:
  - Required Input
    - Data Definition: The base parameters for the allocation routine.
      - Name: allocation_base
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: AllocationParameters
    - Lookback Window: The number of periods to look back in the historical data.
      - Name: lookback_window
      - Tooltip:
        
        Detail:
        
        The periods are based on the frequency of the data (ex: 1 would be 1 month for a monthly dataset).
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
    - Lag: Periods before each forecast date to anchor the window. This should match forecast lag.
      - Name: lag
      - Tooltip:
        
        Detail:
        
        Periods match data frequency (e.g., 52 = look back 52 weeks from each forecast date).
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
- Artifacts:
  - Allocation Output: The dataset with the selected allocation having been applied.
    - Qualified Key Annotation: output_data
    - Aggregate Artifact: False
    - In-Memory Json Accessible: False
    - File Annotations:
      - artifacts_/@output_data/data_/data_<int>.parquet
        
        A partitioned set of parquet files where each file will have no more than 1000000 rows.

3. Simple Spread (Method)

Method: simple_spread
- Type: Method
- Memory Capacity: 2.0 GB
- Allow In-Memory Execution: No
- Read Only: Yes
- Method Limits: This method has been tested up to ~24K pre-allocation targets / ~108M output rows (daily stress) at 15 GB memory. Output rows = targets × allocation columns × forecast periods. Weekly baseline (5,000 targets, 8 allocatables, 52/26 weeks) completes at 3 GB. Monthly (5,000 targets) at 2 GB. Default memory capacity 4 GB; increase for large daily workloads.
- Outputs Dynamic Artifacts: No
- Short Description:
  - Simple spread method for allocation.
- Detailed Description:
  - Choose this method when you have no reliable historical values or want an unweighted equal split across allocation columns. Evenly allocates forecast values to the historical table's allocation columns within the defined dimension columns. Any date allocation groupings are combined with dimension columns. The allocation percentage is 1 divided by the number of unique allocation values for each grouping. When primary groupings have no matching history, configured fallback groupings are tried, then dimension-only allocation. Fallback usage is recorded in the output Notes column.
- Inputs:
  - Required Input
    - Data Definition: The base parameters for the allocation routine.
      - Name: allocation_base
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: AllocationParameters
    - Date Range Lookback Unit: Unit for the historical lookback window (Days, Weeks, Months, or Years). See step label for examples.
      - Name: date_range_lookback_unit
      - Tooltip:
        
        Detail:
        
        Calendar unit for the lookback window — independent of Data Frequency. For simple_spread and historical_average_allocation you may choose a different unit than your dataset granularity (e.g., Weekly data with Days × 364 for ~one year of history). The window filters by calendar dates, not row count. Lag Adjusted Historical Spread does not use this field; it uses Lookback Window and Lag in data periods instead.
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: DateRangeUnits_
    - Date Range Lookback Steps: Number of lookback units before the earliest forecast date.
      - Name: date_range_lookback_steps
      - Tooltip:
        
        Detail:
        
        How many Lookback Units to go back from the earliest forecast date. Only historical rows on or after that start date and before the forecast period are used. Example: Unit = Months, Steps = 12, earliest forecast = 2024-01-01 → history from 2023-01-01 through 2023-12-31.
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
- Artifacts:
  - Allocation Output: The dataset with the selected allocation having been applied.
    - Qualified Key Annotation: output_data
    - Aggregate Artifact: False
    - In-Memory Json Accessible: False
    - File Annotations:
      - artifacts_/@output_data/data_/data_<int>.parquet
        
        A partitioned set of parquet files where each file will have no more than 1000000 rows.

Interface Definitions

No interface definitions found for this routine

Developer Docs

Routine Typename: ForecastAllocation

Method Name	Artifact Keys
`historical_average_allocation`	output_data
`lag_adjusted_historical_spread`	output_data
`simple_spread`	output_data

Versions​

v1.0.0​

Basic Information​

Tags​

Description​

Short Description​

Long Description​

Use Cases​

1. Products Within Stores​

2. Stores Within Regions By Month​

3. Sparse History, Cold Start, or Store Closures​

Routine Methods​

1. Historical Average Allocation (Method)​

2. Lag Adjusted Historical Spread (Method)​

3. Simple Spread (Method)​

Interface Definitions​

Developer Docs​