Matrix Utilities¶
We have some matrixrelated utilities, since matrices are used so heavily in recommendation algorithms.
Building Ratings Matrices¶

lenskit.matrix.
sparse_ratings
(ratings, scipy=False, *, users=None, items=None)¶ Convert a rating table to a sparse matrix of ratings.
 Parameters
ratings (pandas.DataFrame) – a data table of (user, item, rating) triples.
scipy – if
True
, return a SciPy matrix instead ofCSR
.users (pandas.Index) – an index of user IDs.
items (pandas.Index) – an index of items IDs.
 Returns
a named tuple containing the sparse matrix, user index, and item index.
 Return type

class
lenskit.matrix.
RatingMatrix
(matrix, users, items)¶ Bases:
tuple
A rating matrix with associated indices.

matrix
¶ The rating matrix, with users on rows and items on columns.
 Type

users
¶ mapping from user IDs to row numbers.
 Type

items
¶ mapping from item IDs to column numbers.
 Type

property
items
¶ Alias for field number 2

property
matrix
¶ Alias for field number 0

property
users
¶ Alias for field number 1

Compressed Sparse Row Matrices¶
We use CSRformat sparse matrices in quite a few places. Since SciPy’s sparse matrices are not directly usable from Numba, we have implemented a Numbacompiled CSR representation that can be used from accelerated algorithm implementations.

class
lenskit.matrix.
CSR
(nrows=None, ncols=None, nnz=None, ptrs=None, inds=None, vals=None, N=None)¶ Bases:
object
Simple compressed sparse row matrix. This is like
scipy.sparse.csr_matrix
, with a couple of useful differences:It is backed by a Numba jitclass, so it can be directly used from Numbaoptimized functions.
The value array is optional, for cases in which only the matrix structure is required.
The value array, if present, is always doubleprecision.
You generally don’t want to create this class yourself with the constructor. Instead, use one of its class methods.
If you need to pass an instance off to a Numbacompiled function, use
N
:_some_numba_fun(csr.N)
We use the indirection between this and the Numba jitclass so that the main CSR implementation can be pickled, and so that we can have class and instance methods that are not compatible with jitclass but which are useful from interpreted code.

rowptrs
¶ the row pointers.
 Type

colinds
¶ the column indices.
 Type

values
¶ the values
 Type

classmethod
empty
(shape, row_nnzs, *, rpdtype=<class 'numpy.int32'>)¶ Create an empty CSR matrix.
 Parameters
shape (tuple) – the array shape (rows,cols)
row_nnzs (arraylike) – the number of nonzero entries for each row

classmethod
from_coo
(rows, cols, vals, shape=None, rpdtype=<class 'numpy.int32'>)¶ Create a CSR matrix from data in COO format.
 Parameters
rows (arraylike) – the row indices.
cols (arraylike) – the column indices.
vals (arraylike) – the data values; can be
None
.shape (tuple) – the array shape, or
None
to infer from row & column indices.

classmethod
from_scipy
(mat, copy=True)¶ Convert a scipy sparse matrix to an internal CSR.
 Parameters
mat (scipy.sparse.spmatrix) – a SciPy sparse matrix.
copy (bool) – if
False
, reuse the SciPy storage if possible.
 Returns
a CSR matrix.
 Return type

to_scipy
()¶ Convert a CSR matrix to a SciPy
scipy.sparse.csr_matrix
. Avoids copying if possible. Parameters
self (CSR) – A CSR matrix.
 Returns
A SciPy sparse matrix with the same data.
 Return type

property
N
¶ Get the native backing array.

subset_rows
(begin, end)¶ Subset the rows in this matrix.

rowinds
() → numpy.ndarray¶ Get the row indices from this array. Combined with
colinds
andvalues
, this can form a COOformat sparse matrix.

row
(row)¶ Return a row of this matrix as a dense ndarray.
 Parameters
row (int) – the row index.
 Returns
the row, with 0s in the place of missing values.
 Return type

row_extent
(row)¶ Get the extent of a row in the underlying column index and value arrays.

row_cs
(row)¶ Get the column indcies for the stored values of a row.

row_vs
(row)¶ Get the stored values of a row.

row_nnzs
()¶ Get a vector of the number of nonzero entries in each row.
Note
This method is not available from Numba.
 Returns
the number of nonzero entries in each row.
 Return type

normalize_rows
(normalization)¶ Normalize the rows of the matrix.
Note
The normalization ignores missing values instead of treating them as 0.
Note
This method is not available from Numba.
 Parameters
normalization (str) –
The normalization to perform. Can be one of:
'center'
 center rows about the mean'unit'
 convert rows to a unit vector
 Returns
The normalization values for each row.
 Return type

transpose
(values=True)¶ Transpose a CSR matrix.
Note
This method is not available from Numba.

class
lenskit.matrix.
_CSR
(nrows, ncols, nnz, ptrs, inds, vals)¶ Bases:
object
Internal implementation class for
CSR
. If you work with CSRs from Numba, you will use anumba.jitclass()
ed version of this.Note that the
values
array is always present (unlike the Python shim), but is zerolength if no values are present. This eases Numba typechecking.