irspack.utils.IDMapper

class irspack.utils.IDMapper(user_ids, item_ids)[source]

Bases: Generic[UserIdType, ItemIdType], ItemIDMapper[ItemIdType]

A utility class that helps mapping user/item IDs to indices or vice versa.

Parameters:

  • user_ids – List of user IDs. The ordering should be consistent with the user indices of recommenders to be used.

  • item_ids – List of item IDs. The ordering should be consistent with the item indices of recommenders or score arrays to be used.

Raises:

ValueError – When there is a duplicate in item_ids.

__init__(user_ids, item_ids)[source]
Parameters:

  • user_ids (List[UserIdType]) –

  • item_ids (List[ItemIdType]) –

Methods

__init__(user_ids, item_ids)

list_of_user_profile_to_matrix(users_info)

Converts users' profiles (interaction histories for the users) into a sparse matrix.

recommend_for_known_user_batch(recommender, ...)

Retrieves recommendation for known users.

recommend_for_known_user_id(recommender, user_id)

Retrieve recommendation result for a known user. :param recommender: The recommender for scoring. :param user_id: The target user ID. :param cutoff: Maximal number of recommendations allowed. :param allowed_item_ids: If not None, recommend the items within this list. If None, all known item ids can be recommended (except for those in item_ids argument). Defaults to None. :param forbidden_item_ids: If not None, never recommend the items within the list. Defaults to None.

recommend_for_new_user(recommender, user_profile)

Retrieves recommendations for an unknown user by using the user's contact history with the known items. :param recommender: The recommender for scoring. :param user_profile: User's profile given either as a list of item ids the user had a cotact or a item id-rating dict. Previously unseen item ID will be ignored. :param cutoff: Maximal number of recommendations allowed. :param allowed_item_ids: If not None, recommend the items within this list. If None, all known item ids can be recommended (except for those in item_ids argument). Defaults to None. :param forbidden_item_ids: If not None, never recommend the items within the list. Defaults to None.

recommend_for_new_user_batch(recommender, ...)

Retrieves recommendations for unknown users by using their contact history with the known items.

score_to_recommended_items(score, cutoff[, ...])

score_to_recommended_items_batch(score, cutoff)

Retrieve recommendation from score array.
list_of_user_profile_to_matrix(users_info)

Converts users’ profiles (interaction histories for the users) into a sparse matrix.

Parameters:

users_info (Sequence[Union[List[ItemIdType], Dict[ItemIdType, float]]]) – A list of user profiles. Each profile should be either the item ids that the user cotacted or a dictionary of item ratings. Previously unseen item IDs will be ignored.

Returns:

The converted sparse matrix. Each column correspond to self.items_ids.

Return type:

csr_matrix

recommend_for_known_user_batch(recommender, user_ids, cutoff=20, allowed_item_ids=None, per_user_allowed_item_ids=None, forbidden_item_ids=None, n_threads=None)[source]

Retrieves recommendation for known users.

Parameters:

  • recommender (BaseRecommender) – The recommender for scoring.

  • user_ids (List[UserIdType]) – A list of user ids.

  • cutoff (int) – Maximal number of recommendations allowed.

  • allowed_item_ids (Optional[List[ItemIdType]]) – If not None, defines “a list of recommendable item IDs”. Ignored if per_user_allowed_item_ids is set.

  • per_user_allowed_item_ids (Optional[List[List[ItemIdType]]]) – If not None, defines “a list of list of recommendable item IDs” and len(allowed_item_ids) must be equal to score.shape[0]. Defaults to None.

  • forbidden_item_ids (Optional[List[List[ItemIdType]]]) – If not None, defines “a list of list of forbidden item IDs” and len(allowed_item_ids) must be equal to len(item_ids) Defaults to None.

  • n_threads (Optional[int]) – Specifies the number of threads to use for the computation. If None, the environment variable "IRSPACK_NUM_THREADS_DEFAULT" will be looked up, and if the variable is not set, it will be set to os.cpu_count(). Defaults to None.

Returns:

A list of list of tuples consisting of (item_id, score). Each internal list corresponds to the recommender’s recommendation output.

Return type:

List[List[Tuple[ItemIdType, float]]]

recommend_for_known_user_id(recommender, user_id, cutoff=20, allowed_item_ids=None, forbidden_item_ids=None)[source]

Retrieve recommendation result for a known user. :param recommender: The recommender for scoring. :param user_id: The target user ID. :param cutoff: Maximal number of recommendations allowed. :param allowed_item_ids: If not None, recommend the items within this list.

If None, all known item ids can be recommended (except for those in item_ids argument). Defaults to None.

Parameters:

  • forbidden_item_ids (Optional[List[ItemIdType]]) – If not None, never recommend the items within the list. Defaults to None.

  • recommender (BaseRecommender) –

  • user_id (UserIdType) –

  • cutoff (int) –

  • allowed_item_ids (Optional[List[ItemIdType]]) –

Raises:

RuntimeError – When user_id is not in self.user_ids.

Returns:

A List of tuples consisting of (item_id, score).

Return type:

List[Tuple[ItemIdType, float]]

recommend_for_new_user(recommender, user_profile, cutoff=20, allowed_item_ids=None, forbidden_item_ids=None)

Retrieves recommendations for an unknown user by using the user’s contact history with the known items. :param recommender: The recommender for scoring. :param user_profile: User’s profile given either as a list of item ids the user had a cotact or a item id-rating dict.

Previously unseen item ID will be ignored.

Parameters:

  • cutoff (int) – Maximal number of recommendations allowed.

  • allowed_item_ids (Optional[List[ItemIdType]]) – If not None, recommend the items within this list. If None, all known item ids can be recommended (except for those in item_ids argument). Defaults to None.

  • forbidden_item_ids (Optional[List[ItemIdType]]) – If not None, never recommend the items within the list. Defaults to None.

  • recommender (BaseRecommender) –

  • user_profile (Union[List[ItemIdType], Dict[ItemIdType, float]]) –

Returns:

A List of tuples consisting of (item_id, score).

Return type:

List[Tuple[ItemIdType, float]]

recommend_for_new_user_batch(recommender, user_profiles, cutoff=20, allowed_item_ids=None, per_user_allowed_item_ids=None, forbidden_item_ids=None, n_threads=None)

Retrieves recommendations for unknown users by using their contact history with the known items.

Parameters:

  • recommender (BaseRecommender) – The recommender for scoring.

  • user_profiles (Sequence[Union[List[ItemIdType], Dict[ItemIdType, float]]]) – A list of user profiles. Each profile should be either the item ids the user had a cotact, or item-rating dict. Previously unseen item IDs will be ignored.

  • cutoff (int) – Maximal number of recommendations allowed.

  • allowed_item_ids (Optional[List[ItemIdType]]) – If not None, defines “a list of recommendable item IDs”. Ignored if per_user_allowed_item_ids is set.

  • per_user_allowed_item_ids (Optional[List[List[ItemIdType]]]) – If not None, defines “a list of list of recommendable item IDs” and len(allowed_item_ids) must be equal to score.shape[0]. Defaults to None.

  • forbidden_item_ids (Optional[List[List[ItemIdType]]]) – If not None, defines “a list of list of forbidden item IDs” and len(allowed_item_ids) must be equal to len(item_ids) Defaults to None.

  • n_threads (Optional[int]) – Specifies the number of threads to use for the computation. If None, the environment variable "IRSPACK_NUM_THREADS_DEFAULT" will be looked up, and if the variable is not set, it will be set to os.cpu_count(). Defaults to None.

Returns:

A list of list of tuples consisting of (item_id, score). Each internal list corresponds to the recommender’s recommendation output.

Return type:

List[List[Tuple[ItemIdType, float]]]

Retrieve recommendation from score array. An item with negative infinity score for a user will not be recommended for the user.

Parameters:

  • score (ndarray) – 1d numpy ndarray for score.

  • cutoff (int) – Maximal number of recommendations allowed.

  • allowed_item_ids (Optional[List[ItemIdType]]) – If not None, defines “a list of recommendable item IDs”. Ignored if per_user_allowed_item_ids is set.

  • per_user_allowed_item_ids (Optional[List[List[ItemIdType]]]) – If not None, defines “a list of list of recommendable item IDs” and len(allowed_item_ids) must be equal to score.shape[0]. Defaults to None.

  • allowed_item_ids – If not None, defines “a list of list of recommendable item IDs” and len(allowed_item_ids) must be equal to len(item_ids). Defaults to None.

  • forbidden_item_ids (Optional[List[List[ItemIdType]]]) – If not None, defines “a list of list of forbidden item IDs” and len(allowed_item_ids) must be equal to len(item_ids) Defaults to None.

  • n_threads (Optional[int]) –

Return type:

List[List[Tuple[ItemIdType, float]]]