irspack.utils.ItemIDMapper

class irspack.utils.ItemIDMapper(item_ids)[source]

Bases: Generic[ItemIdType]

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

Parameters:: item_ids – List of item IDs. The ordering of this list 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__(item_ids)[source]

Parameters:: item_ids (List[ItemIdType]) –

Methods

`__init__`(item_ids)
`list_of_user_profile_to_matrix`(users_info)	Converts users' profiles (interaction histories for the users) into a sparse matrix.
`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)[source]

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_new_user(recommender, user_profile, cutoff=20, allowed_item_ids=None, forbidden_item_ids=None)[source]

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)[source]

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]]]

score_to_recommended_items_batch(score, cutoff, allowed_item_ids=None, per_user_allowed_item_ids=None, forbidden_item_ids=None, n_threads=None)[source]

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]]]