Binarylogauc

---
name: binarylogauc
description: Compute the BinaryLogAUC metric — provided by torchmetrics. Use when the user has predictions and ground-truth and needs to compute BinaryLogAUC, or asks how to score with BinaryLogAUC.
metadata:
  skill_kind: metric
  source_lib: torchmetrics
  import_path: torchmetrics.classification.BinaryLogAUC
  source: library_introspection
---

# binarylogauc

> Metric `BinaryLogAUC` from `torchmetrics` (torchmetrics.classification.BinaryLogAUC)

## When to invoke this skill

The user has predictions + ground truth and asks to evaluate with BinaryLogAUC, or
mentions `torchmetrics.classification.BinaryLogAUC` directly, or wants the standard torchmetrics implementation.

## Reference signature

```python
from torchmetrics.classification import BinaryLogAUC

# BinaryLogAUC(fpr_range: Tuple[float, float] = (0.001, 0.1), thresholds: Union[int, List[float], torch.Tensor, NoneType] = None, ignore_index: Optional[int] = None, validate_args: bool = False, **kwargs: Any) -> None
```

## Library docstring

```
Compute the `Log AUC`_ score for binary classification tasks.

The score is computed by first computing the ROC curve, which then is interpolated to the specified range of false
positive rates (FPR) and then the log is taken of the FPR before the area under the curve (AUC) is computed. The
score is commonly used in applications where the positive and negative are imbalanced and a low false positive rate
is of high importance.

As input to ``forward`` and ``update`` the metric accepts the following input:

- ``preds`` (:class:`~torch.Tensor`): A float tensor of shape ``(N, ...)`` containing probabilities or logits for
  each observation. If preds has values outside [0,1] range we consider the input to be logits and will auto apply
  sigmoid per element.
- ``target`` (:class:`~torch.Tensor`): An int tensor of shape ``(N, ...)`` containing ground truth labels, and
  therefore only contain {0,1} values (except if `ignore_index` is specified). The value 1 always encodes the
  positive class.

As output to ``forward`` and ``compute`` the metric returns the following output:

- ``logauc`` (:class:`~torch.Tensor`): A single scalar with the logauc score.

Additional dimension ``...`` will be flattened into the batch dimension.

The implementation both supports calculating the metric in a non-binned but accurate version and a binned version
that is less accurate but more memory efficient. Setting the `thresholds` argument to `None` will activate the
non-binned  version that uses memory of size :math:`\mathcal{O}(n_{samples})` whereas setting the `thresholds`
argument to either an integer, list or a 1d tensor will use a binned version that uses memory of
size :math:`\mathcal{O}(n_{thresholds})` (constant memory).

Args:
    fpr_range: 2-element tuple with the lower and upper bound of the false positive rate range to compute the log
        AUC score.
    thresholds:
        Can be one of:

        - If set to `None`, will use a non-binned approach where thresholds are dynamically calculated from
          all the data. Most accurate but also most memory consuming approach.
        - If set to an `int` (larger than 1), will use that number of thresholds linearly spaced from
```

## Quick recipe

```python
import torchmetrics.classification as _m
score = _m.BinaryLogAUC(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)`.