lenskit.metrics.ranking.DCG
===========================

.. py:class:: lenskit.metrics.ranking.DCG(n = None, *, k = None, weight = LogRankWeight(), discount = None, gain = None)
   :canonical: lenskit.metrics.ranking._dcg.DCG

   Bases: :py:obj:`lenskit.metrics.ranking._base.ListMetric`, :py:obj:`lenskit.metrics.ranking._base.RankingMetricBase`


   Compute the _unnormalized_ discounted cumulative gain :cite:p:`ndcg`.

   Discounted cumultative gain is computed as:

   .. math::
       \begin{align*}
       \mathrm{DCG}(L,u) & = \sum_{i=1}^{|L|} \frac{r_{ui}}{d(i)}
       \end{align*}

   Unrated items are assumed to have a utility of 0; if no rating values are
   provided in the truth frame, item ratings are assumed to be 1.

   This metric does *not* normalize by ideal DCG. For that, use :class:`NDCG`.
   See :cite:t:`jeunenNormalisedDiscountedCumulative2024` for an argument for
   using the unnormalized version.

   :param n: The maximum recommendation list length to consider (longer lists are
             truncated).
   :param discount: The discount function to use.  The default, base-2 logarithm, is the
                    original function used by :cite:t:`ndcg`.
   :param gain: The field on the test data to use for gain values.  If ``None`` (the
                default), all items present in the test data have a gain of 1.  If set
                to a string, it is the name of a field (e.g. ``'rating'``).  In all
                cases, items not present in the truth data have a gain of 0.

   :Stability: Caller


   .. py:attribute:: weight
      :type:  lenskit.metrics.ranking._weighting.RankWeight


   .. py:attribute:: discount
      :type:  Discount | None


   .. py:attribute:: gain
      :type:  str | None


   .. py:property:: label

      The metric's default label in output.
      The base implementation returns the class name by default.


   .. py:method:: measure_list(recs, test)

      Compute measurements for a single list.

      :returns:

                - A float for simple metrics
                - Intermediate data for decomposed metrics
                - A dict mapping metric names to values for multi-metric classes