[skip ci] add doctest for regression metrics (pytorch#2324)

Author: sdesrozis

ignite/contrib/metrics/regression/canberra_metric.py

@@ -37,18 +37,24 @@ class CanberraMetric(_BaseRegression):
     .. _`Botchkarev 2018`:
         https://arxiv.org/ftp/arxiv/papers/1809/1809.03006.pdf
 
-    .. testcode::
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
 
-            metric = CanberraMetric()
-            metric.attach(default_evaluator, 'canberra')
-            y_pred = torch.Tensor([[3.8], [9.9], [-5.4], [2.1]])
-            y_true = y_pred * 1.5
-            state = default_evaluator.run([[y_pred, y_true]])
-            print(state.metrics['canberra'])
+        .. testcode::
 
-    .. testoutput::
+                metric = CanberraMetric()
+                metric.attach(default_evaluator, 'canberra')
+                y_pred = torch.Tensor([[3.8], [9.9], [-5.4], [2.1]])
+                y_true = y_pred * 1.5
+                state = default_evaluator.run([[y_pred, y_true]])
+                print(state.metrics['canberra'])
+
+        .. testoutput::
+
+                0.8000...
 
-            0.8000...
     .. versionchanged:: 0.4.3
 
         - Fixed implementation: ``abs`` in denominator.

ignite/contrib/metrics/regression/fractional_absolute_error.py

@@ -34,18 +34,24 @@ class FractionalAbsoluteError(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
-    .. testcode::
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
 
-            metric = FractionalAbsoluteError()
-            metric.attach(default_evaluator, 'fractional_abs_error')
-            y_pred = torch.Tensor([[3.8], [9.9], [-5.4], [2.1]])
-            y_true = y_pred * 0.8
-            state = default_evaluator.run([[y_pred, y_true]])
-            print(state.metrics['fractional_abs_error'])
+        .. testcode::
 
-    .. testoutput::
+                metric = FractionalAbsoluteError()
+                metric.attach(default_evaluator, 'fractional_abs_error')
+                y_pred = torch.Tensor([[3.8], [9.9], [-5.4], [2.1]])
+                y_true = y_pred * 0.8
+                state = default_evaluator.run([[y_pred, y_true]])
+                print(state.metrics['fractional_abs_error'])
+
+        .. testoutput::
+
+                0.2222...
 
-            0.2222...
     .. versionchanged:: 0.4.5
         - Works with DDP.
     """

ignite/contrib/metrics/regression/fractional_bias.py

@@ -34,18 +34,23 @@ class FractionalBias(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
-    .. testcode::
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
 
-            metric = FractionalBias()
-            metric.attach(default_evaluator, 'fractional_bias')
-            y_pred = torch.Tensor([[3.8], [9.9], [5.4], [2.1]])
-            y_true = y_pred * 1.5
-            state = default_evaluator.run([[y_pred, y_true]])
-            print(state.metrics['fractional_bias'])
+        .. testcode::
 
-    .. testoutput::
+                metric = FractionalBias()
+                metric.attach(default_evaluator, 'fractional_bias')
+                y_pred = torch.Tensor([[3.8], [9.9], [5.4], [2.1]])
+                y_true = y_pred * 1.5
+                state = default_evaluator.run([[y_pred, y_true]])
+                print(state.metrics['fractional_bias'])
 
-            0.4000...
+        .. testoutput::
+
+                0.4000...
 
     .. versionchanged:: 0.4.5
         - Works with DDP.

ignite/contrib/metrics/regression/geometric_mean_absolute_error.py

@@ -34,18 +34,24 @@ class GeometricMeanAbsoluteError(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
-    .. testcode::
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
 
-            metric = GeometricMeanAbsoluteError()
-            metric.attach(default_evaluator, 'gmae')
-            y_pred = torch.Tensor([[3.8], [9.9], [-5.4], [2.1]])
-            y_true = y_pred * 1.5
-            state = default_evaluator.run([[y_pred, y_true]])
-            print(state.metrics['gmae'])
+        .. testcode::
 
-    .. testoutput::
+                metric = GeometricMeanAbsoluteError()
+                metric.attach(default_evaluator, 'gmae')
+                y_pred = torch.Tensor([[3.8], [9.9], [-5.4], [2.1]])
+                y_true = y_pred * 1.5
+                state = default_evaluator.run([[y_pred, y_true]])
+                print(state.metrics['gmae'])
+
+        .. testoutput::
+
+                2.2723...
 
-            2.2723...
     .. versionchanged:: 0.4.5
         - Works with DDP.
     """

ignite/contrib/metrics/regression/geometric_mean_relative_absolute_error.py

@@ -47,6 +47,24 @@ class GeometricMeanRelativeAbsoluteError(_BaseRegression):
         device: specifies which device updates are accumulated on. Setting the
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
+
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
+
+        .. testcode::
+
+            metric = GeometricMeanRelativeAbsoluteError()
+            metric.attach(default_evaluator, 'gmare')
+            y_true = torch.Tensor([0, 1, 2, 3, 4, 5])
+            y_pred = y_true * 0.75
+            state = default_evaluator.run([[y_pred, y_true]])
+            print(state.metrics['gmare'])
+
+        .. testoutput::
+
+            0.0...
     """
 
     @reinit__is_reduced

ignite/contrib/metrics/regression/manhattan_distance.py

@@ -33,6 +33,24 @@ class ManhattanDistance(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
+
+        .. testcode::
+
+            metric = ManhattanDistance()
+            metric.attach(default_evaluator, 'manhattan')
+            y_true = torch.Tensor([0, 1, 2, 3, 4, 5])
+            y_pred = y_true * 0.75
+            state = default_evaluator.run([[y_pred, y_true]])
+            print(state.metrics['manhattan'])
+
+        .. testoutput::
+
+            3.75...
+
     .. versionchanged:: 0.4.3
 
         - Fixed sklearn compatibility.

ignite/contrib/metrics/regression/maximum_absolute_error.py

@@ -34,6 +34,24 @@ class MaximumAbsoluteError(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
+
+        .. testcode::
+
+            metric = MaximumAbsoluteError()
+            metric.attach(default_evaluator, 'mae')
+            y_true = torch.Tensor([0, 1, 2, 3, 4, 5])
+            y_pred = y_true * 0.75
+            state = default_evaluator.run([[y_pred, y_true]])
+            print(state.metrics['mae'])
+
+        .. testoutput::
+
+            1.25...
+
     .. versionchanged:: 0.4.5
         - Works with DDP.
     """

ignite/contrib/metrics/regression/mean_absolute_relative_error.py

@@ -34,6 +34,24 @@ class MeanAbsoluteRelativeError(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
+
+        .. testcode::
+
+            metric = MeanAbsoluteRelativeError()
+            metric.attach(default_evaluator, 'mare')
+            y_true = torch.Tensor([1, 2, 3, 4, 5])
+            y_pred = y_true * 0.75
+            state = default_evaluator.run([[y_pred, y_true]])
+            print(state.metrics['mare'])
+
+        .. testoutput::
+
+            0.25...
+
     .. versionchanged:: 0.4.5
         - Works with DDP.
     """

ignite/contrib/metrics/regression/mean_error.py

@@ -33,6 +33,24 @@ class MeanError(_BaseRegression):
         device: specifies which device updates are accumulated on. Setting the
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
+
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
+
+        .. testcode::
+
+            metric = MeanError()
+            metric.attach(default_evaluator, 'me')
+            y_true = torch.Tensor([0, 1, 2, 3, 4, 5])
+            y_pred = y_true * 0.75
+            state = default_evaluator.run([[y_pred, y_true]])
+            print(state.metrics['me'])
+
+        .. testoutput::
+
+            0.625...
     """
 
     @reinit__is_reduced

ignite/contrib/metrics/regression/mean_normalized_bias.py

@@ -34,6 +34,24 @@ class MeanNormalizedBias(_BaseRegression):
             metric's device to be the same as your ``update`` arguments ensures the ``update`` method is
             non-blocking. By default, CPU.
 
+    Examples:
+        To use with ``Engine`` and ``process_function``, simply attach the metric instance to the engine.
+        The output of the engine's ``process_function`` needs to be in format of
+        ``(y_pred, y)`` or ``{'y_pred': y_pred, 'y': y, ...}``.
+
+        .. testcode::
+
+            metric = MeanNormalizedBias()
+            metric.attach(default_evaluator, 'mnb')
+            y_true = torch.Tensor([1, 2, 3, 4, 5])
+            y_pred = y_true * 0.75
+            state = default_evaluator.run([[y_pred, y_true]])
+            print(state.metrics['mnb'])
+
+        .. testoutput::
+
+            0.25...
+
     .. versionchanged:: 0.4.5
         - Works with DDP.
     """