src.fairreckitlib.model.algorithms.top_k_recommender

 1"""This module contains a recommender that utilizes a predictor to produce item recommendations.
 2
 3Classes:
 4
 5    TopK: wrap a predictor to be used as a recommender.
 6
 7This program has been developed by students from the bachelor Computer Science at
 8Utrecht University within the Software Project course.
 9© Copyright Utrecht University (Department of Information and Computing Sciences)
10"""
11
12from typing import Any, Dict
13
14import pandas as pd
15
16from .base_predictor import BasePredictor
17from .base_recommender import BaseRecommender
18
19
20class TopK(BaseRecommender):
21    """Recommender that implements top K recommendations using a predictor."""
22
23    def __init__(self, predictor: BasePredictor, rated_items_filter: bool):
24        """Construct the TopK recommender.
25
26        Args:
27            predictor: the underlying predictor to use for recommendations.
28            rated_items_filter: whether to filter already rated items when
29                producing item recommendations.
30        """
31        BaseRecommender.__init__(self, rated_items_filter)
32        self.predictor = predictor
33
34    def get_name(self) -> str:
35        """Get the name of the underlying predictor.
36
37        Returns:
38            the name of the underlying predictor.
39        """
40        return self.predictor.get_name()
41
42    def get_num_threads(self) -> int:
43        """Get the max number of threads the underlying predictor can use.
44
45        Returns:
46            the number of threads.
47        """
48        return self.predictor.get_num_threads()
49
50    def get_params(self) -> Dict[str, Any]:
51        """Get the parameters of the underlying predictor.
52
53        Returns:
54            the parameters of the underlying predictor.
55        """
56        return self.predictor.get_params()
57
58    def on_train(self, _) -> None:
59        """Train the underlying predictor on the train set.
60
61        Raises:
62            ArithmeticError: possibly raised by the underlying predictor on training.
63            MemoryError: possibly raised by the underlying predictor on training.
64            RuntimeError: possibly raised by the underlying predictor on training.
65        """
66        # use the original train_set matrix to train the predictor
67        self.predictor.train(self.train_set)
68
69    def on_recommend(self, user: int, num_items: int) -> pd.DataFrame:
70        """Compute item recommendations using the underlying predictor.
71
72        Go through all user-item combinations for the specified user and
73        predict a score. Sort in descending order and return the topK items.
74
75        Args:
76            user: the user ID to compute recommendations for.
77            num_items: the number of item recommendations to produce.
78
79        Raises:
80            ArithmeticError: possibly raised by the underlying predictor on testing.
81            MemoryError: possibly raised by the underlying predictor on testing.
82            RuntimeError: when the underlying predictor is not trained yet.
83
84        Returns:
85            dataframe with the columns: 'item' and 'score'.
86        """
87        items = self.predictor.train_set.get_items()
88        # filter items that are rated by the user already
89        if self.rated_items_filter:
90            user_rated_items = self.predictor.train_set.get_user_rated_items(user)
91            items = [i for i in items if i not in user_rated_items]
92
93        # TODO this is not very efficient, but works (also should utilize available num_threads)
94        # compute recommendations for all items and truncate to the top num_items
95        item_ratings = list(map(lambda i: (i, self.predictor.predict(user, i)), items))
96        item_ratings.sort(key=lambda i: i[1], reverse=True)
97
98        return pd.DataFrame(item_ratings[:num_items], columns=['item', 'score'])