Calling forecast engines overview

This topic provides an overview of the requirements to call the forecast engines and to generate forecasts for the selected item or location, when using the CallForecastEngine command.

  • The user, or one of the user's roles, must have access to the macro as well the forecast engine contained in the engine name parameter. If not following error is raised by the macro on execution:

    Forecast engine {0} is not accessible to user {1}

  • Data security rules for the current user executing the macro apply when determining the item and location elements to pass to the Forecast Engine for calculation, based on the passed Item Hierarchy level and selection and Location Hierarchy level and selection. For example:
    • CallForecastEngine("BATS engine","","TUPLE_EXISTS","Brand","Brand A","Region","US","Months")
    • If the current user's data security does not allow them to see Brand A, or any base items under Brand A, in the item hierarchy then no selection will be passed to the engine. If the user can access a subset of base elements under Brand A then only these items will have forecasts generated.
    • If the current user's data security does not allow them to see US or any base locations under US in the location hierarchy then no selection will be passed to the engine. If the user can access a subset of base locations under US then only these locations will have forecasts generated.
    • If any period restrictions prevent them accessing the entire horizon of the cycle period, then only the subset of base periods with access will have engine results persisted. E.g. if a user is restricted to future base periods then any results written to historical periods would not be persisted.
  • The basic sequence for to prepare and call the forecast engine via the CallForecastEngine macro command is as follows:
    • Identify the forecast engine, type and default settings.
    • Determine the parameters for the passed forecast engine.
    • Invalid parameter settings will not be passed to the forecast engine for processing.
    • Missing mandatory parameters is not passed to the forecast engine for processing.
      Note: The parameters applies to all item/locations executed for a forecast engine so invalid values or missing mandatory parameters cancels processing with an error reported in the job manager and audit log.
    • Determine items and location selections to calculate.
    • Based on Forecast Engine measure mapping settings retrieve the appropriate scenario values to pass to the engine (all input mappings).
  • The system prepares and sequences the individual item and location calls to the forecast engine, passing the applicable parameter and measure values for each item and location. The process:
    • The system ensures that the history and weightings measures are linked to at least one period > 0, to generate a forecast. If not, the item and location is not passed to the forecast engine for processing and a Nothing to fit message is displayed.
    • For each item and location selection, you can determine the parameter settings, using the forecast engine parameters and the default parameter code list defined for the forecast engine.
    • Individual item and location calls to the forecast engine must be prepared and sequenced by passing the parameters, and the measure values applicable for each item and location call.
    • Based on the measure mapping settings defined for the forecast engine, you can retrieve the appropriate scenario values that must be passed to the engine (for History, History Mask, and Period Weighting input values).
      Note: Item and location combinations that use invalid parameter settings are not passed to the forecast engine for processing. The error in a parameter is reported only once for a parameter code list, in the discard log.
    • When the algorithm is not ‘Events Only’, perform the short history test to check the number of history data points after removing the leading zeros and user-defined masks, against the Short History parameter.
      Note: 
      • When history points < Short history parameter, the item/location is marked as short history and not passed to the forecast engine.
      • History value = 0 after the first non-zero period are added to the history vector as 0 and counted as part of the short history test.
      • Value of ‘1’ is written to the Short History Exception measure, if mapped in this forecast engine settings.
      • Item/locations count added to the Short History Exception is included in the Discard log.
    • If the history mask value is set (>0) for the cycle period history horizon, data is not available for the forecast. The item and location selection is not passed to the forecast engine for processing and an appropriate exception is logged in the discard log.
      • The forecast engine returns the items and locations (and periods) that contain an exception, because all the exceptions are based on an issue flagged during the last call to the forecast engine.
    • The measures mapped to the exception (Invalid Stat exception, Obsolescence, Outliers, Short History exception, Step Change exception, and Tracking Signal exception) output for each item and location that are passed to the forecast engine must be cleared.
      • When the engine is of the type ATT and the algorithm is HOLTWINTERS, LEASTSQUARES, MOVINGAVERAGE, or CROSTONS, and SMP measure = 0 or not defined, the forecast engine must be called with the fitModelGivenAlgorithm() bypassing the specified algorithm.
    • History and mask vectors must be of the same length.
      Note:  Mask values of 0 (or Null) for all periods are valid. This indicates that no periods are masked.
    • History values are normalized using the specified weighting measure prior to being passed to the engine.
  • When the forecast is generated, the system saves the forecast engine results for each item and location to the scenario values for the defined output measures, using the measure mappings settings. This includes:
    • Normalizing the forecast using the specified period weightings vector for the cycle period future horizon, prior to saving the forecast data.
    • Normalizing the Online Model Fit and Model Fitting History values using the specified period weightings vector for the cycle period history horizon, prior to saving the forecast data, if mapped.
    • If the Obsolescence exception is mapped to a measure for a specific forecast engine, performs an additional obsolescence check for each returned item and location:
      • Definition: The item and locations for which the forecasted level is negative (<0) in the cycle period future horizon (forecast periods).
      • Calculation: Level + (Growth * Forecast periods)< 0.
      • Obsolescence occurs only if Growth < 0. So, the item and locations for which Growth >=0 are not considered.
      • The modified macro steps or growth dampening is not included in the calculation.
      • 12 month future horizon = Level + (Growth * 12). If Level = 100, Growth=-10, this item and location is considered to be obsolete.
    • If mapped, the Seasonal Indices can be derived:
      • Applicable where the algorithm is Holt-Winters (or selected as Holt-Winters, by Best), and the resultant model form is seasonal. The type of seasonal indices returned are indicated by Seasonal Type.
      • This is returned as a vector of n numeric values, where n is the Periodicity passed to the forecast engine.
      • The value is to be written to the most recent n historical periods.
      For example: Forecast engine Periodicity=12 (months), Cycle Periodicity = Months, Cycle Period = FY14 M07. 12 Seasonal indices are applied to months FY13 M07 to FY14 M06.
      Note: Values are prorated to the level at which scenario values are stored, where applicable.
    • Results of the call to the forecast engine are updated to the periods of the cycle period future horizon, the cycle period history horizon, or as a static value to PCONST.
    • Forecast and Outlier, Step Change, and Tracking Signal Exceptions results (a vector of values) are written to the future periods of the cycle period forecast horizon.
    • Standard Deviation, Level, Growth, and Short History Exception results (a single value) are written to the PCONST element of the period dimension.
    • Normalized Model Fitting History and Online Model Fit results (a vector of values) are written to the historical periods of the cycle period history horizon.
  • The results of the CallForecastEngine macro are transferred to the job manager and audit log. The process:
    • The system generates a log file of additional information from the Forecast Engine output.
    • Item and locations without valid history, weighting, and mask input values are returned as Nothing to fit.
    • Item and locations without the valid parameter settings are returned with an error and incorrect values.
    • For each invalid parameter of a parameter code list, an error is logged in the parameter sets. For example, Parameter code list "Default BATS parameters" contains an invalid value (1): (2). 1= parameter, 2 = error
    • When an item and location combination that is not processed successfully is identified, using the validation or returned using the forecast engine with an error code, the error is logged in the discard log, with a detailed error message. For example, There is no non-zero history. A model cannot be fitted .
    • Forecasting exceptions are updated in the discard log for each exception in a job. This includes Short History, Obsolescence, Outliers, Tracking Signal, Step Changes, and Invalid Stat exceptions. For example, 22 item/ locations flagged as outliers.
Related topics