Explainedvariance

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

# explainedvariance

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

## When to invoke this skill

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

## Reference signature

```python
from torchmetrics import ExplainedVariance

# ExplainedVariance(multioutput: Literal['raw_values', 'uniform_average', 'variance_weighted'] = 'uniform_average', **kwargs: Any) -> None
```

## Library docstring

```
Compute `explained variance`_.

.. math:: \text{ExplainedVariance} = 1 - \frac{\text{Var}(y - \hat{y})}{\text{Var}(y)}

Where :math:`y` is a tensor of target values, and :math:`\hat{y}` is a tensor of predictions.

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

- ``preds`` (:class:`~torch.Tensor`): Predictions from model in float tensor
  with shape ``(N,)`` or ``(N, ...)`` (multioutput)
- ``target`` (:class:`~torch.Tensor`): Ground truth values in long tensor
  with shape ``(N,)`` or ``(N, ...)`` (multioutput)

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

- ``explained_variance`` (:class:`~torch.Tensor`): A tensor with the explained variance(s)

In the case of multioutput, as default the variances will be uniformly averaged over the additional dimensions.
Please see argument ``multioutput`` for changing this behavior.

Args:
    multioutput:
        Defines aggregation in the case of multiple output scores. Can be one
        of the following strings (default is ``'uniform_average'``.):

        * ``'raw_values'`` returns full set of scores
        * ``'uniform_average'`` scores are uniformly averaged
        * ``'variance_weighted'`` scores are weighted by their individual variances

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

Raises:
    ValueError:
        If ``multioutput`` is not one of ``"raw_values"``, ``"uniform_average"`` or ``"variance_weighted"``.

Example:
    >>> from torch import tensor
    >>> from torchmetrics.regression import ExplainedVariance
    >>> target = tensor([3, -0.5, 2, 7])
    >>> preds = tensor([2.5, 0.0, 2, 8])
    >>> explained_variance = ExplainedVariance()
    >>> explained_variance(preds, target)
    tensor(0.9572)

    >>> target = tensor([[0.5, 1], [-1, 1], [7, -6]])
    >>> preds = tensor([[0, 2], [-1, 2], [8, -5]])
    >>> explained_variance = ExplainedVariance(multioutput='raw_values')
    >>> explained_variance(preds, target)
    tensor([0.9677, 1.0000])
```

## Quick recipe

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