Technical User Reference (Optimization - Forecast)
This logic contains some functions needed specifically for this Accelerator, such as reading its configuration from the application settings, applying the user filters in each part of the model, preprocessing the data for the charts, and many small helpers for the charts rendering. The elements ParametersUtils, TablesUtils, and LabelsUtils contain the names of many elements, tables and fields of the models.This section details the Model Class and the logics that the Forecast Accelerator deploys. Each step’s aim, outputs, and main reasons to modify the logics are explained. If there is a need to adjust the Python job, refer to Run Python Scripts.
In this section:
Forecast Model Class
The Forecast Model Class organizes a list of logics to create the model architecture. It is a JSON file that refers to some logics and it is transformed into an UI in the Pricefx platform that is organized in 5 steps:
Definition − Maps the transactions source and configures the model.
Additional Configuration − Allows the user to define up to 3 additional sources to be included in the model training data, defines the aggregation level for the forecasting, set the export parameters.
Model Training − Checks the quality of the model after its training and defines the elasticity settings.
Model Predictions − Forecasts quantity or revenue and shows prediction charts.
Export Forecast - Export the production values in a Data Source.
There are two types of logics: calculation, which writes tables in the model, and evaluation, whose purpose is only to display some results. The standard Model Class definition is documented in Model Class (MC).
All the logics of the Forecast Model Class follow a standard naming convention: first FCT_ prefix, then the step name, then calc or eval, depending on the formula nature, then the tab it is referring to.
Library
The logic is FCT_library.
Aim of the logic
This logic contains functions needed specifically for this Accelerator, such as reading its configuration from the application settings, applying the user filters in each part of the model, preprocessing the data for the charts, and many small helpers for the charts rendering. The elements ParametersUtils, TablesUtils, and LabelsUtils contain the names of many elements, tables and fields of the models.
Common reason to modify the logic
This lib is the place to change input names inside the model to reflect the user business vocabulary. LabelsUtils contains text that is shown in the UI, ParametersUtils and TablesUtilscontain table names and parameter names, respectively. Here you can also write functions to be used in different places of the model class.
Definition Step
This step runs one calculation and displays two tabs: Definition and Model Configuration.
Calculation: Generate the Parameter Table
The logic is FCT_1_Def_Calc_Fetch_Data.
Aim of the logic
This logic generates a parameter table containing default model training parameters and second parameter table, allowing advanced settings for some of the configurations. If the tables already exist, it does nothing.
Outputs of the calculation
The TrainingParametersand AdvancedConfiguration parameter tables.
Common reason to modify the logic
To change the default values in the tables, or add new parameters.
Definition Tab
The logics are FCT_1_Def_Eval_definition and FCT_1_Def_Eval_definition_configurator.
Aim of the logics
These logics define the Data Source and the mapping of the entries for the transactions, as well as some configuration of the outputs in the configurator. The main logic calls the configurator and the code for the dashboard portlets.
Outputs of the evaluation
Two portlets show the selected data fields for the in-scope and filtered-out transactions.
Common reason to modify the logics
The mapping could be changed if a field is removed or added. Default values of the configuration could be changed. A portlet may be added to the dashboard, to display a given information.
Model Configuration Tab
The logic is FCT_1_Def_Eval_model_configuration.
Aim of the logic
This logic defines more advanced configuration of the forecasting model.
Outputs of the evaluation
The inputs are stored to be used by the Python job which trains the model.
Common reason to modify the logic
Default values of the configuration could be changed. Add or remove the possibility for the end-user to change some model parameters.
Additional Configuration Step
This step doesn’t run any calculations. It displays two tabs: Additional Sources and Aggregation Level.
Additional Sources Tab
The logics are FCT_2_Add_Eval_additional_sources and FCT_2_Add_Eval_configurator.
Aim of the logics
These logics define the Additional Sources and the mapping of their fields to the fields of the source defined in the Definition step. The main logic calls the configurator and the code for the dashboard portlets.
Outputs of the evaluation
The user inputs are stored to be used to load the sources into model tables in the Model Training Step. The contents of the selected sources are displayed in portlets.
Common reason to modify the logics
Default values of the configuration could be changed.
Remove the possibility to add a kind of additional source.
Aggregation Level Tab
The logic is FCT_2_Add_Eval_aggregation_level.
Aim of the logic
It is a configurator definition that handles the aggregation levels but also the inputs for the export forecast data.
Outputs of the evaluation
The user inputs are stored to be used to define the granularity for the Model Training Step and the Export Forecast step.
Common reason to modify the logic
Replace the default values.
Model Training Step
This step runs the one calculation and displays the tabs Model Training Results, Train and Test Forecasts, Training Curves, and Elasticity Settings.
Calculation: Train the Model.
The logic is FCT_3_Train_Calc_TrainModel.
Aim of the logic
The aim of this logic is to gather the data and convert it into a form that can be used to train the forecasting model and store the results tables.
The Groovy elements are as follows:
Products, Customers - Create the tables Products and Customers, with the available products and customers in the model's scope, taking into account the minimum transactions for each product.
SplitFraction - Calculates the fractions of sales and the unit price for each product and each customer and saves it as a table called Split Weights. There are two fractions: revenue-based and quantity-based.
AggregationCheck - Basic consistencies are checked. Then the hierarchy between the features is calculated, to define which features can be kept or not in the training, once the aggregation is done.
DataQuery – This element takes the mapping and configuration from the Definition tab and defines a query on the source data that converts it from transactions to an aggregated time series for each product and customer. The query is then loaded into the Data model table.
DropExpiredTables – Drops the optional tables defined in the Additional Sources step to prevent them from being kept if the sources are removed.
LoadEventsTable LoadMappedAdditionalSourceTable, LoadMultiFeatureAdditionalSourceTable – These elements take the optional sources from the Additional Sources step and aggregate them to match the aggregation done to the source data in DataQuery.groovy before loading them into model tables.
Train – This element collects the configuration for the forecasting model and triggers the Python job.
The Python jobs are:
QuantityTrainScript.py and RevenueTrainScript.py – These elements are Python scripts that loads the data, further processes them to add new feature columns based on the Model Configuration tab inputs, and trains the machine learning model. Only one is used, depending on the model’s metric. The quantity train script is very close to the Multifactor Elasticity one. The revenue one is adapted for a revenue metric.
Outputs of the calculation
The Groovy elements output the tables: Products, Customers (if set), Split Weight (if meaningful), Aggregation Flag, Data, Events (if set), Mapped Additional Source (if set), and Multi Feature Additional Source (if set).
The trigger Python job triggered will write a set of model tables, including both the processed input data and the model results. It will also add a copy of the model as an attachment in a pickle file called model.pkl. This writing is done directly by the Python job and is not related to a Groovy logic.
The following tables are produced:
processed_data – Final input data after all preprocessing.
X_train, X_test, y_train, and y_test – Data split into training and test data.
train_preds and test_preds – Training and test set model predictions, respectively.
The tables with suffix _curve – Metrics data tables used for producing charts in the Model Training step.
model_parameters – Model parameters used for training.
shap_values – Data for the Feature Importances chart in the Model Training step.
metrics_table – Data for the Metrics table in the Model Training step.
events_encoded – If an events source is set in the Additional Sources step, the events are encoded into a form usable in model training and saved into this table.
Common reason to modify the logic
The scripts of this logic are rather complex and the advice is in general not to change them. Nevertheless, if you are a data scientist, you may modify the Python training script to adapt the machine learning pipeline to you scope.
Model Training Results Tab
The logic is FCT_3_Train_Eval_model_training_results.
Aim of the logic
This logic produces a dashboard with charts and a table to visualize the model results.
PredictVsActualTrain.groovy and PredictVsActualTest.groovy produce two similar charts for the model training data and test data, respectively.
Outputs of the evaluation
Five portlets. Four charts showing the feature importance, scatter plots of the model predictions vs. the historical metric for both the training and test data, and a timeline forecast chart. The display of the table “Metrics Table”, summarizing performance statistics.
Common reason to modify the logic
Add, modify or remove visualizations.
Train and Test Forecasts Tab
The logics are FCT_3_Train_Eval_train_test_forecasts and FCT_3_Train_Eval_configurator.
Aim of the logics
The configurator selects the dimensions to filter among the aggregation levels and the export key levels. It displays the forecast chart for the given set of filters.
Outputs of the evaluation
The forecast chart for the given scope.
Common reason to modify the logics
Modify the definition of the curves, add another portlet based on the user scope, remove user entries to define the scope to display. It would be difficult to add other filter user entries, because the data filtered to define the chart doesn’t have other meaningful fields to filter on.
Training Curves Tab
The logic is FCT_3_Train_Eval_training_curves.
Aim of the logic
These are technical charts for assessing the model training, for a data science purpose.
Outputs of the evaluation
Four portlets displaying the training curves for the three different metrics in the three _curve tables.
Common reason to modify the logic
Add another metric curve, if there is a change in the training script. It is also the best place to add vizualisations for a data science purpose.
Elasticity Settings Tab
The logic is FCT_3_Train_Eval_elasticity_settings.
Aim of the logic
This logic displays a configurator allowing the user to choose the settings for elasticity calculation in the Model Predictions step.
There is first a check box to allow the elasticity settings. It is clickable only for a quantity-based model, aggregated at the product level. If the elasticity setting is not checked, a mechanism saves the previous elasticity setting data, to be reused in case the elasticity calculation is set again.
Outputs of the evaluation
This logic saves the elasticity settings, but also the hidden ones from a previous set, in case of “Calculate Elasticities” unchecked.
These values are next used during the Model Predictions calculation.
Common reason to modify the logic
Default values of the configuration could be changed. Some parameters are hard-coded in the prediction scripts, they could be moved to a user entry.
Model Predictions Step
This step runs the two calculations and displays the tabs Overview and Details.
First Calculation: Results
The logic is FCT_4_Pred_Calc_results.
Aim of the logic
This calculation consists of the following steps:
FallbackProductsMinTransactions.groovy – If the calculation elasticity is set, and a fallback level in it, this element calculates the list of products which do not meet the minimum transaction threshold set in the Elasticity Settings tab of the Model Training step. The list of products is loaded into the fallback_products model table.
DropExpiredElasticityTables.groovy – This element drops expired elasticity tables if the “Calculate Elasticities” checkbox is unticked in the elasticity settings tab.
DropExpiredFallbackTable.groovy – This element drops expired fallback tables if the fallback level is not set in the Elasticity Settings tab.
Prediction.groovy – This element collects calculation parameters and triggers the Python job.
QuantityPredictionScript.py and RevenuePredictionScript.py – The script crorresponding to the metric is run. This element is a Python script that loads the data and then trains a final machine learning model using the parameters in model_parameters on the full dataset, producing a future forecast. If the elasticity is set, it then uses the predictions from this model to generate elasticity curves for each product and number of time periods of the forecast and fits a logistic ('S') curve to the data. The two script are very similar (except the elasticity part).
Outputs of the calculation
The Python job triggered in Prediction.groovy will write a set of model tables. This writing is done directly by the Python job and is not related to a Groovy logic.
The following tables are produced:
forecast – Future forecast outputs.
final_model_preds – Predictions of the final model on the training data.
If the elasticity is set, these tables are also produced:
simple_elasticity – The simple elasticity data to be used as the fallback for products that do not meet the minimum requirements chosen in the Elasticity Settings tab.
fallback_products – The products that do not meet the minimum transaction and minimum r² score requirements chosen in the Elasticity Settings tab.
elasticity_factors – Fitted curve parameters needed to reproduce the elasticity curves.
elasticity_data – Data used for plotting the elasticity curve charts.
elasticity_r2_scores – r² scores for the logistic curve fits.
Common reason to modify the logic
There is no reason to edit this in general. If you need another data structure to output, there is a postprocessing step.
Second Calculation: Postprocessing
The logic is FCT_4_Pred_Calc_post_proc.
Aim of the logic
This calculation precomputes the data needed for the summed forecast of all products portlet and stores it in a table. It is then loaded in the Overview Tab, leading to faster rendering and avoiding potential timeouts with large datasets.
It also splits the forecast data at the export keys level.
Outputs of the calculation
Table summed_forecast used in Overview tab.
Table Forecast Final used in Details tab and exported to a data source.
Table Past Dates Final used in Details tab.
Common reason to modify the logic
There are other precomputations to run to fasten the Results tabs display.
Overview Tab
The logic is FCT_4_Pred_Eval_overview.
Aim of the logic
This logic displays charts and tables for the general results of the forecast, and the elasticity if set.
Outputs of the evaluation
A portlet showing the summed forecast for the model scope.
If the elasticity is set:
Several histograms showing the distribution of the elasticity metrics.
Tables showing the elasticity and fallback elasticity data.
Common reason to modify the logic
To add, modify, or remove charts or tables.
Details Tab
The logics are FCT_4_Pred_Eval_details and FCT_4_Pred_Eval_configurator.
Aim of the logics
The configurator selects the dimensions to filter among the aggregation levels and the export key levels. It displays the forecast chart for the given set of filters, for the past and the future dates.
If the elasticity is set, it displays a table showing the forecast results of the elasticity calculation for the selected set of filters. If a product and a date are also selected, the corresponding elasticity chart is displayed.
Outputs of the evaluation
The portlets corresponding to the description above.
Common reason to modify the logics
To add, modify, or remove charts or tables.
Export Forecast Step
This step runs one calculation and displays one tab.
Calculation: Export Forecast Data Source
The logic is FCT_5_Export_Calc_ExportDS.
Aim of the logic
This calculation triggers a Python job able to push the table Forecast Final into a data source, using the parameters defined in step Additional Configuration, tab Aggregation Levels.
Outputs of the calculation
The data to export is first copied in a model table. It is a way to make some modifications, like getting the previous data if we want to append the data source, replace the renamed null values to nulls, and ensure the fields types.
Then, one of the two Python scripts is run. They are different, depending on the type of export: new data source vs. update existing one. It is the Python scripts which write the data source.
Common reason to modify the logic
There is no reason to edit this in general.
Dashboard
The logic is FCT_5_Export_Eval_Export_Configurator.
Aim of the logic
The dashboard is a configurator but the only button is only a shortcut to go to the data source created or updated by the calculation.
