---
title: torchmetrics.utilities
description: >-
  In the following is listed public utility functions that may be beneficial to
  use in your own code. These functions are
canonical: 'https://lightning.ai/docs/torchmetrics/stable/api-reference/utilities'
---
# torchmetrics.utilities {#torchmetrics-utilities}

In the following is listed public utility functions that may be beneficial to use in your own code. These functions are
not part of the public API and may change at any time.

## torchmetrics.utilities.data {#torchmetrics-utilities-data}

The `data` utilities are used to help with data manipulation, such as converting labels in classification from one
format to another.

### select_topk {#select-topk}

### `torchmetrics.utilities.data.select_topk(prob_tensor, topk=1, dim=1)` {#torchmetrics.utilities.data.select_topk}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L124-L148)

Convert a probability tensor to binary by selecting top-k the highest entries.

Parameters:

*   **prob\_tensor** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – dense tensor of shape `[..., C, ...]`, where `C` is in the position defined by the `dim` argument
    
*   **topk** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – number of the highest entries to turn into 1s
    
*   **dim** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – dimension on which to compare entries
    

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

Returns:

A binary tensor of the same shape as the input tensor of type `torch.int32`

Example

```python
>>> x = torch.tensor([[1.1, 2.0, 3.0], [2.0, 1.0, 0.5]])
>>> select_topk(x, topk=2)
tensor([[0, 1, 1],
        [1, 1, 0]], dtype=torch.int32)
```

### to_categorical {#to-categorical}

### `torchmetrics.utilities.data.to_categorical(x, argmax_dim=1)` {#torchmetrics.utilities.data.to_categorical}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L151-L167)

Convert a tensor of probabilities to a dense label tensor.

Parameters:

*   **x** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – probabilities to get the categorical label \[N, d1, d2, …\]
    
*   **argmax\_dim** ([`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")) – dimension to apply
    

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

Returns:

A tensor with categorical labels \[N, d2, …\]

Example

```python
>>> x = torch.tensor([[0.2, 0.5], [0.9, 0.1]])
>>> to_categorical(x)
tensor([1, 0])
```

### to_onehot {#to-onehot}

### `torchmetrics.utilities.data.to_onehot(label_tensor, num_classes=None)` {#torchmetrics.utilities.data.to_onehot}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L81-L113)

Convert a dense label tensor to one-hot format.

Parameters:

*   **label\_tensor** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – dense label tensor, with shape \[N, d1, d2, …\]
    
*   **num\_classes** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`int`](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)")\]) – number of classes C
    

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

Returns:

A sparse label tensor with shape \[N, C, d1, d2, …\]

Example

```python
>>> x = torch.tensor([1, 2, 3])
>>> to_onehot(x)
tensor([[0, 1, 0, 0],
        [0, 0, 1, 0],
        [0, 0, 0, 1]])
```

### dim_zero_cat {#dim-zero-cat}

### `torchmetrics.utilities.data.dim_zero_cat(x)` {#torchmetrics.utilities.data.dim_zero_cat}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L29-L36)

Concatenation along the zero dimension.

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

### dim_zero_max {#dim-zero-max}

### `torchmetrics.utilities.data.dim_zero_max(x)` {#torchmetrics.utilities.data.dim_zero_max}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L49-L51)

Max along the zero dimension.

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

### dim_zero_mean {#dim-zero-mean}

### `torchmetrics.utilities.data.dim_zero_mean(x)` {#torchmetrics.utilities.data.dim_zero_mean}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L44-L46)

Average along the zero dimension.

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

### dim_zero_min {#dim-zero-min}

### `torchmetrics.utilities.data.dim_zero_min(x)` {#torchmetrics.utilities.data.dim_zero_min}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L54-L56)

Min along the zero dimension.

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

### dim_zero_sum {#dim-zero-sum}

### `torchmetrics.utilities.data.dim_zero_sum(x)` {#torchmetrics.utilities.data.dim_zero_sum}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/data.py#L39-L41)

Summation along the zero dimension.

Return type:

[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")

## torchmetrics.utilities.distributed {#torchmetrics-utilities-distributed}

The `distributed` utilities are used to help with synchronization of metrics across multiple processes.

### gather_all_tensors {#gather-all-tensors}

### `torchmetrics.utilities.distributed.gather_all_tensors(result, group=None)` {#torchmetrics-utilities-distributed-gather-all-tensors-result-group-none}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/distributed.py#L100-L153)

Gather all tensors from several ddp processes onto a list that is broadcast to all processes.

Works on tensors that have the same number of dimensions, but where each dimension may differ. In this case tensors are padded, gathered and then trimmed to secure equal workload for all processes.

Parameters:

*   **result** ([`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")) – the value to sync
    
*   **group** ([`Optional`](https://docs.python.org/3/library/typing.html#typing.Optional "(in Python v3.15)")\[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any "(in Python v3.15)")\]) – the process group to gather results from. Defaults to all processes (world)
    

Return type:

[`List`](https://docs.python.org/3/library/typing.html#typing.List "(in Python v3.15)")\[[`Tensor`](https://docs.pytorch.org/docs/stable/tensors.html#torch.Tensor "(in PyTorch v2.15)")\]

Returns:

list with size equal to the process group where element i corresponds to result tensor from process i

## torchmetrics.utilities.exceptions {#torchmetrics-utilities-exceptions}

### TorchMetricsUserError {#torchmetricsusererror}

### `class torchmetrics.utilities.exceptions.TorchMetricsUserError` {#torchmetrics.utilities.exceptions.TorchMetricsUserError}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/exceptions.py#L16-L17)

Error used to inform users of a wrong combination of Metric API calls.

### TorchMetricsUserWarning {#torchmetricsuserwarning}

### `class torchmetrics.utilities.exceptions.TorchMetricsUserWarning` {#torchmetrics.utilities.exceptions.TorchMetricsUserWarning}

[\[source\]](https://github.com/Lightning-AI/torchmetrics/blob/v1.9.0/src/torchmetrics/utilities/exceptions.py#L20-L21)

Error used to inform users of specific warnings due to the torchmetrics API.

---

**Navigation**

- Parent: [API Reference](/docs/torchmetrics/1.9.0/api-reference.md)