Add doc-string examples (#66)

* Add doc-string examples

* Revert API files

* Improve loss doc-strings

Author: abheesht17

keras_rs/src/layers/feature_interaction/dot_interaction.py

@@ -30,6 +30,53 @@ class DotInteraction(keras.layers.Layer):
             but is much slower.
         **kwargs: Args to pass to the base class.
 
+    Example:
+
+    ```python
+    # 1. Simple forward pass
+    batch_size = 2
+    embedding_dim = 32
+    feature1 = np.random.randn(batch_size, embedding_dim)
+    feature2 = np.random.randn(batch_size, embedding_dim)
+    feature3 = np.random.randn(batch_size, embedding_dim)
+    feature_interactions = keras_rs.layers.DotInteraction()(
+        [feature1, feature2, feature3]
+    )
+
+    # 2. After embedding layer in a model
+    vocabulary_size = 32
+    embedding_dim = 6
+
+    # Create a simple model containing the layer.
+    feature_input_1 = keras.Input(shape=(), name='indices_1', dtype="int32")
+    feature_input_2 = keras.Input(shape=(), name='indices_2', dtype="int32")
+    feature_input_3 = keras.Input(shape=(), name='indices_3', dtype="int32")
+    x1 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(feature_input_1)
+    x2 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(feature_input_2)
+    x3 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(feature_input_3)
+    feature_interactions = keras_rs.layers.DotInteraction()([x1, x2, x3])
+    output = keras.layers.Dense(units=10)(x2)
+    model = keras.Model(
+        [feature_input_1, feature_input_2, feature_input_3], output
+    )
+
+    # Call the model on the inputs.
+    batch_size = 2
+    f1 = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    f2 = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    f3 = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    outputs = model([f1, f2, f3])
+    ```
+
     References:
     - [M. Naumov et al.](https://arxiv.org/abs/1906.00091)
     """

keras_rs/src/layers/feature_interaction/feature_cross.py

@@ -57,13 +57,32 @@ class FeatureCross(keras.layers.Layer):
     Example:
 
     ```python
-    # after embedding layer in a functional model
-    input = keras.Input(shape=(), name='indices', dtype="int64")
-    x0 = keras.layers.Embedding(input_dim=32, output_dim=6)(x0)
-    x1 = FeatureCross()(x0, x0)
-    x2 = FeatureCross()(x0, x1)
+    # 1. Simple forward pass
+    batch_size = 2
+    embedding_dim = 32
+    feature1 = np.random.randn(batch_size, embedding_dim)
+    feature2 = np.random.randn(batch_size, embedding_dim)
+    crossed_features = keras_rs.layers.FeatureCross()(feature1, feature2)
+
+    # 2. After embedding layer in a model
+    vocabulary_size = 32
+    embedding_dim = 6
+
+    # Create a simple model containing the layer.
+    inputs = keras.Input(shape=(), name='indices', dtype="int32")
+    x0 = keras.layers.Embedding(
+        input_dim=vocabulary_size,
+        output_dim=embedding_dim
+    )(inputs)
+    x1 = keras_rs.layers.FeatureCross()(x0, x0)
+    x2 = keras_rs.layers.FeatureCross()(x0, x1)
     logits = keras.layers.Dense(units=10)(x2)
-    model = keras.Model(input, logits)
+    model = keras.Model(inputs, logits)
+
+    # Call the model on the inputs.
+    batch_size = 2
+    input_data = np.random.randint(0, vocabulary_size, size=(batch_size,))
+    outputs = model(input_data)
     ```
 
     References:

keras_rs/src/losses/pairwise_hinge_loss.py

@@ -19,9 +19,69 @@ def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
         `y_i > y_j`.
 """
 extra_args = ""
+example = """
+    1. With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseHingeLoss(),
+        ...
+    )
+    ```
+
+    2. As a standalone function:
+    2.1. Unbatched inputs
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss()
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    2.32000
+
+    2.2 Batched inputs
+    2.2.1 Using default 'auto'/'sum_over_batch_size' reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss()
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    0.75
+
+    2.2.2. With masked inputs (useful for ragged inputs)
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    0.64999
+
+    2.2.3 With `sample_weight`
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss()
+    >>> pairwise_hinge_loss(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    1.02499
+
+    2.2.4 Using `'none'` reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_hinge_loss = keras_rs.losses.PairwiseHingeLoss(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_hinge_loss(y_true=y_true, y_pred=y_pred)
+    [[3. , 0. , 2. , 0.], [0., 0.20000005, 0.79999995, 0.]]
+"""
+
 PairwiseHingeLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="hinge loss",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/losses/pairwise_logistic_loss.py

@@ -28,9 +28,69 @@ def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
         ideal step function, making it suitable for gradient-based optimization.
 """
 extra_args = ""
+example = """
+    1. With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseLogisticLoss(),
+        ...
+    )
+    ```
+
+    2. As a standalone function:
+    2.1. Unbatched inputs
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss()
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    >>> 1.70708
+
+    2.2 Batched inputs
+    2.2.1 Using default 'auto'/'sum_over_batch_size' reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss()
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    0.73936
+
+    2.2.2. With masked inputs (useful for ragged inputs)
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    0.53751
+
+    2.2.3 With `sample_weight`
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss()
+    >>> pairwise_logistic_loss(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    >>> 0.80337
+
+    2.2.4 Using `'none'` reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_logistic_loss = keras_rs.losses.PairwiseLogisticLoss(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_logistic_loss(y_true=y_true, y_pred=y_pred)
+    [[2.126928, 0., 1.3132616, 0.48877698], [0., 0.20000005, 0.79999995, 0.]]
+"""
+
 PairwiseLogisticLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="logistic loss",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/losses/pairwise_loss.py

@@ -154,5 +154,7 @@ def get_config(self) -> dict[str, Any]:
             `"float32"` unless set to different value
             (via `keras.backend.set_floatx()`). If a `keras.DTypePolicy` is
             provided, then the `compute_dtype` will be utilized.
-    """
+
+    Examples:
+{example}"""
 )

keras_rs/src/losses/pairwise_mean_squared_error.py

@@ -64,9 +64,69 @@ def compute_unreduced_loss(
         predicted order of items relative to their true order.
 """
 extra_args = ""
+example = """
+    1. With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseMeanSquaredError(),
+        ...
+    )
+    ```
+
+    2. As a standalone function:
+    2.1. Unbatched inputs
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError()
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    >>> 19.10400
+
+    2.2 Batched inputs
+    2.2.1 Using default 'auto'/'sum_over_batch_size' reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError()
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    5.57999
+    
+    2.2.2. With masked inputs (useful for ragged inputs)
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    4.76000
+
+    2.2.3 With `sample_weight`
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError()
+    >>> pairwise_mse(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    11.0500
+
+    2.2.4 Using `'none'` reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_mse = keras_rs.losses.PairwiseMeanSquaredError(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_mse(y_true=y_true, y_pred=y_pred)
+    [[11., 17.,  5.,  5.], [2.04, 1.3199998, 1.6399999, 1.6399999]]
+"""
+
 PairwiseMeanSquaredError.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="mean squared error",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )

keras_rs/src/losses/pairwise_soft_zero_one_loss.py

@@ -24,9 +24,72 @@ def pairwise_loss(self, pairwise_logits: types.Tensor) -> types.Tensor:
         suitable for gradient-based optimization.
 """
 extra_args = ""
+example = """
+    1. With `compile()` API:
+
+    ```python
+    model.compile(
+        loss=keras_rs.losses.PairwiseSoftZeroOneLoss(),
+        ...
+    )
+    ```
+
+    2. As a standalone function:
+    2.1. Unbatched inputs
+    >>> y_true = np.array([1.0, 0.0, 1.0, 3.0, 2.0])
+    >>> y_pred = np.array([1.0, 3.0, 2.0, 4.0, 0.8])
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss()
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    0.86103
+
+    2.2 Batched inputs
+    2.2.1 Using default 'auto'/'sum_over_batch_size' reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss()
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    0.46202
+
+    2.2.2. With masked inputs (useful for ragged inputs)
+    >>> y_true = {
+    ...     "labels": np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]]),
+    ...     "mask": np.array(
+    ...         [[True, True, True, True], [True, True, False, False]]
+    ...     ),
+    ... }
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    0.29468
+
+    2.2.3 With `sample_weight`
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> sample_weight = np.array(
+    ...     [[2.0, 3.0, 1.0, 1.0], [2.0, 1.0, 0.0, 0.0]]
+    ... )
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss()
+    >>> pairwise_soft_zero_one_loss(
+    ...     y_true=y_true, y_pred=y_pred, sample_weight=sample_weight
+    ... )
+    0.40478
+
+    2.2.4 Using `'none'` reduction.
+    >>> y_true = np.array([[1.0, 0.0, 1.0, 3.0], [0.0, 1.0, 2.0, 3.0]])
+    >>> y_pred = np.array([[1.0, 3.0, 2.0, 4.0], [1.0, 1.8, 2.0, 3.0]])
+    >>> pairwise_soft_zero_one_loss = keras_rs.losses.PairwiseSoftZeroOneLoss(
+    ...     reduction="none"
+    ... )
+    >>> pairwise_soft_zero_one_loss(y_true=y_true, y_pred=y_pred)
+    [
+        [0.8807971 , 0., 0.73105854, 0.43557024],
+        [0., 0.31002545, 0.7191075 , 0.61961967]
+    ]
+"""
+
 PairwiseSoftZeroOneLoss.__doc__ = pairwise_loss_subclass_doc_string.format(
     loss_name="soft zero-one loss",
     formula=formula,
     explanation=explanation,
     extra_args=extra_args,
+    example=example,
 )