Arguments for SVD++ algorithm.

This class implements the SVD++ algorithm for Collaborative Filtering, primarily used for Recommender Systems (Link Prediction).

Based on the paper "Factorization Meets the Neighborhood: a Multifaceted Collaborative Filtering Model" by Yehuda Koren (2008), available at https://dl.acm.org/citation.cfm?id=1401944.

Problem Definition

The algorithm predicts unknown ratings in a user-item system. It accounts for:

• Explicit preferences (user ratings).
• Implicit feedback (the history of items a user has interacted with).
• User and Item biases.

The prediction rule for a rating r_ui (user u, item i) is:

r_ui = µ + b_u + b_i + q_i^T * (p_u + |N(u)|^-0.5 * sum(y_j for j in N(u)))

Where N(u) is the set of items user u has interacted with (implicit feedback).

Input Requirements

!!! IMPORTANT !!! The input graph MUST be a **Directed Bipartite Graph** representing interactions:

• **Vertices**: A mix of Users and Items.
• **Edges**: Directed strictly from **User (src) -> Item (dst)**.
• **Edge Attribute**: A numeric column (default "weight") representing the rating.

DO NOT use this on general/undirected graphs (e.g., social networks), as the algorithm relies on the asymmetry between Users (who provide feedback) and Items (who receive it).

Output Model (Node Embeddings)

The algorithm returns a DataFrame of vertices with the trained model parameters. These parameters function as embeddings:

• column1 (Array[Double]): **Primary Latent Factors (Explicit Embedding)**.
• For Users: Represents preferences (p_u).
• For Items: Represents characteristics (q_i).
• column2 (Array[Double]): **Implicit Factors (Implicit Embedding)**.
• For Items: Represents the influence of the item (y_i) on a user's profile based on viewing history.
• For Users: Generally unused/zero.
• column3 (Double): **Bias**.
• For Users: User bias (b_u).
• For Items: Item bias (b_i).
• column4 (Double): **Implicit Normalization Term**.
• For Users: Precomputed |N(u)|^-0.5.
• For Items: Unused.

Parameter Tuning Guide

Constraints:

• minValue / maxValue: Hard bounds for predicted ratings. Predictions outside this range are clipped. Set these to your rating scale limits (e.g., 1.0 and 5.0).

Learning Rates (Step sizes for Gradient Descent):

• gamma1: Learning rate for **Biases** (b_u, b_i).
• gamma2: Learning rate for **Embeddings/Factors** (p_u, q_i, y_j). > Tip: Increase if convergence is too slow. Decrease if the loss explodes (NaN).

Regularization (Preventing Overfitting):

• gamma6: Regularization for **Biases**.
• gamma7: Regularization for **Embeddings/Factors**. > Tip: Increase these if the model performs well on training data but poorly on test data.