rename peak_signal_noise_ratio (#732)

* psnr --> peak_signal_noise_ratio
* PSNR --> PeakSignalNoiseRatio
* backward compatibility
* docs

Co-authored-by: Jirka <jirka.borovec@seznam.cz>
Co-authored-by: Jirka Borovec <Borda@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -98,7 +98,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   * `torchmetrics.FBeta` -> `torchmetrics.FBetaScore`
 
 
-- Renamed pit metric: ([#737](https://github.com/PyTorchLightning/metrics/pull/737))
+- Renamed image metrics ([#732](https://github.com/PyTorchLightning/metrics/pull/732))
+  * `functional.psnr` -> `functional.peak_signal_noise_ratio`
+  * `PSNR` -> `PeakSignalNoiseRatio`
+
+
+- Renamed PIT metric: ([#737](https://github.com/PyTorchLightning/metrics/pull/737))
   * `torchmetrics.functional.pit` -> `torchmetrics.functional.permutation_invariant_training`
   * `torchmetrics.PIT` -> `torchmetrics.PermutationInvariantTraining`
 

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:PeakSignalNoiseRatio` 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
+from torchmetrics.image import 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)
         ]
     )
@@ -101,7 +101,7 @@ def test_psnr(self, preds, target, data_range, base, reduction, dim, sk_metric,
             ddp,
             preds,
             target,
-            PSNR,
+            PeakSignalNoiseRatio,
             partial(sk_metric, data_range=data_range, reduction=reduction, dim=dim),
             metric_args=_args,
             dist_sync_on_step=dist_sync_on_step,
@@ -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,29 +121,37 @@ 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,
+            PeakSignalNoiseRatio,
+            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,
+            PeakSignalNoiseRatio,
+            peak_signal_noise_ratio,
+            {"data_range": data_range, "base": base, "reduction": reduction, "dim": dim},
         )
 
 
 @pytest.mark.parametrize("reduction", ["none", "sum"])
 def test_reduction_for_dim_none(reduction):
     match = f"The `reduction={reduction}` will not have any effect when `dim` is None."
     with pytest.warns(UserWarning, match=match):
-        PSNR(reduction=reduction, dim=None)
+        PeakSignalNoiseRatio(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)
+        PeakSignalNoiseRatio(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

@@ -55,7 +55,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
@@ -150,6 +155,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
@@ -122,6 +122,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,7 +92,7 @@ def _psnr_update(
     return sum_squared_error, n_obs
 
 
-def psnr(
+def peak_signal_noise_ratio(
     preds: Tensor,
     target: Tensor,
     data_range: Optional[float] = None,
@@ -125,10 +126,10 @@ def psnr(
             If ``dim`` is not ``None`` and ``data_range`` is not provided.
 
     Example:
-        >>> from torchmetrics.functional import psnr
+        >>> 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]])
-        >>> psnr(pred, target)
+        >>> peak_signal_noise_ratio(pred, target)
         tensor(2.5527)
 
     .. note::
@@ -148,3 +149,28 @@ def psnr(
         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,
+    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.
+
+    .. deprecated:: v0.7
+        Use :func:torchmetrics.functional.psnr. Will be removed in v0.8.
+
+    Example:
+
+        >>> psnr(torch.tensor([[0.0, 1.0], [2.0, 3.0]]), torch.tensor([[3.0, 2.0], [1.0, 0.0]]))
+        tensor(2.5527)
+    """
+    warn(
+        "`psnr` was renamed to `peak_signal_noise_ratio` in v0.7 and it will be removed in v0.8",
+        DeprecationWarning,
+    )
+    return peak_signal_noise_ratio(preds, target, data_range, base, reduction, dim)

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,8 +57,8 @@ 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
+        >>> psnr = PeakSignalNoiseRatio()
         >>> 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)
@@ -146,3 +147,32 @@ 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.
+
+    Example:
+        >>> psnr = PSNR()
+        >>> psnr(torch.tensor([[0.0, 1.0], [2.0, 3.0]]), torch.tensor([[3.0, 2.0], [1.0, 0.0]]))
+        tensor(2.5527)
+    """
+
+    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__(data_range, base, reduction, dim, compute_on_step, dist_sync_on_step, process_group)