Merge pull request #668 from mdekstrand/feature/flexmf

Add flexible Torch matrix factorizer

Author: mdekstrand

docs/lenskit.bib

@@ -600,7 +600,7 @@ @article{rbp
   abstract = {A range of methods for measuring the effectiveness of information retrieval systems has been proposed. These are typically intended to provide a quantitative single-value summary of a document ranking relative to a query. However, many of these measures have failings {\dots}}
 }
 
-@inproceedings{rendleBPRBayesianPersonalized2009,
+@inproceedings{BPR,
   title = {{{BPR}}: {{Bayesian Personalized Ranking}} from {{Implicit Feedback}}},
   booktitle = {{{UAI}} '09},
   author = {Rendle, Steffen and Freudenthaler, Christoph and Gantner, Zeno and {Schmidt-Thieme}, Lars},

docs/releases/2025.rst

@@ -15,6 +15,8 @@ information on how to upgrade your code.
 ----------------------
 
 -   Replace broken “softmax” sampler with a proper stochastic sampler (:pr:`667`).
+-   :meth:`~lenskit.data.MatrixRelationshipSet.sample_negatives` now accepts
+    ``"popular"`` as an alias for ``"popularity"``.
 
 .. _2025.2.0:
 

src/lenskit/cli/doctor.py

@@ -1,3 +1,9 @@
+# This file is part of LensKit.
+# Copyright (C) 2018-2023 Boise State University
+# Copyright (C) 2023-2025 Drexel University
+# Licensed under the MIT license, see LICENSE.md for details.
+# SPDX-License-Identifier: MIT
+
 import os
 import platform
 import re

src/lenskit/data/builder.py

@@ -3,6 +3,7 @@
 # Copyright (C) 2023-2025 Drexel University
 # Licensed under the MIT license, see LICENSE.md for details.
 # SPDX-License-Identifier: MIT
+
 """
 Data set builder.
 """

src/lenskit/data/collection/__init__.py

@@ -1,3 +1,9 @@
+# This file is part of LensKit.
+# Copyright (C) 2018-2023 Boise State University
+# Copyright (C) 2023-2025 Drexel University
+# Licensed under the MIT license, see LICENSE.md for details.
+# SPDX-License-Identifier: MIT
+
 """
 Item list collections.
 """

src/lenskit/data/collection/_base.py

@@ -1,3 +1,9 @@
+# This file is part of LensKit.
+# Copyright (C) 2018-2023 Boise State University
+# Copyright (C) 2023-2025 Drexel University
+# Licensed under the MIT license, see LICENSE.md for details.
+# SPDX-License-Identifier: MIT
+
 from __future__ import annotations
 
 import warnings

src/lenskit/data/collection/_list.py

@@ -1,3 +1,9 @@
+# This file is part of LensKit.
+# Copyright (C) 2018-2023 Boise State University
+# Copyright (C) 2023-2025 Drexel University
+# Licensed under the MIT license, see LICENSE.md for details.
+# SPDX-License-Identifier: MIT
+
 import warnings
 from collections.abc import Iterator, Mapping, Sequence
 from typing import Any, Generic, overload

src/lenskit/data/mtarray.py

@@ -3,6 +3,7 @@
 # Copyright (C) 2023-2025 Drexel University
 # Licensed under the MIT license, see LICENSE.md for details.
 # SPDX-License-Identifier: MIT
+
 """
 Multi-format array layout.
 """

src/lenskit/data/relationships.py

@@ -390,9 +390,9 @@ def torch(self, attribute: str | None = None, *, layout: LAYOUT = "csr") -> torc
 
     def sample_negatives(
         self,
-        rows: np.ndarray[int, np.dtype[np.int32]],
+        rows: np.ndarray[tuple[int], np.dtype[np.int32]],
         *,
-        weighting: Literal["uniform", "popularity"] = "uniform",
+        weighting: Literal["uniform", "popular", "popularity"] = "uniform",
         n: int | None = None,
         verify: bool = True,
         max_attempts: int = 10,
@@ -436,10 +436,12 @@ def sample_negatives(
         match weighting:
             case "uniform":
                 columns = rng.choice(self.n_cols, size=shape, replace=True)
-            case "popularity":
+            case "popular" | "popularity":
                 ccol = self._table.column(num_col_name(self.col_type)).to_numpy()
                 trows = rng.choice(self._table.num_rows, size=shape, replace=True)
                 columns = ccol[trows]
+            case _:
+                raise ValueError(f"unknown weighting strategy {weighting}")
         columns = np.require(columns, "i4")
 
         if verify:

src/lenskit/flexmf/__init__.py

@@ -0,0 +1,28 @@
+# This file is part of LensKit.
+# Copyright (C) 2018-2023 Boise State University
+# Copyright (C) 2023-2025 Drexel University
+# Licensed under the MIT license, see LICENSE.md for details.
+# SPDX-License-Identifier: MIT
+
+"""
+Flexible PyTorch matrix factorization models for LensKit.
+
+The components in this package implement several matrix factorization models for
+LensKit, and also serve as an example for practical PyTorch recommender
+training.
+
+.. stability:: internal
+"""
+
+from ._base import FlexMFConfigBase, FlexMFScorerBase
+from ._explicit import FlexMFExplicitConfig, FlexMFExplicitScorer
+from ._implicit import FlexMFImplicitConfig, FlexMFImplicitScorer
+
+__all__ = [
+    "FlexMFConfigBase",
+    "FlexMFScorerBase",
+    "FlexMFExplicitConfig",
+    "FlexMFExplicitScorer",
+    "FlexMFImplicitConfig",
+    "FlexMFImplicitScorer",
+]