Extensive fixes in metrics docstrings.

PiperOrigin-RevId: 304917158
Change-Id: I60ccca4b1a13d75012a95f8d7a2f43fb17682c22

tensorflow/python/keras/losses.py

@@ -48,12 +48,14 @@ class Loss(object):
   * `call()`: Contains the logic for loss calculation using `y_true`, `y_pred`.
 
   Example subclass implementation:
+
   ```python
   class MeanSquaredError(Loss):
+
     def call(self, y_true, y_pred):
-      y_pred = ops.convert_to_tensor_v2(y_pred)
+      y_pred = tf.convert_to_tensor_v2(y_pred)
-      y_true = math_ops.cast(y_true, y_pred.dtype)
+      y_true = tf.cast(y_true, y_pred.dtype)
-      return K.mean(math_ops.square(y_pred - y_true), axis=-1)
+      return tf.reduce_mean(math_ops.square(y_pred - y_true), axis=-1)
   ```
 
   When used with `tf.distribute.Strategy`, outside of built-in training loops
@@ -259,7 +261,7 @@ class MeanSquaredError(LossFunctionWrapper):
 
   `loss = square(y_true - y_pred)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[1., 1.], [1., 0.]]
@@ -284,11 +286,10 @@ class MeanSquaredError(LossFunctionWrapper):
   >>> mse(y_true, y_pred).numpy()
   array([0.5, 0.5], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.MeanSquaredError())
-  model.compile('sgd', loss=tf.keras.losses.MeanSquaredError())
   ```
   """
 
@@ -319,7 +320,7 @@ class MeanAbsoluteError(LossFunctionWrapper):
 
   `loss = abs(y_true - y_pred)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[1., 1.], [1., 0.]]
@@ -344,11 +345,10 @@ class MeanAbsoluteError(LossFunctionWrapper):
   >>> mae(y_true, y_pred).numpy()
   array([0.5, 0.5], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.MeanAbsoluteError())
-  model.compile('sgd', loss=tf.keras.losses.MeanAbsoluteError())
   ```
   """
 
@@ -379,7 +379,7 @@ class MeanAbsolutePercentageError(LossFunctionWrapper):
 
   `loss = 100 * abs(y_true - y_pred) / y_true`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[2., 1.], [2., 3.]]
   >>> y_pred = [[1., 1.], [1., 0.]]
@@ -404,11 +404,11 @@ class MeanAbsolutePercentageError(LossFunctionWrapper):
   >>> mape(y_true, y_pred).numpy()
   array([25., 75.], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd',
-  model.compile('sgd', loss=tf.keras.losses.MeanAbsolutePercentageError())
+                loss=tf.keras.losses.MeanAbsolutePercentageError())
   ```
   """
 
@@ -440,7 +440,7 @@ class MeanSquaredLogarithmicError(LossFunctionWrapper):
 
   `loss = square(log(y_true + 1.) - log(y_pred + 1.))`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[1., 1.], [1., 0.]]
@@ -465,11 +465,11 @@ class MeanSquaredLogarithmicError(LossFunctionWrapper):
   >>> msle(y_true, y_pred).numpy()
   array([0.240, 0.240], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd',
-  model.compile('sgd', loss=tf.keras.losses.MeanSquaredLogarithmicError())
+                loss=tf.keras.losses.MeanSquaredLogarithmicError())
   ```
   """
 
@@ -507,7 +507,7 @@ class BinaryCrossentropy(LossFunctionWrapper):
   floating-pointing value, and both `y_pred` and `y_true` have the shape
   `[batch_size]`.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -535,8 +535,7 @@ class BinaryCrossentropy(LossFunctionWrapper):
   Usage with the `tf.keras` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.BinaryCrossentropy())
-  model.compile('sgd', loss=tf.keras.losses.BinaryCrossentropy())
   ```
   """
 
@@ -589,7 +588,7 @@ class CategoricalCrossentropy(LossFunctionWrapper):
   example. The shape of both `y_pred` and `y_true` are
   `[batch_size, num_classes]`.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0, 1, 0], [0, 0, 1]]
   >>> y_pred = [[0.05, 0.95, 0], [0.1, 0.8, 0.1]]
@@ -614,11 +613,10 @@ class CategoricalCrossentropy(LossFunctionWrapper):
   >>> cce(y_true, y_pred).numpy()
   array([0.0513, 2.303], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.CategoricalCrossentropy())
-  model.compile('sgd', loss=tf.keras.losses.CategoricalCrossentropy())
   ```
   """
 
@@ -671,7 +669,7 @@ class SparseCategoricalCrossentropy(LossFunctionWrapper):
   The shape of `y_true` is `[batch_size]` and the shape of `y_pred` is
   `[batch_size, num_classes]`.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [1, 2]
   >>> y_pred = [[0.05, 0.95, 0], [0.1, 0.8, 0.1]]
@@ -696,11 +694,11 @@ class SparseCategoricalCrossentropy(LossFunctionWrapper):
   >>> scce(y_true, y_pred).numpy()
   array([0.0513, 2.303], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd',
-  model.compile('sgd', loss=tf.keras.losses.SparseCategoricalCrossentropy())
+                loss=tf.keras.losses.SparseCategoricalCrossentropy())
   ```
   """
 
@@ -742,7 +740,7 @@ class Hinge(LossFunctionWrapper):
   `y_true` values are expected to be -1 or 1. If binary (0 or 1) labels are
   provided we will convert them to -1 or 1.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -767,11 +765,10 @@ class Hinge(LossFunctionWrapper):
   >>> h(y_true, y_pred).numpy()
   array([1.1, 1.5], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.Hinge())
-  model.compile('sgd', loss=tf.keras.losses.Hinge())
   ```
   """
 
@@ -802,7 +799,7 @@ class SquaredHinge(LossFunctionWrapper):
   `y_true` values are expected to be -1 or 1. If binary (0 or 1) labels are
   provided we will convert them to -1 or 1.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -827,11 +824,10 @@ class SquaredHinge(LossFunctionWrapper):
   >>> h(y_true, y_pred).numpy()
   array([1.46, 2.26], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.SquaredHinge())
-  model.compile('sgd', loss=tf.keras.losses.SquaredHinge())
   ```
   """
 
@@ -863,7 +859,7 @@ class CategoricalHinge(LossFunctionWrapper):
   `loss = maximum(neg - pos + 1, 0)`
   where `neg=maximum((1-y_true)*y_pred) and pos=sum(y_true*y_pred)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0, 1], [0, 0]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -888,11 +884,10 @@ class CategoricalHinge(LossFunctionWrapper):
   >>> h(y_true, y_pred).numpy()
   array([1.2, 1.6], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.CategoricalHinge())
-  model.compile('sgd', loss=tf.keras.losses.CategoricalHinge())
   ```
   """
 
@@ -923,7 +918,7 @@ class Poisson(LossFunctionWrapper):
 
   `loss = y_pred - y_true * log(y_pred)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[1., 1.], [0., 0.]]
@@ -948,11 +943,10 @@ class Poisson(LossFunctionWrapper):
   >>> p(y_true, y_pred).numpy()
   array([0.999, 0.], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.Poisson())
-  model.compile('sgd', loss=tf.keras.losses.Poisson())
   ```
   """
 
@@ -981,7 +975,7 @@ class LogCosh(LossFunctionWrapper):
   `logcosh = log((exp(x) + exp(-x))/2)`,
   where x is the error `y_pred - y_true`.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [0., 0.]]
   >>> y_pred = [[1., 1.], [0., 0.]]
@@ -1006,11 +1000,10 @@ class LogCosh(LossFunctionWrapper):
   >>> l(y_true, y_pred).numpy()
   array([0.217, 0.], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.LogCosh())
-  model.compile('sgd', loss=tf.keras.losses.LogCosh())
   ```
   """
 
@@ -1040,7 +1033,7 @@ class KLDivergence(LossFunctionWrapper):
 
   See: https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0, 1], [0, 0]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -1065,11 +1058,10 @@ class KLDivergence(LossFunctionWrapper):
   >>> kl(y_true, y_pred).numpy()
   array([0.916, -3.08e-06], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.KLDivergence())
-  model.compile('sgd', loss=tf.keras.losses.KLDivergence())
   ```
   """
 
@@ -1106,7 +1098,7 @@ class Huber(LossFunctionWrapper):
   ```
   where d is `delta`. See: https://en.wikipedia.org/wiki/Huber_loss
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0, 1], [0, 0]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -1131,11 +1123,10 @@ class Huber(LossFunctionWrapper):
   >>> h(y_true, y_pred).numpy()
   array([0.18, 0.13], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.Huber())
-  model.compile('sgd', loss=tf.keras.losses.Huber())
   ```
   """
 
@@ -1177,7 +1168,7 @@ def mean_squared_error(y_true, y_pred):
 
   `loss = mean(square(y_true - y_pred), axis=-1)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.randint(0, 2, size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1209,7 +1200,7 @@ def mean_absolute_error(y_true, y_pred):
 
   `loss = mean(abs(y_true - y_pred), axis=-1)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.randint(0, 2, size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1241,7 +1232,7 @@ def mean_absolute_percentage_error(y_true, y_pred):
 
   `loss = 100 * mean(abs(y_true - y_pred) / y_true, axis=-1)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.random(size=(2, 3))
   >>> y_true = np.maximum(y_true, 1e-7)  # Prevent division by zero
@@ -1277,7 +1268,7 @@ def mean_squared_logarithmic_error(y_true, y_pred):
 
   `loss = mean(square(log(y_true + 1) - log(y_pred + 1)), axis=-1)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.randint(0, 2, size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1325,7 +1316,7 @@ def squared_hinge(y_true, y_pred):
 
   `loss = mean(square(maximum(1 - y_true * y_pred, 0)), axis=-1)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.choice([-1, 1], size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1357,7 +1348,7 @@ def hinge(y_true, y_pred):
 
   `loss = mean(maximum(1 - y_true * y_pred, 0), axis=-1)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.choice([-1, 1], size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1389,7 +1380,7 @@ def categorical_hinge(y_true, y_pred):
   `loss = maximum(neg - pos + 1, 0)`
   where `neg=maximum((1-y_true)*y_pred) and pos=sum(y_true*y_pred)`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.randint(0, 3, size=(2,))
   >>> y_true = tf.keras.utils.to_categorical(y_true, num_classes=3)
@@ -1459,7 +1450,7 @@ def log_cosh(y_true, y_pred):
   like the mean squared error, but will not be so strongly affected by the
   occasional wildly incorrect prediction.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.random(size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1495,7 +1486,7 @@ def categorical_crossentropy(y_true,
                              label_smoothing=0):
   """Computes the categorical crossentropy loss.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0, 1, 0], [0, 0, 1]]
   >>> y_pred = [[0.05, 0.95, 0], [0.1, 0.8, 0.1]]
@@ -1532,7 +1523,7 @@ def categorical_crossentropy(y_true,
 def sparse_categorical_crossentropy(y_true, y_pred, from_logits=False, axis=-1):
   """Computes the sparse categorical crossentropy loss.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [1, 2]
   >>> y_pred = [[0.05, 0.95, 0], [0.1, 0.8, 0.1]]
@@ -1563,7 +1554,7 @@ def sparse_categorical_crossentropy(y_true, y_pred, from_logits=False, axis=-1):
 def binary_crossentropy(y_true, y_pred, from_logits=False, label_smoothing=0):
   """Computes the binary crossentropy loss.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0, 1], [0, 0]]
   >>> y_pred = [[0.6, 0.4], [0.4, 0.6]]
@@ -1610,7 +1601,7 @@ def kl_divergence(y_true, y_pred):
 
   See: https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.randint(0, 2, size=(2, 3)).astype(np.float64)
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1645,7 +1636,7 @@ def poisson(y_true, y_pred):
   The Poisson loss is the mean of the elements of the `Tensor`
   `y_pred - y_true * log(y_pred)`.
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = np.random.randint(0, 2, size=(2, 3))
   >>> y_pred = np.random.random(size=(2, 3))
@@ -1694,7 +1685,7 @@ def cosine_similarity(y_true, y_pred, axis=-1):
 
   `loss = -sum(l2_norm(y_true) * l2_norm(y_pred))`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [1., 1.], [1., 1.]]
   >>> y_pred = [[1., 0.], [1., 1.], [-1., -1.]]
@@ -1728,7 +1719,7 @@ class CosineSimilarity(LossFunctionWrapper):
 
   `loss = -sum(l2_norm(y_true) * l2_norm(y_pred))`
 
-  Usage:
+  Standalone usage:
 
   >>> y_true = [[0., 1.], [1., 1.]]
   >>> y_pred = [[1., 0.], [1., 1.]]
@@ -1758,11 +1749,10 @@ class CosineSimilarity(LossFunctionWrapper):
   >>> cosine_loss(y_true, y_pred).numpy()
   array([-0., -0.999], dtype=float32)
 
-  Usage with the `compile` API:
+  Usage with the `compile()` API:
 
   ```python
-  model = tf.keras.Model(inputs, outputs)
+  model.compile(optimizer='sgd', loss=tf.keras.losses.CosineSimilarity(axis=1))
-  model.compile('sgd', loss=tf.keras.losses.CosineSimilarity(axis=1))
   ```
 
   Args: