lenskit.metrics.ranking.NDCG
============================

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

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


   Compute the normalized 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 is then normalized as follows:

   .. math::
       \begin{align*}
       \mathrm{nDCG}(L, u) & = \frac{\mathrm{DCG}(L,u)}{\mathrm{DCG}(L_{\mathrm{ideal}}, u)}
       \end{align*}

   .. note::
       Negative gains are clipped to zero before computing NDCG.
       This keeps the metric bounded between 0 and 1 and prevents cases where
       negative gains can lead to misleading positive scores due to
       cancellation effects.
   :param n: The maximum recommendation list length to consider (longer lists are
             truncated).
   :param weight: The rank weighting to use.
   :param discount: The discount function to use.  The default, base-2 logarithm, is the
                    original function used by :cite:t:`ndcg`.  It is deprecated in favor
                    of the ``weight`` option.
   :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