src.fairreckitlib.model.algorithms.lenskit.lenskit_algorithms

  1"""This module contains name constants and creation wrappers for implemented lenskit algorithms.
  2
  3Constants:
  4
  5    BIASED_MF: name of the BiasedMF algorithm.
  6    IMPLICIT_MF: name of the ImplicitMF algorithm.
  7    ITEM_ITEM: name of the ItemItem algorithm.
  8    POP_SCORE: name of the PopScore algorithm.
  9    RANDOM: name of the Random recommender.
 10    USER_USER: name of the UserUser algorithm.
 11
 12Functions:
 13
 14    create_biased_mf: create lenskit BiasedMF algorithm.
 15    create_implicit_mf: create lenskit ImplicitMF algorithm.
 16    create_item_item: create lenskit ItemItem algorithm.
 17    create_pop_score: create lenskit PopScore algorithm.
 18    create_random: create lenskit Random algorithm.
 19    create_user_user: create lenskit UserUser algorithm.
 20
 21This program has been developed by students from the bachelor Computer Science at
 22Utrecht University within the Software Project course.
 23© Copyright Utrecht University (Department of Information and Computing Sciences)
 24"""
 25
 26import time
 27from typing import Any, Dict
 28
 29from lenskit.algorithms import CandidateSelector
 30from lenskit.algorithms.als import BiasedMF, ImplicitMF
 31from lenskit.algorithms.basic import PopScore, Random
 32from lenskit.algorithms.item_knn import ItemItem
 33from lenskit.algorithms.user_knn import UserUser
 34from seedbank import numpy_rng
 35
 36BIASED_MF = 'BiasedMF'
 37IMPLICIT_MF = 'ImplicitMF'
 38ITEM_ITEM = 'ItemItem'
 39POP_SCORE = 'PopScore'
 40RANDOM = 'Random'
 41USER_USER = 'UserUser'
 42
 43
 44def create_biased_mf(params: Dict[str, Any]) -> BiasedMF:
 45    """Create the lenskit BiasedMF algorithm.
 46
 47    Args:
 48        params: containing the following name-value pairs:
 49            features(int): the number of features to train.
 50            iterations(int): the number of iterations to train.
 51            user_reg(float): the regularization factor for users.
 52            item_reg(float): the regularization factor for items.
 53            damping(float): damping factor for the underlying bias.
 54            method(str): the solver to use ('cd' or 'lu').
 55            random_seed(int): the random seed or None for the current time as seed.
 56
 57    Returns:
 58        the lenskit BiasedMF algorithm.
 59    """
 60    if params['seed'] is None:
 61        params['seed'] = int(time.time())
 62
 63    return BiasedMF(
 64        params['features'],
 65        iterations=params['iterations'],
 66        reg=(params['user_reg'], params['item_reg']),
 67        damping=params['damping'],
 68        bias=True,
 69        method=params['method'],
 70        rng_spec=numpy_rng(spec=params['seed']),
 71        progress=None,
 72        save_user_features=True
 73    )
 74
 75
 76def create_implicit_mf(params: Dict[str, Any]) -> ImplicitMF:
 77    """Create the lenskit ImplicitMF algorithm.
 78
 79    Args:
 80        params: containing the following name-value pairs:
 81            features(int): the number of features to train.
 82            iterations(int): the number of iterations to train.
 83            reg(float): the regularization factor.
 84            weight(flot): the scaling weight for positive samples.
 85            use_ratings(bool): whether to use the rating column or treat
 86                every rated user-item pair as having a rating of 1.
 87            method(str): the training method ('cg' or 'lu').
 88            random_seed(int): the random seed or None for the current time as seed.
 89
 90    Returns:
 91        the lenskit ImplicitMF algorithm.
 92    """
 93    if params['seed'] is None:
 94        params['seed'] = int(time.time())
 95
 96    return ImplicitMF(
 97        params['features'],
 98        iterations=params['iterations'],
 99        reg=params['reg'],
100        weight=params['weight'],
101        use_ratings=params['use_ratings'],
102        method=params['method'],
103        rng_spec=numpy_rng(spec=params['seed']),
104        progress=None,
105        save_user_features=True
106    )
107
108
109def create_item_item(params: Dict[str, Any], feedback: str) -> ItemItem:
110    """Create the lenskit ItemItem algorithm.
111
112    Args:
113        params: containing the following name-value pairs:
114            max_neighbors(int): the maximum number of neighbors for scoring each item.
115            min_neighbors(int): the minimum number of neighbors for scoring each item.
116            min_similarity(float): minimum similarity threshold for considering a neighbor.
117        feedback: control how feedback should be interpreted ('explicit' or 'implicit').
118
119    Returns:
120        the lenskit ItemItem algorithm.
121    """
122    return ItemItem(
123        params['max_neighbors'],
124        min_nbrs=params['min_neighbors'],
125        min_sim=params['min_similarity'],
126        save_nbrs=None,
127        feedback=feedback
128    )
129
130
131def create_pop_score(params: Dict[str, Any]) -> PopScore:
132    """Create the lenskit PopScore algorithm.
133
134    Args:
135        params: containing the following name-value pairs:
136            score_method(str): for computing popularity scores ('quantile', 'rank' or 'count').
137
138    Returns:
139        the lenskit PopScore algorithm.
140    """
141    return PopScore(
142        score_method=params['score_method']
143    )
144
145
146def create_random(params: Dict[str, Any], selector: CandidateSelector) -> Random:
147    """Create the lenskit Random algorithm.
148
149    Args:
150        params: containing the following name-value pairs:
151            random_seed(int): the random seed or None for the current time as seed.
152        selector: that selects candidate items for recommendations.
153
154    Returns:
155        the lenskit Random algorithm.
156    """
157    if params['seed'] is None:
158        params['seed'] = int(time.time())
159
160    return Random(
161        selector=selector,
162        rng_spec=numpy_rng(spec=params['seed'])
163    )
164
165
166def create_user_user(params: Dict[str, Any], feedback: str) -> UserUser:
167    """Create the lenskit UserUser algorithm.
168
169    Args:
170        params: containing the following name-value pairs:
171            max_neighbors(int): the maximum number of neighbors for scoring each item.
172            min_neighbors(int): the minimum number of neighbors for scoring each item.
173            min_similarity(float): minimum similarity threshold for considering a neighbor.
174        feedback: control how feedback should be interpreted ('explicit' or 'implicit').
175
176    Returns:
177        the lenskit UserUser algorithm.
178    """
179    return UserUser(
180        params['max_neighbors'],
181        min_nbrs=params['min_neighbors'],
182        min_sim=params['min_similarity'],
183        feedback=feedback
184    )