### Install Torchmetrics using uv

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the library using the uv package installer.

```bash
uv add torchmetrics
```

--------------------------------

### Install Torchmetrics with Extra Dependencies

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the library with additional dependencies for specialized metrics like audio, image, or text. Use '[all]' to install all extras.

```bash
pip install torchmetrics[audio]
```

```bash
pip install torchmetrics[image]
```

```bash
pip install torchmetrics[text]
```

```bash
pip install torchmetrics[all]  # install all of the above
```

--------------------------------

### Install Torchmetrics using Pip

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the library using pip for standard installation.

```bash
pip install torchmetrics
```

--------------------------------

### Install PyTorch from source and TorchMetrics

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/quickstart.rst

Optional installation steps if a PyTorch wheel is missing for your OS or Python version. This involves compiling PyTorch from source, potentially with GPU support disabled, and then installing TorchMetrics.

```bash
export USE_CUDA=0
pip install git+https://github.com/pytorch/pytorch.git
pip install git+https://github.com/pytorch/pytorch.git@<release-tag>
pip install torchmetrics
```

--------------------------------

### Install Torchmetrics from Source (Archive)

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the latest stable release from a zip archive of the GitHub repository using pip.

```bash
pip install https://github.com/Lightning-AI/torchmetrics/archive/refs/heads/release/stable.zip
```

--------------------------------

### Install Documentation Build Requirements

Source: https://github.com/lightning-ai/torchmetrics/blob/master/requirements/README.md

Install requirements for building project documentation. Alternatively, the `make docs` command can be used.

```bash
pip install -r requirements/_docs.txt
# OR just run `make docs`
```

--------------------------------

### Install Development Requirements

Source: https://github.com/lightning-ai/torchmetrics/blob/master/tests/README.md

Install all necessary packages for local development and testing. This command should be run from the project's root directory.

```bash
pip install . -r requirements/_devel.txt
```

--------------------------------

### DDP Example: Accuracy Metric with DistributedDataParallel

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Illustrates using the Accuracy metric within a Distributed Data Parallel (DDP) setup. This example shows how to initialize DDP, attach the metric to a model, and compute metrics across multiple processes. Ensure correct environment variables are set for distributed training.

```python
import os
import torch
import torch.distributed as dist
import torch.multiprocessing as mp
from torch import nn
from torch.nn.parallel import DistributedDataParallel as DDP
import torchmetrics


def metric_ddp(rank, world_size):
    os.environ["MASTER_ADDR"] = "localhost"
    os.environ["MASTER_PORT"] = "12355"

    # create default process group
    dist.init_process_group("gloo", rank=rank, world_size=world_size)

    # initialize model
    metric = torchmetrics.classification.Accuracy(task="multiclass", num_classes=5)

    # define a model and append your metric to it
    # this allows metric states to be placed on correct accelerators when
    # .to(device) is called on the model
    model = nn.Linear(10, 10)
    model.metric = metric
    model = model.to(rank)

    # initialize DDP
    model = DDP(model, device_ids=[rank])

    n_epochs = 5
    # this shows iteration over multiple training epochs
    for n in range(n_epochs):
        # this will be replaced by a DataLoader with a DistributedSampler
        n_batches = 10
        for i in range(n_batches):
            # simulate a classification problem
            preds = torch.randn(10, 5).softmax(dim=-1)
            target = torch.randint(5, (10,))

            # metric on current batch
            acc = metric(preds, target)
            if rank == 0:  # print only for rank 0
                print(f"Accuracy on batch {i}: {acc}")

        # metric on all batches and all accelerators using custom accumulation
        # accuracy is same across both accelerators
        acc = metric.compute()
        print(f"Accuracy on all data: {acc}, accelerator rank: {rank}")

        # Resetting internal state such that metric ready for new data
        metric.reset()

    # cleanup
    dist.destroy_process_group()


if __name__ == "__main__":
    world_size = 2  # number of gpus to parallelize over
    mp.spawn(metric_ddp, args=(world_size,), nprocs=world_size, join=True)
```

--------------------------------

### Install Torchmetrics from Source (Git)

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the latest stable release directly from the GitHub repository using pip.

```bash
# with git
pip install git+https://github.com/Lightning-AI/torchmetrics.git@release/stable
```

--------------------------------

### Install Torchmetrics using Conda

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the library using conda from the conda-forge channel.

```bash
conda install -c conda-forge torchmetrics
```

--------------------------------

### Install Latest Developer Version

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Install the latest development version directly from the master branch of the GitHub repository.

```bash
pip install https://github.com/Lightning-AI/torchmetrics/archive/master.zip
```

--------------------------------

### Plotting Metrics with TorchMetrics

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

TorchMetrics provides built-in plotting support for modular metrics via the .plot() method. Install with `pip install torchmetrics[visual]` for plotting capabilities. This example demonstrates plotting single values and multiple aggregated values.

```python
import torch
from torchmetrics.classification import MulticlassAccuracy, MulticlassConfusionMatrix

num_classes = 3

# this will generate two distributions that comes more similar as iterations increase
w = torch.randn(num_classes)
target = lambda it: torch.multinomial((it * w).softmax(dim=-1), 100, replacement=True)
preds = lambda it: torch.multinomial((it * w).softmax(dim=-1), 100, replacement=True)

acc = MulticlassAccuracy(num_classes=num_classes, average="micro")
acc_per_class = MulticlassAccuracy(num_classes=num_classes, average=None)
confmat = MulticlassConfusionMatrix(num_classes=num_classes)

# plot single value
for i in range(5):
    acc_per_class.update(preds(i), target(i))
    confmat.update(preds(i), target(i))
fig1, ax1 = acc_per_class.plot()
fig2, ax2 = confmat.plot()

# plot multiple values
values = []
for i in range(10):
    values.append(acc(preds(i), target(i)))
fig3, ax3 = acc.plot(values)
```

--------------------------------

### Install Development and Integration Test Requirements

Source: https://github.com/lightning-ai/torchmetrics/blob/master/requirements/README.md

Use these commands to install extra requirements for running unittests or integration tests.

```bash
pip install -r requirements/_devel.txt  # unittests
pip install -r requiremnets/_integrate.txt  # integration tests
```

--------------------------------

### Install TorchMetrics using pip or conda

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/quickstart.rst

Install TorchMetrics using either pip or conda. The conda installation uses the conda-forge channel.

```bash
pip install torchmetrics
```

```bash
conda install -c conda-forge torchmetrics
```

--------------------------------

### Run All Tests with Make

Source: https://github.com/lightning-ai/torchmetrics/blob/master/tests/README.md

A convenient command for Unix-based systems with 'make' installed to set up requirements and run the full test suite.

```bash
make test
```

--------------------------------

### Install NVIDIA Container Toolkit for GPU Support

Source: https://github.com/lightning-ai/torchmetrics/blob/master/dockers/README.md

Set up your system to run Docker containers with GPU access by installing the NVIDIA Container Toolkit. This involves adding NVIDIA's package repositories, updating your package list, and installing the toolkit, followed by restarting the Docker service.

```bash
# Add the package repositories
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```

--------------------------------

### Build Documentation Command

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/README.md

Command to build the documentation locally. Ensure LaTeX is installed if math equations are present. After running, inspect the HTML files in `docs/build/html/`.

```bash
make docs
```

--------------------------------

### MetricCollection Example

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Shows how to use MetricCollection to evaluate model output with multiple metrics simultaneously. It wraps a sequence of metrics into a single callable class.

```python
from torchmetrics import MetricCollection
from torchmetrics.classification import MulticlassAccuracy, MulticlassPrecision, MulticlassRecall

metrics = MetricCollection([
    MulticlassAccuracy(num_classes=10),
    MulticlassPrecision(num_classes=10),
    MulticlassRecall(num_classes=10)
])
```

--------------------------------

### Metric Arithmetic Example

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Demonstrates how to combine two metrics using the addition operator. The resulting metric will compute and sum the results of the individual metrics.

```python
from torchmetrics import MetricCollection
from torchmetrics.classification import MulticlassAccuracy, MulticlassPrecision, MulticlassRecall

first_metric = MyFirstMetric()
second_metric = MySecondMetric()

new_metric = first_metric + second_metric
```

--------------------------------

### Save and Load Metric State Dict with Persistence

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Provides a complete example of saving and loading a metric's state dictionary, including enabling persistence to ensure metric states are included in the state dict.

```python
import torch
from torchmetrics.classification import MulticlassAccuracy

metric = MulticlassAccuracy(num_classes=5).to("cuda")
metric.persistent(True)
metric.update(torch.randint(5, (100,)).cuda(), torch.randint(5, (100,)).cuda())
torch.save(metric.state_dict(), "metric.pth")

metric2 = MulticlassAccuracy(num_classes=5).to("cpu")
metric2.load_state_dict(torch.load("metric.pth", map_location="cpu"))
```

--------------------------------

### Sample Function Definition

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/README.md

Defines a sample Python function with type hints and a docstring following Google style. This function takes an integer and an optional float, returning a string representation of their sum. It includes an example usage within the docstring.

```python
from typing import Optional


def my_func(param_a: int, param_b: Optional[float] = None) -> str:
    """Sample function.

    Args:
        param_a: first parameter
        param_b: second parameter

    Return:
        sum of both numbers

    Example::

        >>> my_func(1, 2)
        3

    Note:
        If you want to add something.
    """
    p = param_b if param_b else 0
    return str(param_a + p)
```

--------------------------------

### DunnIndex Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/clustering/dunn_index.rst

The `DunnIndex` class provides a stateful way to compute the Dunn Index over batches of data. Instantiate the class and then call `update` with new data and `compute` to get the final metric.

```APIDOC
## DunnIndex

### Description
Calculates the Dunn Index, a metric for evaluating the quality of a clustering.

### Class Signature
```python
class torchmetrics.clustering.DunnIndex(reduction: Literal['mean', 'sum', 'none'] = 'mean', empty_cluster_reduction: Literal['error', 'ignore'] = 'error')
```

### Parameters
* **reduction** (`Literal['mean', 'sum', 'none']`, optional) - Specifies how to aggregate the results. Defaults to `'mean'`.
* **empty_cluster_reduction** (`Literal['error', 'ignore']`, optional) - Specifies how to handle empty clusters. Defaults to `'error'`.
```

--------------------------------

### SourceAggregatedSignalDistortionRatio Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/audio/source_aggregated_signal_distortion_ratio.rst

The `SourceAggregatedSignalDistortionRatio` class provides a stateful way to compute SA-SDR over batches of data. Instantiate the class and then call `update` with predictions and targets, followed by `compute` to get the final metric.

```APIDOC
## SourceAggregatedSignalDistortionRatio

### Description
Computes the Source Aggregated Signal-to-Distortion Ratio (SA-SDR) metric.

### Class Signature
```python
class torchmetrics.audio.sdr.SourceAggregatedSignalDistortionRatio
```

### Parameters
* **reduction** (str, optional) - Specifies how to reduce the results. Default is `"mean"`.
* **sample_rate** (int, optional) - The sample rate of the audio. Default is `None`.
* **zero_mean** (bool, optional) - If True, center the signals before computation. Default is `False`.
* **keepdim** (bool, optional) - If True, retains the dimension for reduction. Default is `False`.

### Methods
* **update(preds, target)**: Update the state of the metric.
* **compute()**: Compute the final metric value.
```

--------------------------------

### Use class-based Accuracy metric with accumulation

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/quickstart.rst

Initialize and use the class-based Accuracy metric for accumulating states over multiple batches. This example shows how to update the metric, compute the final result, and reset its state.

```python
import torch
# import our library
import torchmetrics

# initialize metric
metric = torchmetrics.classification.Accuracy(task="multiclass", num_classes=5)

n_batches = 10
for i in range(n_batches):
    # simulate a classification problem
    preds = torch.randn(10, 5).softmax(dim=-1)
    target = torch.randint(5, (10,))
    # metric on current batch
    acc = metric(preds, target)
    print(f"Accuracy on batch {i}: {acc}")

# metric on all batches using custom accumulation
acc = metric.compute()
print(f"Accuracy on all data: {acc}")

# Resetting internal state such that metric ready for new data
metric.reset()
```

--------------------------------

### Initialize and Use Metrics

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Demonstrates initializing different types of metrics, including those within nn.ModuleDict and MetricCollection, and how to call them within a forward pass.

```python
self.metric3 = nn.ModuleDict({'accuracy': BinaryAccuracy()})
self.metric4 = MetricCollection([BinaryAccuracy()]) # torchmetrics built-in collection class

def forward(self, batch):
    data, target = batch
    preds = self(data)
    ...
    val1 = self.metric1(preds, target)
    val2 = self.metric2[0](preds, target)
    val3 = self.metric3['accuracy'](preds, target)
    val4 = self.metric4(preds, target)
```

--------------------------------

### Initialize and Use Accuracy Metric on CPU/GPU

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Demonstrates initializing an Accuracy metric, moving it to the appropriate device (CPU or CUDA), and accumulating results over multiple batches. Use this for standard single-device computations.

```python
import torch

# import our library
import torchmetrics

# initialize metric
metric = torchmetrics.classification.Accuracy(task="multiclass", num_classes=5)

# move the metric to device you want computations to take place
device = "cuda" if torch.cuda.is_available() else "cpu"
metric.to(device)

n_batches = 10
for i in range(n_batches):
    # simulate a classification problem
    preds = torch.randn(10, 5).softmax(dim=-1).to(device)
    target = torch.randint(5, (10,)).to(device)

    # metric on current batch
    acc = metric(preds, target)
    print(f"Accuracy on batch {i}: {acc}")

# metric on all batches using custom accumulation
acc = metric.compute()
print(f"Accuracy on all data: {acc}")
```

--------------------------------

### R2Score Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/regression/r2_score.rst

The R2Score module provides a class-based interface for calculating the R2 score. Instantiate the class and use the `update` and `compute` methods to track and get the score.

```APIDOC
## R2Score Module

### Description
Class for calculating the R2 score (coefficient of determination).

### Usage
```python
from torchmetrics import R2Score

r2_score = R2Score()
preds = torch.randn(100)
targets = torch.randn(100)
r2_score.update(preds, targets)
r2 = r2_score.compute()
```

### Parameters
(See torchmetrics.metric.Metric for base parameters)

### Methods
- `update(preds: Tensor, target: Tensor)`: Update the internal state with predictions and targets.
- `compute()`: Compute and return the R2 score.
```

--------------------------------

### Build Torchmetrics Docker Image

Source: https://github.com/lightning-ai/torchmetrics/blob/master/dockers/README.md

Clone the repository and build a Docker image using the provided Dockerfile. Use default arguments for a standard build or specify arguments for custom Python, PyTorch, and CUDA versions.

```bash
git clone https://github.com/Lightning-AI/torchmetrics.git

# build with the default arguments
docker image build -t torchmetrics:latest -f dockers/ubuntu-cuda/Dockerfile .

# build with specific arguments
docker image build -t torchmetrics:ubuntu-cuda11.7.1-py3.10-torch2.0 \
  -f dockers/base-cuda/Dockerfile \
  --build-arg PYTHON_VERSION=3.10 \
  --build-arg PYTORCH_VERSION=2.0 \
  --build-arg CUDA_VERSION=11.7.1 \
  .
```

--------------------------------

### Calculate accuracy using TorchMetrics functional API

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/quickstart.rst

Use the functional API for simple metric calculations. This example demonstrates computing accuracy for a classification problem with random predictions and targets.

```python
import torch
# import our library
import torchmetrics

# simulate a classification problem
preds = torch.randn(10, 5).softmax(dim=-1)
target = torch.randint(5, (10,))

acc = torchmetrics.functional.accuracy(preds, target, task="multiclass", num_classes=5)
```

--------------------------------

### AdjustedRandScore Class

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/clustering/adjusted_rand_score.rst

The `AdjustedRandScore` class provides a stateful way to compute the Adjusted Rand Score. Instantiate the class and then call `update` with predictions and targets, followed by `compute` to get the final score.

```APIDOC
## AdjustedRandScore

### Description
Calculates the Adjusted Rand Score between two clusterings.

### Method Signature
`AdjustedRandScore(*args, **kwargs)`

### Parameters
(Refer to the functional interface for detailed parameter descriptions as the class mirrors its functionality.)

### Usage
```python
from torchmetrics.clustering import AdjustedRandScore

# Example usage
preds = [0, 1, 2, 0, 1, 2]
targets = [0, 1, 2, 1, 0, 2]

metric = AdjustedRandScore()
metric.update(preds, targets)
score = metric.compute()
print(score)
```

### Returns
- `torch.Tensor`: The computed Adjusted Rand Score.
```

--------------------------------

### Download and Prepare Test Data

Source: https://github.com/lightning-ai/torchmetrics/blob/master/tests/README.md

Fetch and extract test data required for certain tests. Navigate to the 'tests/' directory before running these commands.

```bash
cd tests/
S3_DATA=https://pl-public-data.s3.amazonaws.com/metrics/data.zip  # data location
pip install -q "urllib3>1.0"
python -c "from urllib.request import urlretrieve ; urlretrieve('$S3_DATA', 'data.zip')"  # fetch data
unzip -o data.zip  # unzip data
ls -l _data/*  # list data
```

--------------------------------

### Run All Tests (Windows)

Source: https://github.com/lightning-ai/torchmetrics/blob/master/tests/README.md

Execute unit and integration tests on Windows. Note that this command will only run non-DDP tests.

```bash
pytest tests/
```

--------------------------------

### Run Torchmetrics Docker Image with GPUs

Source: https://github.com/lightning-ai/torchmetrics/blob/master/dockers/README.md

Execute a Torchmetrics Docker container with access to all available GPUs using the `--gpus all` flag.

```bash
docker run --rm -it --gpus all torchmetrics:ubuntu-cuda11.7.1-py3.10-torch2.0
```

--------------------------------

### Bootstrapper Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/wrappers/bootstrapper.rst

This section details the Bootstrapper class available for use as a wrapper.

```APIDOC
## Bootstrapper

### Description

The Bootstrapper class is a wrapper that can be applied to other metrics to enable bootstrapping for resampling.

### Module

torchmetrics.wrappers.BootStrapper

### Usage

```python
from torchmetrics.wrappers import BootStrapper
from torchmetrics import Accuracy

# Example usage with Accuracy metric
metric = BootStrapper(Accuracy(task="binary"))

# Update metric with data
metric.update(preds, target)

# Compute the result
result = metric.compute()
```

### Parameters

This class does not have explicit parameters documented in this section, but it wraps an existing metric.

### Methods

- **update(preds, target, ...)**: Updates the internal state of the metric with new data.
- **compute()**: Computes and returns the final metric value.

### Response

- **compute()**: Returns the bootstrapped metric value.
```

--------------------------------

### Advanced Plotting with MetricTracker and MetricCollection

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/plotting.rst

Combine `MetricCollection` with `MetricTracker` for advanced plotting scenarios, including metrics that do not return scalar tensors. This example demonstrates plotting ConfusionMatrix and ROC curves for the last step, alongside other metrics tracked over time.

```python
# Define collection that is a mix of metrics that return a scalar tensors and not
confmat = torchmetrics.ConfusionMatrix(task="binary")
roc = torchmetrics.ROC(task="binary")
collection = torchmetrics.MetricCollection(
    torchmetrics.Accuracy(task="binary"),
    torchmetrics.Recall(task="binary"),
    torchmetrics.Precision(task="binary"),
    confmat,
    roc,
)

# Define tracker over the collection to easy keep track of the metrics over multiple steps
tracker = torchmetrics.wrappers.MetricTracker(collection, maximize=True)

# Run "training" loop
for step in range(num_steps):
    tracker.increment()
    for _ in range(N):
        tracker.update(preds(step), target(step))

# Extract all metrics from all steps
all_results = tracker.compute_all()

# Construct a single figure with appropriate layout for all metrics
fig = plt.figure(layout="constrained")
ax1 = plt.subplot(2, 2, 1)
ax2 = plt.subplot(2, 2, 2)
ax3 = plt.subplot(2, 2, (3, 4))

# ConfusionMatrix and ROC we just plot the last step, notice how we call the plot method of those metrics
confmat.plot(val=all_results[-1]['BinaryConfusionMatrix'], ax=ax1)
roc.plot(all_results[-1]["BinaryROC"], ax=ax2)
```

--------------------------------

### Basic Metric Plotting

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/plotting.rst

Demonstrates the basic usage of the .plot method on a metric instance. This method computes the metric and generates a plot.

```python
metric = AnyMetricYouLike()
for _ in range(num_updates):
    metric.update(preds[i], target[i])
fig, ax = metric.plot()
```

--------------------------------

### Run and Manage Torchmetrics Docker Image

Source: https://github.com/lightning-ai/torchmetrics/blob/master/dockers/README.md

List available Docker images, run a Torchmetrics container interactively, and remove images when no longer needed.

```bash
docker image list
docker run --rm -it torchmetrics:latest bash
```

```bash
docker image list
docker image rm torchmetrics:latest
```

--------------------------------

### Using BootStrapper Wrapper for Confidence Intervals

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Demonstrates how to use the BootStrapper wrapper to compute confidence intervals for a metric by resampling input data. The metric results are returned as a dictionary containing mean and standard deviation.

```python
from torchmetrics.classification import MulticlassAccuracy
from torchmetrics.wrappers import BootStrapper
# creating metrics
wrapped_metric = BootStrapper(MulticlassAccuracy(num_classes=3))
# sample prediction and GT
target = torch.tensor([0, 2, 0, 2, 0, 1, 0, 2])
preds = torch.tensor([2, 1, 2, 0, 1, 2, 2, 2])
# showing the metric results
print(wrapped_metric(preds, target))  # this returns a dict with label info
```

--------------------------------

### PerceptualPathLength Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/image/perceptual_path_length.rst

The `PerceptualPathLength` class provides an object-oriented interface for calculating the Perceptual Path Length metric. It allows for incremental updates and final computation of the metric.

```APIDOC
## PerceptualPathLength Class

### Description
Calculates the Perceptual Path Length (PPL) metric.

### Parameters
* **generator** (GeneratorType) - The type of generator to use. Defaults to 'stylegan2'.
* **return_tensor** (bool) - Whether to return a tensor or a float. Defaults to False.
* **kwargs** - Additional keyword arguments passed to the `torchmetrics.Metric` base class.

### Methods
* **update(preds, target)**: Update the internal state with predictions and targets.
* **compute()**: Compute the final PPL metric.

### Example
```python
from torchmetrics.image.perceptual_path_length import PerceptualPathLength

ppl = PerceptualPathLength()
# Update with generated images and real images
# ppl.update(generated_images, real_images)
# metric = ppl.compute()
```
```

--------------------------------

### ScaleInvariantSignalDistortionRatio Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/audio/scale_invariant_signal_distortion_ratio.rst

The `ScaleInvariantSignalDistortionRatio` class provides a stateful way to compute SI-SDR over batches of audio.

```APIDOC
## ScaleInvariantSignalDistortionRatio

### Description
Computes the Scale-Invariant Signal-to-Distortion Ratio (SI-SDR) metric.

### Class
`torchmetrics.audio.ScaleInvariantSignalDistortionRatio`

### Parameters
- **`reduction`** (callable, optional): Specifies how to reduce the results. Defaults to `'mean'`.
- **`zero_mean`** (bool, optional): If True, center the signals before calculating the metric. Defaults to `False`.
- **`keepdim`** (bool, optional): If True, the output tensor will have the same dimension as the input. Defaults to `False`.

### Methods
- **`update(preds, target)`**: Updates the state of the metric.
- **`compute()`**: Computes the final SI-SDR metric.
```

--------------------------------

### Using MetricCollection for Multiple Metrics

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Demonstrates how to use `MetricCollection` to group and compute multiple metrics simultaneously. This is useful for logging several metrics within a LightningModule.

```python
target = torch.tensor([0, 2, 0, 2, 0, 1, 0, 2])
preds = torch.tensor([2, 1, 2, 0, 1, 2, 2, 2])
metric_collection = MetricCollection([
    MulticlassAccuracy(num_classes=3, average="micro"),
    MulticlassPrecision(num_classes=3, average="macro"),
    MulticlassRecall(num_classes=3, average="macro")
])
print(metric_collection(preds, target))
```

--------------------------------

### Save Metric State Dict

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Demonstrates the recommended way to save a metric's state dictionary, which is more robust than saving the entire metric object.

```python
# Instead of this
torch.save(metric, "metric.pt")
# do this
torch.save(metric.state_dict(), "metric.pt")
```

--------------------------------

### Initialize Separate Metrics for Multiple DataLoaders

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/lightning.rst

When using multiple DataLoaders, initialize a separate instance of each modular metric for each DataLoader to ensure internal states are managed correctly. This also applies when using separate metrics for training, validation, and testing.

```python
class MyModule(LightningModule):

    def __init__(self, num_classes):
        ... 
        self.val_acc = nn.ModuleList(
            [torchmetrics.classification.Accuracy(task="multiclass", num_classes=num_classes) for _ in range(2)]
        )

    def val_dataloader(self):
        return [DataLoader(...), DataLoader(...)]

    def validation_step(self, batch, batch_idx, dataloader_idx):
        x, y = batch
        preds = self(x)
        ...
        self.val_acc[dataloader_idx](preds, y)
        self.log('val_acc', self.val_acc[dataloader_idx])
```

--------------------------------

### Check Metric Device

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Illustrates how to check the device a metric is currently located on using the `.device` property.

```python
print(metric.device)
```

--------------------------------

### Functional Metric Backend Structure

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/implement.rst

The functional backend for a new metric should include three functions: _new_metric_update for initial checks and pre-sync logic, _new_metric_compute for the core computation, and new_metric as a public wrapper.

```python
def _new_metric_update(...):
    # Type/shape checking and pre-distributed syncing logic
    pass

def _new_metric_compute(...):
    # Remaining logic for metric computation
    pass

def new_metric(...):
    # Wraps _update and _compute into a public functional interface
    pass

```

--------------------------------

### LearnedPerceptualImagePatchSimilarity Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/image/learned_perceptual_image_patch_similarity.rst

The `LearnedPerceptualImagePatchSimilarity` class provides a stateful way to compute LPIPS over batches of images. It is designed to be used within a training or evaluation loop where metrics are updated incrementally.

```APIDOC
## LearnedPerceptualImagePatchSimilarity

### Description
Calculates the Learned Perceptual Image Patch Similarity (LPIPS) metric.

### Class Signature
```python
class torchmetrics.image.lpip.LearnedPerceptualImagePatchSimilarity(
    *args,
    **kwargs
)
```

### Parameters
This class inherits parameters from its parent classes. Refer to the parent class documentation for a full list of parameters.
```

--------------------------------

### Running Wrapper Module Interface

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/wrappers/running.rst

The `torchmetrics.wrappers.Running` class provides an interface for managing metrics that are computed over a sequence of data batches. The documentation explicitly excludes the `update` and `compute` members from the public interface documentation, suggesting they are internal or handled differently.

```APIDOC
## Class: torchmetrics.wrappers.Running

### Description

The `Running` wrapper is used to manage metrics that are calculated across multiple batches of data. It provides a way to accumulate results and compute the final metric value after all batches have been processed.

### Usage

This class is intended to be used as a wrapper around other metric classes. The `update` and `compute` methods are core to its functionality but are not exposed in the public API documentation for this specific class, implying they are either inherited and used implicitly or managed through a different interface.

### Parameters

This documentation does not specify any direct parameters for the `Running` wrapper's initialization or public methods.
```

--------------------------------

### Moving Metrics to GPU

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Shows how to manually move a metric to a specific CUDA device. Metric states need to be on the same device as the input data.

```python
from torchmetrics.classification import BinaryAccuracy

target = torch.tensor([1, 1, 0, 0], device=torch.device("cuda", 0))
preds = torch.tensor([0, 1, 0, 0], device=torch.device("cuda", 0))

# Metric states are always initialized on cpu, and needs to be moved to
# the correct device
confmat = BinaryAccuracy().to(torch.device("cuda", 0))
out = confmat(preds, target)
print(out.device) # cuda:0
```

--------------------------------

### Plotting Functional Metric Results

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/plotting.rst

Demonstrates how to plot the output of a Torchmetrics functional interface by first initializing the corresponding metric class.

```python
plot_class = torchmetrics.Accuracy(task="multiclass", num_classes=3)
value = torchmetrics.functional.accuracy(
    torch.randint(3, (10,)), torch.randint(3, (10,)), num_classes=3
)
fig, ax = plot_class.plot(value)
```

--------------------------------

### Logging Multiple Metrics with MetricCollection in LightningModule

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Shows how to integrate `MetricCollection` into a PyTorch LightningModule for logging training and validation metrics. It utilizes `log_dict` for efficient logging and demonstrates metric updates, computation, and resetting.

```python
from torchmetrics import MetricCollection
from torchmetrics.classification import MulticlassAccuracy, MulticlassPrecision, MulticlassRecall

class MyModule(LightningModule):
    def __init__(self, num_classes: int):
        super().__init__()
        metrics = MetricCollection([
            MulticlassAccuracy(num_classes), MulticlassPrecision(num_classes), MulticlassRecall(num_classes)
        ])
        self.train_metrics = metrics.clone(prefix='train_')
        self.valid_metrics = metrics.clone(prefix='val_')

    def training_step(self, batch, batch_idx):
        logits = self(x)
        # ...
        output = self.train_metrics(logits, y)
        # use log_dict instead of log
        # metrics are logged with keys: train_Accuracy, train_Precision and train_Recall
        self.log_dict(output)

    def validation_step(self, batch, batch_idx):
        logits = self(x)
        # ...
        self.valid_metrics.update(logits, y)

    def on_validation_epoch_end(self):
        # use log_dict instead of log
        # metrics are logged with keys: val_Accuracy, val_Precision and val_Recall
        output = self.valid_metrics.compute()
        self.log_dict(output)
        # remember to reset metrics at the end of the epoch
        self.valid_metrics.reset()
```

--------------------------------

### Explained Variance Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/regression/explained_variance.rst

The `ExplainedVariance` class provides a stateful way to compute explained variance over batches.

```APIDOC
## ExplainedVariance

### Description
Calculates the explained variance between predictions and targets.

### Class
`torchmetrics.ExplainedVariance`

### Usage
```python
from torchmetrics import ExplainedVariance

metric = ExplainedVariance()
preds = torch.randn(100)
targets = torch.randn(100)
metric.update(preds, targets)
result = metric.compute()
```

### Parameters
This class does not take any parameters during initialization.

### Methods
- `update(preds, targets)`: Updates the internal state with predictions and targets.
- `compute()`: Computes the final explained variance.
```

--------------------------------

### Run Non-DDP Tests (Linux/Mac)

Source: https://github.com/lightning-ai/torchmetrics/blob/master/tests/README.md

Execute all tests except Distributed Data Parallel (DDP) tests on Linux or Mac systems.

```bash
pytest -m "not DDP" tests/
```

--------------------------------

### Run DDP Tests (Linux/Mac)

Source: https://github.com/lightning-ai/torchmetrics/blob/master/tests/README.md

Execute only Distributed Data Parallel (DDP) tests on Linux or Mac systems. Ensure the USE_PYTEST_POOL environment variable is set.

```bash
USE_PYTEST_POOL="1" pytest -m DDP tests/
```

--------------------------------

### Classwise Wrapper Usage

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/wrappers/classwise_wrapper.rst

This snippet shows how to instantiate and use the ClasswiseWrapper with a base metric.

```APIDOC
## Classwise Wrapper

### Description

The `ClasswiseWrapper` is a utility class that enables the calculation of metrics on a per-class basis. It wraps an existing metric and computes it independently for each class in the target labels.

### Module

.. autoclass:: torchmetrics.wrappers.ClasswiseWrapper
   :members:

```

--------------------------------

### Basic Metric Usage in PyTorch

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/overview.rst

Demonstrates how to use BinaryAccuracy metric within a standard PyTorch training loop. Metrics should be re-initialized per mode (train, validation, test) and reset after each epoch.

```python
from torchmetrics.classification import BinaryAccuracy

train_accuracy = BinaryAccuracy()
valid_accuracy = BinaryAccuracy()

for epoch in range(epochs):
    for x, y in train_data:
        y_hat = model(x)

        # training step accuracy
        batch_acc = train_accuracy(y_hat, y)
        print(f"Accuracy of batch{i} is {batch_acc}")

    for x, y in valid_data:
        y_hat = model(x)
        valid_accuracy.update(y_hat, y)

    # total accuracy over all training batches
    total_train_accuracy = train_accuracy.compute()

    # total accuracy over all validation batches
    total_valid_accuracy = valid_accuracy.compute()

    print(f"Training acc for epoch {epoch}: {total_train_accuracy}")
    print(f"Validation acc for epoch {epoch}: {total_valid_accuracy}")

    # Reset metric states after each epoch
    train_accuracy.reset()
    valid_accuracy.reset()
```

--------------------------------

### Average Precision Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/classification/average_precision.rst

The Average Precision metric can be instantiated as a module for stateful computation.

```APIDOC
## Average Precision Module

### Description
Instantiate the Average Precision metric as a module for use in your classification tasks. This allows for incremental updates and final computation of the metric.

### Class
`torchmetrics.AveragePrecision`

### Usage
```python
from torchmetrics import AveragePrecision

ap = AveragePrecision()
# ... update and compute methods would be called here
```

### Note
`update` and `compute` methods are excluded from this documentation as they are standard for all TorchMetrics modules.
```

--------------------------------

### SignalNoiseRatio Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/audio/signal_noise_ratio.rst

The `SignalNoiseRatio` class provides a stateful way to compute SNR over batches of audio.

```APIDOC
## SignalNoiseRatio

### Description
Computes the signal-to-noise ratio (SNR) between a target signal and an estimated signal.

### Class
`torchmetrics.audio.SignalNoiseRatio`

### Parameters
* `sample_rate` (int): The sampling rate of the audio signals.
* `reduction` (str, optional): Specifies the reduction to apply to the output: `'elementwise' | 'mean' | 'sum'`. Defaults to `'mean'`.
* `zero_division` (int | float | None, optional): Placeholder for cases where the denominator is zero. Defaults to `None`.

### Methods
* `update(preds, target)`: Update the internal state with predictions and targets.
* `compute()`: Compute the final SNR metric.

### Example
```python
from torchmetrics.audio import SignalNoiseRatio

snr = SignalNoiseRatio()
snr(preds, target)
```
```

--------------------------------

### Structural Similarity Index Measure (SSIM) Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/image/structural_similarity.rst

The SSIM module can be instantiated and used to compute the metric over batches of data.

```APIDOC
## Structural Similarity Index Measure (SSIM) Module

### Description
The SSIM module computes the Structural Similarity Index Measure between two images.

### Class
`torchmetrics.image.StructuralSimilarityIndexMeasure`

### Usage
```python
from torchmetrics.image import StructuralSimilarityIndexMeasure

ssim = StructuralSimilarityIndexMeasure()
# Compute SSIM for a batch of images
metric = ssim(preds, target)
```

### Parameters
(Refer to the functional interface for detailed parameter descriptions as the module wraps the functional implementation.)

### Returns
- **metric** (Tensor) - The computed SSIM score.
```

--------------------------------

### Implement Custom Accuracy Metric

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/implement.rst

Use this for a basic accuracy metric. States 'correct' and 'total' are summed across batches in distributed settings.

```python
from torchmetrics import Metric

class MyAccuracy(Metric):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.add_state("correct", default=torch.tensor(0), dist_reduce_fx="sum")
        self.add_state("total", default=torch.tensor(0), dist_reduce_fx="sum")

    def update(self, preds: Tensor, target: Tensor) -> None:
        preds, target = self._input_format(preds, target)
        if preds.shape != target.shape:
            raise ValueError("preds and target must have the same shape")

        self.correct += torch.sum(preds == target)
        self.total += target.numel()

    def compute(self) -> Tensor:
        return self.correct.float() / self.total
```

--------------------------------

### Module Interface

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/classification/label_ranking_average_precision.rst

The `MultilabelRankingAveragePrecision` class provides a stateful way to compute the metric over batches.

```APIDOC
## Class: MultilabelRankingAveragePrecision

### Description
Computes the label ranking average precision score for multi-label classification.

### Usage
```python
from torchmetrics.classification import MultilabelRankingAveragePrecision

metric = MultilabelRankingAveragePrecision()
# ... update metric with data ...
result = metric.compute()
```

### Parameters
(Details for parameters are not provided in the source text, only exclusion of `update` and `compute` methods is mentioned.)
```

--------------------------------

### InfoLM Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/text/infolm.rst

The InfoLM metric can be used as a PyTorch Lightning module. Instantiate the module with desired parameters and then call it like a function.

```APIDOC
## InfoLM Module

### Description

InfoLM metric can be used as a PyTorch Lightning module.

### Method Signature

.. autoclass:: torchmetrics.text.infolm.InfoLM
    :exclude-members: update, compute
```

--------------------------------

### TorchMetrics Metric Implementation Structure

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/implement.rst

When implementing a new metric, create a functional backend with update, compute, and a public interface function. Then, create a module interface subclassing torchmetrics.Metric, using add_state, and calling the functional backend functions.

```python
from torchmetrics.metric import Metric

class NewMetric(Metric):
    def __init__(self, ...):
        super().__init__(...)
        self.add_state("name", default=..., dist_reduce_fx=...)

    def update(self, ...):
        # Call functional backend update
        pass

    def compute(self):
        # Call functional backend compute
        pass

```

--------------------------------

### RootMeanSquaredErrorUsingSlidingWindow Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/image/root_mean_squared_error_using_sliding_window.rst

The module interface for RootMeanSquaredErrorUsingSlidingWindow allows for stateful computation of RMSE over batches of images.

```APIDOC
## RootMeanSquaredErrorUsingSlidingWindow

### Description
Calculates the Root Mean Squared Error (RMSE) between predicted and target images using a sliding window approach. This is useful for metrics where local image patches are important.

### Class
`torchmetrics.image.RootMeanSquaredErrorUsingSlidingWindow`

### Parameters
This class inherits parameters from its parent classes. Refer to the base class documentation for detailed parameter information.

### Methods
- `__init__(...)`: Initializes the metric.
- `update(preds, target)`: Updates the metric's internal state with predictions and targets.
- `compute()`: Computes the final RMSE metric.

### Example
```python
from torchmetrics.image import RootMeanSquaredErrorUsingSlidingWindow

metric = RootMeanSquaredErrorUsingSlidingWindow()
# ... update metric with data ...
rmse = metric.compute()
```
```

--------------------------------

### PeakSignalNoiseRatio Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/image/peak_signal_noise_ratio.rst

The `PeakSignalNoiseRatio` class provides a stateful way to compute PSNR over multiple batches.

```APIDOC
## PeakSignalNoiseRatio

### Description
Calculates the Peak Signal-to-Noise Ratio (PSNR) metric.

### Class Signature
```python
PeakSignalNoiseRatio(data_range: Optional[float] = None, reduction: str = 'element-wise', ignore_index: Optional[int] = None, dim: Optional[int] = None)
```

### Parameters
* **data_range** (Optional[float]) - The range of the input data. If `None`, the range is inferred from the data.
* **reduction** (str) - Specifies the reduction to apply to the output: 'element-wise', 'mean', 'sum', 'none'. Default is 'element-wise'.
* **ignore_index** (Optional[int]) - Specifies a target value that is ignored and does not contribute to the metric computation.
* **dim** (Optional[int]) - Dimension or tuple of dimensions along which to compute the metric. Default is None, which computes the metric over all dimensions.
```

--------------------------------

### MeanIoU Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/segmentation/mean_iou.rst

The MeanIoU metric can be instantiated as a module for use within PyTorch training pipelines. It accumulates predictions and targets and computes the mIoU score.

```APIDOC
## MeanIoU Module

### Description
Instantiate the `MeanIoU` metric to compute the Mean Intersection over Union for segmentation tasks. This class accumulates predictions and targets over batches and computes the final mIoU score.

### Class Signature
```python
class torchmetrics.segmentation.MeanIoU(num_classes: int, ignore_index: Optional[int] = None, reduction: str = 'mean', ...)
```

### Parameters
* **num_classes** (int) - The total number of classes.
* **ignore_index** (Optional[int]) - Specifies a target value that is ignored and does not contribute to the metric calculation. Defaults to None.
* **reduction** (str) - Defines the reduction method for the metric. Defaults to 'mean'.

### Example
```python
from torchmetrics.segmentation import MeanIoU

mIoU = MeanIoU(num_classes=5)

# Example usage within a training loop:
# predictions = model(inputs)
# targets = ...
# mIoU.update(predictions, targets)
# score = mIoU.compute()
```
```

--------------------------------

### ARNIQA Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/image/arniqa.rst

The ARNIQA metric can be used as a PyTorch Lightning module. Instantiate the class and then call it like a function.

```APIDOC
## ARNIQA Module

### Description
Instantiate the ARNIQA metric as a module. This class is used to compute the ARNIQA score for images.

### Class
`torchmetrics.image.ARNIQA`

### Parameters
* `data_range` (int or float, optional) - The range of the input image. Defaults to 1.0.
* `reduction` (str, optional) - Specifies how to reduce the results. Options are 'mean', 'sum', or 'none'. Defaults to 'mean'.
* `disable` (bool, optional) - If True, the metric will be disabled and will always return 0. Defaults to False.

### Example
```python
from torchmetrics.image import ARNIQA

arniqa = ARNIQA()
# Call the metric with images
# score = arniqa(preds, target)
```
```

--------------------------------

### Customizing and Saving Plots

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/pages/plotting.rst

Shows how to customize the appearance of a generated plot using the returned Figure and Axes objects, and how to save the plot to a file.

```python
ax.set_fontsize(fs=20)
fig.set_title("This is a nice plot")
fig.savefig("my_awesome_plot.png")
```

--------------------------------

### PanopticQuality Module

Source: https://github.com/lightning-ai/torchmetrics/blob/master/docs/source/detection/panoptic_quality.rst

The `PanopticQuality` class provides a stateful way to compute panoptic quality over batches of data.

```APIDOC
## PanopticQuality

### Description

Calculate Panoptic Quality metric.

### Method Signature

```python
PanopticQuality(metric, iou_threshold=0.5, label_to_cat_id=None, ...)
```

### Parameters

- **metric** (callable) - Function to compute the panoptic quality.
- **iou_threshold** (float) - IoU threshold for matching.
- **label_to_cat_id** (dict) - Mapping from label id to category id.

### Attributes

- **update**: Updates the internal state with new data.
- **compute**: Computes the final panoptic quality metric.
```

--------------------------------

### Implement Custom Metric with torchmetrics.Metric

Source: https://github.com/lightning-ai/torchmetrics/blob/master/README.md

Subclass torchmetrics.Metric and implement update and compute methods to create custom metrics. Use add_state to define internal states and specify the reduction function for distributed environments.

```python
import torch
from torchmetrics import Metric


class MyAccuracy(Metric):
    def __init__(self):
        # remember to call super
        super().__init__()
        # call `self.add_state`for every internal state that is needed for the metrics computations
        # dist_reduce_fx indicates the function that should be used to reduce
        # state from multiple processes
        self.add_state("correct", default=torch.tensor(0), dist_reduce_fx="sum")
        self.add_state("total", default=torch.tensor(0), dist_reduce_fx="sum")

    def update(self, preds: torch.Tensor, target: torch.Tensor) -> None:
        # extract predicted class index for computing accuracy
        preds = preds.argmax(dim=-1)
        assert preds.shape == target.shape
        # update metric states
        self.correct += torch.sum(preds == target)
        self.total += target.numel()

    def compute(self) -> torch.Tensor:
        # compute final result
        return self.correct.float() / self.total


my_metric = MyAccuracy()
preds = torch.randn(10, 5).softmax(dim=-1)
target = torch.randint(5, (10,))

print(my_metric(preds, target))
```