src.fairreckitlib.model.algorithms.matrix

  1"""This module contains the matrix classes that can be used for algorithm training.
  2
  3Classes:
  4
  5    MatrixDataFrame: (base) matrix implementation for a pandas dataframe matrix.
  6    MatrixCSR: matrix implementation that uses a sparse CSR matrix.
  7
  8This program has been developed by students from the bachelor Computer Science at
  9Utrecht University within the Software Project course.
 10© Copyright Utrecht University (Department of Information and Computing Sciences)
 11"""
 12
 13import numpy as np
 14import pandas as pd
 15from scipy import sparse
 16
 17
 18class Matrix:
 19    """Base class for all train set matrices using a pandas dataframe.
 20
 21    The intended use of the matrix class is to add an extra layer of
 22    abstraction to load a matrix into a specific format depending on
 23    the algorithm implementation that is used. Effectively this will
 24    reduce the memory usage of algorithms by loading the matrix directly
 25    into the expected format.
 26
 27    Public methods:
 28
 29    get_matrix
 30    get_items
 31    get_users
 32    get_user_rated_items
 33    knows_item
 34    knows_item_list
 35    knows_user
 36    knows_user_list
 37    """
 38
 39    def __init__(self, file_path: str):
 40        """Construct the Matrix.
 41
 42        The matrix is expected to be stored in a tab separated file without header,
 43        with the 'user', 'item', 'rating' columns in this order.
 44
 45        Args:
 46            file_path: the file path to where the matrix is stored.
 47
 48        Raises:
 49            FileNotFoundError: when the matrix file is not found.
 50        """
 51        self.matrix = pd.read_csv(
 52            file_path,
 53            sep='\t',
 54            header=None,
 55            names=['user', 'item', 'rating']
 56        )
 57        self.users = self.matrix['user'].unique()
 58        self.items = self.matrix['item'].unique()
 59
 60    def get_matrix(self) -> pd.DataFrame:
 61        """Get the matrix.
 62
 63        Returns:
 64            the matrix dataframe.
 65        """
 66        return self.matrix
 67
 68    def get_items(self) -> np.ndarray:
 69        """Get the (unique) items of the matrix.
 70
 71        Returns:
 72            a list of unique item IDs.
 73        """
 74        return self.items
 75
 76    def get_users(self) -> np.ndarray:
 77        """Get the (unique) users of the matrix.
 78
 79        Returns:
 80            a list of unique user IDs.
 81        """
 82        return self.users
 83
 84    def get_user_rated_items(self, user: int) -> np.ndarray:
 85        """Get the rated items for the specified user.
 86
 87        Args:
 88            user: the user to get the rated items of.
 89
 90        Raises:
 91            KeyError: when the user is not part of the matrix.
 92
 93        Returns:
 94            a list of item IDs that are rated by the user.
 95        """
 96        if user not in self.users:
 97            raise KeyError('User is not part of the matrix')
 98
 99        return self._get_user_rated_items(user)
100
101    def _get_user_rated_items(self, user: int) -> np.ndarray:
102        """Get the rated items for the specified user.
103
104        Args:
105            user: the user to get the rated items of.
106
107        Returns:
108            a list of item IDs that are rated by the user.
109        """
110        is_user = self.matrix['user'] == user
111        return np.array(self.matrix.loc[is_user]['item'].tolist())
112
113    def knows_item(self, item: int) -> bool:
114        """Get if the specified item is known in the matrix.
115
116        Args:
117            item: the item ID to evaluate.
118
119        Returns:
120            whether the item ID is known.
121        """
122        return item in self.items
123
124    def knows_item_list(self, items: pd.Series) -> pd.Series:
125        """Get if the specified items are known in the matrix.
126
127        Args:
128            items: the item IDs to evaluate.
129
130        Returns:
131            a boolean series of the input showing whether each item is a known item ID.
132        """
133        return items.isin(self.items)
134
135    def knows_user(self, user: int) -> bool:
136        """Get if the specified user is known in the matrix.
137
138        Args:
139            user: the user ID to evaluate.
140
141        Returns:
142            whether the user ID is known.
143        """
144        return user in self.users
145
146    def knows_user_list(self, users: pd.Series) -> pd.Series:
147        """Get if the specified users are known in the matrix.
148
149        Args:
150            users: the user IDs to evaluate.
151
152        Returns:
153            a boolean series of the input showing whether each user is a known user ID.
154        """
155        return users.isin(self.users)
156
157
158class MatrixCSR(Matrix):
159    """Matrix implementation with a sparse CSR matrix."""
160
161    def __init__(self, file_path: str):
162        """Construct the CSR Matrix.
163
164        The csr matrix is expected to be stored in a tab separated file without header,
165        with the 'user', 'item', 'rating' columns in this order.
166        The matrix is loaded into a dataframe and converted to a CSR matrix.
167
168        Args:
169            file_path: the file path to where the matrix is stored.
170        """
171        Matrix.__init__(self, file_path)
172        self.matrix = sparse.csr_matrix(
173            (self.matrix['rating'], (self.matrix['user'], self.matrix['item']))
174        )
175
176    def get_matrix(self) -> sparse.csr_matrix:
177        """Get the matrix.
178
179        Returns:
180            the csr matrix.
181        """
182        return self.matrix
183
184    def _get_user_rated_items(self, user: int) -> np.ndarray:
185        """Get the rated items for the specified user.
186
187        Args:
188            user: the user to get the rated items of.
189
190        Returns:
191            a list of item IDs that are rated by the user.
192        """
193        return self.matrix[user].tocoo().col