From 768e6209d0b5257516d3f30f9eb1d5918b80e1ee Mon Sep 17 00:00:00 2001 From: Michael Ekstrand Date: Sun, 29 Dec 2024 21:03:05 -0600 Subject: [PATCH] add component documentation --- docs/guide/index.rst | 2 ++ docs/guide/other-components.rst | 26 ++++++++++++++++++++++++++ docs/guide/rankers.rst | 26 ++++++++++++++++++++++++++ docs/guide/scorers.rst | 18 +++++++++++++++++- 4 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 docs/guide/other-components.rst create mode 100644 docs/guide/rankers.rst diff --git a/docs/guide/index.rst b/docs/guide/index.rst index 49c22f928..16b23c741 100644 --- a/docs/guide/index.rst +++ b/docs/guide/index.rst @@ -28,6 +28,8 @@ guide to how to use LensKit for research, education, and other purposes. conventions scorers + rankers + other-components .. toctree:: :caption: Experiments diff --git a/docs/guide/other-components.rst b/docs/guide/other-components.rst new file mode 100644 index 000000000..f54b11e18 --- /dev/null +++ b/docs/guide/other-components.rst @@ -0,0 +1,26 @@ +Other Components +================ + +LensKit provides a number of other components; they are detailed in the API reference, +but a few that are useful in assembling useful pipelines include: + +Candidate Selectors +~~~~~~~~~~~~~~~~~~~ + +.. autosummary:: + :nosignatures: + + lenskit.basic.UnratedTrainingItemsCandidateSelector + lenskit.basic.AllTrainingItemsCandidateSelector + +History Lookup +~~~~~~~~~~~~~~ + +LensKit pipelines use a history lookup component to obtain user profile data +when the recommender is called with only a user ID, so they do not need to +repeat that logic in each component. + +.. autosummary:: + :nosignatures: + + lenskit.basic.UserTrainingHistoryLookup diff --git a/docs/guide/rankers.rst b/docs/guide/rankers.rst new file mode 100644 index 000000000..80761500a --- /dev/null +++ b/docs/guide/rankers.rst @@ -0,0 +1,26 @@ +.. _rankers: + +Ranking Algorithms +================== + +LensKit provides several ranking components that rank items. + +The usual design for a ranker is to take as input a list of items named `items`, +usually with scores (typically the output of a :ref:`scoring model `), +and possibly the query, and return an ordered item list. Rankers can also take +ranked inputs for re-ranking. By convention, they are named ``XYZRanker``. + +Top-N Ranking +~~~~~~~~~~~~~ + +Classic top-*N* ranking is provided by :class:`lenskit.basic.TopNRanker`. The +standard pipelines configured by :class:`~lenskit.pipeline.RecPipelineBuilder` +use this ranker by default. + +Stochastic Ranking +~~~~~~~~~~~~~~~~~~ + +- :class:`lenskit.basic.SoftmaxRanker` computes a randomized Plackett-Luce + ranking, where each item is selected with probability proportional to its + score. +- :class:`lenskit.basic.RandomSelector` selects items uniformly at random. diff --git a/docs/guide/scorers.rst b/docs/guide/scorers.rst index 9cdc0792a..e270ffa19 100644 --- a/docs/guide/scorers.rst +++ b/docs/guide/scorers.rst @@ -1,3 +1,5 @@ +.. _scorers: + Scoring Models ============== @@ -5,7 +7,9 @@ Most recommendation pipelines are built around a *scoring model* that scores items for a recommendation query (e.g., user). Standard top-*N* recommendation uses these scores to rank items, and they can be used as inputs into other techniques such as samplers and rerankers. Scorers are almost always -:class:`~lenskit.pipeline.Trainable`, and by convention are named `XYZScorer`. +:class:`~lenskit.pipeline.Trainable`, and by convention are named ``XYZScorer``. +They typically take two inputs, the query (`query`) and the list of items to +score (`items`). Scoring models are not limited to traditional pointwise scoring models such as matrix factorization. Many learning-to-rank models are also implemented as @@ -32,3 +36,15 @@ Classical Collaborative Filters lenskit.als.ImplicitMFScorer lenskit.sklearn.svd.BiasedSVDScorer lenskit.funksvd.FunkSVDScorer + + +Utility Scorers +~~~~~~~~~~~~~~~ + +These scorers are used to compose more sophisticated pipelines, usually +involving multiple pipelines. + +.. autosummary:: + :nosignatures: + + lenskit.basic.FallbackScorer