Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/tensorflow_addons/losses/quantiles.py: 60%

1# Copyright 2019 The TensorFlow Authors. All Rights Reserved. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14# ============================================================================== 

15"""Implements quantiles losses.""" 

16 

17import tensorflow as tf 

18from typeguard import typechecked 

19from tensorflow_addons.utils.keras_utils import LossFunctionWrapper 

20from tensorflow_addons.utils.types import TensorLike, FloatTensorLike 

21 

22 

23@tf.function 

24@tf.keras.utils.register_keras_serializable(package="Addons") 

25def pinball_loss( 

26 y_true: TensorLike, y_pred: TensorLike, tau: FloatTensorLike = 0.5 

27) -> tf.Tensor: 

28 """Computes the pinball loss between `y_true` and `y_pred`. 

29 

30 `loss = maximum(tau * (y_true - y_pred), (tau - 1) * (y_true - y_pred))` 

31 

32 In the context of regression this loss yields an estimator of the tau 

33 conditional quantile. 

34 

35 See: https://en.wikipedia.org/wiki/Quantile_regression 

36 

37 Usage: 

38 

39 >>> loss = tfa.losses.pinball_loss([0., 0., 1., 1.], 

40 ... [1., 1., 1., 0.], tau=.1) 

41 >>> loss 

42 <tf.Tensor: shape=(), dtype=float32, numpy=0.475> 

43 

44 Args: 

45 y_true: Ground truth values. shape = `[batch_size, d0, .. dN]` 

46 y_pred: The predicted values. shape = `[batch_size, d0, .. dN]` 

47 tau: (Optional) Float in [0, 1] or a tensor taking values in [0, 1] and 

48 shape = `[d0,..., dn]`. It defines the slope of the pinball loss. In 

49 the context of quantile regression, the value of tau determines the 

50 conditional quantile level. When tau = 0.5, this amounts to l1 

51 regression, an estimator of the conditional median (0.5 quantile). 

52 

53 Returns: 

54 pinball_loss: 1-D float `Tensor` with shape [batch_size]. 

55 

56 References: 

57 - https://en.wikipedia.org/wiki/Quantile_regression 

58 - https://projecteuclid.org/download/pdfview_1/euclid.bj/1297173840 

59 """ 

60 y_pred = tf.convert_to_tensor(y_pred) 

61 y_true = tf.cast(y_true, y_pred.dtype) 

62 

63 # Broadcast the pinball slope along the batch dimension 

64 tau = tf.expand_dims(tf.cast(tau, y_pred.dtype), 0) 

65 one = tf.cast(1, tau.dtype) 

66 

67 delta_y = y_true - y_pred 

68 pinball = tf.math.maximum(tau * delta_y, (tau - one) * delta_y) 

69 return tf.reduce_mean(pinball, axis=-1) 

70 

71 

72@tf.keras.utils.register_keras_serializable(package="Addons") 

73class PinballLoss(LossFunctionWrapper): 

74 """Computes the pinball loss between `y_true` and `y_pred`. 

75 

76 `loss = maximum(tau * (y_true - y_pred), (tau - 1) * (y_true - y_pred))` 

77 

78 In the context of regression, this loss yields an estimator of the tau 

79 conditional quantile. 

80 

81 See: https://en.wikipedia.org/wiki/Quantile_regression 

82 

83 Usage: 

84 

85 >>> pinball = tfa.losses.PinballLoss(tau=.1) 

86 >>> loss = pinball([0., 0., 1., 1.], [1., 1., 1., 0.]) 

87 >>> loss 

88 <tf.Tensor: shape=(), dtype=float32, numpy=0.475> 

89 

90 Usage with the `tf.keras` API: 

91 

92 >>> model = tf.keras.Model() 

93 >>> model.compile('sgd', loss=tfa.losses.PinballLoss(tau=.1)) 

94 

95 Args: 

96 tau: (Optional) Float in [0, 1] or a tensor taking values in [0, 1] and 

97 shape = `[d0,..., dn]`. It defines the slope of the pinball loss. In 

98 the context of quantile regression, the value of tau determines the 

99 conditional quantile level. When tau = 0.5, this amounts to l1 

100 regression, an estimator of the conditional median (0.5 quantile). 

101 reduction: (Optional) Type of `tf.keras.losses.Reduction` to apply to 

102 loss. Default value is `AUTO`. `AUTO` indicates that the reduction 

103 option will be determined by the usage context. For almost all cases 

104 this defaults to `SUM_OVER_BATCH_SIZE`. 

105 When used with `tf.distribute.Strategy`, outside of built-in training 

106 loops such as `tf.keras` `compile` and `fit`, using `AUTO` or 

107 `SUM_OVER_BATCH_SIZE` will raise an error. Please see 

108 https://www.tensorflow.org/alpha/tutorials/distribute/training_loops 

109 for more details on this. 

110 name: Optional name for the op. 

111 

112 References: 

113 - https://en.wikipedia.org/wiki/Quantile_regression 

114 - https://projecteuclid.org/download/pdfview_1/euclid.bj/1297173840 

115 """ 

116 

117 @typechecked 

118 def __init__( 

119 self, 

120 tau: FloatTensorLike = 0.5, 

121 reduction: str = tf.keras.losses.Reduction.AUTO, 

122 name: str = "pinball_loss", 

123 ): 

124 super().__init__(pinball_loss, reduction=reduction, name=name, tau=tau)