src.fairreckitlib.model.algorithms.elliot.elliot_recommender

  1"""This module contains the elliot recommender and creation functions.
  2
  3Classes:
  4
  5    ElliotRecommender: recommender implementation for elliot.
  6
  7Functions:
  8
  9    create_funk_svd: create FunkSVD recommender (factory creation compatible).
 10    create_item_knn: create ItemKNN recommender (factory creation compatible).
 11    create_most_pop: create MostPop recommender (factory creation compatible).
 12    create_multi_vae: create MultiVAE recommender (factory creation compatible).
 13    create_pure_svd: create PureSVD recommender (factory creation compatible).
 14    create_random: create Random recommender (factory creation compatible).
 15    create_user_knn: create UserKNN recommender (factory creation compatible).
 16
 17This program has been developed by students from the bachelor Computer Science at
 18Utrecht University within the Software Project course.
 19© Copyright Utrecht University (Department of Information and Computing Sciences)
 20"""
 21
 22import time
 23from typing import Any, Dict, List
 24
 25import pandas as pd
 26
 27from ..base_recommender import Recommender
 28
 29
 30class ElliotRecommender(Recommender):
 31    """Recommender implementation for the Elliot framework."""
 32
 33    def __init__(self, name: str, params: Dict[str, Any], **kwargs):
 34        """Construct the elliot recommender.
 35
 36        The recommender is not procedural, instead it serves as a wrapper
 37        that holds the correct parameters used by the framework which are
 38        used in the model pipeline.
 39
 40        Args:
 41            name: the name of the recommender.
 42            params: the parameters of the recommender.
 43
 44        Keyword Args:
 45            num_threads(int): the max number of threads the recommender can use.
 46            rated_items_filter(bool): whether to filter already rated items when
 47                producing item recommendations.
 48        """
 49        Recommender.__init__(self, name, params, kwargs['num_threads'],
 50                             kwargs['rated_items_filter'])
 51        if not self.rated_items_filter:
 52            raise RuntimeError('no rated items filter is not supported.')
 53
 54    def on_train(self, train_set: Any) -> None:
 55        """Train the elliot model not supported."""
 56        raise RuntimeError('training is done by running the framework')
 57
 58    def on_recommend(self, user: int, num_items: int) -> pd.DataFrame:
 59        """Recommend with the elliot model not supported."""
 60        raise RuntimeError('recommending is done by running the framework')
 61
 62    def on_recommend_batch(self, users: List[int], num_items: int) -> pd.DataFrame:
 63        """Recommend batching with the elliot model not supported."""
 64        raise RuntimeError('recommending is done by running the framework')
 65
 66
 67def create_funk_svd(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
 68    """Create the FunkSVD recommender.
 69
 70    Args:
 71        name: the name of the algorithm.
 72        params: containing the following name-value pairs:
 73            epochs(int): number of iterations.
 74            factors(int): number of factors of feature embeddings.
 75            learning_rate(float): the learning rate.
 76            regularization_factors(float): regularization coefficient for latent factors.
 77            regularization_bias(flot): regularization coefficient for bias.
 78            seed(int): the random seed or None for the current time as seed.
 79
 80    Returns:
 81        the ElliotRecommender wrapper of FunkSVD.
 82    """
 83    elliot_params = {
 84        'epochs': params['iterations'],
 85        'batch_size': 512,
 86        'factors': params['factors'],
 87        'lr': params['learning_rate'],
 88        'reg_w': params['regularization_factors'],
 89        'reg_b': params['regularization_bias'],
 90        'seed': params['seed'] if params.get('seed') else int(time.time())
 91    }
 92
 93    return ElliotRecommender(name, elliot_params, **kwargs)
 94
 95
 96def create_item_knn(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
 97    """Create the ItemKNN recommender.
 98
 99    Args:
100        name: the name of the algorithm.
101        params: containing the following name-value pairs:
102            neighbors(int): number of item neighbors.
103            similarity(str): similarity function to use.
104            implementation(str): implementation type (‘aiolli’ or ‘classical’).
105
106    Returns:
107        the ElliotRecommender wrapper of ItemKNN.
108    """
109    elliot_params = {
110        'neighbors': params['neighbors'],
111        'similarity': params['similarity'],
112        'implementation': params['implementation'],
113    }
114
115    return ElliotRecommender(name, elliot_params, **kwargs)
116
117
118def create_most_pop(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
119    """Create the MostPop recommender.
120
121    Args:
122        name: the name of the algorithm.
123        params: there are no parameters for this algorithm.
124
125    Returns:
126        the ElliotRecommender wrapper of MostPop.
127    """
128    return ElliotRecommender(name, params, **kwargs)
129
130
131def create_multi_vae(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
132    """Create the MultiVAE recommender.
133
134    Args:
135        name: the name of the algorithm.
136        params: containing the following name-value pairs:
137            iterations(int): number of iterations.
138            factors(int): number of latent factors.
139            learning_rate(float): the learning rate.
140            intermediate_dimensions(int): number of intermediate dimension.
141            regularization_factors(float): regularization coefficient.
142            dropout_probability(float): the dropout probability.
143            seed(int): the random seed or None for the current time as seed.
144
145    Returns:
146        the ElliotRecommender wrapper of MultiVAE.
147    """
148    elliot_params = {
149        'epochs': params['iterations'],
150        'batch_size': 512,
151        'lr': params['learning_rate'],
152        'reg_lambda': params['regularization_factors'],
153        'intermediate_dim': params['intermediate_dimensions'],
154        'latent_dim': params['factors'],
155        'dropout_pkeep': params['dropout_probability'],
156        'seed': params['seed'] if params.get('seed') else int(time.time())
157    }
158
159    return ElliotRecommender(name, elliot_params, **kwargs)
160
161
162def create_pure_svd(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
163    """Create the PureSVD recommender.
164
165    Args:
166        name: the name of the algorithm.
167        params: containing the following name-value pairs:
168            factors(int): number of latent factors.
169            seed(int): the random seed or None for the current time as seed.
170
171    Returns:
172        the ElliotRecommender wrapper of PureSVD.
173    """
174    elliot_params = {
175        'factors': params['factors'],
176        'seed': params['seed'] if params.get('seed') else int(time.time())
177    }
178
179    return ElliotRecommender(name, elliot_params, **kwargs)
180
181
182def create_random(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
183    """Create the Random recommender.
184
185    Args:
186        name: the name of the algorithm.
187        params: containing the following name-value pairs:
188            seed(int): the random seed or None for the current time as seed.
189
190    Returns:
191        the ElliotRecommender wrapper of Random.
192    """
193    elliot_params = {
194        'random_seed': params['seed'] if params.get('seed') else int(time.time())
195    }
196
197    return ElliotRecommender(name, elliot_params, **kwargs)
198
199
200def create_svd_pp(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
201    """Create the SVDpp recommender.
202
203    Args:
204        name: the name of the algorithm.
205        params: containing the following name-value pairs:
206            iterations(int): number of iterations.
207            factors(int): number of latent factors.
208            learning_rate(float): the learning rate.
209            regularization_factors(float): regularization coefficient for latent factors.
210            regularization_bias(float): regularization coefficient for bias.
211            seed(int): the random seed or None for the current time as seed.
212
213    Returns:
214        the ElliotRecommender wrapper of SVDpp.
215    """
216    elliot_params = {
217        'epochs': params['iterations'],
218        'batch_size': 512,
219        'factors': params['factors'],
220        'lr': params['learning_rate'],
221        'reg_w': params['regularization_factors'],
222        'reg_b': params['regularization_bias'],
223        'seed': params['seed'] if params.get('seed') else int(time.time())
224    }
225
226    return ElliotRecommender(name, elliot_params, **kwargs)
227
228
229def create_user_knn(name: str, params: Dict[str, Any], **kwargs) -> ElliotRecommender:
230    """Create the UserKNN recommender.
231
232    Args:
233        name: the name of the algorithm.
234        params: containing the following name-value pairs:
235            neighbors(int): number of user neighbors.
236            similarity(str): similarity function to use.
237            implementation(str): implementation type (‘aiolli’ or ‘classical’).
238
239    Returns:
240        the ElliotRecommender wrapper of UserKNN.
241    """
242    elliot_params = {
243        'neighbors': params['neighbors'],
244        'similarity': params['similarity'],
245        'implementation': params['implementation'],
246    }
247
248    return ElliotRecommender(name, elliot_params, **kwargs)