franc.evaluation.metrics

Methods of evaluation noise cancellation performance.

Attributes

Self

Classes

`EvaluationMetric`	Parent class for evaluation metrics
`EvaluationMetricScalar`	Parent class for evaluation metrics that yield a scalar value
`EvaluationMetricPlottable`	Parent class for evaluation metrics that provide a plotting feature
`RMSMetric`	The RMS of the residual signal
`MSEMetric`	The MSE of the residual signal
`RMetric`	Residual power ratio
`SqrtRMetric`	Square root of the residual power ratio
`BandwidthPowerMetric`	The signal power on a given frequency range
`PSDMetric`	Plots the PSD of the given signal
`ASDMetric`	Plots the ASD of the given signal.
`TimeSeriesMetric`	Plots the signal as a time series
`SpectrogramMetric`	Plots a spectrogram (waterfall diagram) for the residual signal

Functions

welch_multiple_sequences(arrays, nperseg, *args, **kwargs)

Apply scipy.signal.welch to a sequence of arrays

Module Contents

franc.evaluation.metrics.Self

franc.evaluation.metrics.welch_multiple_sequences(arrays, nperseg, *args, **kwargs)

Apply scipy.signal.welch to a sequence of arrays

Additional arguments are passed to the scipy Welch implementation. Spectra are combined with an average weighted by the array lengths. If sequences

Parameters:

arrays (collections.abc.Sequence[numpy.typing.NDArray] | numpy.typing.NDArray) – Sequence of arrays
nperseg – Length of FFT segments

Returns:

frequencies, spectrum mean, spectrum min, spectrum max

Return type:

tuple[numpy.typing.NDArray, numpy.typing.NDArray, numpy.typing.NDArray, numpy.typing.NDArray]

class franc.evaluation.metrics.EvaluationMetric(**kwargs)

Bases: abc.ABC

Parent class for evaluation metrics

applied = False: indicates whether data is available

prediction: collections.abc.Sequence[numpy.typing.NDArray] | numpy.typing.NDArray

dataset: franc.evaluation.dataset.EvaluationDataset

residual: collections.abc.Sequence[numpy.typing.NDArray]: Residual without the signal (=zero for perfect filter).

residual_signal: collections.abc.Sequence[numpy.typing.NDArray]: Residual including the signal (=signal for perfect filter).

parameters: dict

The parameters with which the metric was initialized.

Needed to re instantiate the filter during apply() and for hashing.

name: str

method_hash_value: bytes

unit = 'AU': unit of the target and prediction channels

static init_wrapper(func): A decorator for the __init__function Saves a hash value for the configuration

apply(prediction, dataset)

Apply this filter

Parameters:

prediction (collections.abc.Sequence[numpy.typing.NDArray] | numpy.typing.NDArray) –
dataset (franc.evaluation.dataset.EvaluationDataset) –

Return type:

Self

abstract result_full()

The raw data of the result

Return type:: tuple

property result: Any

The result of the metric evaluation

Return type:: Any

classmethod result_to_text(result_full)

String indicating the evaluation result

Parameters:: result_full (tuple[float | numpy.floating, Ellipsis]) – The return value of metric.result_full()
Return type:: str

property text: The text representation of the evaluation result

classmethod _file_hash()

Calculates a hash value based on the file in which this method was defined.

Return type:: bytes

property method_hash: bytes

A hash representing the configured metric as a bytes object

Return type:: bytes

property method_hash_str: str

A hash representing the configured metric as a base64 like string

Return type:: str

static result_full_wrapper(func)

A decorator for the result_full member function.

Raises an exception if result is accessed on an object that was not applied to data. Caches the result to prevent double calculation.

class franc.evaluation.metrics.EvaluationMetricScalar(**kwargs)

Bases: EvaluationMetric

Parent class for evaluation metrics that yield a scalar value

unit: str: unit of the target and prediction channels

property result: float

The raw data of the result

Return type:: float

static _format_float(number)

classmethod result_to_text(result_full)

String indicating the evaluation result

Parameters:: result_full (tuple[float | numpy.floating, Ellipsis]) –
Return type:: str

class franc.evaluation.metrics.EvaluationMetricPlottable(**kwargs)

Bases: EvaluationMetric

Parent class for evaluation metrics that provide a plotting feature

plot_path: str | pathlib.Path | None = None

classmethod result_to_text(result_full)

String indicating the evaluation result

Parameters:: result_full (tuple[float | numpy.floating, Ellipsis]) –
Return type:: str

abstract plot(ax)

Generate a result plot on the given axes object

Parameters:: ax (matplotlib.axes.Axes) –

save_plot(fname, figsize=(10, 4), tight_layout=True, dpi=200, replot=False)

Save the plot to a file

Parameters:

fname (str | pathlib.Path) – Output file name
figsize (tuple[int, int]) – A matplotlib figure size parameter
tight_layout (bool) – Whether to use matplotlib tight figure command
dpi (float) – Output figure dpi value
replot – If false, no new plot will be generated if a file with the same name already exists.

filename(context)

Generate a filename that includes the given context string

Parameters:: context (str) – This string is included in the generated filename
Return type:: str

class franc.evaluation.metrics.RMSMetric(**kwargs)

Bases: EvaluationMetricScalar

The RMS of the residual signal

name = 'Residual RMS'

result_full()

The raw data of the result

Return type:: tuple[numpy.floating | float, str]

classmethod result_to_text(result_full)

String indicating the evaluation result

Parameters:: result_full (tuple[float | numpy.floating, Ellipsis]) –
Return type:: str

class franc.evaluation.metrics.MSEMetric(**kwargs)

Bases: EvaluationMetricScalar

The MSE of the residual signal

name = 'Residual MSE'

apply(*args, **kwargs): Apply this filter

result_full()

The raw data of the result

Return type:: tuple[numpy.floating | float, str]

classmethod result_to_text(result_full)

String indicating the evaluation result

Parameters:: result_full (tuple[float | numpy.floating, Ellipsis]) –
Return type:: str

class franc.evaluation.metrics.RMetric(**kwargs)

Bases: EvaluationMetricScalar

Residual power ratio

name = 'R'

result_full()

The raw data of the result

Return type:: tuple[numpy.floating | float]

class franc.evaluation.metrics.SqrtRMetric(**kwargs)

Bases: RMetric

Square root of the residual power ratio

name = '√R'

result_full()

The raw data of the result

Return type:: tuple[numpy.floating | float]

class franc.evaluation.metrics.BandwidthPowerMetric(f_start, f_stop, n_fft=1024, window='hann')

Bases: EvaluationMetricScalar

The signal power on a given frequency range

The spectrum is calculated with welch on each sequence. An average weighted by the sequence length is used to combine spectra from the sequences. The closes bins to f_start and f_stop is chosen as the integration borders.

Parameters:

f_start (float) – The frequency at which the power integration starts
f_stop (float) – The frequency at which the power integration stops
n_fft (int) – Sample count per FFT block used by welch
window – The FFT window type

name = 'Residual power on frequency range'

f_start

f_stop

n_fft = 1024

window = 'hann'

result_full(): The raw data of the result

class franc.evaluation.metrics.PSDMetric(n_fft=1024, window='hann', logx=True, logy=True, show_target=True, show_target_minus_signal=True, show_signal=False, autoscale=False)

Bases: EvaluationMetricPlottable

Plots the PSD of the given signal

The spectrum is calculated with Welch on each sequence. An average weighted by the sequence length is used to combine spectra from the sequences. The closes bins to f_start and f_stop is chosen as the integration borders.

Parameters:

n_fft (int) – Sample count per FFT block used by Welch’s method
window (str) – FFT window type
logx (bool) – Logarithmic x scale
logy (bool) – Logarithmic y scale
show_target (bool) – If True, also show spectrum of the target channel
show_target_minus_signal (bool) – If True, also show spectrum of the target channel minus the signal
show_signal (bool) –
autoscale (bool) –

name = 'Power spectral density'

n_fft = 1024

window = 'hann'

logx = True

logy = True

show_target = True

show_target_minus_signal = True

show_signal = False

autoscale = False

do_asd = False

_welch_multiple_sequences(signal)

apply welch_multiple_sequences() with correct settings

Parameters:: signal (collections.abc.Sequence[numpy.typing.NDArray]) –

result_full()

The raw data of the result

Return type:: tuple[numpy.typing.NDArray, numpy.typing.NDArray, numpy.typing.NDArray, numpy.typing.NDArray]

_plot_channel(ax, signal, label, color=None, ls='-', zorder=10)

Plot spectrum of the signal onto the axes object

Parameters:

ax (matplotlib.axes.Axes) –
signal (collections.abc.Sequence[numpy.typing.NDArray]) –
label (str) –

plot(ax)

Plot to the given Axes object

Parameters:: ax (matplotlib.axes.Axes) –

class franc.evaluation.metrics.ASDMetric(*args, **kwargs)

Bases: PSDMetric

Plots the ASD of the given signal. For details, check the PSDMetric definition.

name = 'Amplitude spectral density'

do_asd = True

class franc.evaluation.metrics.TimeSeriesMetric(show_target=True, show_target_minus_signal=True, show_signal=False, residual_with_signal=True, start=0, stop=-1)

Bases: EvaluationMetricPlottable

Plots the signal as a time series

Parameters:

show_target (bool) – if True, display the target channel
show_target_minus_signal (bool) – if True, display the target channel minus the signal channel
start (int) – Start of the shown data as a sample index to the concatenated evaluation sequences.
stop (int) – Stop of the shown data as a sample index to the concatenated evaluation sequences.
show_signal (bool) –

name = 'Time series'

show_target = True

show_target_minus_signal = True

show_signal = False

residual_with_signal = True

start = 0

stop = -1

result_full()

The raw data of the result

Return type:: tuple[collections.abc.Sequence[numpy.typing.NDArray]]

plot(ax)

Plot to the given Axes object

Parameters:: ax (matplotlib.axes.Axes) –

class franc.evaluation.metrics.SpectrogramMetric(n_fft=4096, window='hann', with_signal=True, xlim=None, ylim=None, asd=True)

Bases: EvaluationMetricPlottable

Plots a spectrogram (waterfall diagram) for the residual signal

Parameters:

n_fft (int) – Sample count per FFT block used by Welch’s method
window (str) – FFT window type
with_signal (bool) –
xlim (tuple[float, float] | None) –
ylim (tuple[float, float] | None) –
asd (bool) –

name = 'Spectrogram'

n_fft = 4096

window = 'hann'

with_signal = True

xlim = None

ylim = None

asd = True

result_full()

The spectrogram and additional information :return: (spectrogram, spectrogram extent, figure_label)

The spectrogram extent is given in the format that matplotlib.pyplot.imshow requires.

Return type:: tuple[numpy.typing.NDArray, tuple[float, float, float, float], str]

classmethod result_to_text(result_full)

String indicating the evaluation result

Parameters:: result_full (tuple[float | numpy.floating, Ellipsis]) – The return value of metric.result_full()
Return type:: str

plot(ax)

Generate a result plot on the given axes object

Parameters:: ax (matplotlib.axes.Axes) –