Ndcg Score

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

# ndcg-score

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

## When to invoke this skill

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

## Reference signature

```python
from sklearn.metrics import ndcg_score

# ndcg_score(y_true, y_score, *, k=None, sample_weight=None, ignore_ties=False)
```

## Library docstring

```
Compute Normalized Discounted Cumulative Gain.

Sum the true scores ranked in the order induced by the predicted scores,
after applying a logarithmic discount. Then divide by the best possible
score (Ideal DCG, obtained for a perfect ranking) to obtain a score between
0 and 1.

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

Parameters
----------
y_true : array-like of shape (n_samples, n_labels)
    True targets of multilabel classification, or true scores of entities
    to be ranked. Negative values in `y_true` may result in an output
    that is not between 0 and 1.

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.

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
-------
normalized_discounted_cumulative_gain : float in [0., 1.]
    The averaged NDCG scores for all samples.

See Also
--------
dcg_score : Discounted Cumulative Gain (not normalized).

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 scores. In
European conference on information retrieval (pp. 414-421). Springer,
Berlin, Heidelberg.

Examples
--------
>>> imp
```

## Quick recipe

```python
import sklearn.metrics as _m
score = _m.ndcg_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)`.