src.fairreckitlib.model.algorithms.base_recommender

  1"""This module contains the base class for recommenders.
  2
  3Classes:
  4
  5    BaseRecommender: base class for recommenders.
  6    Recommender: implements basic shared functionality.
  7
  8This program has been developed by students from the bachelor Computer Science at
  9Utrecht University within the Software Project course.
 10© Copyright Utrecht University (Department of Information and Computing Sciences)
 11"""
 12
 13from abc import ABCMeta, abstractmethod
 14from typing import Any, Dict, List
 15
 16import numpy as np
 17import pandas as pd
 18
 19from .base_algorithm import BaseAlgorithm
 20
 21
 22class BaseRecommender(BaseAlgorithm, metaclass=ABCMeta):
 23    """Base class for FairRecKit recommenders.
 24
 25    A recommender is used for recommender experiments. It computes a number of
 26    item recommendations for any user that it was trained on.
 27    Derived recommenders are expected to implement the abstract interface.
 28
 29    Abstract methods:
 30
 31    on_recommend
 32    on_recommend_batch (optional)
 33
 34    Public methods:
 35
 36    has_rated_items_filter
 37    recommend
 38    recommend_batch
 39    """
 40
 41    def __init__(self, rated_items_filter: bool):
 42        """Construct the recommender.
 43
 44        Args:
 45            rated_items_filter: whether to filter already rated items when
 46                producing item recommendations.
 47        """
 48        BaseAlgorithm.__init__(self)
 49        self.rated_items_filter = rated_items_filter
 50
 51    def has_rated_items_filter(self) -> bool:
 52        """Get if the recommender filters already rated items when producing recommendations.
 53
 54        Returns:
 55            whether the recommender filters already rated items.
 56        """
 57        return self.rated_items_filter
 58
 59    def recommend(self, user: int, num_items: int=10) -> pd.DataFrame:
 60        """Compute item recommendations for the specified user.
 61
 62        A recommendation is impossible when the user is not present in
 63        the unique users it was trained on and will return an empty dataframe.
 64
 65        Args:
 66            user: the user ID to compute recommendations for.
 67            num_items: the number of item recommendations to produce.
 68
 69        Raises:
 70            ArithmeticError: possibly raised by a recommender on testing.
 71            MemoryError: possibly raised by a recommender on testing.
 72            RuntimeError: when the recommender is not trained yet.
 73
 74        Returns:
 75            a dataframe with the columns: 'item' and 'score'.
 76        """
 77        if self.train_set is None:
 78            raise RuntimeError('Recommender is not trained for item recommendations')
 79
 80        if not self.train_set.knows_user(user):
 81            return pd.DataFrame(columns=['item', 'score'])
 82
 83        return self.on_recommend(user, num_items)
 84
 85    @abstractmethod
 86    def on_recommend(self, user: int, num_items: int) -> pd.DataFrame:
 87        """Compute item recommendations for the specified user.
 88
 89        The user is assumed to be present in the train set that the
 90        recommender was trained on.
 91        Derived implementations are expected to return a dataframe
 92        with the 'score' column in descending order.
 93
 94        Args:
 95            user: the user ID to compute recommendations for.
 96            num_items: the number of item recommendations to produce.
 97
 98        Raises:
 99            ArithmeticError: possibly raised by a recommender on testing.
100            MemoryError: possibly raised by a recommender on testing.
101            RuntimeError: when the recommender is not trained yet.
102
103        Returns:
104            a dataframe with the columns: 'item' and 'score'.
105        """
106        raise NotImplementedError()
107
108    def recommend_batch(self, users: List[int], num_items: int=10) -> pd.DataFrame:
109        """Compute the items recommendations for each of the specified users.
110
111        All the users that are not present in the train set that the recommender
112        was trained on are filtered before recommendations are made.
113
114        Args:
115            users: the user ID's to compute recommendations for.
116            num_items: the number of item recommendations to produce.
117
118        Raises:
119            ArithmeticError: possibly raised by a recommender on testing.
120            MemoryError: possibly raised by a recommender on testing.
121            RuntimeError: when the recommender is not trained yet.
122
123        Returns:
124            a dataframe with the columns: 'rank', 'user', 'item', 'score'.
125        """
126        if self.train_set is None:
127            raise RuntimeError('Recommender is not trained for item recommendations')
128
129        users = [u for u in users if self.train_set.knows_user(u)]
130        if len(users) == 0:
131            return pd.DataFrame(columns=['rank', 'user', 'item', 'score'])
132
133        return self.on_recommend_batch(users, num_items)
134
135    def on_recommend_batch(self, users: List[int], num_items: int) -> pd.DataFrame:
136        """Compute the items recommendations for each of the specified users.
137
138        All the users are assumed to be present in the train set that
139        the recommender was trained on.
140        A standard batch implementation is provided, but derived classes are
141        allowed to override batching with their own logic.
142
143        Args:
144            users: the user ID's to compute recommendations for.
145            num_items: the number of item recommendations to produce.
146
147        Raises:
148            ArithmeticError: possibly raised by a recommender on testing.
149            MemoryError: possibly raised by a recommender on testing.
150            RuntimeError: when the recommender is not trained yet.
151
152        Returns:
153            a dataframe with the columns: 'rank', 'user', 'item', 'score'.
154        """
155        result = pd.DataFrame()
156
157        for user in users:
158            item_scores = self.recommend(user, num_items)
159
160            item_scores['rank'] = np.arange(1, 1 + num_items)
161            item_scores['user'] = np.full(num_items, user)
162
163            result = pd.concat(
164                [result, item_scores[['rank', 'user', 'item', 'score']]],
165                ignore_index=True
166            )
167
168        return result
169
170
171class Recommender(BaseRecommender, metaclass=ABCMeta):
172    """Recommender that implements basic shared functionality."""
173
174    def __init__(self, name: str, params: Dict[str, Any], num_threads: int,
175                 rated_items_filter: bool):
176        """Construct the recommender.
177
178        Args:
179            name: the name of the recommender.
180            params: the parameters of the recommender.
181            num_threads: the max number of threads the recommender can use.
182            rated_items_filter: whether to filter already rated items when
183                producing item recommendations.
184        """
185        BaseRecommender.__init__(self, rated_items_filter)
186        self.num_threads = num_threads
187        self.recommender_name = name
188        self.params = params
189
190    def get_name(self) -> str:
191        """Get the name of the recommender.
192
193        Returns:
194            the recommender name.
195        """
196        return self.recommender_name
197
198    def get_num_threads(self) -> int:
199        """Get the max number of threads the recommender can use.
200
201        Returns:
202            the number of threads.
203        """
204        return self.num_threads
205
206    def get_params(self) -> Dict[str, Any]:
207        """Get the parameters of the recommender.
208
209        Returns:
210            the recommender parameters.
211        """
212        return dict(self.params)