rename peak_signal_noise_ratio

CHANGELOG.md

@@ -94,6 +94,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * `torchmetrics.Hinge` -> `torchmetrics.HingeLoss`
 
 
+- Renamed image metrics ([#732](https://github.com/PyTorchLightning/metrics/pull/732))
+  * `functional.psnr` -> `functional.peak_signal_noise_ratio`
+  * `PSNR` -> `PeakSignalNoiseRatio`
+
+
 ### Removed
 
 - Removed `embedding_similarity` metric ([#638](https://github.com/PyTorchLightning/metrics/pull/638))

docs/source/pages/overview.rst

@@ -167,7 +167,7 @@ the following limitations:
 * Some metrics does not work at all in half precision on CPU. We have explicitly stated this in their docstring,
   but they are also listed below:
 
-  - :ref:`references/modules:PSNR` and :ref:`references/functional:psnr [func]`
+  - :ref:`references/modules:PSNR` and :ref:`references/functional:peak_signal_noise_ratio [func]`
   - :ref:`references/modules:SSIM` and :ref:`references/functional:ssim [func]`
   - :ref:`references/modules:KLDivergence` and :ref:`references/functional:kl_divergence [func]`
 

docs/source/references/functional.rst

@@ -240,18 +240,17 @@ image_gradients [func]
 .. autofunction:: torchmetrics.functional.image_gradients
     :noindex:
 
-
 multiscale_structural_similarity_index_measure [func]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: torchmetrics.functional.multiscale_structural_similarity_index_measure
     :noindex:
 
 
-psnr [func]
-~~~~~~~~~~~
+peak_signal_noise_ratio [func]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. autofunction:: torchmetrics.functional.psnr
+.. autofunction:: torchmetrics.functional.peak_signal_noise_ratio
     :noindex:
 
 

docs/source/references/modules.rst

@@ -398,10 +398,10 @@ MultiScaleStructuralSimilarityIndexMeasure
 .. autoclass:: torchmetrics.MultiScaleStructuralSimilarityIndexMeasure
     :noindex:
 
-PSNR
-~~~~
+PeakSignalNoiseRatio
+~~~~~~~~~~~~~~~~~~~~
 
-.. autoclass:: torchmetrics.PSNR
+.. autoclass:: torchmetrics.PeakSignalNoiseRatio
     :noindex:
 
 SSIM

tests/image/test_psnr.py

@@ -18,12 +18,12 @@
 import numpy as np
 import pytest
 import torch
-from skimage.metrics import peak_signal_noise_ratio
+from skimage.metrics import peak_signal_noise_ratio as skimage_peak_signal_noise_ratio
 
 from tests.helpers import seed_all
 from tests.helpers.testers import BATCH_SIZE, NUM_BATCHES, MetricTester
-from torchmetrics.functional import psnr
-from torchmetrics.image import PSNR
+from torchmetrics.functional import peak_signal_noise_ratio, psnr
+from torchmetrics.image import PSNR, PeakSignalNoiseRatio
 
 seed_all(42)
 
@@ -64,7 +64,7 @@ def _sk_psnr(preds, target, data_range, reduction, dim):
     np_reduce_map = {"elementwise_mean": np.mean, "none": np.array, "sum": np.sum}
     return np_reduce_map[reduction](
         [
-            peak_signal_noise_ratio(sk_target, sk_preds, data_range=data_range)
+            skimage_peak_signal_noise_ratio(sk_target, sk_preds, data_range=data_range)
             for sk_target, sk_preds in zip(sk_target_lists, sk_preds_lists)
         ]
     )
@@ -112,7 +112,7 @@ def test_psnr_functional(self, preds, target, sk_metric, data_range, base, reduc
         self.run_functional_metric_test(
             preds,
             target,
-            psnr,
+            peak_signal_noise_ratio,
             partial(sk_metric, data_range=data_range, reduction=reduction, dim=dim),
             metric_args=_args,
         )
@@ -121,13 +121,21 @@ def test_psnr_functional(self, preds, target, sk_metric, data_range, base, reduc
     @pytest.mark.xfail(reason="PSNR metric does not support cpu + half precision")
     def test_psnr_half_cpu(self, preds, target, data_range, reduction, dim, base, sk_metric):
         self.run_precision_test_cpu(
-            preds, target, PSNR, psnr, {"data_range": data_range, "base": base, "reduction": reduction, "dim": dim}
+            preds,
+            target,
+            PSNR,
+            peak_signal_noise_ratio,
+            {"data_range": data_range, "base": base, "reduction": reduction, "dim": dim},
         )
 
     @pytest.mark.skipif(not torch.cuda.is_available(), reason="test requires cuda")
     def test_psnr_half_gpu(self, preds, target, data_range, reduction, dim, base, sk_metric):
         self.run_precision_test_gpu(
-            preds, target, PSNR, psnr, {"data_range": data_range, "base": base, "reduction": reduction, "dim": dim}
+            preds,
+            target,
+            PSNR,
+            peak_signal_noise_ratio,
+            {"data_range": data_range, "base": base, "reduction": reduction, "dim": dim},
         )
 
 
@@ -138,12 +146,12 @@ def test_reduction_for_dim_none(reduction):
         PSNR(reduction=reduction, dim=None)
 
     with pytest.warns(UserWarning, match=match):
-        psnr(_inputs[0].preds, _inputs[0].target, reduction=reduction, dim=None)
+        peak_signal_noise_ratio(_inputs[0].preds, _inputs[0].target, reduction=reduction, dim=None)
 
 
 def test_missing_data_range():
     with pytest.raises(ValueError):
         PSNR(data_range=None, dim=0)
 
     with pytest.raises(ValueError):
-        psnr(_inputs[0].preds, _inputs[0].target, data_range=None, dim=0)
+        peak_signal_noise_ratio(_inputs[0].preds, _inputs[0].target, data_range=None, dim=0)

torchmetrics/__init__.py

@@ -53,7 +53,12 @@
     Specificity,
     StatScores,
 )
-from torchmetrics.image import PSNR, SSIM, MultiScaleStructuralSimilarityIndexMeasure  # noqa: E402
+from torchmetrics.image import (  # noqa: E402
+    PSNR,
+    SSIM,
+    MultiScaleStructuralSimilarityIndexMeasure,
+    PeakSignalNoiseRatio,
+)
 from torchmetrics.metric import Metric  # noqa: E402
 from torchmetrics.metric_collections import MetricCollection  # noqa: E402
 from torchmetrics.regression import (  # noqa: E402
@@ -146,6 +151,7 @@
     "Precision",
     "PrecisionRecallCurve",
     "PSNR",
+    "PeakSignalNoiseRatio",
     "R2Score",
     "Recall",
     "RetrievalFallOut",

torchmetrics/functional/__init__.py

@@ -38,7 +38,7 @@
 from torchmetrics.functional.classification.stat_scores import stat_scores
 from torchmetrics.functional.image.gradients import image_gradients
 from torchmetrics.functional.image.ms_ssim import multiscale_structural_similarity_index_measure
-from torchmetrics.functional.image.psnr import psnr
+from torchmetrics.functional.image.psnr import peak_signal_noise_ratio, psnr
 from torchmetrics.functional.image.ssim import ssim
 from torchmetrics.functional.pairwise.cosine import pairwise_cosine_similarity
 from torchmetrics.functional.pairwise.euclidean import pairwise_euclidean_distance
@@ -120,6 +120,7 @@
     "precision",
     "precision_recall",
     "precision_recall_curve",
+    "peak_signal_noise_ratio",
     "psnr",
     "r2_score",
     "recall",

torchmetrics/functional/image/__init__.py

@@ -13,4 +13,4 @@
 # limitations under the License.
 
 from torchmetrics.functional.image.gradients import image_gradients  # noqa: F401
-from torchmetrics.functional.image.psnr import psnr  # noqa: F401
+from torchmetrics.functional.image.psnr import peak_signal_noise_ratio, psnr  # noqa: F401

torchmetrics/functional/image/psnr.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from typing import Optional, Tuple, Union
+from warnings import warn
 
 import torch
 from torch import Tensor, tensor
@@ -91,6 +92,65 @@ def _psnr_update(
     return sum_squared_error, n_obs
 
 
+def peak_signal_noise_ratio(
+    preds: Tensor,
+    target: Tensor,
+    data_range: Optional[float] = None,
+    base: float = 10.0,
+    reduction: str = "elementwise_mean",
+    dim: Optional[Union[int, Tuple[int, ...]]] = None,
+) -> Tensor:
+    """Computes the peak signal-to-noise ratio.
+
+    Args:
+        preds: estimated signal
+        target: groun truth signal
+        data_range:
+            the range of the data. If None, it is determined from the data (max - min). ``data_range`` must be given
+            when ``dim`` is not None.
+        base: a base of a logarithm to use (default: 10)
+        reduction: a method to reduce metric score over labels.
+
+            - ``'elementwise_mean'``: takes the mean (default)
+            - ``'sum'``: takes the sum
+            - ``'none'``: no reduction will be applied
+
+        dim:
+            Dimensions to reduce PSNR scores over provided as either an integer or a list of integers. Default is
+            None meaning scores will be reduced across all dimensions.
+    Return:
+        Tensor with PSNR score
+
+    Raises:
+        ValueError:
+            If ``dim`` is not ``None`` and ``data_range`` is not provided.
+
+    Example:
+        >>> from torchmetrics.functional import peak_signal_noise_ratio
+        >>> pred = torch.tensor([[0.0, 1.0], [2.0, 3.0]])
+        >>> target = torch.tensor([[3.0, 2.0], [1.0, 0.0]])
+        >>> peak_signal_noise_ratio(pred, target)
+        tensor(2.5527)
+
+    .. note::
+        Half precision is only support on GPU for this metric
+    """
+    if dim is None and reduction != "elementwise_mean":
+        rank_zero_warn(f"The `reduction={reduction}` will not have any effect when `dim` is None.")
+
+    if data_range is None:
+        if dim is not None:
+            # Maybe we could use `torch.amax(target, dim=dim) - torch.amin(target, dim=dim)` in PyTorch 1.7 to calculate
+            # `data_range` in the future.
+            raise ValueError("The `data_range` must be given when `dim` is not None.")
+
+        data_range = target.max() - target.min()
+    else:
+        data_range = tensor(float(data_range))
+    sum_squared_error, n_obs = _psnr_update(preds, target, dim=dim)
+    return _psnr_compute(sum_squared_error, n_obs, data_range, base=base, reduction=reduction)
+
+
 def psnr(
     preds: Tensor,
     target: Tensor,
@@ -101,6 +161,8 @@ def psnr(
 ) -> Tensor:
     """Computes the peak signal-to-noise ratio.
 
+        . deprecated:: v0.7
+        Use :function:torchmetrics.functional.psnr. Will be removed in v0.8.
     Args:
         preds: estimated signal
         target: groun truth signal
@@ -147,4 +209,8 @@ def psnr(
     else:
         data_range = tensor(float(data_range))
     sum_squared_error, n_obs = _psnr_update(preds, target, dim=dim)
+    warn(
+        "`psnr` was renamed to `peak_signal_noise_ratio` in v0.7 and it will be removed in v0.8",
+        DeprecationWarning,
+    )
     return _psnr_compute(sum_squared_error, n_obs, data_range, base=base, reduction=reduction)

torchmetrics/functional/regression/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from torchmetrics.functional.image.ms_ssim import multiscale_structural_similarity_index_measure  # noqa: F401
-from torchmetrics.functional.image.psnr import psnr  # noqa: F401
+from torchmetrics.functional.image.psnr import peak_signal_noise_ratio, psnr  # noqa: F401
 from torchmetrics.functional.image.ssim import ssim  # noqa: F401
 from torchmetrics.functional.regression.cosine_similarity import cosine_similarity  # noqa: F401
 from torchmetrics.functional.regression.explained_variance import explained_variance  # noqa: F401

torchmetrics/image/__init__.py

@@ -11,5 +11,5 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from torchmetrics.image.psnr import PSNR  # noqa: F401
+from torchmetrics.image.psnr import PSNR, PeakSignalNoiseRatio  # noqa: F401
 from torchmetrics.image.ssim import SSIM, MultiScaleStructuralSimilarityIndexMeasure  # noqa: F401

torchmetrics/image/psnr.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 from typing import Any, Optional, Sequence, Tuple, Union
+from warnings import warn
 
 import torch
 from torch import Tensor, tensor
@@ -21,7 +22,7 @@
 from torchmetrics.utilities import rank_zero_warn
 
 
-class PSNR(Metric):
+class PeakSignalNoiseRatio(Metric):
     r"""
     Computes `Computes Peak Signal-to-Noise Ratio`_ (PSNR):
 
@@ -56,11 +57,11 @@ class PSNR(Metric):
             If ``dim`` is not ``None`` and ``data_range`` is not given.
 
     Example:
-        >>> from torchmetrics import PSNR
-        >>> psnr = PSNR()
+        >>> from torchmetrics import PeakSignalNoiseRatio
+        >>> peak_signal_noise_ratio = PSNR()
         >>> preds = torch.tensor([[0.0, 1.0], [2.0, 3.0]])
         >>> target = torch.tensor([[3.0, 2.0], [1.0, 0.0]])
-        >>> psnr(preds, target)
+        >>> peak_signal_noise_ratio(preds, target)
         tensor(2.5527)
 
     .. note::
@@ -146,3 +147,76 @@ def compute(self) -> Tensor:
             sum_squared_error = torch.cat([values.flatten() for values in self.sum_squared_error])
             total = torch.cat([values.flatten() for values in self.total])
         return _psnr_compute(sum_squared_error, total, data_range, base=self.base, reduction=self.reduction)
+
+
+class PSNR(PeakSignalNoiseRatio):
+    """Peak Signal Noise Ratio (PSNR).
+
+    .. deprecated:: v0.7
+        Use :class:`torchmetrics.PeakSignalNoiseRatio`. Will be removed in v0.8.
+
+        .. math:: \text{PSNR}(I, J) = 10 * \\log_{10} \\left(\frac{\\max(I)^2}{\text{MSE}(I, J)}\right)
+
+        Where :math:`\text{MSE}` denotes the `mean-squared-error`_ function.
+
+        Args:
+            data_range:
+                the range of the data. If None, it is determined from the data (max - min).
+                The ``data_range`` must be given when ``dim`` is not None.
+            base: a base of a logarithm to use.
+            reduction: a method to reduce metric score over labels.
+
+                - ``'elementwise_mean'``: takes the mean (default)
+                - ``'sum'``: takes the sum
+                - ``'none'``: no reduction will be applied
+
+            dim:
+                Dimensions to reduce PSNR scores over, provided as either an integer or a list of integers. Default is
+                None meaning scores will be reduced across all dimensions and all batches.
+            compute_on_step:
+                Forward only calls ``update()`` and return None if this is set to False.
+            dist_sync_on_step:
+                Synchronize metric state across processes at each ``forward()``
+                before returning the value at the step.
+            process_group:
+                Specify the process group on which synchronization is called.
+
+        Raises:
+            ValueError:
+                If ``dim`` is not ``None`` and ``data_range`` is not given.
+
+        Example:
+            >>> from torchmetrics import PSNR
+            >>> peak_signal_noise_ratio = PSNR()
+            >>> preds = torch.tensor([[0.0, 1.0], [2.0, 3.0]])
+            >>> target = torch.tensor([[3.0, 2.0], [1.0, 0.0]])
+            >>> psnr(preds, target)
+            tensor(2.5527)
+
+        .. note::
+            Half precision is only support on GPU for this metric
+    """
+
+    min_target: Tensor
+    max_target: Tensor
+    higher_is_better = False
+
+    def __init__(
+        self,
+        data_range: Optional[float] = None,
+        base: float = 10.0,
+        reduction: str = "elementwise_mean",
+        dim: Optional[Union[int, Tuple[int, ...]]] = None,
+        compute_on_step: bool = True,
+        dist_sync_on_step: bool = False,
+        process_group: Optional[Any] = None,
+    ) -> None:
+        warn(
+            "`PSNR` was renamed to `PeakSignalNoiseRatio` in v0.7 and it will be removed in v0.8",
+            DeprecationWarning,
+        )
+        super().__init__(
+            compute_on_step=compute_on_step,
+            dist_sync_on_step=dist_sync_on_step,
+            process_group=process_group,
+        )