franc.evaluation.signal_generation

Tools to generate test data and EvaluationDatasets

Attributes

`NDArrayF`
`NDArrayU`

Classes

TestDataGenerator

Generate simple test data for correlated noise mitigation techniques

Functions

`generate_wave_packet`(offset, width, amplitude, ...[, ...])	Generate a Gaussian wave packet. Time related parameters (width and frequency)
`generate_wave_packet_signal`(n_samples, n_wave_packets, ...)	Generate a signal consisting of wave packets with generate_wave_packet.

Module Contents

franc.evaluation.signal_generation.NDArrayF

franc.evaluation.signal_generation.NDArrayU

franc.evaluation.signal_generation.generate_wave_packet(offset, width, amplitude, frequency, phase, generation_width=10, peak_scaling=True)

Generate a Gaussian wave packet. Time related parameters (width and frequency) can be interpreted as number of samples or seconds at a sampling rate of 1 Hz.

The amplitude normalization is chosen so that the sum of squares of the samples is one, so that the amplitude defines a fixed total energy of the signal.

Parameters:

offset (float) – Timing of the wave packet (negative values shift the packet to the past)
width (float) – The standard deviation σ parameter of the hull curve
amplitude (float) – Amplitude of the signal
frequency (float) – Frequency of the sinusoidal signal component
phase (float) – Phase of the sinusoidal signal component in rad. Zero indicates that a maximum is in phase with the peak of the hull curve
generation_width (int) – How many samples to generate, indicated in multiples of the width parameter to one side. Example: width=5 and generation_width=10 will result in 2*5*10=100+1 samples total.
peak_scaling (bool) – If True, amplitude will determine the potential maximum value of the wave packet. If set to False, the wave packet will be scaled so that the sum of the squares of all samples is one.

Return type:

NDArrayF

>>> import franc
>>> franc.eval.signal_generation.generate_wave_packet(400, 100, 1, 0.02, 0)
array([-2.49881816e-53,  1.67054194e-40,  3.81228489e-40, ...,
       -1.79993484e-05, -8.54421912e-06, -1.88708852e-19],
      shape=(2001,))

The defining function for peak_scaling=False is:: sinusoidal = amplitude * np.sin(2 * np.pi * frequency * T + phase) * np.sqrt(2) * np.exp(-((T / width) ** 2) / 2) * np.sqrt(2 / np.pi / width)

franc.evaluation.signal_generation.generate_wave_packet_signal(n_samples, n_wave_packets, width_range, amplitude_range, frequency_range, rng, generation_width=10, peak_scaling=True, offset_range=None)

Generate a signal consisting of wave packets with generate_wave_packet. All values are generated based on uniform distributions with the given ranges.

Parameters:

n_samples (int) – Length of the generated sequence
n_wave_packets (int) – Number of generated wave packets
width_range (tuple[float, float]) – Tuple with lower and upper bound for width parameter
amplitude_range (tuple[float, float]) – Tuple with lower and upper bound for amplitude parameter
frequency_range (tuple[float, float]) – Tuple with lower and upper bound for frequency parameter
rng (numpy.random.Generator) – A numpy random number generator instance
generator_width – How many standard deviations of the hull curve will be generated per packet Higher numbers will increase calculation time
peak_scaling (bool) – Passed to generate_wave_packet()
offset_range (float | None) – The range of time offsets generated for the wave packets If no value is provided, width_range[1] is used.
generation_width (int) –

Returns:

Generated sequence, Sequence[(position, offset, width, amplitude, frequency, phase)] position: position measures in samples from the beginning of the generated sequence (integer) offset: offset of the packet relative to the position variable (float) width: width of the packet amplitude: amplitude of the packet frequency: frequency of the packet phase: phase of the packet

Return type:

tuple[NDArrayF, NDArrayF]

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