CreateContentBasedRecommender — Analysis Tool Box

Introduction

Matching users to items — patients to clinical trials, candidates to jobs, readers to reports — is hard when you can't rely on collaborative signals like "people who liked X also liked Y," either because interaction history is sparse or because new users and items need recommendations from day one. CreateContentBasedRecommender builds a two-tower (dual-encoder) neural network that solves this from features alone: one neural network encodes user attributes, another encodes item attributes, both are mapped into a shared embedding space, and the model learns to predict interaction strength from the dot product of those embeddings — so it generalizes to new users and items as long as their features are available.

Teaching Note

Content-based recommenders are essential for:

Matching patients to suitable clinical trials based on EHR and trial criteria
Recommending public health interventions to specific demographic segments
Suggesting relevant intelligence reports to analysts based on interest profiles
Personalized educational content delivery based on student learning styles
E-commerce product recommendations using item metadata and user browse history
Job-to-candidate matching using skill sets and job descriptions
Routing emergency resources based on geographic and situational metadata
Alerting intelligence officers to relevant temporal patterns in signal data

Parameters

Parameter	Type	Default	Description
`dataframe`required	`pd.DataFrame`	—	The dataset containing user features, item features, and the outcome variable.
`outcome_variable`required	`str`	—	The name of the column representing the target interaction (e.g., 'rating', 'clicks').
`user_list_of_predictor_variables`required	`list`	—	A list of column names representing user-specific attributes (e.g., 'age', 'location').
`item_list_of_predictor_variables`required	`list`	—	A list of column names representing item-specific attributes (e.g., 'category', 'price').
`user_number_of_hidden_layers`	`int`	`2`	Number of dense layers in the user feature tower. Defaults to 2.
`item_number_of_hidden_layers`	`int`	`2`	Number of dense layers in the item feature tower. Defaults to 2.
`number_of_recommendations`	`int`	`10`	The dimensionality of the shared embedding space (output of each tower). Defaults to 10.
`test_size`	`float`	`0.2`	The proportion of data to reserve for the test set (0 to 1). Defaults to 0.2.
`scale_variables`	`bool`	`True`	Whether to standardize input features and scale the outcome variable (MinMax to [-1, 1]). Highly recommended for neural network convergence. Defaults to True.
`plot_loss`	`bool`	`True`	Whether to display a plot of the training loss over epochs. Defaults to True.
`plot_model_test_performance`	`bool`	`True`	Whether to display a scatter/regression plot comparing predicted vs. actual outcomes. Defaults to True.
`print_peak_to_peak_range_of_each_predictor`	`bool`	`False`	Whether to print the range (max - min) of each input variable. Defaults to False.
`initial_learning_rate`	`float`	`0.01`	The learning rate for the Adam optimizer. Defaults to 0.01.
`number_of_steps_gradient_descent`	`int`	`50`	The number of training epochs. Defaults to 50.
`lambda_for_regularization`	`float`	`0.001`	L2 regularization penalty applied to dense layers. Defaults to 0.001.
`random_seed`	`int`	`412`	Seed for reproducibility of weights and data splitting. Defaults to 412.

Returns

If scale_variables is True, a dictionary containing 'User Scaler' (fitted StandardScaler for user features), 'Item Scaler' (fitted StandardScaler for item features), 'Outcome Scaler' (fitted MinMaxScaler for the outcome), and 'Model' (the trained tf.keras.Model). If scale_variables is False, returns only the trained Keras model.

Example

python

from analysistoolbox.prescriptive_analytics import CreateContentBasedRecommender
import pandas as pd

# Healthcare: recommending clinical trials to patients
trial_data = pd.DataFrame({
    'patient_age': [25, 45, 65, 30, 55],
    'patient_severity': [2, 5, 8, 3, 6],
    'trial_phase': [1, 2, 3, 1, 2],
    'trial_risk_level': [0.1, 0.4, 0.7, 0.2, 0.5],
    'fit_score': [0.8, 0.6, 0.9, 0.7, 0.5]
})
results = CreateContentBasedRecommender(
    dataframe=trial_data,
    outcome_variable='fit_score',
    user_list_of_predictor_variables=['patient_age', 'patient_severity'],
    item_list_of_predictor_variables=['trial_phase', 'trial_risk_level'],
    number_of_steps_gradient_descent=100
)