Technical User Reference (Optimization - Price Guidance)
The project contains a Model Class definition, the logics corresponding to the different calculations and dashboards, an internal library logic, shared components for cross-accelerator helpers, and the package definition to deploy the accelerator on Platform Manager.
Price Guidance Model Class
The Price Guidance Model Class organizes a list of logics to create the model architecture. It is a JSON file (ModelClass/Price_Guidance.json) that refers to some logics and is transformed into a UI in the Pricefx platform that is organized in 3 steps:
Definition - defines the user inputs of the modelling: data source and mapping, and the training-data-scope configuration (outliers threshold and test period).
Feature Preparation - reviews the feature importance and correlations, lets the user pick which features to train on, and collects the ML hyperparameters and monotonicity constraints.
Results - displays the outputs of the model training across four dashboards.
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 Price Guidance Accelerator follow a standard naming convention: PG_ prefix, then the step number and an abbreviation of the step name (Def, Fea, Res), then Calc or Eval depending on the formula nature, then the name of the tab.
Library
The logic in PG_Lib.
Aim of the logic
Contains the names and labels of important variables (ParametersUtils for parameter identifiers, LabelsUtils for user-facing labels). This way, adapting to the end-user vocabulary or renaming a parameter can be done from a single place.
General-purpose helpers are split across several scripts, for example:
GeneralUtils - common helpers (input access, model metadata, accelerator settings).
DefinitionUtils - helpers around the Definition step (source resolution, field mapping, target type checks).
EvaluationUtils - shared evaluation logic used by both the Evaluation tab and the model evaluation API.
FormattingUtils - metric-type-aware value formatting.
and others
Common reasons to modify the logic
Change names and labels in ParametersUtils / LabelsUtils to adapt to the end-user vocabulary.
EvaluationUtils can be modified to change how predictions are computed; changes apply to both the model evaluation API and the Evaluation tab dashboard. Modifying this requires care and is typically a data-scientist task.
Shared Components
Two library logics deployed from a shared Pfx Component at .PfxComponents/model-commons: PG_ModelCommons and PG_OptimizationCommons.
Aim of the logic
These libraries hold helpers shared across the Optimization accelerators (Win Rate, Negotiation Guidance, Price Guidance). Their content is maintained in a shared repository and imported as a Pfx Component into each accelerator.
Notably, PG_OptimizationCommons contains CurrencyUtils (currency conversion helpers used by Data Preparation), ConfiguratorUtils (shared configurator components), ColorUtils (color palette helpers), and other cross-accelerator utilities.
Common reasons to modify the logic
Shared libraries should not be modified locally - changes belong in the source repository. After re-importing the Pfx Component, the libraries land with unprefixed names and must be re-prefixed for Price Guidance:
The script renames the folders to PG_ModelCommons and PG_OptimizationCommons and updates their uniqueName in logic.json. It is a safe no-op if the libraries are already prefixed.
Definition Step
This step displays two tabs: Definition and Configuration.
Definition Tab
The logics are PG_1_Def_Eval_Definition and PG_1_Def_Eval_Definition_Configurator.
Aim of the logic
The configurator collects user inputs for the source, the field mapping, the Feature Candidates matrix, the Aggregation for Outlier Definition, and the default negative-value filters. The evaluation logic invokes the configurator and displays the in-scope and filtered-out transactions side-by-side.
Default values are pre-populated from the partition's accelerator settings, captured during the Data Mapping step of installation.
Outputs of the evaluation
The inputs of this step are accessible from the other logics via libs.PG_Lib.DefinitionUtils.
The dashboard renders two portlets: TransactionItemsInScope (transactions used for training) and FilteredOutTransactionItems (transactions excluded by the source filter or by the default negative-value filters).
Common reasons to modify the logic
Add or remove mapping fields. The Data Preparation calculation must also be adapted (see Feature Preparation Step > Calculation: Data Preparation).
Change the displayed tables or add another visualization.
Configuration Tab
The logic is PG_1_Def_Eval_Configuration_Configurator.
Aim of the logic
Sets the parameters that govern the training-data scope: the Outliers acceptable range (Tukey-style IQR multiplier) and the Number of days kept for the test set.
Outputs of the evaluation
The inputs of this step are accessible from the other logics.
Common reasons to modify the logic
Change defaults, or add/remove parameters governing the training-data scope. ML hyperparameters live in the Feature Preparation step's Model Configuration tab, not here.
Feature Preparation Step
This step runs two sequential calculations (data preparation and feature analysis) and displays two tabs: Feature Selection and Model Configuration. The calculations are triggered when entering the step from Definition.
Calculation: Data Preparation
The logic is PG_2_Fea_Calc_DataPreparation.
Aim of the logic
Materializes the in-scope training data, computes outlier bounds on the target metric (per group when an Aggregation for Outlier Definition is set, otherwise over the whole dataset), builds the transactions-over-time aggregation, and runs the currency-consistency and currency-conversion checks. Its outputs are consumed by the Feature Analysis calculation and the Feature Selection dashboard.
Outputs of the calculation
CheckCurrencyConversion - returns warning messages for currency pairs missing exchange rates in the source's date range.
CheckCurrencyConsistency - returns warning messages for NUMBER-typed monetary fields that will be skipped by currency conversion.
OutlierDefinition - resolves the outlier-detection inputs (target metric, IQR threshold, and the selected aggregation fields). The Tukey-style bounds ([Q1 − kIQR, Q3 + kIQR]) are then computed when the transaction table is built.
CreateTransactionTable - materializes the in-scope transactions table without outliers.
CreateOutlierTable - outputs the count of transactions outside the bounds (surfaced later in the Model Information portlet).
CreateFeatureAnalysisData - prepares the dataset consumed by the Feature Analysis Python script.
CreateTransactionsOverTimeTable - aggregates transactions by week.
Common reasons to modify the logic
Adjust the materialization (extra columns, derived fields), the outlier rule, or the warning checks.
Calculation: Feature Analysis
The logic is PG_2_Fea_Calc_FeatureAnalysis.
Aim of the logic
Runs a LightGBM-based feature-importance pass on the candidate features and stores the importance ranking, correlations, detected hierarchies, and the extended / by-unit classification of the numerical features. These outputs drive the Feature Selection dashboard.
Outputs of the calculation
CreateFeatureAnalysisTablePy - the Python script file (CreateFeatureAnalysisTablePy.py) that fits a LightGBM model and computes the feature-importance, correlation, and hierarchy outputs.
RunPython - triggers the Python script.
CreateFeaturePropertiesTable - classifies each numerical candidate feature as Extended or By Unit (via PG_OptimizationCommons.ExtendedValueUtils) and writes the feature_properties table.
Common reasons to modify the logic
Tune the LightGBM hyperparameters, change the importance rule, or add additional correlation or hierarchy heuristics. Changes to the Python script must keep its output schema in sync with the dashboard portlets that consume the tables.
Feature Selection Tab
The logics are PG_2_Fea_Eval_FeaturePreparation and PG_2_Fea_Eval_FeaturePreparation_Configurator.
Aim of the logic
Displays the outputs of the Feature Analysis calculation and embeds a configurator in which the user confirms the features to train on and sets the strategy.
Outputs of the evaluation
Portlets:
Candidate Feature Importance - bar chart of LightGBM importance.
Summary of the features - recommendation table built from feature_analysis and feature_properties.
Transactions Over Time - transaction counts tagged Train or Test.
Hierarchies - visualization built from feature_hierarchies and feature_hierarchies_edges.
Feature Interaction Data - table of all feature pairs from feature_correlations.
Feature Interactions Chart - dependency-wheel visualization of the strongest interactions.
Warnings - banner displayed with the Summary of the features portlet when the currency checks raise issues.
The chosen features for training are accessible via libs.PG_Lib.ConfigurationUtils.
Common reasons to modify the logic
Add or remove portlets, change the recommendation rule, or change which columns are surfaced in the Summary of the features table.
Model Configuration Tab
The logic is PG_2_Fea_Eval_ModelConfiguration_Configurator.
Aim of the logic
Collects the training parameters, the monotonicity constraints and the manual feature binning that the Training calculation reads
Collects the parameters that govern the EBM training: Maximum Number of Training Iterations, Early Stopping, Smoothing Iterations, Number of Pairwise Adjustments, and Pairwise Smoothing Iterations.
It also collects Monotonicity Constraints, an input matrix that lists numerical features and the direction (Increasing or Decreasing) in which their impact should be constrained.
Finally, it collects Feature Binning, an optional matrix pairing a numerical feature with a binning method (Uniform, Uniform Log, Percentiles, Long Tail, Custom) and a number of bins. The Feature Binning matrix, its per-row validation, and the bin-edge maths come from PG_OptimizationCommons.BinningUtils.
Outputs of the evaluation
Three configurator entries, one per element:
ModelParameters - Maximum Number of Training Iterations, Early Stopping, Smoothing Iterations, Number of Pairwise Adjustments, Pairwise Smoothing Iterations, and the Learning Rate Autoscaling checkbox. Learning Rate Autoscaling Reference and Factor appear only while the checkbox is on.
MonotonicityConstraints - input matrix setting a numerical feature as Increasing or Decreasing.
FeatureBinning - input matrix pairing a numerical feature with a binning method (Uniform, Uniform Log, Percentiles, Long Tail, Custom) and a number of bins.
Rarely changed parameters live outside the configurator in the Advanced Parameters lookup table (max_pairwise_combinations, greedy_ratio, coverage_tolerance, normalize_target, crossing_guard_epsilon, learning_rate_override).
Common reasons to modify the logic
Change defaults, or add/remove parameters; if adding parameters, adapt TrainScript.py accordingly.
Results Step
This step runs a training calculation and displays four tabs: Metrics, Feature Impact, Pairwise Impact, and Evaluation.
Price Levels and Models
The selected Strategy decides how many models are trained.
Target Only trains a single model that predicts the target metric directly.
Floor/Target/Stretch trains three models, one per price level, each predicting a different percentile of the target metric, plus a fourth reference model used only to harmonize the pairwise interactions.
Two related registries in PG_Lib.ConfigurationUtils describe this and must not be confused:
Model key - what data is filed under: the model_key column of every training output table. floor, target, stretch, reference. Every price level is mapped to a model, but not every model has a price level.
Calculation: Training Preprocessing
The logic is PG_3_Res_Calc_Training_Preprocessing.
Aim of the logic
Builds the training data, resolves the training parameters, and creates the output tables the Python jobs write into. It also provides the training Python script to be reused in the following logics.
Outputs of the calculation
ConstantFeatures - features that are null or constant in the training data. These are excluded from training and reported in the Model Information portlet.
CategoricalFeatures - list of categorical features used by the training script.
NumericalFeatures - list of numerical features used by the training script.
IsNormalizeTargetEnabled - whether the target is z-score normalized before fitting. Normalization applies to the corridor strategy only and can be switched off through the normalize_target Advanced Parameter.
ComputeLearningRate - resolves the effective learning rate.
CreateFeatureBinsTable - when feature binning is configured, computes each binned feature's bin edges and writes the feature_bin_lookup table.
CreateTrainingData - builds the training_data table from the in-scope transactions after applying the selected-features list and outlier removal. Binned features are replaced by their bin center, with out-of-range values clipped to the nearest bin. A mapped Weight field is carried in as an additional Transaction Weight column.
StoreCategoricalValues - outputs the list of values per categorical feature. Used to avoid additional table queries in the Results tabs.
CreateTrainingOutputTables - creates the shared training output tables (see Training Output Tables) before any job starts, so the parallel jobs only ever append to tables that already exist.
TrainScript - the Python script file (TrainScript.py) implementing the EBM training.
Common reasons to modify the logic
Adjust the materialization (extra columns, derived fields), change how a training parameter is resolved, or add a pre-training check. Changing an output table's fields means changing TableUtils and TrainScript.py together - the table definitions are the contract between them.
Calculation: Training Reference
The logic is PG_3_Res_Calc_Training_Reference.
Aim of the logic
Trains the reference model that fixes one shared set of pairwise interactions for the corridor. The reference model is trained with the same features, parameters, monotonicity constraints and normalization as the quantile models, but with the standard RMSE objective. The selected feature pairs are then used as fixed pairs for the corridor models.
Outputs of the calculation
TrainReference - triggers the reference Python job and returns its parameters. It writes to the same shared tables as other models under model key reference.
Common reasons to modify the logic
Change which parameters the reference model shares with the quantile models, or the condition under which it is trained at all.
Calculation: Training
The logic is PG_3_Res_Calc_Training.
Aim of the logic
Triggers the Python training jobs depending on the strategy:
Target Only - one job, model key target, no quantile level, RMSE objective
Floor/Target/Stretch - one job per price level, each receiving its own quantile_level (the configured percentile divided by 100) and model key. When a reference model was trained, its pair list is passed to every job, so no quantile model selects feature pairs of its own.
The jobs run concurrently where platform capacity allows. There is no data dependency between them, they write into the same tables but with different model_key.
A corridor job whose achieved coverage on the test set differs from its requested percentile by more than the coverage_tolerance (set in Advanced Parameters) fails, so a miscalibrated model never becomes the live corridor.
Outputs of the calculation
Train - triggers the Python jobs and returns the parameters of each, keyed by job name.
The jobs write the shared training output tables described below. The target job additionally exports training_predictions table, holding the EBM own predictions on the training rows, for comparison against the evaluation logic.
Common reasons to modify the logic
Adapt TrainScript.py for new hyperparameters or new outputs - remember to push results either to the calculation outputs or to model tables. Add additional pre-training checks. Change how the job set is derived from the strategy, for example to add a further price level.
Calculation: Training Postprocessing
The logic is PG_3_Res_Calc_Training_Postprocessing.
Aim of the logic
Validates what the training jobs wrote, then scores the historical transactions with the finished model and builds the aggregations the Results tabs display.
Outputs of the calculation
ValidateTrainingOutputs - fails when the rows stored per table and model key do not match what each job reported writing. The jobs append to shared tables concurrently, so this guards against lost or duplicated rows caused by parallel write.
ScoreAndReviewTransactions - streams transaction_data, predicts every price level for each transaction in batches, and merges the predictions back into transaction_data. It accumulates the feature review counters in the same pass and writes the feature_review table, which drives the share-of-transactions chart on the Feature Impact tab.
CreateChangeHistogramTable - the distribution of the price change between the historical and the predicted value, in the change_histogram table.
CreateRevenueProfitSummaryTable - historical versus estimated revenue and profit, in the revenue_profit_summary table.
Common reasons to modify the logic
Add an analytics table over the scored transactions, or change how strictly the training outputs are validated.
Training Output Tables
Each output table exists exactly once, with a model_key dimension column identifying the model that wrote the row. The Target Only strategy writes the same schema with target rows only.
Feature Importance - bar chart of the importances table, target model only. Low importances are not plotted.
Metrics - displays model metrics from the metrics table. The reference model is excluded.
Change Overview
Revenue and Profit Comparison - historical versus estimated revenue and profit.
Model Information - information about each trained model. For a reference model, also displays its selected feature pairs and RMSE and MAE metrics.
Common reasons to modify the logic
Standard portlets; modify or add as needed.
Feature Impact Tab
The logics are PG_3_Res_Eval_FeatureImpact and PG_3_Res_Eval_FeatureImpact_Configurator.
Aim of the logic
Displays the model's impact decomposition for a chosen featuree, and under the Floor/Target/Stretch strategy how the historical transactions fall across the corridor for each of its values.
Outputs of the evaluation
Feature Impact - a chart driven by the shared feature_impact_numerical and feature_impact_categorical tables: shows a line per price level plus the transaction counts. Floor and stretch adjustments are shifted by their model's intercept gap against the target model, so the three lines share one baseline. The stored tables keep the raw values.
Share of Transactions - Floor/Target/Stretch only, driven by the feature_review table. For each value, displays the share of transactions below floor, between floor and target, between target and stretch and above stretch.
Common reasons to modify the logic
Adapt the chart styling or add additional information about each feature.
Pairwise Impact Tab
The logics are PG_3_Res_Eval_PairwiseImpact and PG_3_Res_Eval_PairwiseImpact_Configurator.
Aim of the logic
Displays the model's joint impact heatmap for a chosen pair of features.
Outputs of the evaluation
A heatmap driven by the pairwise_heatmap table produced by the Training Python script. Under Floor/Target/Stretch strategy, the other two price levels impacts are added to every cell, matched on grid position and floor and stretch impacts are shifted by their intercept gap against the target model.
Under Floor/Target/Stretch strategy, the configurator offers a Price Level input (Floor/Target/Stretch only, default Target). The same pairs exist at every price level, because all three models train on the pair list fixed by the reference model.
Common reasons to modify the logic
Adapt the chart styling or add additional information about each feature pair.
Evaluation Tab
The logics are PG_3_Res_Eval_Evaluation and PG_3_Res_Eval_Evaluation_Configurator.
Aim of the logic
Reproduces what the target_prediction model evaluation API does for a single user-supplied set of feature values, and displays the prediction together with its drivers.
Outputs of the evaluation
Two portlets (Overview and Target Drivers) computed via the shared libs.PG_Lib.EvaluationUtils library. The same library backs the model evaluation API, so the dashboard and the API produce identical results for identical inputs.
Common reasons to modify the logic
For display-only changes, modify this logic. For changes that should also affect the API, modify EvaluationUtils instead.
The logic is mostly based on the library element EvaluationUtils. To modify a calculation, change the library so the modification is shared between the API and the Evaluation tab.
The evaluation scores one model per price level. For a Target Only model it is the target model alone, for a Floor/Target/Stretch model it is the floor, target and stretch models. The reference model has no price level and is deliberately never scored. For each evaluated item and each of those models, the prediction is the model's base value plus the sum of every feature's and pair’s contribution. The base value is the model's intercept plus its conformal offset. The contributions are computed by libs.PG_Lib.ImpactUtils which the Evaluation tab also uses, so the API and the tab return identical drivers and predictions for the same input. The impact tables are read once per call and reused across all items, so evaluating a batch costs the same queries as evaluating one item.
Corridor and the crossing guard
For a Floor/Target/Stretch model, the three predictions are computed independently and can therefore come out in the wrong order. The crossing guard restores the ordering by moving the bounds:
the low bound is pulled to at most target − crossing_guard_epsilon
the high bound is pushed to at least target + crossing_guard_epsilon
Value of crossing_guard_epsilon is configurable in Advanced Parameters table. The predictions are stored in the target metric's own units, so for an inverse metric such as Discount %, the floor is the numerically larger value.
Binning
When the model uses manual feature binning, the input value is first mapped to its manual bin's center. The resulting value is then looked up against the model's own bins, taking the last bin whose lower bound is at or below it. Values below the first bin fall into the first bin, and values above the last fall into the last. This mirrors the binning applied to the training data, keeping evaluation consistent with how the model was trained.
Invoking target_prediction evaluation
Evaluation can be invoked via the model API as follows:
Each item must contain key - a string identifier used to correlate input with output.
Feature values are optional. How a missing value is treated depends on whether the feature is present in the item at all:
Feature not present - it contributes nothing to the prediction.
Categorical feature, passed as null or as an empty string - treated as the explicit Null value category, contributing the impact the model learned for rows where that feature was empty during training.
Numerical feature, passed as null - contributes the impact the model learned for rows where that feature was empty during training.
A categorical value that was not seen during training contributes nothing. A numerical value outside the trained range is clamped to the nearest bin.
Result structure
The evaluation returns a Map with:
BasePredictedTarget, BasePredictedFloor, BasePredictedStretch: each model's base value before any feature contributions are added. For a Target Only model, only BasePredictedTarget is populated.
ItemResults: a list of per-item results, each as a Map:
key - the same identifier passed in the input.
predicted_target - the predicted value of the target metric.
predicted_floor, predicted_stretch - the corridor bounds, after the crossing guard. Included in Floor/Target/Stretch models only.
corridor_clamped - true when the crossing guard moved a bound for this item. Included in Floor/Target/Stretch models only.
currency - included only when the chosen Metric Type is monetary (Unit Price or Unit Margin), set to the model's currency.
Example response for a Floor/Target/Stretch model:
Additional elements can be made visible to expose their values to code outside of the model. And as in any Model Class, additional model evaluations can be added to access any calculation based on a model from another piece of code.
