Base frequency loss

class ssp.keras.base_frequency_loss.FrequencyLossFunctionWrapper1D(fn, lowpass=None, f=None, f_filter=6.0, f_min=0.0, p=7.0, decay_start=0, decay_epochs=50, data_format='channels_last', reduction='sum_over_batch_size', name=None, **kwargs)

Bases: Loss

Base class FrequencyLossFunctionWrapper1D to implement new loss functions with the option to apply a frequency filter to the ground truth. This 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==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:

• fn (callable) – Definition of the loss function. The function has to accept two tensors (y_true and y_pred) and return a float.

• 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.

• **kwargs – Additional keyword arguments for fn.

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. See examples of SSP1D and SSP2D for a MWE.

apply_filter(real, imag)

Apply frequency filter

Parameters:

• real (KerasTensor) – real part of Fourier transform of signal y

• imag (KerasTensor) – imaginary part of Fourier transform of signal y

Returns:

y_real, y_imag – Fourier transform of signal y with f>f_filter set to (0 + 0j)

Return type:

(KerasTensor, KerasTensor)

call(y_true, y_pred)

Call method of FrequencyLossFunctionWrapper1D

Parameters:

• y_true (KerasTensor) – Ground truth

• y_pred (KerasTensor) – Prediction

Returns:

loss – The scalar loss calculated from y_true and y_pred using self.fn.

Return type:

KerasTensor

estimate_peak_frequency(power_spectrum)

Estimate peak frequency from spectrum

Parameters:

power_spectrum (KerasTensor) – power spectrum of ground truth

Returns:

peak_frequency – a tensor with shape==(batch_size,) with peak frequency (capped at self.f_min) for each sample

Return type:

KerasTensor

fftshift(x, axis=None)

shifts the FFT spectrum

Parameters:

• x (KerasTensor) – signal

• axis (int, optional) – axis to shift along. Defaults to None.

Returns:

x_shifted – fft-shifted version of x

Return type:

KerasTensor

classmethod from_config(config)

Restore loss function instance from config. Required for model serialization once a model compiled with loss function is saved with keras.Model.save() and loaded with keras.models.load_model().

Parameters:

• cls (FrequencyLossFunctionWrapper1D) – The class itself

• config (dict) – Dictionary holding the configuration of the loss function obtained from self.get_config()

Returns:

cls – An instance of FrequencyLossFunctionWrapper1D

Return type:

FrequencyLossFunctionWrapper1D

Notes

This function is never called by the user but internally by Keras. So don’t panic.

get_config()

Get config of loss function. Required for model serialization once a model compiled with this loss function is saved with keras.Model.save() and loaded with keras.models.load_model().

Returns:

config – Dictionary holding the configuration of the loss function.

Return type:

dict

get_f_hat(real, imag)

Normalize frequency range self.f by estimated peak frequency

Parameters:

• real (KerasTensor) – real part of Fourier transform of signal y

• imag (KerasTensor) – imaginary part of Fourier transform of signal y

Returns:

f_hat – frequency range normalized by estimated peak frequency

Return type:

KerasTensor

get_frequency_filter(real, imag)

The frequency filter is implemented as a hard binary window, which is multiplied with the Fourier spectrum. The window requires (1) the overall length (int), and (2) the length of the window, which is here given by the index where the filter frequency exceeds the frequency vector

The radius of the filter is calculated based on the frequency grid f and f_filter. The closest frequency component to f_filter is found by diff = abs(f - f_filter). The index of the minimum entry in diff is used to calculate the radius of the filter.

All calculations are performed on the positive quadrant of f. For the “adaptive filter”, the frequency spectrum scaled by the peak frequency is used.

Parameters:

• real (KerasTensor) – real part of Fourier transform of signal y

• imag (KerasTensor) – imaginary part of Fourier transform of signal y

Returns:

lowpass_filter – Binary lowpass filter with the same shape as y.

Return type:

KerasTensor

lowpass_decay(spectral_radius)

We want to have a linear decrease in spectral radius over the epochs, starting from full frequency range to spectral radius. The linear function is consequently given by s = int(spectral_radius + alpha*(s - spectral_radius)) where s is the spectral radius (depending on the training epoch), and alpha is the slope of linear function, i.e., (epoch - self.decay_start) / self.decay_epochs

Parameters:

spectral_radius (int) – Desired radius of the binary window.

Returns:

radius – Actual radius at self.epoch

Return type:

int

lowpass_fn(spectral_radius)

Lowpass function

Parameters:

spectral_radius (int) – Desired radius of the binary window.

Returns:

hard_lowpass – binary lowpass filter

Return type:

KerasTensor

static magnitude(real, imag)

Magnitude of signal

Parameters:

• real (KerasTensor) – real part of Fourier transform of signal y

• imag (KerasTensor) – imaginary part of Fourier transform of signal y

Returns:

magnitude – magnitude of spectrum

Return type:

KerasTensor

static tolist(arr)

Casts a KerasTensor to a list. Required for serialization of a KerasTensor.

Parameters:

arr (KerasTensor) – array to be casted to list

Returns:

l – arr as (nested) list

Return type:

list

Notes

Raises RuntimeError when torch backend is used.

transpose_to_channels_first(inputs)

Transpose input data to data format “channels_first”.

The FFT is by default applied along the last dimension of the data. Therefore, we have to transpose the data from “channels_last” (default) to “channels_first”

Parameters:

inputs (KerasTensor) – input tensor to transpose

Returns:

transposed_inputs – input tensor in data format “channels_first”

Return type:

KerasTensor

class ssp.keras.base_frequency_loss.FrequencyLossFunctionWrapper2D(fn, lowpass=None, f=None, f_filter=6.0, f_min=0.0, p=7.0, decay_start=0, decay_epochs=50, data_format='channels_last', reduction='sum_over_batch_size', name=None, **kwargs)

Bases: FrequencyLossFunctionWrapper1D

Base class FrequencyLossFunctionWrapper2D to implement new loss functions with the option to apply a frequency filter to the ground truth. This 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 2-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==None, the FFT calculation is skipped, and no f is required.

This class can thus be used directly in keras.Model.compile()

Parameters:

• fn (callable) – Definition of the loss function. The function has to accept two tensors (y_true and y_pred) and return a float.

• 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. A 1-D f is automatically casted to a 2-D grid. 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.

• **kwargs – Additional keyword arguments for fn.

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. See examples of SSP1D and SSP2D for a MWE.

expand_dims: callable

For the frequency range calculations (mainly estimation of filter size) only the positive frequency range is required! Here, f is a (potentially empty) 1D tensor!

fftshift(x)

FFT shift

shifts the FFT spectra along the last 2 axes

Parameters:

x (KerasTensor) – signal

Returns:

x_shifted – fft-shifted version of ‘x’

Return type:

KerasTensor

get_frequency_filter(real, imag)

The frequency filter is implemented as a hard binary window, which is multiplied with the Fourier spectrum. The window requires (1) the overall length (int), and (2) the length of the window, which is here given by the index where the filter frequency exceeds the frequency vector

The radius of the filter is calculated based on the frequency grid f and f_filter. The closest frequency component to f_filter is found by diff = abs(f - f_filter). The index of the minimum entry in diff is used to calculate the radius of the filter.

All calculations are performed on the positive quadrant of f. For the “adaptive filter”, the frequency spectrum scaled by the peak frequency is used.

Parameters:

• real (KerasTensor) – real part of Fourier transform of signal y

• imag (KerasTensor) – imaginary part of Fourier transform of signal y

Returns:

lowpass_filter – Binary lowpass filter with the same shape as y.

Return type:

KerasTensor

lowpass_decay(spectral_radius: int) → int

We want to have a linear decrease in spectral radius over the epochs, starting from full frequency range to spectral radius. The linear function is consequently given by s = int(spectral_radius + alpha*(s - spectral_radius)) with s: spectral radius(epoch) alpha: slope of linear function, i.e., (epoch - self.decay_start) / self.decay_epochs

Parameters:

spectral_radius (int) – Desired radius of the binary window.

Returns:

radius – Actual radius at self.epoch

Return type:

int

lowpass_fn(spectral_radius)

Lowpass function

Parameters:

spectral_radius (int) – Desired radius of the binary window.

Returns:

hard_lowpass – binary lowpass filter

Return type:

KerasTensor

transpose_to_channels_first(inputs)

Transpose input data to data format “channels_first”.

The FFT is by default applied along the last dimension of the data. Therefore, we have to transpose the data from “channels_last” (default) to “channels_first”

Parameters:

inputs (KerasTensor) – input tensor to transpose

Returns:

transposed_inputs – input tensor in data format “channels_first”

Return type:

KerasTensor