franc.evaluation

Tooling to automate evaluation of filtering techniques on datasets.

Submodules

Classes

`EvaluationDataset`	A representation of a dataset for the evaluation of noise mitigation methods.
`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
`MSEMetric`	The MSE of the residual signal
`RMSMetric`	The RMS 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
`EvaluationRun`	Representation of an evaluation run
`TestDataGenerator`	Generate simple test data for correlated noise mitigation techniques
`ReportElement`	Parent class for elements placed in a report object that generate latex code
`FilterInterface`	common interface definition for Filter implementations

Functions

`rms`(a)	Calculate the root mean square value of an array
`total_power`(a)	calculate the total power of a signal (square or RMS)
`residual_power_ratio`(target, prediction[, start, ...])	Calculate the ratio between residual power of the residual and the target signal
`residual_amplitude_ratio`(args, *kwargs)	Calculate the ratio between residual amplitude of the residual and the target signal
`measure_runtime`(filter_classes[, n_samples, ...])	Measure the runtime of filers for a specific scenario
`make_2d_array`(A)	add a dimension to 1D arrays and leave 2D arrays as they are
`handle_from_dict`(init_func)	A decorator for the init functions of classes derived from FitlerInterface

Package Contents

franc.evaluation.rms(a)

Calculate the root mean square value of an array

Parameters:: a (collections.abc.Sequence[float] | numpy.typing.NDArray[numpy.floating]) –
Return type:: float

franc.evaluation.total_power(a)

calculate the total power of a signal (square or RMS)

>>> import franc, numpy
>>> signal = numpy.ones(10) * 2
>>> franc.evaluation.total_power(signal)
4.0

Parameters:: a (collections.abc.Sequence[float] | numpy.typing.NDArray[numpy.floating]) –
Return type:: float

class franc.evaluation.EvaluationDataset(sample_rate, witness_conditioning, target_conditioning, witness_evaluation, target_evaluation, signal_conditioning=None, signal_evaluation=None, name='Unnamed', target_unit='1', supplementary_data=None)

A representation of a dataset for the evaluation of noise mitigation methods.

Provided sequences will be stored as immutable float64 numpy arrays.

Parameters:

sample_rate (float) – Sample rate in Hz
witness_conditioning (collections.abc.Sequence[collections.abc.Sequence[NDArrayF]]) – witness channel data for the conditioning format: witness_conditioning[sequence_idx][channel_idx][sample_idx]
target_conditioning (collections.abc.Sequence[NDArrayF]) – target channel data for the conditioning format: witness_conditioning[sequence_idx][sample_idx]
witness_evaluation (collections.abc.Sequence[collections.abc.Sequence[NDArrayF]]) – witness channel data for the evaluation
target_evaluation (collections.abc.Sequence[NDArrayF]) – target channel data for the evaluation
signal_conditioning (collections.abc.Sequence[NDArrayF] | None) – (Optional) A signal that can be subtracted from the target for performance metrics
signal_evaluation (collections.abc.Sequence[NDArrayF] | None) – (Optional) A signal that can be subtracted from the target for performance metrics
name (str) – (Optional) a string describing the dataset
supplementary_data (dict | None) – (Optional) A dict with additional data passed to the evaluation metrics Must be hashable (only common python built-in types and numpy arrays are allowed)
target_unit (str) –

sample_rate: float

witness_conditioning: collections.abc.Sequence[collections.abc.Sequence[NDArrayF]]

target_conditioning: collections.abc.Sequence[NDArrayF]

witness_evaluation: collections.abc.Sequence[collections.abc.Sequence[NDArrayF]]

target_evaluation: collections.abc.Sequence[NDArrayF]

signal_conditioning: collections.abc.Sequence[NDArrayF] | None

signal_evaluation: collections.abc.Sequence[NDArrayF] | None

name: str

target_unit: str

supplementary_data: dict

static _prepare_dataset(witness_inp, target_inp, signal_inp=None)

Convert input to immutable np.float64 arrays and check shape

Parameters:

witness_inp (collections.abc.Sequence[collections.abc.Sequence[NDArrayF]]) –
target_inp (collections.abc.Sequence[NDArrayF]) –
signal_inp (collections.abc.Sequence[NDArrayF] | None) –

Return type:

tuple[collections.abc.Sequence[collections.abc.Sequence[NDArrayF]], collections.abc.Sequence[NDArrayF], collections.abc.Sequence[NDArrayF] | None]

property channel_count: int

Number of witness channels

Return type:: int

property has_signal: bool

Indicates whether the dataset has a signal channel

Return type:: bool

sequence_lengths(which)

Returns the lengths of the evaluation or conditioning sequences

Parameters:: which (str) – A string selecting which sequence will be analyzed. Must be one of the following values: “cond”, “conditioning”, “eval”, or “evaluation”.
Return type:: list[int]

get_min_sequence_len(separate=False)

Get the length of the shortest sequence in the dataset

Parameters:: separate (bool) – If True, returns the minimum separately for conditioning and evaluation data.
Return type:: int | tuple[int, int]

static _hash_wts_data(witness, target, signal=None)

Calculate a hash value for a set of witness, target, signal data

Parameters:

witness (collections.abc.Sequence[collections.abc.Sequence[NDArrayF]]) –
target (collections.abc.Sequence[NDArrayF]) –
signal (collections.abc.Sequence[NDArrayF] | None) –

hash_bytes()

return a hash over the dataset data as a bytes object

Return type:: bytes

hash_str()

return a hash over the dataset data as a string

Return type:: str

__hash__()

Return type:: int

description()

Generate a description of the dataset

Return type:: str

class franc.evaluation.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.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.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.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.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.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.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.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.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.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.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.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) –

class franc.evaluation.EvaluationRun(method_configurations, dataset, optimization_metric, metrics=None, name='unnamed', directory='.', figsize=(10, 4))

Representation of an evaluation run

Parameters:

method_configurations (collections.abc.Sequence[tuple[type[franc.evaluation.filter_interface.FilterInterface], collections.abc.Sequence]]) – A list of tuples with the following format [(filter_technique, [{‘n_filter’: 1024, ..}, ..]), ..]
dataset (franc.evaluation.dataset.EvaluationDataset) – An EvaluationDataset instance
optimization_metric (franc.evaluation.metrics.EvaluationMetricScalar) – The optimization metric by which the optimum is selected
metrics (collections.abc.Sequence[franc.evaluation.metrics.EvaluationMetric] | None) – All metrics which will be exported
name (str) – (optional) name of the evaluation run
directory (str) – (optional) the directory in which results are saved If results are saved, the required folder structure will be created
figsize (tuple[float, float]) –

multi_sequence_support = True

method_configurations

dataset

optimization_metric

metrics = []

name = 'unnamed'

directory

figsize = (10, 4)

all_configurations_list: list | None = None

_check_method_configurations(method_configurations)

Throw meaningful errors for problems with the configurations

Parameters:: method_configurations (collections.abc.Sequence[tuple[type[franc.evaluation.filter_interface.FilterInterface], collections.abc.Sequence]]) –
Return type:: bool

get_all_configurations()

Returns a list of all unique (filter_technique, configuration) pairs.

Return type:: list

_create_folder_structure()

Create standardized folder structure for results

Return type:: None

static save_np_array_list(data, filename)

Save a list of numpy arrays to a .npz file

Parameters:

data (collections.abc.Sequence[collections.abc.Sequence[NDArrayF]] | collections.abc.Sequence[NDArrayF] | NDArrayF) –
filename (str | pathlib.Path) –

Return type:

None

static load_np_array_list(filename)

Load a list of numpy arrays from a .npz file

Parameters:: filename (str | pathlib.Path) –
Return type:: collections.abc.Sequence[NDArrayF]

static software_version_report()

generate a list of strings indicating the important software versions

Return type:: list[str]

static platform_info_report()

generate a list of strings indicating platform information (cpu, OS, ..)

Return type:: list[str]

generate_overview_plots(results)

Generate overview plots Returns a Report section with the generated plot

Parameters:: results (list[tuple[type[franc.evaluation.filter_interface.FilterInterface], list]]) –

generate_parameter_scan_plots(results)

Generate a plot of the optimization_metric values over all varied parameters Returns a report section with the generated plots

Parameters:: results (list[tuple[type[franc.evaluation.filter_interface.FilterInterface], list[tuple[dict, numpy.typing.NDArray, franc.evaluation.metrics.EvaluationMetricScalar, list[franc.evaluation.metrics.EvaluationMetric], str]]]]) –
Return type:: list[list[franc.evaluation.report_generation.ReportFigure]]

generate_report(results, compile_report=False, report_type=LatexReport)

Generate a report for the given results object from run()

Parameters:

results (list[tuple[type[franc.evaluation.filter_interface.FilterInterface], list]]) –
compile_report (bool) –
report_type (type[franc.evaluation.report_generation.LatexReport] | type[franc.evaluation.report_generation.HTMLReport]) –

get_prediction(filter_technique, conf)

Load the prediction created by applying the given filter and configuration to the dataset

Parameters:

filter_technique (type[franc.evaluation.filter_interface.FilterInterface]) –
conf (dict[str, Any]) –

Return type:

tuple[collections.abc.Sequence[numpy.typing.NDArray] | numpy.typing.NDArray, str, str]

run()

Execute the evaluation run

Returns:: list of (Prediction, optimization_metric, other_metrics) objects
Return type:: list[tuple[type[franc.evaluation.filter_interface.FilterInterface], list]]

hash_str()

returns a hash over the dataset and filtering configurations as a string

Return type:: str

franc.evaluation.residual_power_ratio(target, prediction, start=None, stop=None, remove_dc=True)

Calculate the ratio between residual power of the residual and the target signal

Parameters:

target (collections.abc.Sequence) – target signal array
prediction (collections.abc.Sequence) – prediction array (same length as target
start (int | None) – use only a section of the arrays, start at this index
stop (int | None) – use only a section of the arrays, stop at this index
remove_dc (bool) – if true, the mean is subtracted from each array to remove the DC component before the calculations

Return type:

float

franc.evaluation.residual_amplitude_ratio(*args, **kwargs)

Calculate the ratio between residual amplitude of the residual and the target signal

Parameters:

target – target signal array
prediction – prediction array (same length as target
start – use only a section of the arrays, start at this index
stop – use only a section of the arrays, stop at this index
component (remove DC) – remove DC component before calculation

Return type:

float

franc.evaluation.measure_runtime(filter_classes, n_samples=int(10000.0), n_channel=1, n_filter=128, idx_target=0, additional_filter_settings=None, repititions=1)

Measure the runtime of filers for a specific scenario Be aware that this gives no feedback upon how much multithreading is used!

Parameters:

n_samples (int) – Length of the test data
n_channel (int) – Number of witness sensor channels
n_filter (int) – Length of the FIR filters / input block size
idx_target (int) – Position of the prediction
additional_filter_settings (collections.abc.Sequence[dict[str, Any]] | None) – optional settings passed to the filters
repititions (int) – how many repititions to perform during the timing measurement
filter_classes (collections.abc.Sequence[franc.evaluation.filter_interface.FilterInterface]) –

Returns:

(time_conditioning, time_apply) each in seconds

Return type:

tuple[collections.abc.Sequence, collections.abc.Sequence]

class franc.evaluation.TestDataGenerator(witness_noise_level=0.1, target_noise_level=0, transfer_function=1, sample_rate=1.0, rng_seed=None)

Generate simple test data for correlated noise mitigation techniques The channel count is implicitly defined by the shape of witness_noise_level

Parameters:

witness_noise_level (float | collections.abc.Sequence) – Amplitude ratio of the sensor noise to the correlated noise in the witness sensor
target_noise_level (float) – Amplitude ratio of the sensor noise Scalar or 1D-vector for multiple sensors to the correlated noise in the target sensor
transfer_function (float) – Ratio between the amplitude in the target and witness signals
sample_rate (float) – The outputs are referenced to an ASD of 1/sqrt(Hz) if a sample rate is provided
rng_seed (int | None) – Optional value to generate the dataset based on a fixed seed for reproducible results. If not set, the randomly seeded global numpy rng is used.

>>> import franc as fnc
>>> # create data with two witness sensors with relative noise amplitudes of 0.1
>>> tdg = fnc.evaluation.TestDataGenerator(witness_noise_level=[0.1, 0.1])
>>> # generate a dataset with 1000 samples
>>> witness, target = tdg.generate(1000)
>>> witness.shape, target.shape
((2, 1000), (1000,))

rng: Any

witness_noise_level

target_noise_level

transfer_function

sample_rate = 1.0

scaled_whitenoise(shape)

Generate white noise with an ASD of one

Parameters:: shape – shape of the new array
Returns:: Array of white noise
Return type:: NDArrayF

generate(n)

Generate sequences of samples

Parameters:: n (int) – number of samples
Returns:: witness signal, target signal
Return type:: tuple[NDArrayF, NDArrayF]

generate_multiple(n)

Generate sequences of samples

Parameters:: n (collections.abc.Sequence[int] | NDArrayU) – Tuple with the length of the sequences
Returns:: witness signals, target signals
Return type:: tuple[collections.abc.Sequence, collections.abc.Sequence]

dataset(n_condition, n_evaluation, generate_signal=False, signal_amplitude=1.0, sample_rate=1.0, name=None)

Generate an EvaluationDataset

Parameters:

n_condition (collections.abc.Sequence[int] | numpy.typing.NDArray[numpy.uint]) – Sequence of integers indicating the number of conditioning samples generated per sample sequence
n_evaluation (collections.abc.Sequence[int] | numpy.typing.NDArray[numpy.uint]) – Number of evaluation samples
sample_rate (float) – (Optional) Sample rate for the generate EvaluationDataset
name (str | None) – (Optional) Specify the name of the EvaluationDataset
generate_signal (bool) –
signal_amplitude (float) –

Return type:

franc.evaluation.dataset.EvaluationDataset

Example: >>> # generate two sequences of 100 samples each of conditioning data and one 100 sample sequence of evaluation data >>> import franc as fnc >>> ds = fnc.evaluation.TestDataGenerator().dataset((100, 100), (100,))

class franc.evaluation.ReportElement

Bases: abc.ABC

Parent class for elements placed in a report object that generate latex code

abstract latex()

Generate latex code

Return type:: str

abstract html()

Generate latex code

Return type:: str

class franc.evaluation.FilterInterface(n_channel, _from_dict=None)

Bases: abc.ABC

common interface definition for Filter implementations

Parameters:: n_channel (int) – Number of witness sensor channels

requires_apply_target: bool

n_channel: int

method_hash_value: bytes

supports_multi_sequence = True

filter_name = 'FilterInterface'

default_args = [None]

static supports_saving_loading()

Indicates whether saving and loading is supported Due to the way dataclasses work with inheritance, class values with default values don’t work in the parent dataclass. Thus, this is a function

Return type:: bool

condition(witness, target)

Use an input dataset to condition the filter

Parameters:

witness (collections.abc.Sequence | collections.abc.Sequence[collections.abc.Sequence] | numpy.typing.NDArray) – Witness sensor data
target (collections.abc.Sequence | numpy.typing.NDArray) – Target sensor data

abstract condition_multi_sequence(witness, target)

Similar to condition(), but expects multiple sequences

First index to the given data objects indicates the sequence. The last index indicates the time within a single sequence. Sequences must not have the same length.

Parameters:

witness (collections.abc.Sequence | collections.abc.Sequence[collections.abc.Sequence] | numpy.typing.NDArray) –
target (collections.abc.Sequence | numpy.typing.NDArray) –

Return type:

Any

apply(witness, target=None, pad=True, update_state=False)

Apply the filter to a single sequence of input data

Parameters:

witness (collections.abc.Sequence | numpy.typing.NDArray) – Witness sensor data (1D or 2D array)
target (collections.abc.Sequence | numpy.typing.NDArray | None) – Target sensor data (1D array)
pad (bool) – if True, apply padding zeros so that the length matches the target signal
update_state (bool) – if True, the filter state will be changed. If false, the filter state will remain

Returns:

prediction

Return type:

numpy.typing.NDArray

abstract apply_multi_sequence(witness, target, pad=True, update_state=False)

Apply the filter to multiple sequences of input data.

Similar to apply() but expects multiple sequences. First index to the given data objects indicates the sequence. The last index indicates the time within a single sequence. Sequences must not have the same length.

Parameters:

witness (collections.abc.Sequence | numpy.typing.NDArray) –
target (collections.abc.Sequence | numpy.typing.NDArray | None) –
pad (bool) –
update_state (bool) –

Return type:

collections.abc.Sequence[numpy.typing.NDArray]

check_data_dimensions(witness, target=None)

Check the dimensions of the provided input data and apply make_2d_array()

Parameters:

witness (collections.abc.Sequence | numpy.typing.NDArray) – Witness sensor data
target (collections.abc.Sequence | numpy.typing.NDArray | None) – Target sensor data

Returns:

data as (target, witness)

Raises:

AssertionError

Return type:

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

check_data_dimensions_multi_sequence(witness: collections.abc.Sequence | numpy.typing.NDArray, target: None) → tuple[list[numpy.typing.NDArray], None]

check_data_dimensions_multi_sequence(witness: collections.abc.Sequence | numpy.typing.NDArray, target: collections.abc.Sequence | numpy.typing.NDArray) → tuple[list[numpy.typing.NDArray], list[numpy.typing.NDArray]]

Check the dimensions of the provided input data and apply make_2d_array()

Parameters:

witness – Witness sensor data
target – Target sensor data

Returns:

data as (target, witness)

Raises:

AssertionError

as_dict()

Returns a dictionary that represents the state of this filter.

Return type:: dict[str, Any]

classmethod from_dict(input_dict)

Create a filter instance from a dictionary that was created from as_dict()

Parameters:: input_dict (dict[str, Any]) –
Return type:: FilterTypeT

classmethod make_filename(filename)

Append the file type of save files for this class to the given filename, if it is not already present

Parameters:: filename (str | pathlib.Path) –

save(filename, warn_incompatible=False)

Save the filter state as a numpy file

The given filename will be autocompleted with a “.<filter_name>.npz” filename extension, unless a matching extension is detected.

warn_incompatible: set to True to warn for object types might not: compatible with np.save(allow_pickle=False) during development

Parameters:

filename (str | pathlib.Path) –
warn_incompatible (bool) –

classmethod load(filename)

Load a filter state from the supplied filename.

The given filename will be autocompleted with a “.<filter_name>.npz” filename extension, unless a matching extension is detected.

Return type:: FilterTypeT

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 of the method and parameters NOTE: This is not a hash of the conditioned filter! Thus, the same filter configuration applied to a different dataset will result in the same hash!

Return type:: bytes

property method_filename_part: str

string that can be used in a file name

Return type:: str

franc.evaluation.make_2d_array(A)

add a dimension to 1D arrays and leave 2D arrays as they are This is intended to allow 1D array input for single channel application

Parameters:: A (collections.abc.Sequence | collections.abc.Sequence[collections.abc.Sequence] | numpy.typing.NDArray) – input array
Returns:: extended array
Raises:: ValueError if the input shape is not compatible
Return type:: numpy.typing.NDArray

>>> import franc as fnc
>>> fnc.evaluation.make_2d_array([1, 2])
array([[1, 2]])

>>> import franc as fnc
>>> fnc.evaluation.make_2d_array([[1, 2], [3, 4]])
array([[1, 2],
       [3, 4]])

franc.evaluation.handle_from_dict(init_func)

A decorator for the init functions of classes derived from FitlerInterface

If the _from_dict keyword argument is passed, the __init__() function is ignored and the class is initialized based on the passed dictionary. Otherwise, the constructor is called the usual way.

Parameters:: init_func (collections.abc.Callable) –