Implementation:Online ml River Facto FFM
| Knowledge Sources | |
|---|---|
| Domains | Online_Learning, Factorization_Machines, Recommender_Systems |
| Last Updated | 2026-02-08 16:00 GMT |
Overview
Field-aware Factorization Machines (FFM) are online learning models for regression and classification that capture feature interactions through field-aware latent factors.
Description
FFM extends standard Factorization Machines by introducing field awareness, where each feature has multiple latent vectors - one for each field it can interact with. The model equation includes linear terms and pairwise field-aware interaction terms. For each feature pair (j, j'), the model computes the dot product between the latent vector of feature j for field j' and the latent vector of feature j' for field j. This allows the model to learn different interaction patterns based on which fields features belong to. Field names are automatically inferred by splitting feature names at the first underscore. String features are automatically one-hot encoded as categorical variables.
Usage
Use FFM when modeling click-through rates, recommendation systems, or any scenario where pairwise feature interactions depend on feature semantics (fields). It is particularly effective in advertising and recommendation tasks where features naturally group into fields (user, item, context, etc.). The field-aware approach captures richer interactions than standard FM but requires more memory and computation.
Code Reference
Source Location
- Repository: Online_ml_River
- File: river/facto/ffm.py
Signature
class FFMRegressor(
n_factors=10,
weight_optimizer: optim.base.Optimizer | None = None,
latent_optimizer: optim.base.Optimizer | None = None,
loss: optim.losses.RegressionLoss | None = None,
sample_normalization=False,
l1_weight=0.0,
l2_weight=0.0,
l1_latent=0.0,
l2_latent=0.0,
intercept=0.0,
intercept_lr: optim.base.Scheduler | float = 0.01,
weight_initializer: optim.initializers.Initializer | None = None,
latent_initializer: optim.initializers.Initializer | None = None,
clip_gradient=1e12,
seed: int | None = None,
)
class FFMClassifier(
n_factors=10,
weight_optimizer: optim.base.Optimizer | None = None,
latent_optimizer: optim.base.Optimizer | None = None,
loss: optim.losses.BinaryLoss | None = None,
sample_normalization=False,
l1_weight=0.0,
l2_weight=0.0,
l1_latent=0.0,
l2_latent=0.0,
intercept=0.0,
intercept_lr: optim.base.Scheduler | float = 0.01,
weight_initializer: optim.initializers.Initializer | None = None,
latent_initializer: optim.initializers.Initializer | None = None,
clip_gradient=1e12,
seed: int | None = None,
)
Import
from river import facto
I/O Contract
| Parameter | Type | Description |
|---|---|---|
| x | dict | Feature dictionary with feature names as keys and numerical/categorical values |
| y | float/bool | Target value for regression or classification |
| Method | Return Type | Description |
|---|---|---|
| predict_one(x) | float/bool | Predicted value or class label |
| predict_proba_one(x) | dict | Probability distribution over classes (classifier only) |
| learn_one(x, y) | None | Updates the model with the given sample |
Usage Examples
from river import facto
# Regression example
dataset = (
({'user': 'Alice', 'item': 'Superman', 'time': .12}, 8),
({'user': 'Alice', 'item': 'Terminator', 'time': .13}, 9),
({'user': 'Alice', 'item': 'Star Wars', 'time': .14}, 8),
({'user': 'Alice', 'item': 'Notting Hill', 'time': .15}, 2),
({'user': 'Bob', 'item': 'Superman', 'time': .13}, 8),
({'user': 'Bob', 'item': 'Terminator', 'time': .12}, 9),
)
model = facto.FFMRegressor(
n_factors=10,
intercept=5,
seed=42,
)
for x, y in dataset:
model.learn_one(x, y)
prediction = model.predict_one({'user': 'Bob', 'item': 'Harry Potter', 'time': .14})
print(f"Prediction: {prediction}") # 5.319945