lenskit.data.MatrixRelationshipSet
==================================

.. py:class:: lenskit.data.MatrixRelationshipSet(name, vocabularies, schema, table)
   :canonical: lenskit.data._relationships.MatrixRelationshipSet

   Bases: :py:obj:`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 :meth:`~RelationshipSet.matrix` method.


   .. py:attribute:: row_type
      :type:  str


   .. py:attribute:: col_type
      :type:  str


   .. py:method:: __getstate__()


   .. py:method:: __setstate__(state)


   .. py:property:: row_vocabulary

      The vocabulary for row entities.


   .. py:property:: col_vocabulary

      The vocabulary for column entities.


   .. py:property:: n_rows


   .. py:property:: n_cols
      :type: int



   .. py:method:: matrix(*, row_entity = None, col_entity = None)

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

      .. versionchanged:: 2025.6

          Removed the fixed defaults for ``row_entity`` and ``col_entity``.

      :param row_entity: The specified row entity of the matrix.  Defaults to the first
                         entity in the relationship's list of involved entities.
      :param col_entity: The specified column entity of the matrix. Defaults to the last
                         entity in the relationship's list of involved entities.



   .. py:method:: 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.



   .. py:method:: coo_structure()

      Get the compressed sparse row structure of this relationship matrix.



   .. py:method:: 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.

      :param attribute: The attribute to return, or ``None`` to return an indicator-only
                        sparse matrix (all observed values are 1).
      :param layout: The matrix layout to return.

      :returns: The sparse matrix.



   .. py:method:: 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.

      :param attribute: The attribute to return, or ``None`` to return an indicator-only
                        sparse matrix (all observed values are 1).
      :param layout: The matrix layout to return.

      :returns: The sparse matrix.



   .. py:method:: 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.

      :param rows: The row numbers.  Duplicates are allowed, and negative columns
                   are sampled independently for each row. Must be a 1D array or
                   tensor.
      :param weighting: The weighting for sampled negatives; ``uniform`` samples them
                        uniformly at random, while ``popularity`` samples them
                        proportional to their popularity (number of occurrences).
      :param n: The number of negatives to sample for each user.  If ``None``,
                a single-dimensional vector is returned.
      :param verify: Whether to verify that the negative items are actually negative.
                     Unverified sampling is much faster but can return false
                     negatives.
      :param max_attempts: When verification is on, the maximum attempts before giving up
                           and returning a possible false negative.
      :param rng: A random number generator to use.



   .. py:method:: 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.



   .. py:method:: 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''.



   .. py:method:: to_ilc()

      Get the rows as an item list collection.

      .. deprecated:: 2025.6

          Deprecated alias for :meth:`item_lists`.



   .. py:method:: item_lists()

      Get the rows as an item list collection.



   .. py:method:: row_stats()


   .. py:method:: col_stats()