SSP1D

class ssp.keras.loss_functions.SSP1D(lowpass=None, f=None, f_filter=6, f_min=0, p=7, decay_epochs=50, decay_start=0, data_format='channels_last', reduction='sum_over_batch_size', name=None)[source]

Bases: FrequencyLossFunctionWrapper1D

Surface Similarity Parameter for 1-D signals with an optional lowpass filter. The frequency filter helps the model to focus on the relevant frequency range without the need to, e.g., remove HF noise in additional preprocessing steps.

There are two lowpass filters to choose from, the “static” and the “adaptive” lowpass. The “static” lowpass defines a global cut-off frequency at f_filter. The “adaptive” lowpass analyzes the ground truth data, extracts the peak frequency, and sets a dynamic cut-off frequency at for each sample. The parameter f_filter becomes a multiplier for the peak frequency, after which the frequency components are suppressed.

The definition of a lowpass {“static”, “adaptive”} requires a frequency range f. It enables an additional step in the loss calculation, where (1) the ground truth is transformed via 1-D FFT, (2) a hard binary lowpass filter is applied to the Fourier spectrum to set all frequencies f>f_filter to (0+0j), (3) the filtered ground truth is transformed back to its initial space.

If lowpass is None, the FFT calculation is skipped, and no f is required.

This class inherits from keras.losses.Loss and can thus be used directly in keras.Model.compile()

Parameters:

  • lowpass (str, optional {None, “static”, “adaptive”}) – Lowpass filter that is applied to the ground truth in order to suppress the higher frequency range f>f_filter. Defaults to None.

  • f (KerasTensor, optional) – Frequency range for the data. Is required once a lowpass {“static”, “adaptive”} is used. Defaults to None.

  • f_filter (float, optional) – Threshold for the lowpass filter. With the static lowpass, the ground truth spectrum is set to 0+j0 for f>f_filter. With the adaptive lowpass, the ground truth spectrum is set to 0+j0 for f>f_filter*f_p, where f_p is the peak frequency that is automatically derived from the ground truth spectrum. Defaults to 6.0.

  • f_min (float, optional) – Cap for the lowest peak frequency for cases when the automatic estimation of the peak frequency fails (estimated f_p<0 or f_p is Nan). Defaults to 0.0.

  • p (float, optional) – Exponent to weigh the spectrum towards the peak frequency (for the estimation of the peak frequency), c.f. Mansard & Funke, “On the fitting of parametric models to measured wave spectra” (1988), and Sobey & Young, “Hurricane Wind Waves—A discrete spectral model” (1986), https://ascelibrary.org/doi/10.1061/%28ASCE%290733-950X%281986%29112%3A3%28370%29. Defaults to 7.0.

  • decay_start (int, optional) – Epoch from which on the lowpass filter is linearly decreased from 0 to f_filter. Defaults to 0. Requires `UseLossLowpassDecay` callback to work, cf. Notes

  • decay_epochs (int, optional) – Number of epochs over which the lowpass filter is linearly decreased from 0 to f_filter. Defaults to 50. Requires `UseLossLowpassDecay` callback to work, cf. Notes

  • data_format (str, optional {“channels_last”, “channels_first”}) – The ordering of the dimensions in the inputs: “channels_last” corresponds to inputs with shape (batch_size, *dims, channels), “channels_first” corresponds to inputs with shape (batch_size, channels, *dims). Defaults to “channels_last”.

  • reduction (str, optional {“sum_over_batch_size”, None, “auto”, “sum”}) – Type of reduction to apply to the loss. In almost all cases this should be “sum_over_batch_size”. Supported options are “sum”, “sum_over_batch_size” or None.

  • name (str, optional) – Name of the loss function. The name is inhereted from class name if name=None. Defaults to None.

Notes

Both the “adaptive” and “static” lowpass filter can be linearly increased from 0 to f_filter over decay_epoch epochs, starting at epoch decay_start. For this to work, the training has to be conducted using the UseLossLowpassDecay callback, which sets the class variable self.epoch to the current training epoch.

Examples

>>> from ssp.keras import SSP1D
>>> from keras import ops
>>> from math import pi
>>> t = ops.arange(0, 2 * pi, 2 * pi / 512)
>>> y1 = ops.sin(t)
>>> y2 = ops.sin(t + pi / 16)  # sin with phase shift
>>> ssp = SSP1D()
>>> ops.convert_to_numpy(ssp(y1, y2))
array(0.09801717, dtype=float32)

Usage in an ML training

>>> from ssp.keras import SSP1D
>>> from keras import ops, Sequential, layers
>>> from math import pi
>>> t = ops.arange(0, 2 * pi, 2 * pi / 512)
>>> y = ops.expand_dims(ops.sin(t), axis=0)  # shape (1, 512)
>>> x = ops.ones((1, 32))  # some input data with shape (1, 32)
>>> model = Sequential([layers.Dense(64), layers.Dense(512)])
>>> model.build(input_shape=x.shape)
>>> model.compile(optimizer="adam", loss=SSP1D())
>>> model.fit(x=x, y=y, epochs=1)

Usage in an ML training with static lowpass (note that the lowpass does not make sense since we have a harmonic sine as input)

>>> from ssp.keras import SSP1D
>>> from ssp.keras.ops import fftfreq
>>> from keras import ops, Sequential, layers
>>> from math import pi
>>> t = ops.arange(0, 2 * pi, 2 * pi / 512)
>>> f = fftfreq(n=512, d=2 * pi / 512)
>>> y = ops.expand_dims(ops.sin(t), axis=0)  # shape (1, 512)
>>> x = ops.ones((1, 32))  # some input data with shape (1, 32)
>>> model = Sequential([layers.Dense(64), layers.Dense(512)])
>>> model.build(input_shape=x.shape)
>>> model.compile(optimizer="adam", loss=SSP1D(lowpass="static", f=f, f_filter=2.0))
>>> model.fit(x=x, y=y, epochs=1)

Usage in an ML training with adaptive lowpass (note that the lowpass does not make sense since we have a harmonic sine as input)

>>> from ssp.keras import SSP1D
>>> from ssp.keras.ops import fftfreq
>>> from keras import ops, Sequential, layers
>>> from math import pi
>>> t = ops.arange(0, 2 * pi, 2 * pi / 512)
>>> f = fftfreq(n=512, d=2 * pi / 512)
>>> y = ops.expand_dims(ops.sin(t), axis=0)  # shape (1, 512)
>>> x = ops.ones((1, 32))  # some input data with shape (1, 32)
>>> model = Sequential([layers.Dense(64), layers.Dense(512)])
>>> model.build(input_shape=x.shape)
>>> model.compile(optimizer="adam", loss=SSP1D(lowpass="adaptive", f=f, f_filter=6.0))
>>> model.fit(x=x, y=y, epochs=1)

Usage in an ML training with adaptive lowpass and decay callback (note that the lowpass does not make sense since we have a harmonic sine as y)

>>> from ssp.keras import SSP1D
>>> from ssp.keras.callbacks import UseLossLowpassDecay
>>> from ssp.keras.ops import fftfreq
>>> from keras import ops, Sequential, layers
>>> from math import pi
>>> t = ops.arange(0, 2 * pi, 2 * pi / 512)
>>> f = fftfreq(n=512, d=2 * pi / 512)
>>> y = ops.expand_dims(ops.sin(t), axis=0)  # shape (1, 512)
>>> x = ops.ones((1, 32))  # some input data with shape (1, 32)
>>> model = Sequential([layers.Dense(64), layers.Dense(512)])
>>> model.build(input_shape=x.shape)
>>> model.compile(optimizer="adam", loss=SSP1D(lowpass="adaptive", f=f, f_filter=6.0, decay_start=0, decay_epochs=5))
>>> model.fit(x=x, y=y, epochs=10, callbacks=[UseLossLowpassDecay()])
call(y_true, y_pred)[source]

Call method of SSP1D

Parameters:

  • y_true (KerasTensor) – Ground truth signal

  • y_pred (KerasTensor) – Predicted signal

Returns:

y – Surface Similarity Parameter between arrays y_true and y_pred. The shape is determined by self.reduction.

Return type:

KerasTensor

Notes

The call method of FrequencyLossFunctionWrapper1D is overwritten, since with the SSP, we can remain in frequency domain and omit the ifft. Magically, it is the same result if the SSP is applied in time- or frequency domain!