recnexteval 0.1.0__py3-none-any.whl

recnexteval/algorithms/time_aware_item_knn/decay_functions.py

@@ -0,0 +1,260 @@
+# 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 numpy as np
+from numpy.typing import ArrayLike
+
+
+class DecayFunction:
+    def __call__(self, time_distances: ArrayLike) -> ArrayLike:
+        """Apply the decay.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: Array of event ages to which decays have been applied.
+        :rtype: ArrayLike
+        """
+        raise NotImplementedError()
+
+
+class ExponentialDecay(DecayFunction):
+    """Applies exponential decay.
+
+    For each value x in ``time_distances`` the decayed value is computed as
+
+    .. math::
+
+        f(x) = e^{-\\alpha * x}
+
+    where alpha is the decay parameter.
+
+    :param decay: Exponential decay parameter, should be in the [0, 1] interval.
+    :type decay: float
+    """
+
+    @classmethod
+    def validate_decay(cls, decay: float) -> None:
+        """Verify if the decay parameter is in the right range for this decay function."""
+        if not (0 <= decay <= 1):
+            raise ValueError(f"Decay parameter = {decay} is not in the supported range: [0, 1].")
+
+    def __init__(self, decay: float):
+        self.validate_decay(decay)
+        self.decay = decay
+
+    def __call__(self, time_distances: ArrayLike) -> ArrayLike:
+        """Apply the decay function.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: The decayed time array.
+        :rtype: ArrayLike
+        """
+
+        return np.exp(-self.decay * time_distances)
+
+
+class ConvexDecay(DecayFunction):
+    """Applies a convex decay function.
+
+    For each value x in the ``time_distances`` the decayed value is computed as
+
+    .. math::
+
+        f(x) = \\alpha^{x}
+
+    where :math:`alpha` is the decay parameter.
+
+    :param decay: The decay parameter, should be in the ]0, 1] interval.
+    :type decay: float
+    """
+
+    @classmethod
+    def validate_decay(cls, decay: float):
+        """Verify if the decay parameter is in the right range for this decay function."""
+        if not (0 < decay <= 1):
+            raise ValueError(f"Decay parameter = {decay} is not in the supported range: ]0, 1].")
+
+    def __init__(self, decay: float):
+        self.validate_decay(decay)
+        self.decay = decay
+
+    def __call__(self, time_distances: ArrayLike):
+        """Apply the decay function.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: The decayed time array.
+        :rtype: ArrayLike
+        """
+
+        return np.power(self.decay, time_distances)
+
+
+class ConcaveDecay(DecayFunction):
+    """Applies a concave decay function.
+
+    For each value x in the ``time_distances`` the decayed value is computed as
+
+    .. math::
+
+        f(x) = 1 - \\alpha^{1-\\frac{x}{N}}
+
+    where :math:`alpha` is the decay parameter and :math:`N` is the ``max_distance`` parameter.
+
+    :param decay: The decay parameter, should be in the [0, 1[ interval.
+    :type decay: float
+    :param max_distance: Normalizing parameter, to put distances in the [0, 1].
+    :type max_distance: float
+    """
+
+    @classmethod
+    def validate_decay(cls, decay: float):
+        """Verify if the decay parameter is in the right range for this decay function."""
+        if not (0 < decay <= 1):
+            raise ValueError(f"Decay parameter = {decay} is not in the supported range: ]0, 1].")
+
+    def __init__(self, decay: float, max_distance: float):
+        self.validate_decay(decay)
+        self.decay = decay
+        self.max_distance = max_distance
+
+    def __call__(self, time_distances: ArrayLike):
+        """Apply the decay function.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: The decayed array.
+        :rtype: ArrayLike
+        """
+        if (time_distances > self.max_distance).any():
+            raise ValueError(
+                "At least one of the distances is bigger than the specified max_distance."
+            )
+        return 1 - np.power(self.decay, 1 - (time_distances / self.max_distance))
+
+
+class LogDecay(DecayFunction):
+    """Applies a logarithmic decay function.
+
+    For each value x in the ``time_distances`` the decayed value is computed as
+
+    .. math::
+
+        f(x) = log_\\alpha ((\\alpha-1)(1-\\frac{x}{N}) + 1)
+
+    where :math:`alpha` is the decay parameter and :math:`N` is the ``max_distance`` parameter.
+
+    :param decay: The decay parameter, should be in the range ]1, inf[
+    :type decay: float
+    :param max_distance: Normalizing parameter, to put distances in the [0, 1].
+    :type max_distance: float
+    """
+
+    @classmethod
+    def validate_decay(cls, decay: float):
+        """Verify if the decay parameter is in the right range for this decay function."""
+        if not (1 < decay):
+            raise ValueError(f"Decay parameter = {decay} is not in the supported range: ]1, inf[.")
+
+    def __init__(self, decay: float, max_distance: float):
+        self.validate_decay(decay)
+        self.decay = decay
+        self.max_distance = max_distance
+
+    def __call__(self, time_distances: ArrayLike):
+        """Apply the decay function.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: The decayed time array.
+        :rtype: ArrayLike
+        """
+        if (time_distances > self.max_distance).any():
+            raise ValueError(
+                "At least one of the distances is bigger than the specified max_distance."
+            )
+        return np.log(((self.decay - 1) * (1 - time_distances / self.max_distance)) + 1) / np.log(
+            self.decay
+        )
+
+
+class LinearDecay(DecayFunction):
+    """Applies a linear decay function.
+
+    For each value x in the ``time_distances`` the decayed value is computed as
+
+    .. math::
+
+        f(x) = \\max(1 - (\\frac{x}{N}) \\alpha, 0)
+
+    where :math:`alpha` is the decay parameter and :math:`N` is the ``max_distance`` parameter.
+
+    :param decay: The decay parameter, should be in the [0, inf[ interval.
+    :type decay: float
+    :param max_distance: Normalizing parameter, to put distances in the [0, 1].
+    :type max_distance: float
+    """
+
+    @classmethod
+    def validate_decay(cls, decay: float):
+        if not (0 <= decay):
+            raise ValueError(f"Decay parameter = {decay} is not in the supported range: [0, +inf[.")
+
+    def __init__(self, decay: float, max_distance: float):
+        self.validate_decay(decay)
+        self.decay = decay
+        self.max_distance = max_distance
+
+    def __call__(self, time_distances: ArrayLike):
+        """Apply the decay function.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: The decayed time array.
+        :rtype: ArrayLike
+        """
+        if (time_distances > self.max_distance).any():
+            raise ValueError(
+                "At least one of the distances is bigger than the specified max_distance."
+            )
+        results = 1 - (time_distances / self.max_distance) * self.decay
+        results[results < 0] = 0
+        return results
+
+
+class InverseDecay(DecayFunction):
+    """Invert the scores.
+
+    Decay parameter only added for interface unity.
+    For each value x in the ``time_distances`` the decayed value is computed as
+
+    .. math::
+
+        f(x) = \\frac{1}{x}
+    """
+
+    def __call__(self, time_distances: ArrayLike):
+        """Apply the decay function.
+
+        :param time_distances: array of distances to be decayed.
+        :type time_distances: ArrayLike
+        :returns: The decayed time array.
+        :rtype: ArrayLike
+        """
+
+        results = time_distances.astype(float).copy()
+        results[results > 0] = 1 / results[results > 0]
+        results[results == 0] = 1
+        return results
+
+
+class NoDecay(ExponentialDecay):
+    """Turns the array into a binary array."""
+
+    def __init__(self):
+        super().__init__(0)

recnexteval/algorithms/time_aware_item_knn/ding_2005.py

@@ -0,0 +1,52 @@
+# 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
+
+from recnexteval.algorithms.time_aware_item_knn.base import TARSItemKNN
+
+
+class TARSItemKNNDing(TARSItemKNN):
+    """Time aware variant of ItemKNN which uses an exponential decay function at prediction time and cosine similarity.
+
+    Algorithm as presented in
+    Yi Ding and Xue Li. 2005.
+    Time weight collaborative filtering.
+    In Proceedings of the 14th ACM international conference on Information and knowledge management (CIKM '05).
+    Association for Computing Machinery, New York, NY, USA, 485–492.
+    https://doi.org/10.1145/1099554.1099689
+
+
+    Computation of the similarity matrix is the same as normal ItemKNN.
+    When predicting however the user's older interactions are given less weight in the final prediction score.
+
+    .. math::
+
+        \\text{sim}(u, i) = \\sum\\limits_{j \\in X_u} e^{-\\alpha \\cdot \\delta t_{u,j}} \\cdot \\text{sim}(i, j)
+
+    Where :math:`\\alpha` is the `predict_decay` parameter.
+
+    :param K: How many neigbours to use per item,
+        make sure to pick a value below the number of columns of the matrix to fit on.
+        Defaults to 200
+    :type K: int, Optional
+    :param pad_with_popularity: Whether to pad the similarity matrix with RecentPop Algorithm.
+        Defaults to True.
+    :type pad_with_popularity: bool, optional
+    :param predict_decay: Defines the decay scaling used for decay during prediction.
+        Defaults to 1 / (24 * 3600).
+        This means for every day since an interaction, the value of it will be divided by 'e'.
+    :type predict_decay: float, optional
+    :param similarity: Which similarity measure to use. Defaults to `"cosine"`.
+        ``["cosine", "conditional_probability"]`` are supported.
+    :type similarity: str, optional
+
+    This code is adapted from RecPack :cite:`recpack`
+    """
+
+    SUPPORTED_SIMILARITIES = ["cosine", "conditional_probability"]
+
+    def __init__(self, K: int = 200, pad_with_popularity: bool = True, predict_decay: float = 1 / (24 * 3600), similarity: str = "cosine"):
+        super().__init__(K=K, pad_with_popularity=pad_with_popularity, fit_decay=0, predict_decay=predict_decay, similarity=similarity, decay_function="exponential")

recnexteval/algorithms/time_aware_item_knn/liu_2010.py

@@ -0,0 +1,65 @@
+# 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
+
+"""Module with time-dependent ItemKNN implementations"""
+
+from recnexteval.algorithms.time_aware_item_knn.base import TARSItemKNN
+
+
+class TARSItemKNNLiu(TARSItemKNN):
+    """Time aware variant of ItemKNN which uses an exponential decay function and cosine similarity.
+
+    Algorithm as described in
+    Nathan N. Liu, Min Zhao, Evan Xiang, and Qiang Yang.
+    2010. Online evolutionary collaborative filtering.
+    In Proceedings of the fourth ACM conference on Recommender systems (RecSys '10).
+    Association for Computing Machinery, New York, NY, USA, 95–102.
+    https://doi.org/10.1145/1864708.1864729
+
+    The algorithm uses an exponential decay function:
+
+    .. math::
+
+        \\Gamma(x) = e^{- \\alpha \\cdot \\text{x}}
+
+    where :math:`\\alpha` is the decay scaling parameter,
+    and x is the time between the maximal timestamp in the matrix
+    and the timestamp of the event.
+
+    Similarity is computed on this weighted matrix, using cosine similarity.
+    At prediction time a user's history is weighted using the same formula with a different alpha.
+    This weighted history is then multiplied with the precomputed similarity matrix.
+
+    :param K: How many neigbours to use per item,
+        make sure to pick a value below the number of columns of the matrix to fit on.
+        Defaults to 200
+    :type K: int, optional
+    :param pad_with_popularity: Whether to pad the similarity matrix with RecentPop Algorithm.
+        Defaults to True.
+    :type pad_with_popularity: bool, optional
+    :param fit_decay: Defines the decay scaling used for decay during model fitting.
+        Defaults to 1 / (24 * 3600).
+        This means for every day since an interaction, the value of it will be divided by 'e'.
+    :type fit_decay: float, optional
+    :param predict_decay: Defines the decay scaling used for decay during prediction.
+        Defaults to 1 / (24 * 3600).
+        This means for every day since an interaction, the value of it will be divided by 'e'.
+    :type predict_decay: float, optional
+
+    This code is adapted from RecPack :cite:`recpack`
+    """
+
+    def __init__(
+        self,
+        K: int = 200,
+        pad_with_popularity: bool = True,
+        fit_decay: float = 1 / (24 * 3600),
+        predict_decay: float = 1 / (24 * 3600),
+    ):
+        super().__init__(
+            K=K, pad_with_popularity=pad_with_popularity, fit_decay=fit_decay, predict_decay=predict_decay, similarity="cosine", decay_function="exponential"
+        )

recnexteval/algorithms/time_aware_item_knn/similarity_functions.py

@@ -0,0 +1,106 @@
+# 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
+
+
+from scipy.sparse import csr_matrix, diags
+from sklearn.metrics.pairwise import cosine_similarity
+
+from recnexteval.utils import invert, to_binary
+
+
+def compute_conditional_probability(X: csr_matrix, pop_discount: float = 0) -> csr_matrix:
+    """Compute conditional probability like similarity.
+
+    Computation using equation (3) from the original ItemKNN paper.
+    'Item-based top-n recommendation algorithms.'
+    Deshpande, Mukund, and George Karypis
+
+    .. math ::
+        sim(i,j) = \\frac{\\sum\\limits_{u \\in U} \\mathbb{I}_{u,i} X_{u,j}}{Freq(i) \\times Freq(j)^{\\alpha}}
+
+    Where :math:`\\mathbb{I}_{ui}` is 1 if the user u has visited item i, and 0 otherwise.
+    And alpha is the pop_discount parameter.
+    Note that this is a non-symmetric similarity measure.
+    Given that X is a binary matrix, and alpha is set to 0,
+    this simplifies to pure conditional probability.
+
+    .. math::
+        sim(i,j) = \\frac{Freq(i \\land j)}{Freq(i)}
+
+    :param X: user x item matrix with scores per user, item pair.
+    :type X: csr_matrix
+    :param pop_discount: Parameter defining popularity discount. Defaults to 0
+    :type pop_discount: float, Optional.
+    """
+    # matrix with co_mat_i,j =  SUM(1_u,i * X_u,j for each user u)
+    # If the input matrix is binary, this is the cooccurence count matrix.
+    co_mat = to_binary(X).T @ X
+
+    # Compute the inverse of the item frequencies
+    A = invert(diags(to_binary(X).sum(axis=0).A[0]).tocsr())
+
+    if pop_discount:
+        # This has all item similarities
+        # Co_mat is weighted by both the frequencies of item i
+        # and the frequency of item j to the pop_discount power.
+        # If pop_discount = 1, this similarity is symmetric again.
+        item_cond_prob_similarities = A @ co_mat @ A.power(pop_discount)
+    else:
+        # Weight the co_mat with the amount of occurences of item i.
+        item_cond_prob_similarities = A @ co_mat
+
+    # Set diagonal to 0, because we don't support self similarity
+    item_cond_prob_similarities.setdiag(0)
+
+    return item_cond_prob_similarities
+
+
+def compute_cosine_similarity(X: csr_matrix) -> csr_matrix:
+    """Compute the cosine similarity between the items in the matrix.
+
+    Self similarity is removed.
+
+    :param X: user x item matrix with scores per user, item pair.
+    :type X: csr_matrix
+    :return: similarity matrix
+    :rtype: csr_matrix
+    """
+    # X.T otherwise we are doing a user KNN
+    item_cosine_similarities = cosine_similarity(X.T, dense_output=False)
+    item_cosine_similarities.setdiag(0)
+    # Set diagonal to 0, because we don't want to support self similarity
+
+    return item_cosine_similarities
+
+
+def compute_pearson_similarity(X: csr_matrix) -> csr_matrix:
+    """Compute the pearson correlation as a similarity between each item in the matrix.
+
+    Self similarity is removed.
+    When computing similarity, the avg of nonzero entries per user is used.
+
+    :param X: Rating or psuedo rating matrix.
+    :type X: csr_matrix
+    :return: similarity matrix.
+    :rtype: csr_matrix
+    """
+
+    if (X == 1).sum() == X.nnz:
+        raise ValueError("Pearson similarity can not be computed on a binary matrix.")
+
+    count_per_item = (X > 0).sum(axis=0).A
+
+    avg_per_item = X.sum(axis=0).A.astype(float)
+
+    avg_per_item[count_per_item > 0] = (
+        avg_per_item[count_per_item > 0] / count_per_item[count_per_item > 0]
+    )
+
+    X = X - (X > 0).multiply(avg_per_item)
+
+    # Given the rescaled matrix, the pearson correlation is just cosine similarity on this matrix.
+    return compute_cosine_similarity(X)

recnexteval/algorithms/time_aware_item_knn/top_k.py

@@ -0,0 +1,61 @@
+# 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
+
+from typing import Optional
+
+import numpy as np
+from scipy.sparse import csr_matrix
+
+
+def get_top_K_ranks(X: csr_matrix, K: Optional[int] = None) -> csr_matrix:
+    """Returns a matrix of ranks assigned to the largest K values in X.
+
+    Selects K largest values for every row in X and assigns a rank to each.
+
+    :param X: Matrix from which we will select K values in every row.
+    :type X: csr_matrix
+    :param K: Amount of values to select.
+    :type K: int, optional
+    :return: Matrix with K values per row.
+    :rtype: csr_matrix
+    """
+    U, I, V = [], [], []
+    for row_ix, (le, ri) in enumerate(zip(X.indptr[:-1], X.indptr[1:])):
+        K_row_pick = min(K, ri - le) if K is not None else ri - le
+
+        if K_row_pick != 0:
+            top_k_row = X.indices[
+                le + np.argpartition(X.data[le:ri], list(range(-K_row_pick, 0)))[-K_row_pick:]
+            ]
+
+            for rank, col_ix in enumerate(reversed(top_k_row)):
+                U.append(row_ix)
+                I.append(col_ix)
+                V.append(rank + 1)
+
+    X_top_K = csr_matrix((V, (U, I)), shape=X.shape)
+
+    return X_top_K
+
+
+def get_top_K_values(X: csr_matrix, K: Optional[int] = None) -> csr_matrix:
+    """Returns a matrix of only the K largest values for every row in X.
+
+    Selects the top-K items for every user (which is equal to the K nearest neighbours.)
+    In case of a tie for the last position, the item with the largest index of the tied items is used.
+
+    :param X: Matrix from which we will select K values in every row.
+    :type X: csr_matrix
+    :param K: Amount of values to select.
+    :type K: int, optional
+    :return: Matrix with K values per row.
+    :rtype: csr_matrix
+    """
+    top_K_ranks = get_top_K_ranks(X, K)
+    top_K_ranks[top_K_ranks > 0] = 1  # ranks to binary
+
+    return top_K_ranks.multiply(X)  # elementwise multiplication

recnexteval/algorithms/time_aware_item_knn/utils.py

@@ -0,0 +1,47 @@
+# 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
+
+
+EPSILON = 1e-13
+
+logger = logging.getLogger(__name__)
+
+
+def invert(x: np.ndarray | csr_matrix) -> np.ndarray | csr_matrix:
+    """Invert an array.
+
+    :param x: [description]
+    :type x: [type]
+    :return: [description]
+    :rtype: [type]
+    """
+    if isinstance(x, np.ndarray):
+        ret = np.zeros(x.shape)
+    elif isinstance(x, csr_matrix):
+        ret = csr_matrix(x.shape)
+    else:
+        raise TypeError("Unsupported type for argument x.")
+    ret[x.nonzero()] = 1 / x[x.nonzero()]
+    return ret
+
+
+def to_binary(X: csr_matrix) -> csr_matrix:
+    """Converts a matrix to binary by setting all non-zero values to 1.
+
+    :param X: Matrix to convert to binary.
+    :type X: csr_matrix
+    :return: Binary matrix.
+    :rtype: csr_matrix
+    """
+    X_binary = X.astype(bool).astype(X.dtype)
+
+    return X_binary

recnexteval/algorithms/time_aware_item_knn/vaz_2013.py

@@ -0,0 +1,50 @@
+# 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
+
+from recnexteval.algorithms.time_aware_item_knn.base import TARSItemKNN
+
+
+class TARSItemKNNVaz(TARSItemKNN):
+    """Time aware variant of ItemKNN which uses a exponential decay function and pearson similarity.
+
+    Algorithm as described in
+    Understanding the Temporal Dynamics of Recommendations across Different Rating Scales
+    Paula Cristina Vaz, Ricardo Ribeiro, David Martins de Matos.
+    Late-Breaking Results, Project Papers and Workshop Proceedings of the 21st Conference
+    on User Modeling, Adaptation, and Personalization. Rome, Italy, June 10-14, 2013.
+
+    The algorithm uses an exponential decay function:
+
+    .. math::
+
+        \\Gamma(x) = e^{- \\alpha \\cdot \\text{x}}
+
+    where :math:`\\alpha` is the decay scaling parameter,
+    and x is the time between the maximal timestamp in the matrix
+    and the timestamp of the event.
+
+    :param K: How many neigbours to use per item,
+        make sure to pick a value below the number of columns of the matrix to fit on.
+        Defaults to 200
+    :type K: int, optional
+    :param pad_with_popularity: Whether to pad the similarity matrix with RecentPop Algorithm.
+        Defaults to True.
+    :type pad_with_popularity: bool, optional
+    :param fit_decay: Defines the decay scaling used for decay during model fitting.
+        Defaults to 1/(24*3600). 
+        This means for every day since an interaction, the value of it will be divided by 'e'.
+    :type fit_decay: float, optional
+    :param predict_decay: Defines the decay scaling used for decay during prediction.
+        Defaults to 1/(24*3600).
+        This means for every day since an interaction, the value of it will be divided by 'e'.
+    :type predict_decay: float, optional
+
+    This code is adapted from RecPack :cite:`recpack`
+    """
+
+    def __init__(self, K: int = 200, pad_with_popularity: bool = True, fit_decay: float = 1 / (24 * 3600), predict_decay: float = 1 / (24 * 3600)):
+        super().__init__(K, pad_with_popularity=pad_with_popularity, fit_decay=fit_decay, predict_decay=predict_decay, similarity="pearson", decay_function="exponential")