recnexteval 0.1.0__py3-none-any.whl

recnexteval/settings/single_time_point_setting.py

@@ -0,0 +1,111 @@
+import logging
+from warnings import warn
+
+import numpy as np
+
+from recnexteval.matrix import InteractionMatrix, TimestampAttributeMissingError
+from .base import Setting
+from .splitters import (
+    NLastInteractionTimestampSplitter,
+    TimestampSplitter,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class SingleTimePointSetting(Setting):
+    """Single time point setting for data split.
+
+    Splits an interaction dataset at a single timestamp into background
+    (training) data and evaluation data. The evaluation data can be
+    further processed to produce unlabeled inputs and ground-truth
+    targets for model evaluation.
+
+    Args:
+        background_t: Time point to split the data. The background
+            split covers interactions with timestamps in `[0, background_t)`.
+        n_seq_data: Number of last sequential interactions
+            to provide as input for prediction. Defaults to `1`.
+        top_K: Number of interactions per user to select for
+            evaluation purposes. Defaults to `1`.
+        t_upper: Upper bound on the timestamp of
+            interactions included in evaluation. Defaults to the maximum
+            32-bit integer value (acts like infinity).
+        include_all_past_data: If True, include all past
+            interactions when constructing input sequences. Defaults to False.
+        seed: Random seed for reproducible behavior.
+            If None, a seed will be generated.
+    """
+    IS_BASE: bool = False
+
+    def __init__(
+        self,
+        background_t: int,
+        n_seq_data: int = 1,
+        top_K: int = 1,
+        t_upper: int = np.iinfo(np.int32).max,
+        include_all_past_data: bool = False,
+        seed: int = 42,
+    ):
+        super().__init__(seed=seed)
+        self.t = background_t
+        """Seconds before `t` timestamp value to be used in `background_set`."""
+        self.t_upper = t_upper
+        """Seconds after `t` timestamp value to be used in `ground_truth_data`."""
+        self.n_seq_data = n_seq_data
+        self.top_K = top_K
+
+        logger.info("Splitting data at time %s with t_upper interval %s", background_t, t_upper)
+
+        self._background_splitter = TimestampSplitter(
+            t=background_t,
+            t_lower=None,
+            t_upper=t_upper,
+        )
+        self._splitter = NLastInteractionTimestampSplitter(
+            t=background_t,
+            t_upper=t_upper,
+            n_seq_data=n_seq_data,
+            include_all_past_data=include_all_past_data,
+        )
+        self._t_window = background_t
+
+    def _split(self, data: InteractionMatrix) -> None:
+        """Split the dataset by timestamp into background and evaluation sets.
+
+        The method raises :class:`TimestampAttributeMissingError` when the
+        provided :class:`InteractionMatrix` does not contain timestamp
+        information. It will warn if the chosen split time is before the
+        earliest timestamp in the data.
+
+        Args:
+            data: Interaction matrix to split. Must have timestamps.
+
+        Raises:
+            TimestampAttributeMissingError: If `data` has no timestamp attribute.
+        """
+        if not data.has_timestamps:
+            raise TimestampAttributeMissingError()
+        if data.min_timestamp > self.t:
+            warn(
+                f"Splitting at time {self.t} is before the first timestamp"
+                " in the data. No data will be in the training set."
+            )
+
+        self._background_data, _ = self._background_splitter.split(data)
+        past_interaction, future_interaction = self._splitter.split(data)
+        self._unlabeled_data, self._ground_truth_data = self.prediction_data_processor.process(
+            past_interaction=past_interaction,
+            future_interaction=future_interaction,
+            top_K=self.top_K,
+        )
+
+        if len(self._background_data) == 0:
+            logger.info("Background data is empty after splitting at time %s", self.t)
+        if len(self._unlabeled_data) == 0:
+            logger.info("Unlabeled data is empty after splitting at time %s", self.t)
+        if len(self._ground_truth_data) == 0:
+            logger.info("Ground truth data is empty after splitting at time %s", self.t)
+
+        logger.info("Finished splitting data at time %s", self.t)

recnexteval/settings/sliding_window_setting.py

@@ -0,0 +1,153 @@
+import logging
+from typing import Optional
+from warnings import warn
+
+import numpy as np
+from tqdm import tqdm
+
+from recnexteval.matrix import InteractionMatrix, TimestampAttributeMissingError
+from .base import Setting
+from .splitters import NLastInteractionTimestampSplitter, TimestampSplitter
+
+
+logger = logging.getLogger(__name__)
+
+
+class SlidingWindowSetting(Setting):
+    """Sliding window setting for splitting data.
+
+    The data is split into a background set and evaluation set. The evaluation set is defined by a sliding window
+    that moves over the data. The window size is defined by the :data:`window_size` parameter. The evaluation set comprises of the
+    unlabeled data and ground truth data stored in a list. The unlabeled data contains the last :data:`n_seq_data` interactions
+    of the users/item before the split point along with masked interactions after the split point. The number of
+    interactions per user/item is limited to :data:`top_K`.
+    The ground truth data is the interactions after the split point and spans :data:`window_size` seconds.
+
+    Core attribute
+    ====================
+    - :attr:`background_data`: Data used for training the model. Interval is `[0, background_t)`.
+    - :attr:`unlabeled_data`: List of unlabeled data. Each element is a :class:`InteractionMatrix` object of interval `[0, t)`.
+    - :attr:`ground_truth_data`: List of ground truth data. Each element is a :class:`InteractionMatrix` object
+      of interval `[t, t + window_size)`.
+    - :attr:`data_timestamp_limit`: List of timestamps that the splitter will slide over the data.
+    - :attr:`incremental_data`: List of data that is used to incrementally update the model. Each element is
+      a :class:`InteractionMatrix` object of interval `[t, t + window_size)`.
+
+    :param background_t: Time point to split the data into background and evaluation data. Split will be from `[0, t)`
+    :type background_t: int
+    :param window_size: Size of the window in seconds to slide over the data.
+        Affects the incremental data being released to the model. If
+        :param:`t_ground_truth_window` is not provided, ground truth data will also
+        take this window.
+    :type window_size: int, optional
+    :param n_seq_data: Number of last sequential interactions to provide as
+         data for model to make prediction. Defaults to 0.
+    :type n_seq_data: int, optional
+    :param top_K: Number of interaction per user that should be selected for evaluation purposes.
+    :type top_K: int, optional
+    :param t_upper: Upper bound on the timestamp of interactions.
+        Defaults to maximal integer value (acting as infinity).
+    :type t_upper: int, optional
+    :param t_ground_truth_window: Size of the window in seconds to slide over the data for ground truth data.
+        If not provided, defaults to window_size during computation.
+    :type t_ground_truth_window: int, optional
+    :param seed: Seed for random number generator.
+    :type seed: int, optional
+    """
+
+    IS_BASE: bool = False
+
+    def __init__(
+        self,
+        background_t: int,
+        window_size: int = np.iinfo(np.int32).max,  # in seconds
+        n_seq_data: int = 0,
+        top_K: int = 10,
+        t_upper: int = np.iinfo(np.int32).max,
+        t_ground_truth_window: None | int = None,
+        seed: int = 42,
+    ) -> None:
+        super().__init__(seed=seed)
+        self._sliding_window_setting = True
+        self.t = background_t
+        self.window_size = window_size
+        """Window size in seconds for splitter to slide over the data."""
+        self.n_seq_data = n_seq_data
+        self.top_K = top_K
+        self.t_upper = t_upper
+        """Upper bound on the timestamp of interactions. Defaults to maximal integer value (acting as infinity)."""
+
+        if t_upper and t_upper < background_t:
+            raise ValueError("t_upper must be greater than background_t")
+
+        if t_ground_truth_window is None:
+            t_ground_truth_window = window_size
+
+        self.t_ground_truth_window = t_ground_truth_window
+
+        self._background_splitter = TimestampSplitter(background_t, None, None)
+        self._window_splitter = NLastInteractionTimestampSplitter(
+            background_t,
+            t_ground_truth_window,
+            n_seq_data,
+        )
+
+    def _split(self, data: InteractionMatrix) -> None:
+        if not data.has_timestamps:
+            raise TimestampAttributeMissingError()
+        if data.min_timestamp > self.t:
+            warn(
+                f"Splitting at time {self.t} is before the first "
+                "timestamp in the data. No data will be in the background(training) set."
+            )
+        if self.t_upper:
+            data = data.timestamps_lt(self.t_upper)
+
+        self._background_data, _ = self._background_splitter.split(data)
+        self._ground_truth_data, self._unlabeled_data, self._t_window, self._incremental_data = (
+            [],
+            [],
+            [],
+            [],
+        )
+
+        # sub_time is the subjugate time point that the splitter will slide over the data
+        sub_time = self.t
+        max_timestamp = data.max_timestamp
+
+        pbar = tqdm(total=int((max_timestamp - sub_time) / self.window_size))
+        while sub_time <= max_timestamp:
+            self._t_window.append(sub_time)
+            # the set used for eval will always have a timestamp greater than
+            # data released such that it is unknown to the model
+            self._window_splitter.update_split_point(sub_time)
+            past_interaction, future_interaction = self._window_splitter.split(data)
+
+            # if past_interaction, future_interaction is empty, log an info message
+            if len(past_interaction) == 0:
+                logger.info(
+                    "Split at time %s resulted in empty unlabelled testing samples.", sub_time
+                )
+            if len(future_interaction) == 0:
+                logger.info("Split at time %s resulted in empty incremental data.", sub_time)
+
+            unlabeled_set, ground_truth = self.prediction_data_processor.process(
+                past_interaction=past_interaction,
+                future_interaction=future_interaction,
+                top_K=self.top_K,
+            )
+            self._unlabeled_data.append(unlabeled_set)
+            self._ground_truth_data.append(ground_truth)
+
+            self._incremental_data.append(future_interaction)
+
+            sub_time += self.window_size
+            pbar.update(1)
+        pbar.close()
+
+        self._num_split_set = len(self._unlabeled_data)
+        logger.info(
+            "Finished split with window size %s seconds. Number of splits: %s in total.",
+            self.window_size,
+            self._num_split_set,
+        )

recnexteval/settings/splitters/__init__.py

@@ -0,0 +1,14 @@
+
+
+from .base import Splitter
+from .n_last import NLastInteractionSplitter
+from .n_last_timestamp import NLastInteractionTimestampSplitter
+from .timestamp import TimestampSplitter
+
+
+__all__ = [
+    "Splitter",
+    "TimestampSplitter",
+    "NLastInteractionTimestampSplitter",
+    "NLastInteractionSplitter",
+]

recnexteval/settings/splitters/base.py

@@ -0,0 +1,57 @@
+import logging
+from abc import ABC, abstractmethod
+
+from recnexteval.matrix import InteractionMatrix
+
+
+logger = logging.getLogger(__name__)
+
+
+class Splitter(ABC):
+    """Abstract base class for dataset splitters.
+
+    Implementations should split an :class:`InteractionMatrix` into two
+    parts according to a splitting condition (for example, by timestamp).
+    """
+
+    def __init__(self) -> None:
+        pass
+
+    @property
+    def name(self) -> str:
+        """Return the class name of the splitter.
+
+        Returns:
+            The splitter class name.
+        """
+        return self.__class__.__name__
+
+    @property
+    def identifier(self) -> str:
+        """Return a string identifier including the splitter's parameters.
+
+        The identifier includes the class name and a comma-separated list of
+        attribute name/value pairs from `self.__dict__`.
+
+        Returns:
+            Identifier string like `Name(k1=v1,k2=v2)`.
+        """
+
+        paramstring = ",".join((f"{k}={v}" for k, v in self.__dict__.items()))
+        return self.name + f"({paramstring})"
+
+    @abstractmethod
+    def split(self, data: InteractionMatrix) -> tuple[InteractionMatrix, InteractionMatrix]:
+        """Split an interaction matrix into two parts.
+
+        Args:
+            data (InteractionMatrix): The interaction dataset to split.
+
+        Returns:
+            A pair of `InteractionMatrix` objects representing the two parts.
+
+        Raises:
+            NotImplementedError: If the concrete splitter does not implement this method.
+        """
+
+        raise NotImplementedError(f"{self.name} must implement the _split method.")

recnexteval/settings/splitters/n_last.py

@@ -0,0 +1,39 @@
+import logging
+
+from recnexteval.matrix import InteractionMatrix
+from .base import Splitter
+
+
+logger = logging.getLogger(__name__)
+
+
+class NLastInteractionSplitter(Splitter):
+    """Splits the n most recent interactions of a user into the second return value,
+    and earlier interactions into the first.
+
+    Args:
+        n (int): Number of most recent actions to assign to the second return value.
+        n_seq_data (int, optional): Number of last interactions to provide as unlabeled data
+            for model to make prediction. Defaults to 1.
+
+    Raises:
+        ValueError: If n is less than 1, as this would cause the ground truth data to be empty.
+    """
+
+    def __init__(self, n: int, n_seq_data: int = 1) -> None:
+        super().__init__()
+        if n < 1:
+            raise ValueError(
+                f"n must be greater than 0, got {n}. "
+                f"Values for n < 1 will cause the ground truth data to be empty."
+            )
+        self.n = n
+        self.n_seq_data = n_seq_data
+
+    def split(self, data: InteractionMatrix) -> tuple[InteractionMatrix, InteractionMatrix]:
+        future_interaction = data.get_users_n_last_interaction(self.n)
+        past_interaction = data - future_interaction
+        past_interaction = past_interaction.get_users_n_last_interaction(self.n_seq_data)
+        logger.debug(f"{self.identifier} has complete split")
+
+        return past_interaction, future_interaction

recnexteval/settings/splitters/n_last_timestamp.py

@@ -0,0 +1,76 @@
+import logging
+
+from recnexteval.matrix import InteractionMatrix
+from .timestamp import TimestampSplitter
+
+
+logger = logging.getLogger(__name__)
+
+
+class NLastInteractionTimestampSplitter(TimestampSplitter):
+    """Splits with n last interactions based on a timestamp.
+
+    Splits the data into unlabeled and ground truth data based on a timestamp.
+    Historical data contains last `n_seq_data` interactions before the timestamp `t`
+    and the future interaction contains interactions after the timestamp `t`.
+
+
+    Attributes:
+        past_interaction: List of unlabeled data. Interval is `[0, t)`.
+        - future_interaction: Data used for training the model.
+            Interval is `[t, t+t_upper)` or `[t,inf]`.
+        n_seq_data: Number of last interactions to provide as data for model to make prediction.
+            These interactions are past interactions from before the timestamp `t`.
+
+    Args:
+        t: Timestamp to split on in seconds since epoch.
+        t_upper: Seconds past t. Upper bound on the timestamp
+            of interactions. Defaults to None (infinity).
+        n_seq_data: Number of last interactions to provide as data
+            for model to make prediction. Defaults to 1.
+        include_all_past_data: If True, include all past data in the past_interaction.
+            Defaults to False.
+    """
+
+    def __init__(
+        self,
+        t: int,
+        t_upper: None | int = None,
+        n_seq_data: int = 1,
+        include_all_past_data: bool = False,
+    ) -> None:
+        super().__init__(t=t, t_lower=None, t_upper=t_upper)
+        self.n_seq_data = n_seq_data
+        self.include_all_past_data = include_all_past_data
+
+    def update_split_point(self, t: int) -> None:
+        logger.debug(f"{self.identifier} - Updating split point to t={t}")
+        self.t = t
+
+    def split(self, data: InteractionMatrix) -> tuple[InteractionMatrix, InteractionMatrix]:
+        """Splits data such that the following definition holds:
+
+        - past_interaction: List of unlabeled data. Interval is `[0, t)`.
+        - future_interaction: Data used for training the model.
+            Interval is `[t, t+t_upper)` or `[t,inf]`.
+
+        Args:
+            data: Interaction matrix to be split. Must contain timestamps.
+
+        Returns:
+            A 2-tuple containing the `past_interaction` and `future_interaction` matrices.
+        """
+        if self.t_upper is None:
+            future_interaction = data.timestamps_gte(self.t)
+        else:
+            future_interaction = data.timestamps_lt(self.t + self.t_upper).timestamps_gte(self.t)
+
+        if self.include_all_past_data:
+            past_interaction = data.timestamps_lt(self.t)
+        else:
+            past_interaction = data.get_users_n_last_interaction(
+                self.n_seq_data, self.t, future_interaction.user_ids
+            )
+
+        logger.debug(f"{self.identifier} has complete split")
+        return past_interaction, future_interaction

recnexteval/settings/splitters/timestamp.py

@@ -0,0 +1,82 @@
+import logging
+
+from recnexteval.matrix import InteractionMatrix
+from .base import Splitter
+
+
+logger = logging.getLogger(__name__)
+
+
+class TimestampSplitter(Splitter):
+    """Split an interaction dataset by timestamp.
+
+    The splitter divides the data into two parts:
+
+    1. Interactions with timestamps in the interval `[t - t_lower, t)`,
+       representing past interactions.
+    2. Interactions with timestamps in the interval `[t, t + t_upper]`,
+       representing future interactions.
+
+    If `t_lower` or `t_upper` are not provided, they default to infinity,
+    meaning the corresponding interval is unbounded on that side.
+
+    Note that a user can appear in both the past and future interaction sets.
+
+    Attributes:
+        past_interaction (InteractionMatrix): Interactions in the interval
+            `[0, t)`, representing unlabeled data for prediction.
+        future_interaction (InteractionMatrix): Interactions in the interval
+            `[t, t + t_upper)` or `[t, inf)`, used for training the model.
+
+    Args:
+        t: Timestamp to split on, in seconds since the Unix epoch.
+        t_lower: Seconds before `t` to include in
+            the past interactions. If None, the interval is unbounded.
+            Defaults to None.
+        t_upper: Seconds after `t` to include in
+            the future interactions. If None, the interval is unbounded.
+            Defaults to None.
+    """
+
+    def __init__(
+        self,
+        t: int,
+        t_lower: None | int = None,
+        t_upper: None | int = None,
+    ) -> None:
+        super().__init__()
+        self.t = t
+        self.t_lower = t_lower
+        self.t_upper = t_upper
+
+    def split(self, data: InteractionMatrix) -> tuple[InteractionMatrix, InteractionMatrix]:
+        """Split the interaction data by timestamp.
+
+        The method populates the `past_interaction` and `future_interaction`
+        attributes with the corresponding subsets of the input data.
+
+        Args:
+            data: The interaction dataset to split.
+                Must include timestamp information.
+
+        Returns:
+            A pair containing the past interactions and future interactions.
+        """
+
+        if self.t_lower is None:
+            # timestamp < t
+            past_interaction = data.timestamps_lt(self.t)
+        else:
+            # t-t_lower =< timestamp < t
+            past_interaction = data.timestamps_lt(self.t).timestamps_gte(self.t - self.t_lower)
+
+        if self.t_upper is None:
+            # timestamp >= t
+            future_interaction = data.timestamps_gte(self.t)
+        else:
+            # t =< timestamp < t + t_upper
+            future_interaction = data.timestamps_gte(self.t).timestamps_lt(self.t + self.t_upper)
+
+        logger.debug(f"{self.identifier} has complete split")
+
+        return past_interaction, future_interaction

recnexteval/utils/__init__.py

@@ -0,0 +1,115 @@
+"""Utility module for RecNextEval library.
+
+This module provides a set of general utility functions used throughout RecNextEval.
+It includes utilities for file handling, configuration, matrix operations, and logging.
+
+## Utility Functions
+
+General-purpose utility functions that support library operations:
+
+- `create_config_yaml`: Create configuration YAML file
+- `safe_dir`: Safely manage directory operations
+- `add_columns_to_csr_matrix`: Add columns to sparse matrix
+- `add_rows_to_csr_matrix`: Add rows to sparse matrix
+- `arg_to_str`: Convert arguments to string representation
+- `df_to_sparse`: Convert DataFrame to sparse matrix
+- `to_binary`: Convert data to binary format
+- `to_tuple`: Convert data to tuple format
+- `ProgressBar`: Progress bar utility for tracking operations
+
+## Path Utilities
+
+Directory and path management functions:
+
+- `get_cache_dir`: Get cache directory path
+- `get_data_dir`: Get data directory path
+- `get_logs_dir`: Get logs directory path
+- `get_repo_root`: Get repository root directory
+- `safe_dir`: Safely create and manage directories
+
+## Logging Control
+
+Functions to control logging level and warning suppression:
+
+- `log_level`: Get current logging level
+- `log_level_by_name`: Set logging level by name (DEBUG, INFO, WARNING, ERROR)
+- `prepare_logger`: Initialize logger for RecNextEval
+- `suppress_warnings`: Suppress all Python warnings
+- `suppress_specific_warnings`: Suppress specific warning types
+
+## Logging Example
+
+```python
+import logging
+import warnings
+import recnexteval
+
+# Set log level to INFO
+recnexteval.log_level_by_name("INFO")
+
+# Suppress all warnings
+recnexteval.suppress_warnings(suppress=True)
+
+# Log information
+logger = logging.getLogger("recnexteval")
+logger.info("This is an informational message.")
+
+# Warnings will be suppressed
+warnings.warn("This warning will not appear.")
+```
+
+## Configuration
+
+- `create_config_yaml`: Generate configuration YAML file for RecNextEval
+"""
+
+from .logging_tools import (
+    log_level,
+    log_level_by_name,
+    prepare_logger,
+    suppress_specific_warnings,
+    suppress_warnings,
+)
+from .path import (
+    get_cache_dir,
+    get_data_dir,
+    get_logs_dir,
+    get_repo_root,
+    safe_dir,
+)
+from .util import (
+    ProgressBar,
+    add_columns_to_csr_matrix,
+    add_rows_to_csr_matrix,
+    arg_to_str,
+    df_to_sparse,
+    invert,
+    to_binary,
+    to_tuple,
+)
+from .uuid_util import generate_algorithm_uuid
+from .yaml_tool import create_config_yaml
+
+
+__all__ = [
+    "create_config_yaml",
+    "safe_dir",
+    "add_columns_to_csr_matrix",
+    "add_rows_to_csr_matrix",
+    "arg_to_str",
+    "df_to_sparse",
+    "prepare_logger",
+    "to_binary",
+    "to_tuple",
+    "ProgressBar",
+    "log_level",
+    "log_level_by_name",
+    "suppress_warnings",
+    "suppress_specific_warnings",
+    "get_cache_dir",
+    "get_data_dir",
+    "get_logs_dir",
+    "get_repo_root",
+    "invert",
+    "generate_algorithm_uuid",
+]