Dcg Score

---
name: dcg-score
description: Compute the dcg_score metric — provided by scikit-learn. Use when the user has predictions and ground-truth and needs to compute dcg_score, or asks how to score with dcg_score.
metadata:
  skill_kind: metric
  source_lib: scikit-learn
  import_path: sklearn.metrics.dcg_score
  source: library_introspection
---

# dcg-score

> Metric `dcg_score` from `scikit-learn` (sklearn.metrics.dcg_score)

## When to invoke this skill

The user has predictions + ground truth and asks to evaluate with dcg_score, or
mentions `sklearn.metrics.dcg_score` directly, or wants the standard scikit-learn implementation.

## Reference signature

```python
from sklearn.metrics import dcg_score

# dcg_score(y_true, y_score, *, k=None, log_base=2, sample_weight=None, ignore_ties=False)
```

## Library docstring

```
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
<https://en.wikipedia.org/wiki/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
```

## Quick recipe

```python
import sklearn.metrics as _m
score = _m.dcg_score(y_true, y_pred)
```

## Don'ts

- Don't reimplement when the library version handles edge cases (NaN, ties, empty inputs) better than a hand-rolled formula.
- Always check the library version's argument order — sklearn is `(y_true, y_pred)` while torchmetrics is `(preds, target)`.