fusionlab.nn.components.AdaptiveQuantileLoss

class fusionlab.nn.components.AdaptiveQuantileLoss

Bases: Loss, NNLearner

Adaptive Quantile Loss layer that computes quantile loss for given quantiles [1].

The layer expects y_true of shape \((B, H, O)\), where B is batch size, H is horizon, and O is output dimension, and y_pred of shape \((B, H, Q, O)\), where Q is the number of quantiles if they are specified.

\[\text{QuantileLoss}(\hat{y}, y) = \max(q \cdot (y - \hat{y}),\, (q - 1) \cdot (y - \hat{y}))\]

The final loss is the mean across batch, time, quantiles, and output dimension.

Parameters:

quantiles (list of float, optional) – A list of quantiles used to compute quantile loss. If set to 'auto', defaults to [0.1, 0.5, 0.9]. If None, the loss returns 0.0 (no quantile loss).

Notes

For quantile regression, each quantile penalizes under- and over-estimates differently, encouraging a robust modeling of the distribution of possible outcomes.

call(`y_true`, `y_pred`, training=False)

Compute the quantile loss.

get_config()

Returns configuration for serialization.

from_config(`config`)

Creates a new instance from config dict.

Examples

>>> from fusionlab.nn.components import AdaptiveQuantileLoss
>>> import tensorflow as tf
>>> # Suppose y_true is (B, H, O)
... # y_pred is (B, H, Q, O)
>>> y_true = tf.random.normal((32, 10, 1))
>>> y_pred = tf.random.normal((32, 10, 3, 1))
>>> # Instantiate with custom quantiles
>>> aq_loss = AdaptiveQuantileLoss([0.2, 0.5, 0.8])
>>> # Forward pass (loss calculation)
>>> loss_value = aq_loss(y_true, y_pred)

See also

MultiObjectiveLoss

Can combine this quantile loss with an anomaly loss.

AnomalyLoss

Computes anomaly-based loss, complementary to quantile loss.

References

[1]

Lim, B., & Zohren, S. (2021). “Time-series forecasting with deep learning: a survey.” Philosophical Transactions of the Royal Society A, 379(2194), 20200209.

__init__(quantiles, name='AdaptiveQuantileLoss')

Initializes Loss class.

Parameters:

• reduction – Type of tf.keras.losses.Reduction to apply to loss. Default value is AUTO. AUTO indicates that the reduction option will be determined by the usage context. For almost all cases this defaults to SUM_OVER_BATCH_SIZE. When used under a tf.distribute.Strategy, except via Model.compile() and Model.fit(), using AUTO or SUM_OVER_BATCH_SIZE will raise an error. Please see this custom training [tutorial]( https://www.tensorflow.org/tutorials/distribute/custom_training) for more details.

• name – Optional name for the instance.

• quantiles (List[float] | None)

Methods

__init__(quantiles[, name])	Initializes Loss class.
call(y_true, y_pred)	Compute quantile loss.
from_config(config)	Creates a new instance from a config dict.
get_config()	Configuration for serialization.
get_params([deep])	Get the parameters for this learner.
help(**kwargs)
load(file_path[, format])	Load the learner's state from a specified file in the desired format.
save([file_path, format, overwrite, ...])	Save the learner's state to a specified file in the desired format.
set_params(**params)	Set the parameters of this learner.
summary()	Provide a summary of the learner's parameters.

Attributes

my_params

__init__(quantiles, name='AdaptiveQuantileLoss')

Initializes Loss class.

Parameters:

• reduction – Type of tf.keras.losses.Reduction to apply to loss. Default value is AUTO. AUTO indicates that the reduction option will be determined by the usage context. For almost all cases this defaults to SUM_OVER_BATCH_SIZE. When used under a tf.distribute.Strategy, except via Model.compile() and Model.fit(), using AUTO or SUM_OVER_BATCH_SIZE will raise an error. Please see this custom training [tutorial]( https://www.tensorflow.org/tutorials/distribute/custom_training) for more details.

• name – Optional name for the instance.

• quantiles (List[float] | None)

call(y_true, y_pred)

Compute quantile loss.

Parameters:

• y_true (tf.Tensor) – Ground truth of shape (B, H, O).

• y_pred (tf.Tensor) – Predicted values of shape (B, H, Q, O) if quantiles is not None.

• training (bool, optional) – Unused parameter, included for consistency. Defaults to False.

Returns:

A scalar representing the mean quantile loss. 0.0 if quantiles is None.

Return type:

tf.Tensor

get_config()

Configuration for serialization.

Returns:

Dictionary with ‘quantiles’.

Return type:

dict

classmethod from_config(config)

Creates a new instance from a config dict.

Parameters:

config (dict) – Configuration dictionary.

Returns:

A new instance of the layer.

Return type:

AdaptiveQuantileLoss

help(**kwargs)

my_params = AdaptiveQuantileLoss(quantiles, name='AdaptiveQuantileLoss')