lenskit.als =========== .. py:module:: lenskit.als .. autoapi-nested-parse:: LensKit ALS implementations. Classes ------- .. autoapisummary:: lenskit.als.ALSBase lenskit.als.ALSConfig lenskit.als.BiasedMFConfig lenskit.als.BiasedMFScorer lenskit.als.ImplicitMFConfig lenskit.als.ImplicitMFScorer Package Contents ---------------- .. py:class:: ALSBase(config = None, **kwargs) :canonical: lenskit.als._common.ALSBase Bases: :py:obj:`lenskit.training.UsesTrainer`, :py:obj:`lenskit.pipeline.Component`\ [\ :py:obj:`lenskit.data.ItemList`\ ], :py:obj:`abc.ABC` Base class for ALS models. :Stability: Caller .. py:attribute:: config :type: ALSConfig The component configuration object. Component classes that support configuration **must** redefine this attribute with their specific configuration class type, which can be a Python dataclass or a Pydantic model class. .. py:attribute:: users :type: lenskit.data.Vocabulary | None .. py:attribute:: items :type: lenskit.data.Vocabulary .. py:attribute:: user_embeddings :type: lenskit.data.types.NPMatrix | None .. py:attribute:: item_embeddings :type: lenskit.data.types.NPMatrix .. py:property:: logger :type: structlog.stdlib.BoundLogger .. py:method:: __call__(query, items) Run the pipeline's operation and produce a result. This is the key method for components to implement. .. py:method:: new_user_embedding(user_num, items) :abstractmethod: Generate an embedding for a user given their current ratings. .. py:method:: finalize_scores(user_num, items, user_bias) Perform any final transformation of scores prior to returning them. .. py:class:: ALSConfig :canonical: lenskit.als._common.ALSConfig Bases: :py:obj:`lenskit.config.common.EmbeddingSizeMixin`, :py:obj:`pydantic.BaseModel` Configuration for ALS scorers. .. py:attribute:: embedding_size :type: pydantic.PositiveInt The dimension of user and item embeddings (number of latent features to learn). .. py:attribute:: epochs :type: pydantic.PositiveInt :value: 10 The number of epochs to train. .. py:attribute:: regularization :type: pydantic.PositiveFloat | lenskit.data.types.UIPair[pydantic.PositiveFloat] :value: 0.1 L2 regularization strength. .. py:attribute:: user_embeddings :type: bool | Literal['prefer'] :value: True Whether to retain user embeddings after training. If ``True``, they are retained, but are ignored if the query has historical items; if ``False``, they are not. If set to ``"prefer"``, then the user embeddings from training time are used even if the query has a user history. This makes inference faster when histories only consist of the user's items from the training set. .. py:property:: user_reg :type: float .. py:property:: item_reg :type: float .. py:class:: BiasedMFConfig :canonical: lenskit.als._explicit.BiasedMFConfig Bases: :py:obj:`lenskit.als._common.ALSConfig` Configuration for ALS scorers. .. py:attribute:: damping :type: lenskit.basic.Damping :value: 5.0 Damping for the bias model. .. py:class:: BiasedMFScorer(config = None, **kwargs) :canonical: lenskit.als._explicit.BiasedMFScorer Bases: :py:obj:`lenskit.als._common.ALSBase` Biased matrix factorization trained with alternating least squares :cite:p:`NetflixALS,ExplicitALS`. This is a prediction-oriented algorithm suitable for explicit feedback data, using the alternating least squares approach to compute :math:`P` and :math:`Q` to minimize the regularized squared reconstruction error of the ratings matrix. See the base class :class:`ALSBase` for documentation on the estimated parameters you can extract from a trained model. See :class:`BiasedMFConfig` and :class:`ALSConfig` for the configuration options for this component. :Stability: Caller .. py:attribute:: config :type: BiasedMFConfig The component configuration object. Component classes that support configuration **must** redefine this attribute with their specific configuration class type, which can be a Python dataclass or a Pydantic model class. .. py:attribute:: bias :type: lenskit.basic.BiasModel .. py:method:: create_trainer(data, options) Create a model trainer to train this model. .. py:method:: new_user_embedding(user_num, items) Generate an embedding for a user given their current ratings. .. py:method:: finalize_scores(user_num, items, user_bias) Perform any final transformation of scores prior to returning them. .. py:class:: ImplicitMFConfig :canonical: lenskit.als._implicit.ImplicitMFConfig Bases: :py:obj:`lenskit.als._common.ALSConfig` Configuration for ALS scorers. .. py:attribute:: weight :type: float :value: 40 The confidence weight for positive examples. .. py:attribute:: use_ratings :type: bool :value: False If ``True``, use rating values instead of just presence or absence. .. py:class:: ImplicitMFScorer(config = None, **kwargs) :canonical: lenskit.als._implicit.ImplicitMFScorer Bases: :py:obj:`lenskit.als._common.ALSBase` Implicit matrix factorization trained with alternating least squares :cite:p:`hu:implicit-mf`. This algorithm outputs 'predictions', but they are not on a meaningful scale. If its input data contains ``rating`` values, these will be used as the 'confidence' values; otherwise, confidence will be 1 for every rated item. With weight :math:`w`, this function decomposes the matrix :math:`\mathbb{1}^* + Rw`, where :math:`\mathbb{1}^*` is an :math:`m \times n` matrix of all 1s. See the base class :class:`ALSBase` for documentation on the estimated parameters you can extract from a trained model. See :class:`ImplicitMFConfig` and :class:`ALSConfig` for the configuration options for this component. .. versionchanged:: 2025.1 ``ImplicitMFScorer`` no longer supports multiple training methods. It always uses Cholesky decomposition now. .. versionchanged:: 0.14 By default, ``ImplicitMF`` ignores a ``rating`` column if one is present in the training data. This can be changed through the ``use_ratings`` option. .. versionchanged:: 0.13 In versions prior to 0.13, ``ImplicitMF`` used the rating column if it was present. In 0.13, we added an option to control whether or not the rating column is used; it initially defaulted to ``True``, but with a warning. In 0.14 it defaults to ``False``. :Stability: Caller .. py:attribute:: config :type: ImplicitMFConfig The component configuration object. Component classes that support configuration **must** redefine this attribute with their specific configuration class type, which can be a Python dataclass or a Pydantic model class. .. py:method:: create_trainer(data, options) Create a model trainer to train this model. .. py:method:: new_user_embedding(user_num, user_items) Generate an embedding for a user given their current ratings.