lenskit.data.MatrixRelationshipSet#

class lenskit.data.MatrixRelationshipSet(name, vocabularies, schema, table)#

Bases: RelationshipSet

Two-entity relationships without duplicates, accessible in matrix form.

Note

Client code does not need to construct this class; obtain instances from a relationship set’s matrix() method.

Parameters:
row_type: str#
col_type: str#
__getstate__()#
__setstate__(state)#
property row_vocabulary#

The vocabulary for row entities.

property col_vocabulary#

The vocabulary for column entities.

property n_rows#
property n_cols: int#
Return type:

int

matrix(*, row_entity=None, col_entity=None)#

Convert this relationship set into a matrix, coalescing duplicate observations.

Changed in version 2025.6: Removed the fixed defaults for row_entity and col_entity.

Parameters:

  • row_entity (str | None) – The specified row entity of the matrix. Defaults to the first entity in the relationship’s list of involved entities.

  • col_entity (str | None) – The specified column entity of the matrix. Defaults to the last entity in the relationship’s list of involved entities.

Return type:

MatrixRelationshipSet

csr_structure(*, format: Literal['numpy'] = 'numpy') → lenskit.data.matrix.CSRStructure#
csr_structure(*, format: Literal['arrow']) → lenskit.data.matrix.SparseRowArray

Get the compressed sparse row structure of this relationship matrix.

coo_structure()#

Get the compressed sparse row structure of this relationship matrix.

Return type:

lenskit.data.matrix.COOStructure

scipy(attribute: str | None = None, *, layout: Literal['coo'], legacy: Literal[True]) → scipy.sparse.coo_matrix#
scipy(attribute: str | None = None, *, layout: Literal['coo'], legacy: Literal[False] = False) → scipy.sparse.coo_array[Any, tuple[int, int]]
scipy(attribute: str | None = None, *, layout: Literal['csr'] = 'csr', legacy: Literal[True]) → scipy.sparse.csr_matrix
scipy(attribute: str | None = None, *, layout: Literal['csr'] = 'csr', legacy: Literal[False] = False) → scipy.sparse.csr_array[Any, tuple[int, int]]
scipy(attribute: str | None = None, *, layout: lenskit.data.types.LAYOUT = 'csr', legacy: bool = False) → scipy.sparse.sparray | scipy.sparse.spmatrix

Get this relationship matrix as a SciPy sparse matrix.

Note

If the selected attribute has missing values, they are omitted from the returned matrix.

Parameters:

  • attribute – The attribute to return, or None to return an indicator-only sparse matrix (all observed values are 1).

  • layout – The matrix layout to return.

Returns:

The sparse matrix.

torch(attribute: str | None = None, *, layout: Literal['csr'] = 'csr') → torch.Tensor#
torch(attribute: str | None = None, *, layout: Literal['coo']) → torch.Tensor

Get this relationship matrix as a PyTorch sparse tensor.

Note

If the selected attribute has missing values, they are omitted from the returned matrix.

Parameters:

  • attribute – The attribute to return, or None to return an indicator-only sparse matrix (all observed values are 1).

  • layout – The matrix layout to return.

Returns:

The sparse matrix.

sample_negatives(rows, *, weighting='uniform', n=None, verify=True, max_attempts=10, rng=None)#

Sample negative columns (columns with no observation recorded) for an array of rows. On a normal interaction matrix, this samples negative items for users.

Parameters:

  • rows (numpy.ndarray[tuple[int], numpy.dtype[numpy.int32]]) – The row numbers. Duplicates are allowed, and negative columns are sampled independently for each row. Must be a 1D array or tensor.

  • weighting (Literal['uniform', 'popular', 'popularity']) – The weighting for sampled negatives; uniform samples them uniformly at random, while popularity samples them proportional to their popularity (number of occurrences).

  • n (int | None) – The number of negatives to sample for each user. If None, a single-dimensional vector is returned.

  • verify (bool) – Whether to verify that the negative items are actually negative. Unverified sampling is much faster but can return false negatives.

  • max_attempts (int) – When verification is on, the maximum attempts before giving up and returning a possible false negative.

  • rng (numpy.random.Generator | None) – A random number generator to use.

Return type:

numpy.typing.NDArray[numpy.int32]

row_table(id: lenskit.data.types.ID) → pyarrow.Table | None#
row_table(*, number: int) → pyarrow.Table

Get a single row of this interaction matrix as a table.

row_items(id: lenskit.data.types.ID) → lenskit.data._items.ItemList | None#
row_items(*, number: int) → lenskit.data._items.ItemList

Get a single row of this interaction matrix as an item list. Only valid when the column entity class is ``item’’.

to_ilc()#

Get the rows as an item list collection.

Deprecated since version 2025.6: Deprecated alias for item_lists().

Return type:

lenskit.data._collection.ItemListCollection

item_lists()#

Get the rows as an item list collection.

Return type:

lenskit.data._collection.ItemListCollection

row_stats()#
col_stats()#