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[UserIdType]) – List of user IDs. The ordering should be consistent with the user indices of recommenders to be used.
item_ids (List[ItemIdType]) – 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.
`recommend_for_new_user`(recommender, user_profile)	Retrieves recommendations for an unknown user by using the user's contact history with the known items.
`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[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 (List[ItemIdType] | None) – If not None, defines “a list of recommendable item IDs”. Ignored if per_user_allowed_item_ids is set.
per_user_allowed_item_ids (List[List[ItemIdType]] | None) – 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 (List[List[ItemIdType]] | None) – 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 (int | None) – 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.

Parameters:

recommender (BaseRecommender) – The recommender for scoring.
user_id (UserIdType) – The target user ID.
cutoff (int) – Maximal number of recommendations allowed.
allowed_item_ids (List[ItemIdType] | None) – 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 (List[ItemIdType] | None) – If not None, never recommend the items within the list. Defaults to None.

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.

Parameters:

recommender (BaseRecommender) – The recommender for scoring.
user_profile (List[ItemIdType] | Dict[ItemIdType, float]) – 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.
cutoff (int) – Maximal number of recommendations allowed.
allowed_item_ids (List[ItemIdType] | None) – 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 (List[ItemIdType] | None) – If not None, never recommend the items within the list. Defaults to None.

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[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 (List[ItemIdType] | None) – If not None, defines “a list of recommendable item IDs”. Ignored if per_user_allowed_item_ids is set.
per_user_allowed_item_ids (List[List[ItemIdType]] | None) – 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 (List[List[ItemIdType]] | None) – 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 (int | None) – 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]]]

score_to_recommended_items_batch(score, cutoff, allowed_item_ids=None, per_user_allowed_item_ids=None, forbidden_item_ids=None, n_threads=None)#

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 (List[ItemIdType] | None) – If not None, defines “a list of recommendable item IDs”. Ignored if per_user_allowed_item_ids is set.
per_user_allowed_item_ids (List[List[ItemIdType]] | None) – 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 (List[List[ItemIdType]] | None) – 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 (int | None)

Return type:

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