Toggle Menu
Prev Up Next

scikit-learn 1.3.2
Other versions

Please cite us if you use the software.

# `sklearn.metrics`.dcg_score

sklearn.metrics.dcg_score(y_true, y_score, *, k=None, log_base=2, sample_weight=None, ignore_ties=False)

  Compute Discounted Cumulative Gain.

  Sum the true scores ranked in the order induced by the predicted scores, after applying a logarithmic discount.

  This ranking metric yields a high value if true labels are ranked high by `y_score`.

  Usually the Normalized Discounted Cumulative Gain (NDCG, computed by ndcg_score) is preferred.

  Parameters:
    y_true array-like of shape (n_samples, n_labels)

      True targets of multilabel classification, or true scores of entities to be ranked.

    y_score array-like of shape (n_samples, n_labels)

      Target scores, can either be probability estimates, confidence values, or non-thresholded measure of decisions (as returned by “decision_function” on some classifiers).

    k int, default=None

      Only consider the highest k scores in the ranking. If None, use all outputs.

    log_base float, default=2

      Base of the logarithm used for the discount. A low value means a sharper discount (top results are more important).

    sample_weight array-like of shape (n_samples,), default=None

      Sample weights. If `None`, all samples are given the same weight.

    ignore_ties bool, default=False

      Assume that there are no ties in y_score (which is likely to be the case if y_score is continuous) for efficiency gains.

  Returns:
    discounted_cumulative_gain float

      The averaged sample DCG scores.

  See also

  `ndcg_score`

    The Discounted Cumulative Gain divided by the Ideal Discounted Cumulative Gain (the DCG obtained for a perfect ranking), in order to have a score between 0 and 1.

  References

  Wikipedia entry for Discounted Cumulative Gain.

  Jarvelin, K., & Kekalainen, J. (2002). Cumulated gain-based evaluation of IR techniques. ACM Transactions on Information Systems (TOIS), 20(4), 422-446.

  Wang, Y., Wang, L., Li, Y., He, D., Chen, W., & Liu, T. Y. (2013, May). A theoretical analysis of NDCG ranking measures. In Proceedings of the 26th Annual Conference on Learning Theory (COLT 2013).

  McSherry, F., & Najork, M. (2008, March). Computing information retrieval performance measures efficiently in the presence of tied scores. In European conference on information retrieval (pp. 414-421). Springer, Berlin, Heidelberg.

  Examples

      >>> import numpy as np
      >>> from sklearn.metrics import dcg_score
      >>> # we have groud-truth relevance of some answers to a query:
      >>> true_relevance = np.asarray([[10, 0, 0, 1, 5]])
      >>> # we predict scores for the answers
      >>> scores = np.asarray([[.1, .2, .3, 4, 70]])
      >>> dcg_score(true_relevance, scores)
      9.49...
      >>> # we can set k to truncate the sum; only top k answers contribute
      >>> dcg_score(true_relevance, scores, k=2)
      5.63...
      >>> # now we have some ties in our prediction
      >>> scores = np.asarray([[1, 0, 0, 0, 1]])
      >>> # by default ties are averaged, so here we get the average true
      >>> # relevance of our top predictions: (10 + 5) / 2 = 7.5
      >>> dcg_score(true_relevance, scores, k=1)
      7.5
      >>> # we can choose to ignore ties for faster results, but only
      >>> # if we know there aren't ties in our scores, otherwise we get
      >>> # wrong results:
      >>> dcg_score(true_relevance,
      ...           scores, k=1, ignore_ties=True)
      5.0