Basic RC‐MF command

Run the following command from the repository root:

python experiment_runner.py \
    --dataset Beauty \
    --epochs 100 \
    --seed 0 \
    --models rc_mf

This command trains RC-MF using the default configuration defined in:

config/model_search_spaces.yml

Command-line arguments

Argument	Description	Default
--dataset	Dataset identifier recognized by the data loader	Required
--epochs	Number of model-training epochs	50
--seed	Random seed	0
--models	Models to train and evaluate	All registered models
--use_bo	Enable Bayesian optimization	Disabled
--use_gridsearch	Enable grid search	Disabled
--config_path	Model-search configuration file	config/model_search_spaces.yml

Bayesian optimization and grid search cannot be enabled simultaneously.

Run without hyperparameter optimization

When neither --use_bo nor --use_gridsearch is provided, the runner uses the model's default parameters.

python experiment_runner.py \
    --dataset Beauty \
    --epochs 100 \
    --seed 0 \
    --models rc_mf

This mode is useful for:

• testing the installation;
• checking data loading;
• debugging the model;
• running a fast baseline experiment;
• reproducing a fixed configuration.

Run with Bayesian optimization

Enable Bayesian optimization with:

python experiment_runner.py \
    --dataset Beauty \
    --epochs 100 \
    --seed 0 \
    --use_bo \
    --models rc_mf

The Bayesian-optimization search may include:

• learning_rate;
• lambda_reg;
• lam_user_calib;
• lam_item_calib;
• lam_group_calib;
• n_user_groups;
• n_item_groups;
• clip_correction;
• use_oof_calibration.

The exact search ranges and optimization budget are read from:

config/model_search_spaces.yml

The selected configuration is saved in:

results/Beauty/seed_0/rc_mf/Beauty_best_params.json

Run with grid search

python experiment_runner.py \
    --dataset Beauty \
    --epochs 100 \
    --seed 0 \
    --use_gridsearch \
    --models rc_mf

Grid search and Bayesian optimization cannot be requested in the same run.

Compare RC-MF with standard matrix factorization

python experiment_runner.py \
    --dataset Beauty \
    --epochs 100 \
    --seed 0 \
    --models rc_mf cornac_mf

With Bayesian optimization:

python experiment_runner.py \
    --dataset Beauty \
    --epochs 100 \
    --seed 0 \
    --use_bo \
    --models rc_mf cornac_mf

Run RC-MF on multiple random seeds

The runner processes one random seed per execution.

for seed in 0 1 2 3 4 5 6 7 8 9
do
    python experiment_runner.py \
        --dataset Beauty \
        --epochs 100 \
        --seed "$seed" \
        --models rc_mf
done

With Bayesian optimization:

for seed in 0 1 2 3 4 5 6 7 8 9
do
    python experiment_runner.py \
        --dataset Beauty \
        --epochs 100 \
        --seed "$seed" \
        --use_bo \
        --models rc_mf
done

Run RC-MF on multiple datasets

for dataset in Beauty Appliances Fashion GiftCards Health Magazine Music ml100k
do
    python experiment_runner.py \
        --dataset "$dataset" \
        --epochs 100 \
        --seed 0 \
        --models rc_mf
done

Residual-calibration settings

The RC-MF class supports the following main parameters.

Parameter	Meaning
k	Number of latent dimensions
n_epochs	Number of backbone training epochs
learning_rate	Matrix-factorization learning rate
lambda_reg	Backbone regularization
n_user_groups	Number of user-activity groups
n_item_groups	Number of item-popularity groups
lam_user_calib	User-correction shrinkage
lam_item_calib	Item-correction shrinkage
lam_group_calib	Group-correction shrinkage
calibration_iters	Number of coordinate-update iterations
use_oof_calibration	Use out-of-fold residuals
oof_folds	Number of out-of-fold partitions
clip_correction	Maximum absolute residual correction
use_global_calib	Enable the global correction
use_user_calib	Enable user-specific corrections
use_item_calib	Enable item-specific corrections
use_group_calib	Enable group-specific corrections

Example direct Python usage

RC-MF can also be instantiated directly.

from models.residual_calibrated_mf import ResidualCalibratedMF

model = ResidualCalibratedMF(
    k=20,
    n_epochs=100,
    random_state=0,
    learning_rate=0.003,
    lambda_reg=0.02,
    n_user_groups=3,
    n_item_groups=3,
    lam_user_calib=20.0,
    lam_item_calib=20.0,
    lam_group_calib=10.0,
    calibration_iters=5,
    use_oof_calibration=True,
    oof_folds=3,
    clip_correction=1.0,
)

model.fit(R_train)

predictions = model.predict(R_test)

Here, R_train and R_test must be two-dimensional NumPy arrays or SciPy sparse matrices. Nonzero finite entries are treated as observed ratings.

Predict selected user-item pairs

pairs = [
    [0, 12],
    [0, 25],
    [4, 10],
]

predictions = model.predict_pairs(pairs)

Score candidate items for one user

item_ids = [1, 5, 10, 20]
scores = model.score_items(user_id=0, item_ids=item_ids)

This method is used by the experimental runner to compute ranking metrics.

Obtain residual diagnostics

Observation-level diagnostics:

residual_df = model.get_residual_diagnostics()

Group-level diagnostics:

group_df = model.get_residual_group_diagnostics()

The observation-level output includes:

• user identifier;
• item identifier;
• observed rating;
• user-activity group;
• item-popularity group;
• joint group identifier;
• residual before calibration;
• residual after calibration.

The group-level output includes:

• number of observations;
• mean residual before and after calibration;
• MAE before and after calibration;
• RMSE before and after calibration;
• absolute mean residual before and after calibration.