Tweediedeviancescore

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

# tweediedeviancescore

> Metric `TweedieDevianceScore` from `torchmetrics` (torchmetrics.TweedieDevianceScore)

## When to invoke this skill

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

## Reference signature

```python
from torchmetrics import TweedieDevianceScore

# TweedieDevianceScore(power: float = 0.0, **kwargs: Any) -> None
```

## Library docstring

```
Compute the `Tweedie Deviance Score`_.

.. math::
    deviance\_score(\hat{y},y) =
    \begin{cases}
    (\hat{y} - y)^2, & \text{for }p=0\\
    2 * (y * log(\frac{y}{\hat{y}}) + \hat{y} - y),  & \text{for }p=1\\
    2 * (log(\frac{\hat{y}}{y}) + \frac{y}{\hat{y}} - 1),  & \text{for }p=2\\
    2 * (\frac{(max(y,0))^{2 - p}}{(1 - p)(2 - p)} - \frac{y(\hat{y})^{1 - p}}{1 - p} + \frac{(
        \hat{y})^{2 - p}}{2 - p}), & \text{otherwise}
    \end{cases}

where :math:`y` is a tensor of targets values, :math:`\hat{y}` is a tensor of predictions, and
:math:`p` is the `power`.

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

- ``preds`` (:class:`~torch.Tensor`): Predicted float tensor with shape ``(N,...)``
- ``target`` (:class:`~torch.Tensor`): Ground truth float tensor with shape ``(N,...)``

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

- ``deviance_score`` (:class:`~torch.Tensor`): A tensor with the deviance score

Args:
    power:

        - power < 0 : Extreme stable distribution. (Requires: preds > 0.)
        - power = 0 : Normal distribution. (Requires: targets and preds can be any real numbers.)
        - power = 1 : Poisson distribution. (Requires: targets >= 0 and y_pred > 0.)
        - 1 < p < 2 : Compound Poisson distribution. (Requires: targets >= 0 and preds > 0.)
        - power = 2 : Gamma distribution. (Requires: targets > 0 and preds > 0.)
        - power = 3 : Inverse Gaussian distribution. (Requires: targets > 0 and preds > 0.)
        - otherwise : Positive stable distribution. (Requires: targets > 0 and preds > 0.)

    kwargs: Additional keyword arguments, see :ref:`Metric kwargs` for more info.

Example:
    >>> from torchmetrics.regression import TweedieDevianceScore
    >>> targets = torch.tensor([1.0, 2.0, 3.0, 4.0])
    >>> preds = torch.tensor([4.0, 3.0, 2.0, 1.0])
    >>> deviance_score = TweedieDevianceScore(power=2)
    >>> deviance_score(preds, targets)
    tensor(1.2083)
```

## Quick recipe

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