recnexteval 0.1.0__py3-none-any.whl

recnexteval/evaluators/strategy.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+
+from .state_management import AlgorithmStateManager
+
+
+class EvaluationStrategy(ABC):
+    """Abstract strategy for different evaluation modes"""
+
+    @abstractmethod
+    def should_advance_window(self, algo_state_mgr: AlgorithmStateManager, current_step: int, total_steps: int) -> bool:
+        """Determine if should advance to next window"""
+        pass
+
+
+class SlidingWindowStrategy(EvaluationStrategy):
+    """Strategy for sliding window evaluation"""
+
+    def should_advance_window(self, algo_state_mgr: AlgorithmStateManager, current_step: int, total_steps: int) -> bool:
+        """Advance only when all algorithms predicted"""
+        return (
+            algo_state_mgr.is_all_predicted()
+            and algo_state_mgr.is_all_same_data_segment()
+            and current_step < total_steps
+        )
+
+
+class SingleTimePointStrategy(EvaluationStrategy):
+    """Strategy for sliding window evaluation"""
+
+    def should_advance_window(self, algo_state_mgr: AlgorithmStateManager, current_step: int, total_steps: int) -> bool:
+        """Advance only when all algorithms predicted"""
+        return algo_state_mgr.is_all_predicted() and current_step < total_steps

recnexteval/evaluators/util.py

@@ -0,0 +1,124 @@
+import logging
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from recnexteval.matrix import InteractionMatrix
+
+
+logger = logging.getLogger(__name__)
+
+
+class MetricLevelEnum(StrEnum):
+    MICRO = "micro"
+    MACRO = "macro"
+    WINDOW = "window"
+    USER = "user"
+
+    @classmethod
+    def has_value(cls, value: str) -> bool:
+        """Check valid value for MetricLevelEnum.
+
+        Args:
+            value: String value input.
+
+        Returns:
+            Whether the value is valid.
+        """
+        return value in MetricLevelEnum
+
+
+@dataclass
+class UserItemBaseStatus:
+    """Unknown and known user/item base.
+
+    This class is used to store the status of the user and item base. The class
+    stores the known and unknown user and item set. The class also provides
+    methods to update the known and unknown user and item set.
+    """
+
+    unknown_user: set[int] = field(default_factory=set)
+    known_user: set[int] = field(default_factory=set)
+    unknown_item: set[int] = field(default_factory=set)
+    known_item: set[int] = field(default_factory=set)
+
+    @property
+    def known_shape(self) -> tuple[int, int]:
+        """Known shape of the user-item interaction matrix.
+
+        This is the shape of the released user/item interaction matrix to the
+        algorithm. This shape follows from assumption in the dataset that
+        ID increment in the order of time.
+
+        Returns:
+            Tuple of (|user|, |item|).
+        """
+        return (len(self.known_user), len(self.known_item))
+
+    @property
+    def global_shape(self) -> tuple[int, int]:
+        """Global shape of the user-item interaction matrix.
+
+        This is the shape of the user-item interaction matrix considering all
+        the users and items that has been possibly exposed. The global shape
+        considers the fact that an unknown user/item can be exposed during the
+        prediction stage when an unknown user/item id is requested for prediction
+        on the algorithm.
+
+        Returns:
+            Tuple of (|user|, |item|).
+        """
+        return (
+            len(self.known_user) + len(self.unknown_user),
+            len(self.known_item) + len(self.unknown_item),
+        )
+
+    @property
+    def global_user_ids(self) -> set[int]:
+        """Set of global user ids.
+
+        Returns the set of global user ids. The global user ids are the union of
+        known and unknown user ids.
+
+        Returns:
+            set[int]: Set of global user ids.
+        """
+        return self.known_user.union(self.unknown_user)
+
+    @property
+    def global_item_ids(self) -> set[int]:
+        """Set of global item ids.
+
+        Returns the set of global item ids. The global item ids are the union of
+        known and unknown item ids.
+
+        Returns:
+            set[int]: Set of global item ids.
+        """
+        return self.known_item.union(self.unknown_item)
+
+    def update_known_user_item_base(self, data: InteractionMatrix) -> None:
+        """Updates the known user and item set with the data.
+
+        Args:
+            data (InteractionMatrix): Data to update the known user and item set with.
+        """
+        self.known_item.update(data.item_ids)
+        self.known_user.update(data.user_ids)
+
+    def update_unknown_user_item_base(self, data: InteractionMatrix) -> None:
+        """Updates the unknown user and item set with the data.
+
+        Args:
+            data (InteractionMatrix): Data to update the unknown user and item set with.
+        """
+        self.unknown_user = data.user_ids.difference(self.known_user)
+        self.unknown_item = data.item_ids.difference(self.known_item)
+
+    def reset_unknown_user_item_base(self) -> None:
+        """Clears the unknown user and item set.
+
+        This method clears the unknown user and item set. This method should be
+        called after the Phase 3 when the data release is done.
+        """
+        self.unknown_user = set()
+        self.unknown_item = set()

recnexteval/matrix/__init__.py

@@ -0,0 +1,48 @@
+"""
+recnexteval.matrix
+
+This module provides classes and utilities for handling interaction matrices in recommendation systems.
+
+The core component is the InteractionMatrix, which represents user-item interactions as a structured matrix.
+It stores interaction data in a pandas DataFrame and offers methods for filtering, masking, and converting to sparse matrices.
+This is essential for building and evaluating recommender algorithms, such as collaborative filtering, where interactions
+between users and items need to be efficiently processed.
+
+Use cases include:
+- Preprocessing interaction data for training recommendation models.
+- Handling temporal data with timestamp-based filtering (e.g., recent interactions).
+- Masking unknown users/items during evaluation to prevent data leakage.
+- Converting data to CSR format for efficient matrix operations in libraries like SciPy.
+
+Classes:
+    InteractionMatrix: The main class for creating and manipulating interaction matrices from datasets.
+        It supports operations like filtering by users/items, timestamps, and shape masking.
+    PredictionMatrix: A subclass of InteractionMatrix tailored for prediction-related operations.
+        It provides masking for the expected (user, item) exposed.
+
+Enums:
+    ItemUserBasedEnum: Enum for specifying whether operations are item-based or user-based.
+        Used in methods that group or filter data by users or items.
+
+Exceptions:
+    TimestampAttributeMissingError: Raised when required timestamp attributes are missing from the data.
+        Ensures that time-aware operations are only performed on timestamped data.
+
+Functions:
+    to_csr_matrix: Utility function to convert data structures to CSR matrix format.
+        Useful for creating sparse representations of interaction data for computational efficiency.
+"""
+
+from .exception import TimestampAttributeMissingError
+from .interaction_matrix import InteractionMatrix, ItemUserBasedEnum
+from .prediction_matrix import PredictionMatrix
+from .util import to_csr_matrix
+
+
+__all__ = [
+    "InteractionMatrix",
+    "PredictionMatrix",
+    "to_csr_matrix",
+    "ItemUserBasedEnum",
+    "TimestampAttributeMissingError",
+]

recnexteval/matrix/exception.py

@@ -0,0 +1,5 @@
+class TimestampAttributeMissingError(Exception):
+    """Error raised when timestamp attribute is missing."""
+
+    def __init__(self, message: str = "InteractionMatrix is missing timestamps.") -> None:
+        super().__init__(message)