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:

Bash

./.PfxComponents/model-commons/prefix-libraries.sh PG

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 provides an embedded configurator (the “Select features” input matrix) for the user to confirm which features to train on.

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.
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 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

The inputs are accessible from the Training calculation.

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.

Calculation: Training

The logic is PG_3_Res_Calc_Training.

Aim of the logic

Prepares the training data and triggers the EBM Python training. The Python script learns the target metric as a sum of per-feature shape functions plus the selected pairwise interactions, with optional monotonicity constraints on numerical features.

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.
CreateFeatureBinsTable - when feature binning is configured, computes each binned feature's bin edges (from MIN/MAX for the uniform methods, or from sampled percentiles for the percentile and long-tail methods, or from the user's custom edges) and writes the feature_bin_lookup table, which maps each bin to its lower edge, upper edge, and center.
CreateTrainingData - builds the training table from the in-scope transactions after applying the selected-features list and outlier removal. When feature binning is configured, each binned feature's value is replaced by its bin center via a range join to feature_bin_lookup, with out-of-range values clipped to the nearest bin. When a Weight field is mapped in the Definition step, it is carried into the training table 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.
TrainScript - the Python script file (TrainScript.py) implementing the EBM training.
Train - triggers the Python job. Registered as training:py-train in the job tracker.
feature_score_<featureName> and feature_density_<featureName>, and per-pair tables pairwise_impact_<featureName1>_<featureName2> and heatmap_<featureName1>_<featureName2>. A metrics table holds the training-set and test-set performance metrics (R², Bias, …).

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.

Metrics Tab

The logic is PG_3_Res_Eval_Metrics.

Aim of the logic

Displays global information about the trained model and its performance.

Outputs of the evaluation

Portlets only: Feature Importance, Metrics, and Model Information.

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 feature.

Outputs of the evaluation

Two charts (Score on top, Density on bottom) driven by the feature_score_<featureName> and feature_density_<featureName> tables produced by the Training Python script.

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 heatmap_<featureName1>_<featureName2> tables produced by the Training Python script. Only pairs that were learned by the model are valid; the configurator filters Feature 2 to valid partners for the chosen Feature 1.

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.

Model Evaluation

The model class has an evaluation called target_prediction, implemented in the logic PG_Model_Evaluation. It can be called from any place in the solution - see Business User Reference (Optimization - Price Guidance) | Model Evaluation for the user-facing description.

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.

For each evaluated item, the prediction is the model's baseline (BasePredictedTarget) plus the sum of every feature's contribution. The contributions are computed by libs.PG_Lib.FeatureImpactUtils, which the Evaluation tab also uses, so the API and the tab return identical drivers and predictions for the same input.

When the model uses feature binning, each input value is first assigned to its feature's bin (mapped to the bin center, with out-of-range values clipped to the nearest bin) before its contribution is read. This mirrors the binning applied to the training data, keeping evaluation consistent with how the model was trained.

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.

Invoking target_prediction evaluation

Evaluation can be invoked via the model API as follows:

Groovy

api.model("My Price Guidance Model").evaluate("target_prediction", [
  items: [
    [key: "item1", customer_segment: "Premium", quantity: 10],
    [key: "item2", customer_segment: "Standard", quantity: 5],
  ]
])

items: a list of input items, each as a Map.
- Each item must contain key - a string identifier used to correlate input with output.
- Feature values are optional - any feature included contributes to the prediction; omitted features contribute nothing.
- There is a deliberate distinction in how missing values are treated:
  - Omitted, or passed as null - the feature contributes nothing to the prediction (as if it had no impact).
  - Passed as an empty string "" - for a categorical feature, this is treated as the explicit Null value category and contributes the impact the model learned for rows where that feature was null during training.

Result structure

The evaluation returns a Map with:

BasePredictedTarget: the model's baseline value before any feature contributions are added.
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.
- currency - included only when the chosen Metric Type is monetary (Unit Price or Unit Margin), set to the model's currency.

Example response:

JSON

{
  "BasePredictedTarget": 33.17655343263911,
  "ItemResults": [
    {
      "key": "item1",
      "predicted_target": 33.17655343263911,
      "currency": "EUR"
    }
  ]
}