recpack.matrix.InteractionMatrix

class recpack.matrix.InteractionMatrix(df: pandas.core.frame.DataFrame, item_ix: str, user_ix: str, timestamp_ix: Optional[str] = None, shape: Optional[Tuple[int, int]] = None)

An InteractionMatrix contains interactions between users and items at a certain time.

It provides a number of properties and methods for easy manipulation of this interaction data.

Note

The InteractionMatrix does not assume binary user-item pairs. If a user interacts with an item more than once, there will be two entries for this user-item pair.

Parameters
  • df (pd.DataFrame) – Dataframe containing user-item interactions. Must contain at least item ids and user ids.

  • item_ix (str) – Item ids column name.

  • user_ix (str) – User ids column name.

  • timestamp_ix (str, optional) – Interaction timestamps column name.

  • shape (Tuple[int, int], optional) – The desired shape of the matrix, i.e. the number of users and items. If no shape is specified, the number of users will be equal to the maximum user id plus one, the number of items to the maximum item id plus one.

Methods

copy()

Create a deep copy of this InteractionMatrix.

eliminate_timestamps([inplace])

Remove all timestamp information.

from_csr_matrix(X)

Create an InteractionMatrix from a csr_matrix containing interactions.

get_timestamp(interaction_id)

Return the timestamp of a specific interaction by interaction ID.

indices_in(u_i_lists[, inplace])

Select interactions between the specified user-item combinations.

interactions_in(interaction_ids[, inplace])

Select the interactions by their interaction ids

items_in(I[, inplace])

Keep only interactions with the specified items.

load(file_prefix)

Create a new interaction matrix instance from saved file.

nonzero()

save(file_prefix)

Save the interaction matrix to files.

timestamps_gt(timestamp[, inplace])

Select interactions after a given timestamp.

timestamps_gte(timestamp[, inplace])

Select interactions after and including a given timestamp.

timestamps_lt(timestamp[, inplace])

Select interactions up to a given timestamp.

timestamps_lte(timestamp[, inplace])

Select interactions up to and including a given timestamp.

union(im)

Combine events from this InteractionMatrix with another.

users_in(U[, inplace])

Keep only interactions by one of the specified users.

Attributes

INTERACTION_IX

ITEM_IX

TIMESTAMP_IX

USER_IX

active_items

The set of all items with at least one interaction.

active_users

The set of all users with at least one interaction.

binary_item_history

The unique items interacted with, per user.

binary_values

All user-item interactions as a sparse, binary matrix of size (users, items).

density

The density of the interaction matrix.

has_timestamps

Boolean indicating whether instance has timestamp information.

indices

Returns a tuple of lists of user IDs and item IDs corresponding to interactions.

interaction_history

The interactions per user

last_timestamps_matrix

A sparse matrix with the last timestamp for each user, item pair.

num_active_items

The number of items with at least one interaction.

num_active_users

The number of users with at least one interaction.

num_interactions

The total number of interactions.

properties

sorted_interaction_history

The interaction IDs per user, sorted by timestamp (ascending).

sorted_item_history

The items the user interacted with for every user sorted by timestamp (ascending).

timestamps

Timestamps of interactions as a pandas Series, indexed by user ID and item ID.

values

All user-item interactions as a sparse matrix of size (|users|, |items|).

class InteractionMatrixProperties(num_users: int, num_items: int, has_timestamps: bool)
property active_items: Set[int]

The set of all items with at least one interaction.

Returns

Set of user IDs with at least one interaction.

Return type

Set[int]

property active_users: Set[int]

The set of all users with at least one interaction.

Returns

Set of user IDs with at least one interaction.

Return type

Set[int]

property binary_item_history: Iterator[Tuple[int, List[int]]]

The unique items interacted with, per user.

Yield

Tuples of user ID, list of distinct item IDs the user interacted with.

Return type

List[Tuple[int, List[int]]]

property binary_values: scipy.sparse._csr.csr_matrix

All user-item interactions as a sparse, binary matrix of size (users, items).

An entry is 1 if there is at least one interaction between that user and item. In all other cases the entry is 0.

Returns

Binary csr_matrix of interactions.

Return type

csr_matrix

copy() recpack.matrix.interaction_matrix.InteractionMatrix

Create a deep copy of this InteractionMatrix.

Returns

Deep copy of this InteractionMatrix.

Return type

InteractionMatrix

property density: float

The density of the interaction matrix.

The density is computed as the fraction of user item pairs that have an interaction

Returns

The density.

Return type

float

eliminate_timestamps(inplace: bool = False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Remove all timestamp information.

Parameters

inplace (bool) – Modify the data matrix in place. If False, returns a new object.

classmethod from_csr_matrix(X: scipy.sparse._csr.csr_matrix) recpack.matrix.interaction_matrix.InteractionMatrix

Create an InteractionMatrix from a csr_matrix containing interactions.

Warning

No timestamps can be passed this way!

Returns

InteractionMatrix constructed from the csr_matrix.

Return type

InteractionMatrix

get_timestamp(interaction_id: int) int

Return the timestamp of a specific interaction by interaction ID.

Parameters

interaction_id (int) – the interaction ID in the DataFrame to fetch the timestamp of.

Raises

AttributeError – Raised if the object does not have timestamps.

Returns

The timestamp of the interaction.

Return type

int

property has_timestamps: bool

Boolean indicating whether instance has timestamp information.

Returns

True if timestamps information is available, False otherwise.

Return type

bool

property indices: Tuple[List[int], List[int]]

Returns a tuple of lists of user IDs and item IDs corresponding to interactions.

Returns

Tuple of lists of user IDs and item IDs that correspond to at least one interaction.

Return type

Tuple[List[int], List[int]]

indices_in(u_i_lists: Tuple[List[int], List[int]], inplace=False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Select interactions between the specified user-item combinations.

Parameters
  • u_i_lists (Tuple[List[int], List[int]]) – Two lists as a tuple, the first list are the indices of users, and the second are indices of items, both should be of the same length.

  • inplace (bool, optional) – Apply the selection in place to the object, defaults to False

Returns

None if inplace is True, otherwise a new InteractionMatrix object with the selection of events.

Return type

Union[InteractionMatrix, None]

property interaction_history: Iterator[Tuple[int, List[int]]]

The interactions per user

Yield

Tuples of user ID, list of interaction IDs.

Return type

List[Tuple[int, List[int]]]

interactions_in(interaction_ids: List[int], inplace: bool = False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Select the interactions by their interaction ids

Parameters
  • interaction_ids (List[int]) – A list of interaction ids

  • inplace (bool, optional) – Apply the selection in place, or return a new InteractionMatrix object, defaults to False

Returns

None if inplace, otherwise new InteractionMatrix object with the selected interactions

Return type

Union[None, InteractionMatrix]

items_in(I: Union[Set[int], List[int]], inplace=False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Keep only interactions with the specified items.

Parameters
  • I (Union[Set[int], List[int]]) – A Set or List of items to select the interactions.

  • inplace (bool, optional) – Apply the selection in place or not, defaults to False

Returns

None if inplace, otherwise returns a new InteractionMatrix object

Return type

Union[InteractionMatrix, None]

property last_timestamps_matrix: scipy.sparse._csr.csr_matrix

A sparse matrix with the last timestamp for each user, item pair.

By using the maximal timestamp for each pair, we make it possible to use non deduplicated datasets.

classmethod load(file_prefix) recpack.matrix.interaction_matrix.InteractionMatrix

Create a new interaction matrix instance from saved file.

Parameters

file_prefix (str) – The prefix of the files to load, should end in the filename, but without extension (no .csv or such).

Returns

InteractionMatrix created from file.

Return type

InteractionMatrix

property num_active_items: int

The number of items with at least one interaction.

Returns

Number of active items.

Return type

int

property num_active_users: int

The number of users with at least one interaction.

Returns

Number of active users.

Return type

int

property num_interactions: int

The total number of interactions.

Returns

Total interaction count.

Return type

int

save(file_prefix: str) None

Save the interaction matrix to files.

Creates two files one at <file_prefix>.csv with the raw dataframe, and a second at <file_prefix>_properties.yaml which contains the properties of the interaction matrix.

Parameters

file_prefix (str) – The prefix of the files to save, should end in the filename, but without extension (no .csv or such).

property sorted_interaction_history: Iterator[Tuple[int, List[int]]]

The interaction IDs per user, sorted by timestamp (ascending).

Raises

AttributeError – If there is no timestamp column can’t sort

Yield

tuple of user ID, list of interaction IDs sorted by timestamp

Return type

List[Tuple[int, List[int]]]

property sorted_item_history: Iterator[Tuple[int, List[int]]]

The items the user interacted with for every user sorted by timestamp (ascending).

Raises

AttributeError – If there is no timestamp column.

Yield

Tuple of user ID, list of item IDs sorted by timestamp.

Return type

List[Tuple[int, List[int]]]

property timestamps: pandas.core.series.Series

Timestamps of interactions as a pandas Series, indexed by user ID and item ID.

Raises

AttributeError – If there is no timestamp column.

Returns

Series of interactions with multi-index on (user ID, item ID)

Return type

pd.Series

timestamps_gt(timestamp: float, inplace: bool = False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Select interactions after a given timestamp.

Parameters
  • timestamp (float) – The timestamp with which the interactions timestamp is compared.

  • inplace (bool, optional) – Apply the selection in place if True, defaults to False

Returns

None if inplace, otherwise returns a new InteractionMatrix object

Return type

Union[InteractionMatrix, None]

timestamps_gte(timestamp: float, inplace: bool = False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Select interactions after and including a given timestamp.

Parameters
  • timestamp (float) – The timestamp with which the interactions timestamp is compared.

  • inplace (bool, optional) – Apply the selection in place if True, defaults to False

Returns

None if inplace, otherwise returns a new InteractionMatrix object

Return type

Union[InteractionMatrix, None]

timestamps_lt(timestamp: float, inplace: bool = False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Select interactions up to a given timestamp.

Parameters
  • timestamp (float) – The timestamp with which the interactions timestamp is compared.

  • inplace (bool, optional) – Apply the selection in place if True, defaults to False

Returns

None if inplace, otherwise returns a new InteractionMatrix object

Return type

Union[InteractionMatrix, None]

timestamps_lte(timestamp: float, inplace: bool = False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Select interactions up to and including a given timestamp.

Parameters
  • timestamp (float) – The timestamp with which the interactions timestamp is compared.

  • inplace (bool, optional) – Apply the selection in place if True, defaults to False

Returns

None if inplace, otherwise returns a new InteractionMatrix object

Return type

Union[InteractionMatrix, None]

union(im: recpack.matrix.interaction_matrix.InteractionMatrix) recpack.matrix.interaction_matrix.InteractionMatrix

Combine events from this InteractionMatrix with another.

The matrices need to have the same shape and either both have timestamps or neither.

Parameters

im (InteractionMatrix) – InteractionMatrix to union with.

Returns

Union of interactions in this InteractionMatrix and the other.

Return type

InteractionMatrix

users_in(U: Union[Set[int], List[int]], inplace=False) Optional[recpack.matrix.interaction_matrix.InteractionMatrix]

Keep only interactions by one of the specified users.

Parameters
  • U (Union[Set[int], List[int]]) – A Set or List of users to select the interactions from.

  • inplace (bool, optional) – Apply the selection in place or not, defaults to False

Returns

None if inplace, otherwise returns a new InteractionMatrix object

Return type

Union[InteractionMatrix, None]

property values: scipy.sparse._csr.csr_matrix

All user-item interactions as a sparse matrix of size (|users|, |items|).

Each entry is the number of interactions between that user and item. If there are no interactions between a user and item, the entry is 0.

Returns

Interactions between users and items as a csr_matrix.

Return type

csr_matrix