This section details the Model Class and logics that the Product Recommendation Accelerator deploys. For each step, its aim, its outputs, and the main reasons to modify the logics are explained.

In this section:

Product Recommendation 2 Model Class

The ProductRecommendation V2 (PR2) ModelClass 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 optimized UI in the Pricefx platform. It is organized in 3 steps:

Definition – Maps the transaction source.
Configuration – Allows selection of different types of recommendations and their configuration.
Product Recommendations – Provides summary of calculated recommendations, and enables their exploration and manual adding of recommendations.

See Model Classes for more information.

Recommendation Types

There are seven recommendation types in PR2: Frequently Purchased, Others buy, Bought together, Similar products, Similar from another brand, Up-sell, and Down-sell. For details on each type, see Overview (Optimization - Product Recommendation).

We can group these recommendations in two ways:

Who are they producing recommendations for:
1. Recommendations for product (Product to product) – Bought together, Similar products, Similar from another brand, Up-sell, Down-sell
2. Recommendations for customer (Customer to product) – Frequently Purchased
3. Recommendations for segment (Segment to product) – Others buy
What information are they based on:
1. Transaction based – Frequently Purchased, Others buy, Bought together
  1. Customer based (Frequently Purchased and Others buy need additional information about customer)
2. Similarity based – Similar products, Similar from another brand, Up-sell, Down-sell

These groups are mentioned for two reasons. First, after calculation of each individual category, Product to product recommendations are aggregated into a single table, and shown together in a graph and table on the Review Recommendations tab. Second, what information are they based on is important for their configuration, and how they are grouped together there.

Optionality of Recommendation Types

In contrast with ProductRecommendation V1, every recommendation type is now optional, and can be either turned on or off, while the rest of model works normally.

Each calculation logic contains an element called EnabledCheck, this element cancels the calculation if the related recommendation is disabled. The element EnabledCheck is present in every calculation with the exception of DataPrep and PostProcessing, as those are not based around a single recommendation category. The following reference is written as if all categories are enabled, not discussing in each step what happens if they are not.

Disabled Recommendations

If some recommendation type is disabled, then:

If part of DataPrep depends on it, this part is skipped, i.e. there is no CustomerIds table if customer based recommendations are disabled, and no SegmentMapTable if Others buy is disabled.
Its calculation is skipped.
In PostProcessing if all product to product types are disabled, the AggregatedRecQuery element is skipped, otherwise the disabled category is not included in aggregation. The RecTypeSharedProductsCount table is created with all categories, even if they are disabled.
In the Summary tab the disabled type is not present in the portlet and graph.
Review Recommendations tab – If the customer based types are disabled, there is no input for customers. Disabled category is not present in the graph and among portlets. If some of product to product types are disabled, and some enabled, we still have product to product recommendations in the graph and in the portlet, as they are sourced from ProductAggregatedTable, which is missing only if all product to product recommendations are disabled.
Add Manual Recommendations tab – If the recommendation type is disabled, we are not able to add any valid manual recommendations for this type.
In Evaluation – If the name of a disabled category is passed as categoryName, an alert is created and null returned by the element ProductRecommendation. In AggregatedRecommendation (categoryName = 'aggregated'), the disabled type is not added to aggregation, even if it is explicitly mentioned among includedRecommendations.

Library

The logic is PR2_Lib.

PR2_Lib contains the following elements:

CustSegPyUtils – Script and values needed to generate customer segments using scikit-learn clustering.

DefinitionUtils – Contains functions allowing access to user defined values from steps Definition and Configuration.

QueryFormattingUtils – Tools for formatting numeric fields in SQL query.

LabelUtils – Contains text that is shown in the UI.

ManualRecommendationUtils – Tools used to read user defined manual recommendations.

ParameterUtils – Names of parameters used for naming of inputs and everywhere in the code.

SimilarityUtils – Names and tools associated with Product Similarity Model Class.

TableCreateUtils – Tools used to create tables used by model.

TableUtils – Names of tables and table fields used by model.

ValueUtils – Values used as defaults for inputs.

MixpanelUtils – Tools for tracking of model usage inside Mixpanel.

Change text visible to users in LabelUtils or in case of table / table fields names in TableUtils.

Change default values for inputs in ValueUtils. If the name of Product Similarity ModelClass or its relevant table or table field was modified, change SimilarityUtils accordingly.

Definition Step

This step allows selection of transaction source, and mapping of its fields.

The logics are PR2_Def_Eval_Scope and PR2_Def_Eval_Scope_Configurator.

These logics provide the user input to define a transaction source, filter it and map it. The main logic calls the configurator and the code for the dashboard portlets.

A dashboard shows the transactions in the scope and the filtered-out transactions. It is an evaluation logic, so nothing is written in the model, but the user inputs defining the data mapping are available in the next steps.

Add additional mappings.

Configuration Step

This step allows selection of different types of recommendations and their configuration.

The logic is PR2_Conf_Eval_Configuration_Configurator.

In this step, every recommendation type present in PR2 has its configuration section, allowing you to turn it on or off, and change additional settings, such as a number of recommendations or thresholds. Additional mappings of recommendation type specific fields of the source defined in the Definition step are present for customer based recommendations. For Similarity based recommendations, Product Similarity model has to be selected.

Every selected recommendation type is assigned a score weight in the input matrix at bottom of the page. Weights can be modified by users, and are used to aggregate multiple recommendation types together.

There is no output, but user inputs are stored and used in calculations in the next step.

Remove existing recommendation type option or add a new one – both would be fairly big modifications affecting whole Model Class. To change labels or default values present in the logic modify an appropriate element in PR2_Lib.

Product Recommendations Step

In this step, first all recommendations are calculated based on the previous user inputs. Then, three tabs are present, allowing users to explore results of those calculations and add manual recommendations. The Summary tab provides a summary for each recommendation type. The Review Recommendations tab allows users to observe recommendations for selected Products and Customers. In the Add Manual Recommendations tab additional recommendations can be manually added.

Calculation: DataPrep

The logic is PR2_Rec_Calc_DataPrep.

Store selected data from the transaction source and user input permanently in the model to preserve the state they were in when the model was calculated.

There are multiple elements each creating a table with data that is used in future calculations and evaluation:

CreateCustomerIdsTable and CreateProductIdsTable create a table mapping unique IDs to names for customers/products. If multiple names are associated to a single ID in the data source, latest name is kept and a warning is produced. Those tables are later used as a source of names for customer / product IDs.

CreateSegmentMap creates a table containing mapping of customer IDs to segment IDs. Based on configuration, it is either taken from the transactions source or it is model generated. If multiple segments are linked to a single customer in the transaction source, an exception is thrown. Model generated segmentation is created by a Python job: Python engine is triggered, using a script and configuration stored in the library element CustSegPyUtils.

CreateWeightsTable – Stores user inputted weights in the table.

Tables CustomerIds, ProductIds, SegmentMapTable and WeightsTable.

Add more data from the transaction source to be stored in the model tables. Modify how weight multipliers are created.

Calculation: LoadSimilarityMetaTable

Combines product information from the transaction source with similarity information from the Product Similarity model, creating a source table for all similarity based recommendations.

The logic is PR2_Rec_Calc_CreateSimProdSourceTable.

This logic creates a meta table used as a source for all similarity based recommendations. In SQL query, data from the transaction source is combined with data from the selected Product Similarity model. End result is a table containing pairs of products and coproducts with known similarity (taken from the PS model), and additional metrics (computed from the transaction source).

Table SimilarProducts_Source used as a source for all similarity based recommendations.

Modify contained SQL query to add additional fields / metrics to the created table, or remove unused ones.

Calculation: LoadSimilarRecommendations

The logic is PR2_Rec_Calc_CreateSimilarRecommendations.

This logic produces recommendations of type Similar products. In SQL query, it takes data from SimilarProducts_Source, ranks coproducts based on the score, and keeps only recommendations with similarity passing the configured similarity threshold and not exceeding the maximum number of recommendations.

Table SimilarProducts containing recommendations.

Modify contained SQL query to add additional fields to created table, or remove unused.

Calculation: LoadUpSellRecommendations

The logic is PR2_Rec_Calc_CreateUpSellRecommendations.

This logic produces recommendations of type Up-sell. In SQL query, it takes data from SimilarProducts_Source, ranks co products based on selected priority, and keeps only recommendations with similarity passing configured similarity threshold and not exceeding maximum number of recommendations.

Table UpSellProducts containing recommendations.

Modify contained SQL query to add additional fields to the created table, or remove unused ones.

Calculation: LoadDownSellRecommendations

The logic is PR2_Rec_Calc_CreateDownSellRecommendations.

This logic produces recommendations of type Down-sell. In SQL query, it takes data from SimilarProducts_Source, ranks coproducts based on the selected priority, and keeps only recommendations with similarity passing the configured similarity threshold and not exceeding the maximum number of recommendations.

Table DownSellProducts containing recommendations.

Modify contained SQL query to add additional fields to the created table, or remove unused ones.

Calculation: LoadBrandRecommendations

The logic is PR2_Rec_Calc_CreateBrandRecommendations.

This logic produces recommendations of type Similar from another brand. In SQL query, it takes data from SimilarProducts_Source, keep only records where the product brand matches the selected brand, and coproduction is of a different brand, ranks coproducts based on the selected priority, and keeps only recommendations with similarity passing the configured similarity threshold and not exceeding the maximum number of recommendations.

Table SimilarFromBrandProducts containing recommendations.

Modify contained SQL query to add additional fields to the created table, or remove unused ones.

Calculation: LoadProductRecommendations

The logic is PR2_Rec_Calc_CreateProductRecommendations.

This logic produces recommendations of the type Bought together.

In the element ProdAuxTable a temporary table is created, holding data about what baskets the product appeared in, together with count and margin.

In the next element ProductRecQuery by joining the temporary table itself, we are able to get pairs of products and coproducts that were bought together, with additional metrics, e.g. probability of concurrence, score, rank. By applying the user set limitations, the final recommendation table is created.

Temporary table ProdAuxTableNew which is dropped once the final table is created.

Table ProductRecommendations containing Bought together recommendations.

Modify contained SQL query to add additional fields to the created table, or remove unused ones.

Calculation: LoadCustomerRecommendations

The logic is PR2_Rec_Calc_CreateCustomerRecommendations.

This logic produces recommendations of the type Frequently purchased.

Initially we calculate in what percentage of customers purchases the product was purchased (probability) and other metrics. This information is used to calculate score, allowing for ranking, and creation of recommendations.

Table CustomerRecommendations containing Frequently purchased recommendations.

Modify contained SQL query to add additional fields to the created table, or remove unused ones.

Calculation: LoadSegmentRecommendations

The logic is PR2_Rec_Calc_CreateSegmentRecommendations.

This logic produces recommendations of the type Others buy.

The table SegmentMapTable is used to map each customer to a segment. The rest of the logic is analogous to the previous one, but instead of customers, we are using segments, calculating metrics for pairs of segments and products.

Table SegmentRecommendations containing Others buy recommendations.

Modify contained SQL query to add additional fields to the created table, or remove unused ones.

Calculation: PostProcessing

The logic is PR2_Rec_Calc_PostProc.

There are two elements in this logic, first one aggregates all product to product recommendations into a single table, the second one computes for two recommendation types the number of unique products recommended by both.

In the element AggregatedRecQuery for every pair of a product and recommended coproduct, we take the score of this pair from all recommendation types, apply weights to them to create a single aggregated score, and create a list of recommendation types it is coming from, and order by their partial scores.

In the element SummaryGraphMetricsQuery we create a table, which for every pair of recommendation types contains a sum of distinct product IDs recommended by both. This is later used in the graph on the Summary tab.

Table ProductAggregatedTable containing aggregation of all product to product recommendations.

Table RecTypeSharedProductsCount with the count of unique product IDs recommended by both, for every pair of recommendation types.

Update existing elements, add new elements with calculations taking place after all recommendation categories were computed.

Summary Tab

The logic is PR2_Rec_Eval_Summary.

This tab provides a summary of created recommendations. For each recommendation type, we calculate the total number of recommendations, and the number of unique eligible products / customers – i.e. those for which there are some recommendations. For segment specific recommendation (Others buy), the number of eligible customers belonging to the segment, and the number of segments is shown, together with total number of recommendations. This data is shown in the portlet.
In the network graph, the total number of recommendation is used, together with data from the table RecTypeSharedProductsCount. The resulting graph depicts each recommendation category as a point, sized based on the total number of recommendations, and linked to each other based on the number of unique products recommended by two categories.

Dashboard with a portlet and network graph.

To show additional information in the summary, add new recommendation categories, modify the graph.

Review Recommendations Tab

The logics are PR2_Rec_Eval_Review_Configurator and PR2_Rec_Eval_Review.

This tab allows users to check recommendations for specified product(s) and/or customer(s). The first logic is a configurator with two inputs, one for customers and one for products. There is no explicit input for a segment – segment(s) of the selected customer(s) are used.
The second logic generates portlets based on selected inputs:

Recommendation Results shows the total number of recommendations, their total and average score.
Network graph Recommended products from selection combines all recommendations into a graph, linking selected products, customers and segments to their recommended products. The link between the customer and the segment is also present.
Customer Specific: Recommended Products shows recommendations from Frequently Purchased.
Product Specific: Recommended Co-Products shows all product to product recommendations aggregated. [Bought together, Similar products, Up-sell, Down-sell, Similar from another brand]
Customer Segment Specific: Recommended Products shows recommendations from Others buy.
Customer Segment Details lists all customers in selected segment(s).

Configurator with inputs for customer(s) and product(s). Dashboard with portlets and network graph based on the selected inputs.

Select which fields from the recommendation tables are present in each portlet, as only the selected ones are visible. Modify the network graph.

Add Manual Recommendations Tab

The logic is PR2_Rec_Eval_Manual_Configurator.

This step allows users to manually add recommendations. It contains a configurator with three input matrices for manual recommendations. It is for categories Frequently purchased, Bought together and Others buy. Each matrix allows users to select a recommended product, score of that recommendation, and eligible customer / product / segment – one for which the recommendation is made.

Three inputs for manual recommendation. After they are saved via the Save Model button, manual recommendations are added to the calculated recommendations in the evaluation.

Possibly add a manual recommendations input for other product to product categories – this would be a significant change.

Evaluation

The model has a single evaluation ProductRecommendation_Eval.

The logic is PR2_ModelEval_ProductRecommendation.

It is a way for the models to communicate outside of themselves, in case of PR2, its main purpose is to provide calculated recommendations. It contains two different methods.

In the element ProductRecommendation recommendations are returned for a single selected recommendation category, as a list of ItemRecommendation objects. This is used by Product Recommendation API.

In the element AggregatedRecommendation multiple categories can be selected, recommendations from different categories are aggregated, and returned as a list of maps. Each map represents a single recommendation, and keys are mapped to values as ID, name, score, similarity, probability and list of categories. This can be used to directly connect the recommendations model to quotes, without Product Recommendation API, see: https://gitlab.pricefx.eu/components/demo/product-recommendations-in-quotes.

Sample of an evaluation call collecting results from the ProductRecommendation element:

api.model(NAME_OF_MODEL)?.evaluate('ProductRecommendation_Eval',
        [categoryName           : 'boughtTogether',
         customers              : [customerId],
         products               : [sku],
         excludedProducts: [],])?.ProductRecommendation

Explanation from the documentation:

This Model Evaluation method is called by Product Recommendation API used in quotes.
In each call, based on selected recommendation type, products and customers,
recommended items of that recommendation type are returned.
Required input:
    'categoryName' - for specifying type of recommendations that will be returned.
            valid names are : ['boughtTogether', 'Bought together', 'upSell', 'Up-sell', 'downSell', 'Down-sell', 'similarProducts', 'Similar products',
            'similarBrand', 'Similar from another brand', 'frequentlyPurchased', 'Frequently purchased', 'othersBuy', 'Others buy'].
            Each name have Internationalization translation key, with value to which it translates in quotes.
Optional inputs:
    'customers' - List of customers for which customer and segment based ('frequentlyPurchased' and 'othersBuy')
            recommendations are returned.
    'products' - List of products in quote for which product based recommendations ['boughtTogether', 'upSell',
            'downSell', 'similarProducts', 'similarBrand'] are returned.
    'excludedProducts' - List of products to be excluded from recommendations. In addition to 'excludedProducts',
            products already in quote (ones in 'products' input) are also excluded.

Output:
    Using in Quote:
        -List of ItemRecommendation objects (each contain product ID and score)
    Using for evaluation outside:
        -List of objects (each containing product ID, score, product name, probability, product rank, and similarity).

If we want to obtain results from AggregatedRecommendation, there are a few differences. Code example:

api.model(NAME_OF_MODEL)?.evaluate('ProductRecommendation_Eval',
        [categoryName           : 'aggregated',
         customers              : [customerId],
         products               : [sku],
         excludedProducts: [],
         includedRecommendations: [],
         excludedRecommendations: [],])?.AggregatedRecommendation

Differences:

categoryName ‘aggregated' is the only option for AggregatedRecommendation. The result from .evaluate() is then under the AggregatedRecommendation key, the matching element it is produced by.
By default all enabled recommendations are added to the aggregation. If the includedRecommendations list is provided, only those are added to the aggregation. Otherwise, if the excludedRecommendations list is provided, excluded ones are not added to the aggregation.
If Product is recommended to multiple customers, segments or products, only a single instance with the highest score is kept for each category and used for the customer, segment and product aggregation.
The output is a list of maps. Each recommendation is a single map with following keys:
- Product Id and Product Name
- Score – Aggregated for all enabled categories.
- Similarity– If product to coproduct similarity is known.
- Probability– Probability coming from the highest scoring among categories Bought together, Frequently purchased, Others buy.
- Recommendations Types – List of categories the recommendation comes from, ordered by their score in the descending order.
- Product Rank – Ranking of the recommended product based on the score, among all other products returned by this evaluation call.

Modify behavior of aggregation in AggregatedRecommendation, add more fields to the output.

Technical User Reference (Optimization - Product Recommendation)

Product Recommendation 2 Model Class

Recommendation Types

Optionality of Recommendation Types

Disabled Recommendations

Library

Definition Step

Configuration Step

Product Recommendations Step

Calculation: DataPrep

Calculation: LoadSimilarityMetaTable

Calculation: LoadSimilarRecommendations

Calculation: LoadUpSellRecommendations

Calculation: LoadDownSellRecommendations

Calculation: LoadBrandRecommendations

Calculation: LoadProductRecommendations

Calculation: LoadCustomerRecommendations

Calculation: LoadSegmentRecommendations

Calculation: PostProcessing

Summary Tab

Review Recommendations Tab

Add Manual Recommendations Tab

Evaluation