recnexteval 0.1.0__py3-none-any.whl

recnexteval/metrics/ranking/dcg.py

@@ -0,0 +1,55 @@
+# Adopted from RecPack, An Experimentation Toolkit for Top-N Recommendation
+# Copyright (C) 2020  Froomle N.V.
+# License: GNU AGPLv3 - https://gitlab.com/recpack-maintainers/recpack/-/blob/master/LICENSE
+# Author:
+#   Lien Michiels
+#   Robin Verachtert
+
+import logging
+
+import numpy as np
+from scipy.sparse import csr_matrix
+
+from ..core.listwise_top_k import ListwiseMetricK
+from ..core.util import sparse_divide_nonzero
+
+
+logger = logging.getLogger(__name__)
+
+
+class DCGK(ListwiseMetricK):
+    """Computes the sum of gains of all items in a recommendation list.
+
+    Relevant items that are ranked higher in the Top-K recommendations have a higher gain.
+
+    The Discounted Cumulative Gain (DCG) is computed for every user as
+
+    .. math::
+
+        \\text{DiscountedCumulativeGain}(u) = \\sum\\limits_{i \\in Top-K(u)} \\frac{y^{true}_{u,i}}{\\log_2 (\\text{rank}(u,i) + 1)}
+
+
+    :param K: Size of the recommendation list consisting of the Top-K item predictions.
+    :type K: int
+
+    This code is adapted from RecPack :cite:`recpack`
+    """
+    IS_BASE: bool = False
+
+    def _calculate(self, y_true: csr_matrix, y_pred: csr_matrix) -> None:
+        logger.debug("Precision compute started - %s", self.name)
+        logger.debug("Shape of matrix: (%d, %d)", y_true.shape[0], y_true.shape[1])
+        logger.debug("Number of ground truth interactions: %d", y_true.nnz)
+
+        denominator = y_pred.multiply(y_true)
+        # Denominator: log2(rank_i + 1)
+        denominator.data = np.log2(denominator.data + 1)
+        # Binary relevance
+        # Numerator: rel_i
+        numerator = y_true
+
+        dcg = sparse_divide_nonzero(numerator, denominator)
+
+        self._scores = csr_matrix(dcg.sum(axis=1))
+
+        logger.debug(f"DCGK compute complete - {self.name}")

recnexteval/metrics/ranking/ndcg.py

@@ -0,0 +1,78 @@
+# Adopted from RecPack, An Experimentation Toolkit for Top-N Recommendation
+# Copyright (C) 2020  Froomle N.V.
+# License: GNU AGPLv3 - https://gitlab.com/recpack-maintainers/recpack/-/blob/master/LICENSE
+# Author:
+#   Lien Michiels
+#   Robin Verachtert
+
+import logging
+from typing import Optional
+
+import numpy as np
+from scipy.sparse import csr_matrix
+
+from ..core.listwise_top_k import ListwiseMetricK
+from ..core.util import sparse_divide_nonzero
+
+
+logger = logging.getLogger(__name__)
+
+
+class NDCGK(ListwiseMetricK):
+
+    """Computes the normalized sum of gains of all items in a recommendation list.
+
+    The normalized Discounted Cumulative Gain (nDCG) is similar to DCG,
+    but normalizes by dividing the resulting sum of cumulative gains
+    by the best possible discounted cumulative gain for a list of recommendations
+    of length K for a user with history length N.
+
+    Scores are always in the interval [0, 1]
+
+    .. math::
+
+        \\text{NormalizedDiscountedCumulativeGain}(u) = \\frac{\\text{DCG}(u)}{\\text{IDCG}(u)}
+
+    where IDCG stands for Ideal Discounted Cumulative Gain, computed as:
+
+    .. math::
+
+        \\text{IDCG}(u) = \\sum\\limits_{j=1}^{\\text{min}(K, |y^{true}_u|)} \\frac{1}{\\log_2 (j + 1)}
+
+    :param K: Size of the recommendation list consisting of the Top-K item predictions.
+    :type K: int
+
+    This code is adapted from RecPack :cite:`recpack`
+    """
+    IS_BASE: bool = False
+
+    def _calculate(self, y_true: csr_matrix, y_pred: csr_matrix) -> None:
+        logger.debug(f"NDCGK compute started - {self.name}")
+        logger.debug(f"Number of users: {y_true.shape[0]}")
+        logger.debug(f"Number of ground truth interactions: {y_true.nnz}")
+
+        self.discount_template = 1.0 / np.log2(np.arange(2, self.K + 2))
+        # Calculate IDCG values by creating a list of partial sums
+        self.IDCG_cache = np.concatenate([[1], np.cumsum(self.discount_template)])
+
+        # Correct predictions only
+        denominator = y_pred.multiply(y_true)
+        # Denominator: log2(rank_i + 1)
+        denominator.data = np.log2(denominator.data + 1)
+        # Binary relevance
+        # Numerator: rel_i
+        numerator = y_true
+
+        dcg = sparse_divide_nonzero(numerator, denominator)
+
+        per_user_dcg = dcg.sum(axis=1)
+
+        hist_len = y_true.sum(axis=1).astype(np.int32)
+        hist_len[hist_len > self.K] = self.K
+
+        self._scores = sparse_divide_nonzero(
+            csr_matrix(per_user_dcg),
+            csr_matrix(self.IDCG_cache[hist_len]),
+        )
+
+        logger.debug(f"NDCGK compute complete - {self.name}")

recnexteval/metrics/ranking/precision.py

@@ -0,0 +1,51 @@
+import logging
+
+import scipy.sparse
+from scipy.sparse import csr_matrix
+
+from ..core.listwise_top_k import ListwiseMetricK
+
+
+logger = logging.getLogger(__name__)
+
+
+class PrecisionK(ListwiseMetricK):
+    """Computes the fraction of top-K recommendations that correspond
+    to true interactions.
+
+    Given the prediction and true interaction in binary representation,
+    the matrix is multiplied elementwise. These will result in the true
+    positives to be 1 and the false positives to be 0. The sum of the
+    resulting true positives is then divided by the number of actual top-K
+    interactions to get the precision on user level.
+
+    In simple terms, precision is the ratio of correctly predicted positive
+    observations to the total predictions made.
+
+    Precision is computed per user as:
+
+    .. math::
+
+        \\text{Precision}(u) = \\frac{\\sum\\limits_{i \\in \\text{Top-K}(u)} y^{true}_{u,i}}{K}\\
+
+    ref: RecPack
+
+    :param K: Size of the recommendation list consisting of the Top-K item predictions.
+    :type K: int
+    """
+    IS_BASE: bool = False
+
+    def _calculate(self, y_true: csr_matrix, y_pred: csr_matrix) -> None:
+        scores = scipy.sparse.lil_matrix(y_pred.shape)
+
+        logger.debug("Precision compute started - %s", self.name)
+        logger.debug("Shape of matrix: (%d, %d)", y_true.shape[0], y_true.shape[1])
+        logger.debug("Number of ground truth interactions: %d", y_true.nnz)
+
+        # obtain true positives
+        scores[y_pred.multiply(y_true).astype(bool)] = 1
+        scores = scores.tocsr()
+
+        # true positive/total predictions
+        self._scores = csr_matrix(scores.sum(axis=1)) / self.K
+        logger.debug("Precision compute complete - %s", self.name)

recnexteval/metrics/ranking/recall.py

@@ -0,0 +1,42 @@
+import logging
+
+import scipy.sparse
+from scipy.sparse import csr_matrix
+
+from ..core.listwise_top_k import ListwiseMetricK
+
+
+logger = logging.getLogger(__name__)
+
+
+class RecallK(ListwiseMetricK):
+    """Computes the fraction of true interactions that made it into
+    the Top-K recommendations.
+
+    Recall per user is computed as:
+
+    .. math::
+
+        \\text{Recall}(u) = \\frac{\\sum\\limits_{i \\in \\text{Top-K}(u)} y^{true}_{u,i} }{\\sum\\limits_{j \\in I} y^{true}_{u,j}}
+
+    ref: RecPack
+
+    :param K: Size of the recommendation list consisting of the Top-K item predictions.
+    :type K: int
+    """
+    IS_BASE: bool = False
+
+    def _calculate(self, y_true: csr_matrix, y_pred: csr_matrix) -> None:
+        scores = scipy.sparse.lil_matrix(y_pred.shape)
+
+        logger.debug("Precision compute started - %s", self.name)
+        logger.debug("Shape of matrix: (%d, %d)", y_true.shape[0], y_true.shape[1])
+        logger.debug("Number of ground truth interactions: %d", y_true.nnz)
+
+        # obtain true positives
+        scores[y_pred.multiply(y_true).astype(bool)] = 1
+        scores = scores.tocsr()
+
+        # true positive/total actual interactions
+        self._scores = csr_matrix(scores.sum(axis=1) / y_true.sum(axis=1))
+        logger.debug(f"Recall compute complete - {self.name}")

recnexteval/models/__init__.py

@@ -0,0 +1,4 @@
+from .base import BaseModel, ParamMixin
+
+
+__all__ = ["BaseModel", "ParamMixin"]

recnexteval/models/base.py

@@ -0,0 +1,69 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseModel(ABC):
+    """Base class for all recnexteval components.
+
+    Provides common properties like name and universal IS_BASE flag.
+    """
+
+    IS_BASE: bool = True
+
+    @property
+    def name(self) -> str:
+        """Name of the object's class.
+
+        :return: Name of the object's class
+        :rtype: str
+        """
+        return self.__class__.__name__
+
+
+class ParamMixin(ABC):
+    """Mixin class for all recnexteval components with parameters.
+
+    Provides common properties like name, params, and identifier.
+    """
+
+    @property
+    def name(self) -> str:
+        """Name of the object's class.
+
+        :return: Name of the object's class
+        :rtype: str
+        """
+        return self.__class__.__name__
+
+    @abstractmethod
+    def get_params(self) -> dict[str, Any]:
+        """Get the parameters of the object.
+
+        :return: Parameters of the object
+        :rtype: dict
+        """
+        ...
+
+    @property
+    def params(self) -> dict[str, Any]:
+        """Parameters of the object.
+
+        :return: Parameters of the object
+        :rtype: dict
+        """
+        return self.get_params()
+
+    @property
+    def identifier(self) -> str:
+        """Identifier of the object.
+
+        Identifier is made by combining the class name with the parameters
+        passed at construction time.
+
+        Constructed by recreating the initialisation call.
+        Example: `Algorithm(param_1=value)`
+
+        :return: Identifier of the object
+        """
+        paramstring = ",".join((f"{k}={v}" for k, v in self.get_params().items()))
+        return self.name + "(" + paramstring + ")"

recnexteval/preprocessing/__init__.py

@@ -0,0 +1,37 @@
+"""Preprocessing module for data preparation.
+
+This module contains filters and preprocessors for preparing data before
+transforming it into an InteractionMatrix object.
+
+## Filters
+
+Filters are used to filter data before transforming it into an InteractionMatrix
+object. Filter implementations must extend the abstract `Filter` class.
+
+Available filters:
+
+- `Filter`: Abstract base class for filter implementations
+- `MinItemsPerUser`: Filter requiring minimum interactions per user
+- `MinUsersPerItem`: Filter requiring minimum interactions per item
+
+## Preprocessor
+
+The preprocessor allows adding filters for data preprocessing and manages ID
+mappings. After applying filters, it updates item and user ID mappings to
+internal IDs to reduce computation load and enable easy matrix representation.
+
+Available preprocessor:
+
+- `DataFramePreprocessor`: Preprocesses pandas DataFrames into InteractionMatrix
+"""
+
+from recnexteval.preprocessing.filter import Filter, MinItemsPerUser, MinUsersPerItem
+from recnexteval.preprocessing.preprocessor import DataFramePreprocessor
+
+
+__all__ = [
+    "Filter",
+    "MinItemsPerUser",
+    "MinUsersPerItem",
+    "DataFramePreprocessor",
+]

recnexteval/preprocessing/filter.py

@@ -0,0 +1,181 @@
+"""Data filtering module.
+
+This module provides abstract base class and filter implementations for
+removing interactions from a DataFrame based on various criteria.
+"""
+
+from abc import ABC, abstractmethod
+
+import pandas as pd
+
+
+class Filter(ABC):
+    """Abstract base class for filter implementations.
+
+    A filter must implement an `apply` method that takes a pandas DataFrame
+    as input and returns a processed pandas DataFrame as output.
+    """
+
+    @abstractmethod
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply filter to the DataFrame.
+
+        Args:
+            df: DataFrame to filter.
+
+        Returns:
+            Filtered DataFrame.
+        """
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        attrs = self.__dict__
+        return f"{self.__class__.__name__}({', '.join((f'{k}={v}' for k, v in attrs.items()))})"
+
+
+class MinItemsPerUser(Filter):
+    """Filter requiring users to have minimum interaction count.
+
+    Removes users who have interacted with fewer than the specified minimum
+    number of items. Adapted from RecPack.
+
+    Args:
+        min_items_per_user: Minimum number of items a user must interact with.
+        item_ix: Column name containing item identifiers.
+        user_ix: Column name containing user identifiers.
+        count_duplicates: Whether to count multiple interactions with the same
+            item. Defaults to True.
+
+    Example:
+        Original interactions:
+        ```
+        user | item
+        1 | a
+        1 | b
+        1 | c
+        2 | a
+        2 | b
+        2 | d
+        3 | a
+        3 | b
+        3 | d
+        ```
+
+        After `MinItemsPerUser(3)`:
+        ```
+        user | item
+        1 | a
+        1 | b
+        2 | a
+        2 | b
+        3 | a
+        3 | b
+        ```
+
+        Users 1 and 2 are removed (have fewer than 3 items).
+    """
+
+    def __init__(
+        self,
+        min_items_per_user: int,
+        item_ix: str,
+        user_ix: str,
+        count_duplicates: bool = True,
+    ) -> None:
+        self.min_items_per_user = min_items_per_user
+        self.count_duplicates = count_duplicates
+        self.item_ix = item_ix
+        self.user_ix = user_ix
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply minimum items per user filter.
+
+        Args:
+            df: DataFrame to filter.
+
+        Returns:
+            DataFrame containing only users with sufficient interactions.
+        """
+        uids = (
+            df[self.user_ix]
+            if self.count_duplicates
+            else df.drop_duplicates([self.user_ix, self.item_ix])[self.user_ix]
+        )
+
+        cnt_items_per_user = uids.value_counts()
+        users_of_interest = list(cnt_items_per_user[cnt_items_per_user >= self.min_items_per_user].index)
+        return df[df[self.user_ix].isin(users_of_interest)].copy()
+
+
+class MinUsersPerItem(Filter):
+    """Filter requiring items to have minimum user interaction count.
+
+    Removes items that have been interacted with by fewer than the specified
+    minimum number of users. Adapted from RecPack.
+
+    Args:
+        min_users_per_item: Minimum number of users that must interact with item.
+        item_ix: Column name containing item identifiers.
+        user_ix: Column name containing user identifiers.
+        count_duplicates: Whether to count multiple interactions from the same
+            user. Defaults to True.
+
+    Example:
+        Original interactions:
+        ```
+        user | item
+        1 | a
+        1 | b
+        1 | c
+        2 | a
+        2 | b
+        2 | d
+        3 | a
+        3 | b
+        3 | d
+        ```
+
+        After `MinUsersPerItem(3)`:
+        ```
+        user | item
+        1 | a
+        1 | b
+        2 | a
+        2 | b
+        3 | a
+        3 | b
+        ```
+
+        Items with fewer than 3 users are removed (c and d).
+    """
+
+    def __init__(
+        self,
+        min_users_per_item: int,
+        item_ix: str,
+        user_ix: str,
+        count_duplicates: bool = True,
+    ) -> None:
+        self.item_ix = item_ix
+        self.user_ix = user_ix
+        self.min_users_per_item = min_users_per_item
+        self.count_duplicates = count_duplicates
+
+    def apply(self, df: pd.DataFrame) -> pd.DataFrame:
+        """Apply minimum users per item filter.
+
+        Args:
+            df: DataFrame to filter.
+
+        Returns:
+            DataFrame containing only items with sufficient user interactions.
+        """
+        iids = (
+            df[self.item_ix]
+            if self.count_duplicates
+            else df.drop_duplicates([self.user_ix, self.item_ix])[self.item_ix]
+        )
+
+        cnt_users_per_item = iids.value_counts()
+        items_of_interest = list(cnt_users_per_item[cnt_users_per_item >= self.min_users_per_item].index)
+        return df[df[self.item_ix].isin(items_of_interest)].copy()

recnexteval/preprocessing/preprocessor.py

@@ -0,0 +1,137 @@
+"""Data preprocessing module.
+
+This module provides the DataFramePreprocessor class for converting pandas
+DataFrames into InteractionMatrix objects with optional filtering.
+"""
+
+import logging
+from typing import Literal
+
+import pandas as pd
+
+from recnexteval.matrix import InteractionMatrix
+from recnexteval.preprocessing.filter import Filter
+
+
+logger = logging.getLogger(__name__)
+
+
+class DataFramePreprocessor:
+    """Preprocesses pandas DataFrames into InteractionMatrix objects.
+
+    Allows adding filters for data preprocessing before transforming data into
+    an InteractionMatrix object. After applying filters, updates item and user
+    ID mappings to internal IDs to reduce computation load and enable easy
+    matrix representation.
+
+    Args:
+        item_ix: Column name containing item identifiers.
+        user_ix: Column name containing user identifiers.
+        timestamp_ix: Column name containing timestamps.
+    """
+
+    def __init__(self, item_ix: str, user_ix: str, timestamp_ix: str) -> None:
+        self._item_id_mapping = dict()
+        self._user_id_mapping = dict()
+        self.item_ix = item_ix
+        self.user_ix = user_ix
+        self.timestamp_ix = timestamp_ix
+        self.filters: list[Filter] = []
+
+    @property
+    def item_id_mapping(self) -> pd.DataFrame:
+        """Map from original item IDs to internal item IDs.
+
+        Returns:
+            DataFrame with columns for internal item IDs and original item IDs.
+        """
+        return pd.DataFrame.from_records(
+            list(self._item_id_mapping.items()),
+            columns=[InteractionMatrix.ITEM_IX, self.item_ix],
+        )
+
+    @property
+    def user_id_mapping(self) -> pd.DataFrame:
+        """Map from original user IDs to internal user IDs.
+
+        Returns:
+            DataFrame with columns for internal user IDs and original user IDs.
+        """
+        return pd.DataFrame.from_records(
+            list(self._user_id_mapping.items()),
+            columns=[InteractionMatrix.USER_IX, self.user_ix],
+        )
+
+    def add_filter(self, filter_: Filter) -> None:
+        """Add a preprocessing filter to be applied.
+
+        The filter will be applied before transforming to an InteractionMatrix
+        object. Filters are applied in order of addition and different orderings
+        can lead to different results.
+
+        Args:
+            filter_: The filter to be applied.
+        """
+        self.filters.append(filter_)
+
+    def _print_log_message(
+        self,
+        step: Literal["before", "after"],
+        stage: Literal["preprocess", "filter"],
+        df: pd.DataFrame,
+    ) -> None:
+        """Log preprocessing progress.
+
+        Prints a log message with the number of interactions, items, and users
+        in the DataFrame at the current stage.
+
+        Args:
+            step: Indicates whether log is before or after preprocessing.
+            stage: Current stage of preprocessing (preprocess or filter).
+            df: The DataFrame being processed.
+        """
+        logger.debug(f"\tinteractions {step} {stage}: {len(df.index)}")
+        logger.debug(f"\titems {step} {stage}: {df[self.item_ix].nunique()}")
+        logger.debug(f"\tusers {step} {stage}: {df[self.user_ix].nunique()}")
+
+    def _update_id_mappings(self, df: pd.DataFrame) -> None:
+        """Update internal ID mappings for users and items.
+
+        Internal ID mappings are updated to reduce computation load and enable
+        easy matrix representation. IDs are assigned by timestamp order.
+
+        Args:
+            df: DataFrame to update ID mappings for.
+        """
+        # Sort by timestamp to incrementally assign user and item ids by timestamp
+        df.sort_values(by=[self.timestamp_ix], inplace=True, ignore_index=True)
+        user_index = pd.CategoricalIndex(df[self.user_ix], categories=df[self.user_ix].unique())
+        self._user_id_mapping = dict(enumerate(user_index.drop_duplicates()))
+        df[self.user_ix] = user_index.codes
+
+        item_index = pd.CategoricalIndex(df[self.item_ix], categories=df[self.item_ix].unique())
+        self._item_id_mapping = dict(enumerate(item_index.drop_duplicates()))
+        df[self.item_ix] = item_index.codes
+
+    def process(self, df: pd.DataFrame) -> InteractionMatrix:
+        """Process DataFrame through filters and convert to InteractionMatrix.
+
+        Args:
+            df: DataFrame to process.
+
+        Returns:
+            InteractionMatrix object created from processed DataFrame.
+        """
+        self._print_log_message("before", "preprocess", df)
+
+        for filter_ in self.filters:
+            logger.debug(f"applying filter: {filter_}")
+            df = filter_.apply(df)
+            self._print_log_message("after", "filter", df)
+
+        self._update_id_mappings(df)
+        self._print_log_message("after", "preprocess", df)
+
+        # Convert input data into internal data objects
+        interaction_m = InteractionMatrix(df, self.item_ix, self.user_ix, self.timestamp_ix)
+        return interaction_m