Implementation:Online ml River Facto FFM

Knowledge Sources	Online_ml_River
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

Input
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

Output
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

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment