Implementation:Recommenders team Recommenders Affinity Matrix

Knowledge Sources	Recommenders
Domains	Recommender Systems, Data Transformation, Sparse Matrices
Last Updated	2026-02-10 00:00 GMT

Overview

Provides the AffinityMatrix class for converting between Pandas DataFrames of user-item-rating tuples and sparse user/item affinity matrices.

Description

The AffinityMatrix class bridges tabular rating data and matrix representations required by matrix-based recommendation algorithms. During initialization, it accepts a DataFrame with configurable user, item, rating, and prediction column names, plus an optional pre-defined items list. The internal _gen_index method creates bidirectional index mappings: map_users and map_items dictionaries map original user/item IDs to contiguous integer indices, while map_back_users and map_back_items provide the reverse mapping. These dictionaries can optionally be saved as numpy files for model persistence. The gen_affinity_matrix method generates the user-item affinity matrix using scipy.sparse.coo_matrix in the format coo_matrix((data, (rows, columns)), shape=(Nusers, Nitems)), converting the result to a dense numpy array and logging the matrix sparseness percentage. The map_back_sparse method reverses the process: given a numpy matrix, it extracts non-zero entries using np.where, reconstructs user/item/rating tuples via itertools.chain, maps indices back to original IDs, and returns a DataFrame with either rating or prediction column based on the kind parameter.

Usage

Use this class when working with algorithms that operate on user-item affinity matrices, such as VAE-based recommenders, RBMs, or other matrix factorization approaches. Instantiate with your ratings DataFrame, call gen_affinity_matrix to produce the matrix, and use map_back_sparse to convert model predictions back to DataFrame format.

Code Reference

Source Location

• Repository: Recommenders
• File: recommenders/datasets/sparse.py
• Lines: 1-185

Signature

class AffinityMatrix:
    def __init__(
        self,
        df,
        items_list=None,
        col_user=DEFAULT_USER_COL,
        col_item=DEFAULT_ITEM_COL,
        col_rating=DEFAULT_RATING_COL,
        col_pred=DEFAULT_PREDICTION_COL,
        save_path=None,
    )

    def gen_affinity_matrix(self) -> tuple[np.ndarray, dict, dict]

    def map_back_sparse(self, X, kind) -> pd.DataFrame

Import

from recommenders.datasets.sparse import AffinityMatrix

I/O Contract

Inputs

Name	Type	Required	Description
df	pd.DataFrame	Yes	DataFrame containing user-item-rating data.
items_list	np.ndarray or None	No (default: None)	Pre-defined list of unique items. If None, unique items are extracted from the DataFrame.
col_user	str	No (default: "userID")	Column name for user IDs.
col_item	str	No (default: "itemID")	Column name for item IDs.
col_rating	str	No (default: "rating")	Column name for ratings.
col_pred	str	No (default: "prediction")	Column name for predictions in the output DataFrame.
save_path	str or None	No (default: None)	Directory path to save user/item mapping dictionaries as numpy files.
X	np.ndarray	Yes (for map_back_sparse)	User-item affinity matrix (Nusers x Nitems) with non-zero entries.
kind	str	Yes (for map_back_sparse)	Output type: "ratings" uses col_rating, otherwise uses col_pred.

Outputs

Name	Type	Description
return (gen_affinity_matrix)	tuple(np.ndarray, dict, dict)	Tuple of (affinity_matrix, map_users, map_items). The matrix has shape (Nusers, Nitems) with unrated items as 0.
return (map_back_sparse)	pd.DataFrame	DataFrame with user, item, and rating/prediction columns mapped back to original IDs.

Usage Examples

Basic Usage

import pandas as pd
from recommenders.datasets.sparse import AffinityMatrix

# Create a sample ratings DataFrame
ratings_df = pd.DataFrame({
    "userID": [1, 1, 2, 2, 3],
    "itemID": [10, 20, 10, 30, 20],
    "rating": [4.0, 3.5, 5.0, 2.0, 4.5],
})

# Initialize the AffinityMatrix
am = AffinityMatrix(df=ratings_df)

# Generate the affinity matrix
matrix, user_map, item_map = am.gen_affinity_matrix()
print(matrix.shape)  # (3, 3) - 3 users x 3 items

# Convert a prediction matrix back to DataFrame format
predictions_df = am.map_back_sparse(matrix, kind="predictions")
print(predictions_df.columns.tolist())
# ['userID', 'itemID', 'prediction']

# Save mappings for later use with a trained model
am_persistent = AffinityMatrix(df=ratings_df, save_path="/tmp/model_maps")
am_persistent.gen_affinity_matrix()
# Saves user_dict.npy, item_dict.npy, user_back_dict.npy, item_back_dict.npy

Dependencies

• pandas - DataFrame construction and manipulation
• numpy - Array operations and file persistence
• scipy.sparse - coo_matrix for sparse matrix construction
• itertools - Flattening nested lists
• recommenders.utils.constants - Default column name constants

Related Pages

Requires Environment

• Environment:Recommenders_team_Recommenders_Python_Core_Dependencies