Utilities

class haskoning_atr_tools.signal_processing_tool.utils.plot.LegendHandler(legend: Legend = None, orig_handle: Line2D = None, fontsize: float = 10, handle_box: Legend = None)

Bases: object

Custom legend handler for matplotlib plots.

static legend_artist(legend: Legend, orig_handle: Line2D, fontsize: float, handlebox: OffsetBox) → Line2D

Method to create a custom legend artist.

Input:

• legend (Legend): The legend instance.

• orig_handle (Line2D): The original line handle.

• fontsize (float): The font size for the legend.

• handlebox (Legend): The handle box for the legend.

Output:

• Returns the custom line for the legend.

haskoning_atr_tools.signal_processing_tool.utils.plot.bar_plot_function(x_values: List[float], y_values: List[List[float]], labels: List[str], title: str, x_label: str, y_label: str, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | str | None = None, show: bool = True, bar_width: float = 1, show_bar_values: bool = True, decimals_displayed: int = 2) → Path | None

Generic function for plotting in the Signal Processing Tool for grouped bar graph with given x and y values.

Input:

• x_values (list of lists of floats): The x-coordinates of the bars.

• y_values (list of lists of floats): The heights of the bars for each group.

• labels (list of str): The labels for each group of bars.

• title (str): The title of the plot.

• x_label (str): The label for the x-axis.

• y_label (str): The label for the y-axis.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• bar_width (float): The width of the bars. Default value is 1.

• show_bar_values (bool): Select to display the labels on the bars. Default value is True.

• decimals_displayed (int): The number of decimal places for formatting values. Default value is 2.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

haskoning_atr_tools.signal_processing_tool.utils.plot.get_frequency_ban_level_units(level_type: str, amplitude_units: str, x_units: str) → str

Function to get the units for frequency band levels based on the level type.

Input:

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

• amplitude_units (str): The units of the amplitude (e.g., ‘m/s^2’, ‘N’, etc.).

• x_units (str): The units of the x-axis (e.g., ‘s’, ‘Hz’, etc.).

Output:

• Returns the string for plotting the units of the frequency band levels.

haskoning_atr_tools.signal_processing_tool.utils.plot.handle_plot_saving(file: Path | str | None, title: str) → Path

Generic function to handle saving the plot to a file.

haskoning_atr_tools.signal_processing_tool.utils.plot.plot_function(x_values: List[List[float]], y_values: List[List[float]], labels: List[str], title: str, x_label: str, y_label: str, log_scale_x: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | str | None = None, show: bool = True, line_width: float = 1, plot_max_values: bool = False, horizontal_line: float | None = None) → Path | None

Generic function for plotting in the Signal Processing Tool for function with the given x and y values.

Input:

• x_values (list of lists of floats): The x-coordinates of the points on the plot.

• y_values (list of lists of floats): The y-coordinates of the points on the plot.

• labels (list of str): The labels for the data series.

• title (str): The title of the plot.

• x_label (str): The label for the x-axis.

• y_label (str): The label for the y-axis.

• log_scale_x (bool): Select to set the x-axis to a logarithmic scale. Default value is False.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• line_width (float): Change line width, default = 1.

• plot_max_values (bool): Select to calculate the maximum y value for each line and add it to the plot. Default value is False.

• horizontal_line (float): Optional input to draw a horizontal line at this y-value. Default value is None.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

haskoning_atr_tools.signal_processing_tool.utils.plot.plot_signal_composition(time_domain: Tuple[List[float], List[float]], frequency_domain: Tuple[List[float], List[float]], significant_amplitudes: List[Tuple[float, float, float]], log_scale_frequency: bool = False, file: Path | str | None = None, show: bool = True) → Path | None

This function creates a 3D plot of the signal composition.

Input:

• time_domain (tuple of 2 lists of floats): Tuple containing time stamps and amplitudes of the time signal.

• frequency_domain (tuple of 2 lists of floats): Tuple containing frequencies and amplitudes of the frequency domain signal.

• significant_amplitudes (list of tuples with 3 floats): List of tuples containing significant amplitudes, frequencies, and phase angles.

• log_scale_frequency (bool): Select to set the frequency axis to a logarithmic scale. Default value is False.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

haskoning_atr_tools.signal_processing_tool.utils.utils.get_sbr_vibration_limit(building_function: str, time_of_day: str, limit_type: str) → float

Retrieves the SRB vibration limit based on building function, time of day, and limit type.

Input:

• building_function (str): The function of the building. Select from ‘residential’, ‘healthcare’, ‘meeting’, ‘office’, or ‘critical’.

• time_of_day (str): Select the time of day: ‘day’, or ‘night’.

• limit_type (str): Select the type of limit: ‘A1’, ‘A2’, or ‘A3’.

Output:

• Returns the vibration limit value.

haskoning_atr_tools.signal_processing_tool.utils.utils.read_columns_from_file(file: str | Path, skip_rows: int, columns: list, delimiter: str = ',') → list[list[float]]

This function reads the specified columns from a file (csv or xlsx-file).

Input:

• file (Path or str): The file path to the data file.

• skip_rows (int): The number of rows to skip at the beginning of the file.

• columns (list): The names or indices of the columns to read.

• delimiter (str): The delimiter used in the csv-file. Default is ‘,’.

Output:

• Returns a list of lists, each containing the data from the specified columns. Order according the requested columns to be read.

haskoning_atr_tools.signal_processing_tool.utils.utils.write_data_to_file(folder_path: str, file_name: str, data: list[list[float]], columns_header: list, column_numbers: list, skip_rows: int = 0, file_type: str = 'csv') → Path

Writes specified columns to a file (CSV or Excel).

Input:

• folder_path (str): The path to the folder.

• file_name (str): The name of the file.

• data (list[list[float]]): The data to write, each sublist representing a column.

• columns_header (list): The names of the columns.

• column_numbers (list): The column numbers to write the data into.

• skip_rows (int): The number of rows to skip at the beginning of the file.

• file_type (str): The type of the file (‘csv’ or ‘xlsx’). Defaults to ‘csv’.

Output:

• Returns the path of the created csv- or xlsx-file.

Time domain tools

class haskoning_atr_tools.signal_processing_tool.time_domain.data.TimeDomainData(parent: TimeDomainCollection, name: str, amplitude_type: str, amplitudes: ~typing.List[float] = <factory>, amplitude_units: str = 'Unknown units', time_stamps: ~typing.List[float] = <factory>, time_stamps_units: str = 'Unknown units', sbr_b_rms: ~typing.List[float] = <factory>)

Bases: object

The TimeDomainData class represents individual time domain data sets.

Input:

• parent (TimeDomainCollection): The parent collection that this data belongs to.

• name (str): The name of the time domain data.

• amplitude_type (str): The type of the time domain data. Example: ‘velocity, acceleration, pressure’.

• amplitudes (list of float): List of amplitude values for the time domain data. Initialised as empty list.

• time_stamps (list of float): List of time stamps corresponding to the amplitude values. Initialised as empty list.

• amplitude_units (str): The units of the amplitude values. Defaults to ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults to ‘Unknown units’.

apply_filter_to_signal(highpass_limit: float | None = None, lowpass_limit: float | None = None, gpass: float = 1, gstop: float = 5, override: bool = True, name: str | None = None, collection_name: str | None = None) → Self

This method applies a highpass and/or lowpass filter to the time domain data based on the provided parameters.

Input:

• highpass_limit (float): The highpass limit for the filter. If None, by default, no highpass filter is applied.

• lowpass_limit (float): The lowpass limit for the filter. If None, by default, no lowpass filter is applied.

• gpass (float): The maximum loss in the passband (in dB). Default is 1.

• gstop (float): The minimum attenuation in the stopband (in dB). Default is 5.

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

• name (str): The name for the new TimeDomainData object if override is False. If None, use the original name.

• collection_name (str, optional): The collection name for the new TimeDomainData object if override is False. If None, use the original collection name.

Output:

• Returns the filtered time domain data object.

check_time_domain(check_average: bool = True, check_ft_suitability: bool = True, check_noise: bool = True) → bool

Perform various checks on the signal to ensure it is suitable for further processing.

Input:

• check_average (bool): Select to check if the signal has an average of more than 1/10 the biggest amplitude. Default value True.

• check_ft_suitability (bool): Select to check if the signal is suitable for Fourier Transform. By checking if time_stamps are constant, if the signal is periodic and the signal is stationary. Default value True.

• check_noise (bool): Select to check if the signal has noise (variance is significantly different from zero). Default value True.

Output:

• Warnings are raised if the checked criteria are not met.

combine_time_domains(other_time_domain_list: List[Self], override: bool = True) → Self

Method to combine the amplitudes of this TimeDomainData with a list of other TimeDomainData.

Input:

• other_time_domain_list (list of obj): List of other time domain data to combine with.

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

Output:

• Returns the combined time domain data object.

convert_to_frequency_domain(window_type: str | None = None, highpass_limit: float = None, lowpass_limit: float = None, gpass: float = 1, gstop: float = 5, calibrate: bool = True, normalise_length: bool = True, name: str = None, collection_name: str = None) → FrequencyDomainData

Create frequency domain data from the time domain data. This method applies a filter to the time domain data, normalises to the signal length, performs a Fast Fourier Transform (FFT) on the time domain data, and creates a new FrequencyDomainData object with the transformed data.

Input:

• window_type (str): Select the type of window to apply to the signal before FFT. Default value is None, in which case no window is applied (same as applying ‘Rectangular’ window).

• highpass_limit (float): The high-pass limit for the filter. If None, by default, no high pass filter is applied.

• lowpass_limit (float): The low-pass limit for the filter. If None, by default, no low pass filter is applied.

• gpass (float): The maximum loss in the passband, in [dB]. Default is 1 dB.

• gstop (float): The minimum attenuation in the stopband, in [dB]. Default is 5 dB.

• calibrate (bool): Select to apply the windowing compensating factor. Default value is True.

• normalise_length (bool): Select to normalise the amplitude spectrum by the signal length. Default value is True.

• name (str): The name for the FrequencyDomainData. Default value None, in which case it is created from the name of the time domain data instance self.

• collection_name (str): The name of the collection to which the frequency domain data belongs. Default value None, in which case it is created from the name of the time domain collection instance self.

Output:

• Returns the newly created instance of FrequencyDomainData class, the frequency domain data created from the time domain data.

crop_time_domain(from_front: bool = True, number_of_items: int | None = None, time_amount: float | None = None, percentage_to_crop: float | None = None, crop_at: float | None = None, override: bool = True) → Self

Method to crop the signal at the front or back given different cues.

Input:

• from_front (bool): If True, by default, crop from the front. If False, crop from the back.

• number_of_items (int): Optional input for the number of items to remove.

• time_amount (float): Optional input for the amount of time to remove.

• percentage_to_crop (float): Optional input for the percentage of the signal to remove. (10 = 10%)

• crop_at (float): Optional input for the value of the time_stamp signal from where to remove.

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

Output:

• Returns the cropped time domain data object.

octaves_from_tdd(third_octave: bool = False, level_type: str = 'RMS', window_type: str | None = None, calibrate: bool = True, normalise_length: bool = True, averaging: str | None = None, overlap: float = 0.5, segment_length: float | None = None, segment_duration: float | None = None, segment_amount: int | None = None, remove_baseline: bool = False) → Dict[float, float]

This function creates octaves from the TimeDomainData by converting it to frequency domain data first.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

• window_type (str): Select the type of window to apply to the signal before FFT. Default value is None, in which case no window is applied (same as applying ‘Rectangular’ window).

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

• normalise_length (bool): Select to normalise the amplitude spectrum by the signal length. Default value is True.

• averaging (str): Controls whether and how the signal is segmented and averaged before computing frequency bands. Options include: ‘1s’, ‘0.125s’, or ‘custom’. In case of ‘custom’ the segment-length, segment-duration or segment-amount should be specified. Default value is None, in which case no segmentation or averaging is applied. The entire signal is processed as a single block.

• overlap (float): The percentage of overlap between segments in decimal format. 50% (0.5) is recommended and used by default.

• segment_length (int): The length of the segment in amount of data points. Default value is None. Input only used for custom averaging.

• segment_duration (float): The duration of the segment in time unit. Default value is None. Input only used for custom averaging.

• segment_amount (int): The amount of segments to divide the signal into. Default value is None. Input only used for custom averaging.

• remove_baseline (bool): Select to remove the baseline from each segment. Default value is True.

Output:

• Returns dictionary with the calculated octave bands.

perform_sbr_b_rms(method: str = 'fast', tau: float = 0.125, apply_frequency_weighting: bool = True, highpass_frequency: float = 5.6, lowpass_frequency: float = 80.0) → List[float]

Method to calculate and add SBR-B RMS values to the TimeDomainData object.

Input:

• method (str): Method to use for calculation (‘fast’ or ‘slow’). Default value is ‘fast’.

• tau (float): Time constant, in [s]. Default value 0.125s according SBR-B.

• apply_frequency_weighting (bool): Select to apply frequency weighting. Default value is True.

• highpass_frequency (float): High-pass filter frequency, in [Hz]. Default value is 5.6 Hz according SBR-B.

• lowpass_frequency (float): Low-pass filter frequency, in [Hz]. Default value is 80 Hz according SBR-B.

Output:

• Returns the calculated RMS values.

plot(log_scale_x: bool = False, log_scale_y: bool = False, x_lim: list = None, y_lim: list = None, show: bool = True, file: Path | str | None = None, plot_max_values: bool = False, horizontal_line: float | None = None) → None

Function to plot the transient data of the TimeDomainData object.

Input:

• log_scale_x (bool): Select to set the x-axis to a logarithmic scale. Default value is False.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• plot_max_values (bool): Select to calculate the maximum y value for each line and add it to the plot. Default value is False.

• horizontal_line (float): Optional input to draw a horizontal line at this y-value. Default value is None.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

plot_octaves_tdd(third_octave: bool = False, level_type: str = 'RMS', window_type: str = 'Hanning', calibrate: bool = True, normalise_length: bool = True, averaging: str | None = None, overlap: float = 0.5, segment_length: float | None = None, segment_duration: float | None = None, segment_amount: int | None = None, remove_baseline: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, show: bool = True, file: Path | str | None = None, show_bar_values: bool = True, decimals_displayed: int = 2, bar_width: float = 1) → Path | None

Method to plot the octave or third-octave bands of the TimeDomainData object.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

• window_type (str): Select the type of window to apply to the signal before FFT. Default value is ‘Hanning’.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

• normalise_length (bool): Select to normalise the amplitude spectrum by the signal length. Default value is True.

• averaging (str): Controls whether and how the signal is segmented and averaged before computing frequency bands. Options include: ‘1s’, ‘0.125s’, or ‘custom’. In case of ‘custom’ the segment-length, segment-duration or segment-amount should be specified. Default value is None, in which case no segmentation or averaging is applied. The entire signal is processed as a single block.

• overlap (float): The percentage of overlap between segments in decimal format. 50% (0.5) is recommended and used by default.

• segment_length (int): The length of the segment in amount of data points. Default value is None. Input only used for custom averaging.

• segment_duration (float): The duration of the segment in time unit. Default value is None. Input only used for custom averaging.

• segment_amount (int): The amount of segments to divide the signal into. Default value is None. Input only used for custom averaging.

• remove_baseline (bool): Select to remove the baseline from each segment. Default value is True.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• show_bar_values (bool): Select to display the labels on the bars. Default value is True.

• decimals_displayed (int): The number of decimal places for formatting values. Default value is 2.

• bar_width (float): The width of the bars. Default value is 1.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

plot_sbr_b_rms(log_scale_x: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, show: bool = True, file: Path | str | None = None, limit_parameters: list | None = None, plot_max_values: bool = True) → Path | None

Method to plot the SBR-B RMS of the TimeDomainData object.

Input:

• log_scale_x (bool): Select to set the x-axis to a logarithmic scale. Default value is False.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• limit_parameters (list): List of parameters for the SBR-B vibration limit. Example: [building function, time of day, and limit type] = [‘office’, ‘day’, ‘A1’]. Default value is None, in which case no limit is plotted.

• plot_max_values (bool): Select to calculate the maximum y value for each line and add it to the plot. Default value is False.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

plot_signal_composition_3d(amplitude_threshold: float | None = None, log_scale_frequency: bool = False, file: Path | str | None = None, show: bool = True) → Path | None

Create a 3D plot of the signal composition for the TimeDomainData. The frequency domain data is either taken from an existing FrequencyDomainData with the same name as the TimeDomainData, or it is created with default settings and window-type ‘Hanning’.

Input:

• amplitude_threshold (float): Optional input for the threshold for significant amplitudes. Default value None, in which case 10% of max amplitude is used.

• log_scale_frequency (bool): Select to set the frequency axis to a logarithmic scale. Default value is False.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

remove_baseline(override: bool = True) → Self

Remove the baseline component from the time domain data. For electrical signals known as DC offset. But in mechanics can be a constant value of the signals such as a constant acceleration due to gravity for an acceleration measurement, or a constant velocity for a velocity measurement or an average value position in terms of displacement signal.

Input:

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

Output:

• Returns the time domain data object with removed baseline.

rotate_with_orthogonal_pair(partner_signal: Self, angle: float, new_names: List[str] | None = None) → Tuple[Self, Self]

This method rotates the signal represented by this time domain and another orthogonal time domain by a specified angle. The rotation is performed on the plane defined by the two time domain signals.

The two time domain signals should be orthogonal, have the same time stamps (time interval/length) and be synchronised.

Input:

• partner_signal (Obj): The other time domain data object defining the orthogonal component of the signal. It should have the same time stamps as this time domain.

• angle (float): The angle of rotation in degrees.

• new_names (list of str): Optional input for a list containing new names for the rotated time domain data.

Output:

• Returns a tuple with the rotated time domain data objects.

property sampling_interval: float | None

Returns the time step delta of the time domain data, only if the time steps are evenly spaced.

scale_amplitude(factor: float, override: bool = True) → Self

Method to scale the amplitudes of the TimeDomainData by a given factor.

Input:

• factor (float): The scaling factor to apply to the amplitudes.

• override (bool): If True, by default, modify the current object. If False, return a new scaled object.

Output:

• Returns the scaled time domain data object.

segment_time_domain(segment_length: int | None = None, segment_duration: float | None = None, segment_amount: int | None = None, overlap: float = 0.5, remove_baseline: bool = False, collection_name: str | None = None) → TimeDomainCollection

This method divides the time domain data into smaller segments. Segmenting, overlapping and averaging is done as integral part of Welch method to reduce Random Error. Nevertheless, if the segments are left with low amount of time steps, the bias error will increase and the frequency resolution will decrease.

Input:

• segment_length (int): The length of the segment in amount of data points. Default is None.

• segment_duration (float): The duration of the segment in time unit. Default is None.

• segment_amount (int): The amount of segments to divide the signal into. Default is None.

• overlap (float): The percentage of overlap between segments in decimal format. 50% (0.5) is recommended and used by default.

• remove_baseline (bool): If True, remove the baseline from each segment. Default is True.

• collection_name (str): The name of the collection to which the segmented data belongs. If None, a default name is used.

Output:

• Returns the collection of segmented time domain data.

shift_start_time(start_time: float, override: bool = True) → Self

Shift the start time of the time domain data.

Input:

• start_time (float): The new start time for the time domain.

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

Output:

• Returns the shifted time domain data object.

stitch_time_domain(other_time_domain_list: List[Self], override: bool = True) → Self

Stitch together multiple TimeDomainData objects.

Input:

• other_time_domain_list (list of obj): List of other time domain data to stitch with.

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

Output:

• Returns the stitched time domain data object.

zero_pad_time_domain(pad_from: str = 'both', number_of_items: int = None, time_amount: float = None, percentage_to_pad: float = None, override: bool = True) → Self

Method to zero pad the signal at the front, back, or both given different cues.

Input:

• pad_from (str): Where to pad the signal. Options are ‘front’, ‘back’, ‘both’. Defaults to ‘both’.

• number_of_items (int): Optional input for the number of items to pad.

• time_amount (float): Optional input for the amount of time to pad.

• percentage_to_pad (float): Optional input for the percentage of the signal to pad (10 = 10%).

• override (bool): If True, by default, modify the current object. If False, return a new cropped object.

Output:

• Returns the padded time domain data object.

class haskoning_atr_tools.signal_processing_tool.time_domain.collection.TimeDomainCollection(parent: ATRProject, name: str, time_domain_data: dict = <factory>)

Bases: object

The TimeDomainCollection class represents a collection of TimeDomainData objects.

Input:

• name (str): The name of the time domain collection.

• parent (obj): The parent project or entity that this collection belongs to.

• time_domain_data (list): A list of TimeDomainData objects that are part of the collection.

add_time_domain_data_to_collection(time_domain_data: TimeDomainData) → None

Adds a TimeDomainData object to the time_domain_data.

Input:

• time_domain_data (TimeDomainData): The TimeDomainData object to be added to the collection.

Output:

• TimeDomainCollection is added to the collection.

check_time_stamps_alignment() → bool

Check if time stamps align across all TimeDomainData objects in the collection.

convert_collection_to_frequency_domain(window_type: str | None = None, highpass_limit: float = None, lowpass_limit: float = None, gpass: float = 1, gstop: float = 5, calibrate: bool = True, normalise_length: bool = True, name: str | None = None) → FrequencyDomainCollection

Create frequency domain data from all the time domain data in the collection and group them in one collection. Uses convert_to_frequency_domain which applies a filter to the time domain data, normalises the signal length, performs a Fast Fourier Transform (FFT) on the time domain data, and creates a new FrequencyDomainData object with the transformed data.

Input:

• window_type (str): Select the type of window to apply to the signal before FFT. Default value is None, in which case no window is applied (same as applying ‘Rectangular’ window).

• highpass_limit (float): The high-pass limit for the filter. If None, by default, no high pass filter is applied.

• lowpass_limit (float): The low-pass limit for the filter. If None, by default, no low pass filter is applied.

• gpass (float): The maximum loss in the passband, in [dB]. Default is 1 dB.

• gstop (float): The minimum attenuation in the stopband, in [dB]. Default is 5 dB.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

• normalise_length (bool): Select to normalise the amplitude spectrum by the signal length. Default value is True.

• name (str): The name for the FrequencyDomainData. Default value None, in which case it is created from the name of the time domain data instance self.

Output:

• Returns the collection of frequency domain data created from the time domain collection.

plot(log_scale_x: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | None = None, show: bool = True, plot_max_values: bool = False) → Path | None

Method creates plot of all the transient data in the collection.

Input:

• log_scale_x (bool): Select to set the x-axis to a logarithmic scale. Default value is False.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• plot_max_values (bool): Select to calculate the maximum y value for each line and add it to the plot. Default value is False.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

plot_collection_octaves_tdd(third_octave: bool = False, level_type: str | None = 'RMS', window_type: str = 'Hanning', calibrate: bool = True, normalise_length: bool = True, averaging: str | None = None, overlap: float = 0.5, segment_length: float | None = None, segment_duration: float | None = None, segment_amount: int | None = None, remove_baseline: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, show: bool = True, file: Path | None = None, show_bar_values: bool = True, decimals_displayed: int = 2, bar_width: float = 1) → None

Method to create plot the octave or third-octave bands for all TimeDomainData objects in the collection.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

• window_type (str): Select the type of window to apply to the signal before FFT. Default value is ‘Hanning’.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

• normalise_length (bool): Select to normalise the amplitude spectrum by the signal length. Default value is True.

• averaging (str): Controls whether and how the signal is segmented and averaged before computing frequency bands. Options include: ‘1s’, ‘0.125s’, or ‘custom’. In case of ‘custom’ the segment-length, segment-duration or segment-amount should be specified. Default value is None, in which case no segmentation or averaging is applied. The entire signal is processed as a single block.

• overlap (float): The percentage of overlap between segments in decimal format. 50% (0.5) is recommended and used by default.

• segment_length (int): The length of the segment in amount of data points. Default value is None. Input only used for custom averaging.

• segment_duration (float): The duration of the segment in time unit. Default value is None. Input only used for custom averaging.

• segment_amount (int): The amount of segments to divide the signal into. Default value is None. Input only used for custom averaging.

• remove_baseline (bool): Select to remove the baseline from each segment. Default value is True.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• show_bar_values (bool): Select to display the labels on the bars. Default value is True.

• decimals_displayed (int): The number of decimal places for formatting values. Default value is 2.

• bar_width (float): The width of the bars. Default value is 1.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

rotate_orthogonal_pair(first_time_domain_data_name: str, second_time_domain_data_name: str, angle: float, new_names: List[str] = None) → tuple[TimeDomainData, TimeDomainData]

Method rotates two orthogonal time domain data objects by a specified angle. This method rotates the signal represented by two time domain that are orthogonal to each other by a specified angle. The rotation is performed on the plane defined by the two time domain.

The two time domain should be orthogonal, have the same time stamps (time interval/length) and be synchronised.

Input:

• first_time_domain_data_name (str): The name of the first time domain data.

• second_time_domain_data_name (str): The name of the second time domain data.

• angle (float): The angle of rotation in degrees.

• new_names (list of str): The new names for the TimeDomainData objects. Default value None, which will

Output:

• Returns a tuple containing the rotated time domain data.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_ricker_wavelet(duration: float, sampling_rate: int, center_frequency: float, centered: bool = False) → Tuple[List[float], List[float]]

Create a Ricker wavelet for a given duration, sampling rate, and center frequency.

Input:

• duration (float): Duration of the wavelet, in [s].

• sampling_rate (int): Sampling rate, in [-].

• center_frequency (float): Center frequency of the wavelet, in [Hz].

• centered (bool): Select to center the time steps around zero. Default value False.

Output:

• Returns a tuple containing the generated signal as list of floats and the corresponding time steps as list of floats, in [s].

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_ricker_wavelet_time_domain_data(project, center_frequency: float, centered: bool = False, duration: float = 10, sampling_rate: int | float = 100, name: str | None = None, collection_name: str = 'Unknown Collection', amplitude_type: str = None, amplitude_units: str = 'Unknown units', time_stamps_units: str = 'Unknown units') → TimeDomainData

Creates a time domain data object with Ricker wavelet signal.

Input:

• project (obj): Project object containing collections of objects and project variables.

• center_frequency (float): Center frequency of the wavelet, in [Hz].

• centered (bool): Select to center the time steps around zero. Default value False.

• duration (float): The total duration of the signal, in [s]. Default value is 10 seconds.

• sampling_rate (float, int): Sampling rate, in [Hz]. Default value is a sampling rate of 100 Hz.

• name (str): The name of the new time domain data. Default value ‘Ricker wavelet with xHz center frequency’.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

• amplitude_type (str): The type of the time domain data. For example: ‘velocity’, ‘acceleration’, or ‘pressure’. Default value is None.

• amplitude_units (str): The units of the amplitude values. Default value is ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults to ‘Unknown units’.

Output:

• Returns the newly created time domain data object based on the inputs for Ricker wavelet signal.

• TimeDomainData is added to the specified TimeDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_sinusoidal_time_domain_data(project, harmonic_amplitudes: float | List[float], harmonic_frequencies: float | List[float], harmonic_phase_shift: float | List[float] | None = None, duration: float = 10, sampling_rate: int | float = 100, name: str = 'Sinusoidal signal', collection_name: str = 'Unknown Collection', amplitude_type: str = None, amplitude_units: str = 'Unknown units', time_stamps_units: str = 'Unknown units') → TimeDomainData

Creates a time domain data object with sinusoidal amplitudes.

Input:

• project (obj): Project object containing collections of objects and project variables.

• harmonic_amplitudes (list of float): Amplitudes of the harmonics. Alternative input can be a single amplitude as float.

• harmonic_frequencies (list of float): Frequencies of the harmonics. Alternative input can be a single frequency as float.

• harmonic_phase_shift (list of float): Optional input for phase shifts of the harmonics in degrees. If not provided, all phase shifts are 0. Alternative input can be a single phase_shift as float.

• duration (float): Duration of the signal, in [s]. Default value is 10 seconds.

• sampling_rate (float, int): Sampling rate, in [Hz]. Default value is a sampling rate of 100 Hz.

• name (str): The name of the new time domain data. Default value is ‘Sinusoidal signal’.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

• amplitude_type (str): The type of the time domain data. For example: ‘velocity’, ‘acceleration’, or ‘pressure’. Default value is None.

• amplitude_units (str): The units of the amplitude values. Default value is ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults to ‘Unknown units’.

Output:

• Returns the newly created time domain data object based on the inputs for sinusoidal signal.

• TimeDomainData is added to the specified TimeDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_sinusoidal_time_signal(harmonic_amplitudes: List[float] | float, harmonic_frequencies: List[float] | float, harmonic_phase_shift: float | List[float] | None = None, duration: float = 10, sampling_rate: int | float = 100) → Tuple[List[float], List[float]]

Create a time signal by adding several sinusoidal waves with specific frequencies, amplitudes, and phase shifts.

Input:

• harmonic_amplitudes (list of float): Amplitudes of the harmonics. Alternative input can be a single amplitude as float.

• harmonic_frequencies (list of float): Frequencies of the harmonics. Alternative input can be a single frequency as float.

• harmonic_phase_shift (list of float): Optional input for phase shifts of the harmonics in degrees. If not provided, all phase shifts are 0. Alternative input can be a single phase_shift as float.

• duration (float): Duration of the signal, in [s]. Default value is 10 seconds.

• sampling_rate (float, int): Sampling rate, in [Hz]. Default value is a sampling rate of 100 Hz.

Output:

• Returns a tuple containing the generated signal as list of floats and the corresponding time steps as list of floats, in [s].

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_special_time_domain_data(project, signal_type: str, duration: float = 10, event_time: float = 0.0, amplitude: float = 1.0, sampling_rate: int | float = 100, name: str | None = None, collection_name: str = 'Unknown Collection', amplitude_type: str = None, amplitude_units: str = 'Unknown units', time_stamps_units: str = 'Unknown units') → TimeDomainData

Creates a new time domain data object with special signal and adds it to the specified collection in the project.

Input:

• project (obj): Project object containing collections of objects and project variables.

• signal_type (str): The type of signal to generate. Valid types are ‘heaviside’, ‘kronecker’, and ‘dirac’.

• duration (float): The total duration of the signal, in [s]. Default value is 10 seconds.

• event_time (float): The event time is representing the time, in [s] at which the signal event occurs. It’s used to position the signal (step, impulse, or discrete spike) within the total duration of the signal. Default value is 0, placing the event at the start of the signal.

• amplitude (float): The amplitude of the signal. Default value is 1.0. Amplitude is not used for the dirac method.

• sampling_rate (float, int): Sampling rate, in [Hz]. Default value is a sampling rate of 100 Hz.

• name (str): The name of the new time domain data. Default value ‘Special signal’ with additional information from inputs.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

• amplitude_type (str): The type of the time domain data. For example: ‘velocity’, ‘acceleration’, or ‘pressure’. Default value is None.

• amplitude_units (str): The units of the amplitude values. Default value is ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults to ‘Unknown units’.

Output:

• Returns the newly created time domain data object based on the inputs for special signal.

• TimeDomainData is added to the specified TimeDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_special_time_signal(signal_type: str, duration: float = 10, event_time: float = 0.0, amplitude: float = 1.0, sampling_rate: int | float = 100) → Tuple[List[float], List[float]]

Create a special time signal of a specified type. This function generates a time signal based on the specified type, duration, event time, amplitude, and sampling rate. The supported signal types are ‘heaviside’, ‘kronecker’, and ‘dirac’.

Input:

• signal_type (str): The type of signal to generate. Valid types are ‘heaviside’, ‘kronecker’, and ‘dirac’.

• duration (float): The total duration of the signal, in [s]. Default value is 10 seconds.

• event_time (float): The event time is representing the time, in [s] at which the signal event occurs. It’s used to position the signal (step, impulse, or discrete spike) within the total duration of the signal. Default value is 0, placing the event at the start of the signal.

• amplitude (float): The amplitude of the signal. Default value is 1.0. Amplitude is not used for the dirac method.

• sampling_rate (float, int): Sampling rate, in [Hz]. Default value is a sampling rate of 100 Hz.

Output:

• Returns a tuple containing the generated signal as list of floats and the corresponding time steps as list of floats, in [s].

Raises:

• ValueError: If the signal type is not valid or if the event time is outside the duration.

Example:

In this example a time signal is created with the heaviside method.

signal, time_stamps = create_special_time_signal('heaviside', 1.0, 0.5, amplitude=2.0, sampling_rate=100)

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_time_domain_collection(project, name: str, time_domain_data_list: List[TimeDomainData]) → TimeDomainCollection

Creates a new time domain collection and adds it to the project.

Input:

• name (str): The name of the new time domain collection.

• time_domain_data_list (list of obj): A list of time domain data objects to include in the collection.

Output:

• Returns the newly created time domain collection.

• The collection is added to the time domain collections in project.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_time_domain_collection_from_file(project, collection_name: str, info_list: List[list]) → TimeDomainCollection

Creates a time domain collection with multiple time domain data objects from cvs- or xlsx-files.

Input:

• project (obj): Project object containing collections of objects and project variables.

• collection_name (str): The name of the collection to which the signals will be added.

• info_list (list of list): A list of lists, each containing the arguments for creating a TimeDomainData object from a file. The sublist should be in the order of the arguments for create_time_domain_data_from_file, such as: [file, time_column, amplitude_column, name, amplitude_type, amplitude_units, time_stamps_units, skip_rows, header]. Only file, time_column, and amplitude_column are mandatory; the other arguments are not required.

Output:

• Returns the newly created time domain collection object.

• TimeDomainData objects are created based on the imported signal from the csv- or xlsx-file.

• The TimeDomainData objects are added to the TimeDomainCollection.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_time_domain_collection_from_sigicom_csv(project, collection_name: str, info_list: List[list]) → TimeDomainCollection

Creates a time domain collection with multiple time domain data objects from Sigicom csv-files.

Input:

• project (obj): Project object containing collections of objects and project variables.

• collection_name (str): The name of the collection to which the signals will be added.

• info_list (list of list): A list of lists, each containing the arguments for creating a TimeDomainData object from a Sigicom csv-file. The sublist should be in the order of the arguments for create_time_domain_data_from_sigicom_csv, such as: [file, name, amplitude_type, amplitude_units, time_stamps_units]. Only file is mandatory the other arguments are not required.

Output:

• Returns the newly created time domain collection object.

• TimeDomainData objects are created based on the imported signal from the Sigicom csv-file.

• The TimeDomainData objects are added to the TimeDomainCollection.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_time_domain_data(project, name: str, amplitude_type: str, amplitudes: List[float], time_stamps: List[float], amplitude_units: str = 'Unknown units', time_stamps_units: str = 'Unknown units', collection_name: str = 'Unknown Collection') → TimeDomainData

Creates a new time domain data object and adds it to the specified collection in the project.

Input:

• project (obj): Project object containing collections of objects and project variables.

• name (str): The name of the new time domain data.

• amplitude_type (str): The type of the time domain data. For example: ‘velocity’, ‘acceleration’, or ‘pressure’. Default value is None.

• amplitudes (list of float): A list of amplitude values for the time domain data.

• time_stamps (list of float): A list of time stamps corresponding to the amplitude values.

• amplitude_units (str): The units of the amplitude values. Default value is ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults value is ‘Unknown units’.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created time domain data object.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_time_domain_data_from_file(project, file: str | Path, time_column: str | int, amplitude_column: str | int, name: str | None = None, amplitude_type: str = None, amplitude_units: str = 'Unknown units', time_stamps_units: str = 'Unknown units', skip_rows: int = 0, header: bool = True, delimiter: str = ',', collection_name: str = 'Unknown Collection') → TimeDomainData

Creates a time domain data object from file (csv-file or xlsx-file).

Input:

• project (obj): Project object containing collections of objects and project variables.

• file (Path or str): The file path to the data file.

• time_column (str or int): The name or index of the column containing time stamps.

• amplitude_column (str or int): The name or index of the column containing amplitude values.

• name (str): The name of the new time domain data. Default value is the name of the file.

• amplitude_type (str): The type of the time domain data. For example: ‘velocity’, ‘acceleration’, or ‘pressure’. Default value is None.

• amplitude_units (str): The units of the amplitude values. Default value is ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults to ‘Unknown units’.

• skip_rows (int): Optional input for the number of rows to skip at the beginning of the file. Defaults to 0.

• header (bool): Select whether the file contains a header row. Defaults to True.

• delimiter (str): The delimiter used in the csv-file. Default is ‘,’.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created time domain data object based on the imported signal.

• TimeDomainData is added to the specified TimeDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.time_domain.create.create_time_domain_data_from_sigicom_csv(project, file: str | Path, name: str | None = None, amplitude_type: str = None, amplitude_units: str = 'Unknown units', time_stamps_units: str = 'Unknown units', collection_name: str = 'Unknown Collection') → TimeDomainData

Creates a time domain data object from a Sigicom csv-file.

Input:

• project (obj): Project object containing collections of objects and project variables.

• file (Path or str): The file path to the Sigicom csv-file.

• name (str): The name of the new time domain data. Default value is the name of the Sigicom csv-file.

• amplitude_type (str): The type of the time domain data. For example: ‘velocity’, ‘acceleration’, or ‘pressure’. Default value is None.

• amplitude_units (str): The units of the amplitude values. Default value is ‘Unknown units’.

• time_stamps_units (str): The units of the time stamps. Defaults to ‘Unknown units’.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created time domain data object based on the imported signal.

• TimeDomainData is added to the specified TimeDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.amplitude_spectrum_from_time_domain_data(amplitudes: List[float], sampling_rate: float, window_type: str | None = None, calibrate: bool = True, normalise_length: bool = True) → Tuple[List[float], List[float], List[float]]

This function performs FFT on the time domain data and calculate the corresponding phase angles. It uses the SciPy package for the FFT calculation. If the input amplitudes are all real numbers, it uses the more efficient real FFT computation.

Input:

• amplitudes (list of float): The amplitude values of the signal.

• sampling_rate (float, int): Sample rate of the signal, in [Hz].

• window_type (str): The type of window to apply. Default value is None, no window is applied.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

• normalise_length (bool): Select to normalise the amplitude spectrum by the signal length. Default value is True.

Output:

• Returns tuple containing three lists of floats: Amplitude spectrum, corresponding phase angles, in [deg] and corresponding frequencies, in [Hz].

haskoning_atr_tools.signal_processing_tool.time_domain.tools.apply_filter_to_time_domain_data(amplitudes: List[float], sampling_rate: float, highpass_limit: float = None, lowpass_limit: float = None, gpass: float = 1, gstop: float = 5) → List[float]

Apply a Butterworth filter to a signal.

Input:

• amplitudes (list of float): List of amplitude values of the signal.

• sampling_rate (float): The sampling rate of the signal, in [Hz].

• highpass_limit (float): The high-pass limit for the filter. If None, by default, no high pass filter is applied.

• lowpass_limit (float): The low-pass limit for the filter. If None, by default, no low pass filter is applied.

• gpass (float): The maximum loss in the passband, in [dB]. Default is 1 dB.

• gstop (float): The minimum attenuation in the stopband, in [dB]. Default is 5 dB.

Output:

• Returns the filtered amplitudes as list of floats.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.apply_window(amplitudes: List[float], window_type: str | None = None, calibrate: bool = True) → List[float]

Function to Apply a window to the signal and windowing compensating factor before performing FFT.

Input:

• amplitudes (list of float): The amplitude values of the signal.

• window_type (str): The type of window to apply. Default value is None, no window is applied.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

Output:

• Returns the amplitude values of the signal after applying the window as list of floats.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.calculate_progressive_effective_rms_fast(amplitude_data: List[float], time_stamps: List[float], tau: float = 0.125) → List[float]

Function to calculate the progressive effective RMS value using the fast difference equation method.

Input:

• amplitude_data (list of floats): The amplitude data.

• time_stamps (list of floats): List of time points, in [s].

• tau (float): Time constant, in [s]. Default value 0.125s according SBR-B guideline.

Output:

• Returns the calculated RMS values.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.calculate_progressive_effective_rms_slow(amplitude_data: List[float], time_stamps: List[float], tau: float = 0.125) → List[float]

Calculate the progressive effective RMS value using the slow integration method.

Reference:

Input:

• amplitude_data (list of floats): The amplitude data.

• time_stamps (list of floats): List of time points, in [s].

• tau (float): Time constant, in [s]. Default value 0.125s according SBR-B.

Output:

• Returns the calculated RMS values.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.calculate_sbr_b_rms(amplitudes: List[float], time_stamps: List[float], method: str = 'fast', tau: float = 0.125, f0: float = 5.6, v0: float = 1.0, amplitude_type: str = 'velocity', apply_frequency_weighting: bool = True, highpass_freq: float = 1.0, lowpass_freq: float = 80.0) → List[float]

Calculate the RMS values from time domain data according SBR-B guideline.

Input:

• amplitudes (list of floats): The amplitude data

• time_stamps (List[float]): List of time points in seconds

• method (str): Method to use for calculation (‘fast’ or ‘slow’)

• tau (float): Time constant in seconds (default: 0.125s for SBR-B)

• f0 (float): Reference frequency, in [Hz]. Default value 5.6 Hz according SBR-B guideline.

• v0 (float): Reference velocity, in [mm/s]. Default value 1.0 mm/s according SBR-B guideline.

• amplitude_type (str): Type of amplitude data. Select from ‘velocity’ or ‘acceleration’. Default value is ‘velocity’.

• apply_frequency_weighting (bool): Select to apply frequency weighting. Default value is True.

• highpass_limit (float): The high-pass limit for the filter. By default, 1Hz is applied, according SBR-B guideline.

• lowpass_limit (float): The low-pass limit for the filter. By default, 80Hz is applied, according SBR-B guideline.

Output:

• Returns list of the calculated RMS values.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_periodicity(amplitudes: List[float], threshold: float = 0.01) → bool

Function to check if the signal is periodic by checking if the amplitude the signal starts and ends with less than 1% of the max amplitude.

Note

This check is very simplified, check can be extended in future.

Input:

• amplitudes (list of float]): The amplitude values of the signal.

• threshold (float): The threshold for determining periodicity.

Output:

• Returns boolean with the outcome of the check. True if the signal is periodic, False otherwise.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_stationary(amplitudes: List[float], relative_tolerance: float = 0.1, absolute_tolerance: float = 0.1) → bool

Function to check if the signal is stationary (mean and variance do not change over time) by checking if the variance of the first half of the signal is significantly different from the second half, we consider it non-stationary.

Input:

• amplitudes (List[float]): The amplitude values of the time domain.

• relative_tolerance (float): The relative tolerance parameter for comparing variances. Default value is 0.1.

• absolute_tolerance (float): The absolute tolerance parameter for comparing means max amplitude difference. Default value is 0.1.

Output:

• Returns True if the signal is stationary, else False.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_td_average(amplitudes: List[float], relative_limit: float = 0.1) → bool

Function to check if the average of the signal is more than a specified fraction of the maximum amplitude.

Input:

• amplitudes (list of float]): The amplitude values of the signal.

• relative_limit (float): The fraction of the maximum amplitude to compare against. Default value is 0.1.

Output:

• Returns boolean with the outcome of the check. Warning is thrown if the average of the signal is more than the specified fraction of the maximum amplitude.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_td_ft_suitability(amplitudes: List[float], time_stamps: List[float]) → bool

Function to check if the signal is suitable for Fourier Transform by checking time intervals, periodicity, and if it is stationary.

Input:

• amplitudes (list of floats): The amplitude values of the signal.

• time_stamps (list of floats): The time stamps corresponding to the amplitude values.

Output:

• The function checks suitability for Fourier Transform, if the signal does not comply a warning is raised.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_td_noise(amplitudes: List[float], relative_limit: float = 0.01) → bool

Function to check if the signal has noise by evaluating its variance.

Input:

• amplitudes (list of float]): The amplitude values of the signal.

• relative_limit (float): The fraction of the maximum amplitude to compare against. Default value is 0.01.

Output:

• Returns boolean with the outcome of the check. Warning is thrown if the signal has noise (variance is significantly different from zero).

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_time_domain_compatibility(time_domain_list: List[Dict[str, str | List[float]]], identifier: str = 'time domain data') → None

Function to check if the time domain data are compatible by verifying if amplitude_type, amplitude_units, time_stamps_units, and time_stamps step size are the same.

Input:

• time_domain_list (list of dicts): A list of dictionaries, each containing the following keys and values: ‘amplitude_type’ as string, the type of the time domain data. ‘amplitude_units’ as string, the units of the amplitude values. ‘time_stamps_units’ as string, the units of the time stamps. ‘time_stamps’ as list of floats, the time stamps of the time domain.

• identifier (str): The identifier of the time domain data. Default value is ‘time domain data’.

Output:

• Check is executed and raises warning for any failing check.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.check_time_stamps_intervals(time_stamps: List[float]) → bool

Function to check if all time steps in the time domain are the same size.

Input:

• time_stamps (list of floats): The time stamps of the time domain.

Output:

• Returns boolean with the outcome of the check. Warning is thrown if the time steps are not the same size.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.combine_time_domain_data(time_domain_list: List[Dict[str, List[float]]]) → Tuple[List[float], List[float]]

Combine the amplitudes of multiple signals.

Input:

• time_domain_list (list of dicts): A list of dictionaries, each containing ‘time_stamps’ (as list of floats), the time stamps of the time domain and ‘amplitudes’ (as list of floats), the amplitudes of the time domain.

Output:

• Returns the combined time_stamps and amplitudes as tuple with two lists of floats.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.crop_time_domain_data(time_stamps: List[float], amplitudes: List[float], from_front: bool = True, number_of_items: int | None = None, time_amount: float | None = None, percentage_to_crop: float | None = None, crop_at: float | None = None) → Tuple[List[float], List[float]]

Function to crop signal at the front or back given different cues.

Input:

• time_stamps (list): List of time stamps.

• amplitudes (list): List of amplitude values.

• from_front (bool): If True, as default, crop from the front. If False, crop from the back.

• number_of_items (int): The number of items to remove.

• time_amount (float): The amount of time to remove.

• percentage_to_crop (float): The percentage of the signal to remove. (10 = 10%)

• crop_at (float): The value of the time_stamp signal from where to remove.

Output:

• Returns tuple with cropped time stamps as list of floats and amplitudes as list of floats.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.fft_from_time_domain_data(amplitudes: List[float], sampling_rate: float | int, window_type: str | None = None, calibrate: bool = True) → Tuple[ndarray, ndarray]

Function that applies windowing and respective calibration to the time domain data, then performs the full complex spectrum of a signal FFT on the corrected data with usage of the SciPy package.

Input:

• amplitudes (list of float): The amplitude values of the signal.

• sampling_rate (float, int): Sample rate, in [Hz].

• window_type (str): The type of window to apply. Default value is None, no window is applied.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

Output:

• Returns tuple of numpy arrays, the FFT values and the corresponding frequencies.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.frequency_weighting(frequency_data: ndarray, amplitudes: ndarray, amplitude_type: str = 'velocity', f0: float = 5.6, v0: float = 1.0) → ndarray

Calculate frequency weighting factors and apply them to amplitudes at each respective frequency.

Input:

• frequency_data (np.ndarray): NumPy array of frequency values, in [Hz].

• amplitudes (np.ndarray): Numpy array of amplitude values.

• amplitude_type (str): Type of amplitude data. Select from ‘velocity’ or ‘acceleration’. Default value is ‘velocity’.

• f0 (float): Reference frequency, in [Hz]. Default value 5.6 Hz according SBR-B guideline.

• v0 (float): Reference velocity, in [mm/s]. Default value 1.0 mm/s according SBR-B guideline.

Output:

• Returns the frequency weighted amplitudes.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.rfft_from_time_domain_data(amplitudes: List[float], sampling_rate: float | int, window_type: str | None = None, calibrate: bool = True) → Tuple[ndarray, ndarray]

Function that applies windowing and respective calibration to the time domain data, then performs the real-valued signal FFT on the corrected data with usage of the SciPy package.

Input:

• amplitudes (list of float): The amplitude values of the signal.

• sampling_rate (float, int): Sampling rate, in [Hz].

• window_type (str): The type of window to apply. Default value is None, no window is applied.

• calibrate (str): Select to apply the windowing compensating factor. Default value is True.

Output:

• Returns tuple of numpy arrays, the FFT values and the corresponding frequencies.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.rotate_signals(amplitudes1: List[float], amplitudes2: List[float], angle: float) → Tuple[List[float], List[float]]

Rotate two orthogonal signals by a specified angle.

Input:

• amplitudes1 (list of floats): Amplitudes of the first signal.

• amplitudes2 (list of floats): Amplitudes of the second signal.

• angle (float): The angle of rotation, in [deg].

Output:

• Returns tuple: Rotated amplitudes of the two signals.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.shift_time_stamp_start(time_stamps: List[float], start_time: float) → List[float]

Function to shift the start time of the time domain data.

Input:

• time_stamps (list of floats): The original time stamps of the time domain.

• start_time (float): The new start time for the time domain.

Output:

• Returns the shifted time stamps as list of float.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.stitch_time_domain_data(time_domain_list: List[Dict[str, str | List[float]]]) → Tuple[List[float], List[float]]

Stitch together multiple signals.

Input:

• time_domain_list (list of dicts): A list of dictionaries, each containing the following keys and values: ‘amplitude_type’ as string, the type of the time domain data. ‘amplitude_units’ as string, the units of the amplitude values. ‘time_stamps_units’ as string, the units of the time stamps. ‘time_stamps’ as list of floats, the time stamps of the time domain.

Output:

• Returns the stitched time_stamps and amplitudes as tuple with two lists of floats.

haskoning_atr_tools.signal_processing_tool.time_domain.tools.zero_pad_time_domain_data(time_stamps: List[float], amplitudes: List[float], pad_from: str = 'both', number_of_items: int | None = None, time_amount: float | None = None, percentage_to_pad: float | None = None) → Tuple[List[float], List[float]]

Zero pad the signal at the front, back, or both given different cues.

Input:

• time_stamps (list of float): List of time stamps.

• amplitudes (list of float): List of amplitude values.

• pad_from (str): Where to pad the signal. Options are ‘front’, ‘back’, ‘both’. Defaults to ‘both’.

• number_of_items (int): Optional input for the number of items to pad.

• time_amount (float): Optional input for the amount of time to pad.

• percentage_to_pad (float): Optional input for the percentage of the signal to pad (10 = 10%).

Output:

• Returns tuple with padded time stamps as list of floats and amplitudes as list of floats.

Frequency domain tools

class haskoning_atr_tools.signal_processing_tool.frequency_domain.data.FrequencyDomainData(parent: FrequencyDomainCollection, name: str, amplitude_type: str = 'Unknown', amplitudes: ~typing.List[float] = <factory>, amplitude_units: str = 'Unknown', frequencies: ~typing.List[float] = <factory>, frequency_units: str = 'Unknown', phase_angles: ~typing.List[float] | None = <factory>, phase_angle_units: str = 'Unknown', power_density: ~typing.List[float] | None = None, power_units: str = 'Unknown', energy_density: ~typing.List[float] | None = None, energy_units: str = 'Unknown', max_amplitude: float = None, freq_at_max_amplitude: float = None, freq_increment: float = None, significant_amplitudes: ~typing.List[~typing.Tuple[float, float, float]] = None, window_used: str = 'rectangular', signal_duration: float = None, rms_spectrum: ~typing.List[float] | None = None, total_rms: float | None = None)

Bases: object

The FrequencyDomainData class represents individual data sets of frequency spectrum quantities.

Input:

• parent (FrequencyDomainCollection): The parent collection that this data belongs to.

• name (str): The name of the frequency spectrum data.

• amplitude_type (str): The type of the frequency spectrum data. Example: velocity, acceleration, pressure. Default value ‘Unknown’.

• amplitudes (list of floats): A list of amplitude values for the frequency spectrum data.

• amplitude_units (str): The units of the amplitude values. Defaults value ‘Unknown’.

• frequencies (list of floats): A list of frequencies for the frequency spectrum data.

• frequency_units (str): The units of the frequencies. Defaults value ‘Unknown’.

• phase_angles (list of floats): A list of phase angles for the frequency spectrum data.

• phase_angle_units (str): The units of the phase angles. Defaults to “Unknown”.

• power_density (list of floats): A list of power density values for the frequency spectrum data.

• power_units (str): The units of the power density values. Default value ‘Unknown’.

• energy_density (list of floats): A list of energy density values for the frequency spectrum data.

• energy_units (str): The units of the energy density values. Default value ‘Unknown’.

• max_amplitude (float): The maximum amplitude value in the frequency spectrum data.

• freq_at_max_amplitude (float): The frequency at which the maximum amplitude occurs.

• freq_increment (float, optional): The frequency increment between data points.

• significant_amplitudes (list of tuples with 3 floats): A list of significant amplitudes with their corresponding frequencies and phases.

• window_used (str): The window function used for the frequency domain transformation. Default value None, no window function applied.

• signal_duration (float): Optional input for the duration of the signal, in [s]. May be required for certain functions applied on the FrequencyDomainData.

• rms_spectrum (list of floats): A list of RMS values for the frequency spectrum data.

• total_rms (float): The total RMS value of the frequency spectrum data.

check_frequency_data() → None

Checks the frequency data for consistency and validity.

convert_to_time_domain(name: str | None = None, collection_name: str | None = None) → TimeDomainData

Method to convert the frequency domain data to time domain as TimeDomainData using inverse FFT. This method uses the inverse Fast Fourier Transform (iFFT) to convert frequency domain data to time domain data. It creates a new TimeDomainData object with the transformed data.

Input:

• name (str): Optional input for the name for the TimeDomainData. If not given, its created form the name from the FrequencyDomainData self.

• collection_name (str): Optional input for the name of the collection to which the time domain data belongs. If not provided, it uses the collection name from the FrequencyDomainData self.

Output:

• Returns the time domain data created from the frequency domain data.

• The time domain data is added to the time domain collection with the requested name.

find_max_amplitude(frequency_range: List[float] | None = None) → Tuple[float, float]

Method to find the maximum amplitude within a given frequency range.

Input:

• frequency_range (list of floats): The frequency range to search for the maximum amplitude.

Output:

• Returns tuple with the maximum amplitude as float and its corresponding frequency as float.

find_significant_amplitudes(amplitude_threshold: float | None = None) → List[Tuple[float, float, float]]

Method identifies the significant amplitudes and assigns them as an attribute to the FrequencyDomainData.

Input:

• amplitude_threshold (float): Optional input for the threshold for significant amplitudes. Default value None, in which case 10% of max amplitude is used.

Output:

• Returns list of tuples with the significant amplitudes as float, the frequencies as float and phase angles as float, in [deg].

get_energy_density(window_used: str | None = None, recalculate: bool = False) → list[float]

Calculate the energy density by multiplying the power density by the signal duration.

Input:

• window_used (str): The window used for the FFT. If not provided, use self.window_used.

• recalculate (bool): Select to recalculate the energy density overwriting the existing data. Default value is False

Output:

• Returns the energy density values as list of floats.

get_power_density(window_used: str | None = None, recalculate: bool = False) → List[float]

Method calculates or returns the power density of the frequency domain data.

Input:

• window_used (str): The window used for the FFT. If not provided, use self.window_used.

• recalculate (bool): Select to recalculate the power density overwriting the existing data. Default value is False

Output:

• Returns the power density values as list of floats.

get_rms_spectrum(window_used: str | None = None, recalculate: bool = False) → List[float]

Method to calculate or return the RMS spectrum of the frequency domain data.

Input:

• window_used (str): The window used for the FFT. If not provided, use self.window_used.

• recalculate (bool): Select to recalculate the energy density overwriting the existing data. Default value is False

Output:

• Returns the RMS spectrum values as list of floats.

get_total_rms(window_used: str | None = None, recalculate: bool = False) → float

Method to calculate the total RMS of the frequency domain data.

Input:

• window_used (str): The window used for the FFT. If not provided, use self.window_used.

• recalculate (bool): Select to recalculate the energy density overwriting the existing data. Default value is False

Output:

• Returns the total RMS value as float.

octaves(third_octave: bool = False, level_type: str = 'RMS') → Dict[float, float]

Method to calculate the octave or third-octave bands of the FrequencyDomainData object depending on the octave type.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

Output:

• Returns the dictionary of the octave or third-octave bands.

plot(spectrum_type: str = 'amplitude', log_scale_x: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | str | None = None, show: bool = True, line_width: float = 1, plot_max_values: bool = False) → Path | None

Plots the specified spectrum typ of the FrequencyDomainData object.

Input:

• spectrum_type (str): The type of spectrum to plot. Options are: ‘amplitude’, ‘power density’ or ‘psd’, ‘energy density’ or ‘esd’, and ‘rms’ or ‘linear’. Default value is ‘amplitude’.

• log_scale_x (bool): Select to set the x-axis to a logarithmic scale. Default value is False.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• line_width (float): Change line width, default = 1.

• plot_max_values (bool): Select to calculate the maximum y value for each line and add it to the plot. Default value is False.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

plot_octaves(third_octave: bool = False, level_type: str | None = None, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | str | None = None, show: bool = True, bar_width: float = 1, show_bar_values: bool = True, decimals_displayed: int = 2) → Path | None

Plot the octave or third-octave bands of the FrequencyDomainData object.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• bar_width (float): The width of the bars. Default value is 1.

• show_bar_values (bool): Select to display the labels on the bars. Default value is True.

• decimals_displayed (int): The number of decimal places for formatting values. Default value is 2.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

class haskoning_atr_tools.signal_processing_tool.frequency_domain.collection.FrequencyDomainCollection(parent: ATRProject, name: str, frequency_domain_data: ~typing.List[~haskoning_atr_tools.signal_processing_tool.frequency_domain.data.FrequencyDomainData] = <factory>)

Bases: object

The FrequencyDomainCollection class represents a collection of frequency spectrum objects.

Input:

• name (str): The name of the frequency domain collection.

• parent (obj): The parent project or entity that this collection belongs to.

• frequency_domain_data (list): List of FrequencyDomainData objects that are part of the collection.

add_frequency_domain_data_to_collection(frequency_domain_data: FrequencyDomainData) → None

Method adds a FrequencyDomainData object to the frequency_domain_data.

Input:

• frequency_domain_data (FrequencyDomainData): The FrequencyDomainData object to be added to the collection.

Output:

• FrequencyDomainCollection is added to the collection.

averaged_octaves(third_octave: bool = False, level_type: str = 'RMS') → Dict[float, float]

Calculate the average octave or third-octave bands of all the FrequencyDomainData object in the FrequencyDomainCollection, for different octave type.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

Output:

• Returns dictionary of the octave or third-octave bands.

check_frequency_alignment() → bool

Check if frequencies align across all FrequencyDomainData objects in the collection.

convert_collection_to_time_domain(name: str = None) → TimeDomainCollection

Method converts the frequency domain collection to a time domain collection.

Input:

• name (str): The name of the collection to which the time domain data belongs. Default value is None, in which case the name of the frequency domain collection is used.

Output:

• Returns the converted time domain collection.

find_collections_max_amplitudes(frequency_range: List[float] | None = None) → Dict[str, Tuple[float, float]]

Method to find the maximum amplitude within a given frequency range for all frequency domain objects in the collection.

Input:

• frequency_range (list of floats): The frequency range to search for the maximum amplitude.

Output:

• Returns dictionary with name of the frequency domain object and value tuple with the maximum amplitude as float and its corresponding frequency as float.

find_collections_significant_amplitudes(amplitude_threshold: float | None = None) → Dict[str, List[Tuple[float, float, float]]]

Method to find the significant amplitudes, with optional threshold, for all frequency domain objects in the collection.

Input:

• amplitude_threshold (float): Optional input for the threshold for significant amplitudes. Default value None, in which case 10% of max amplitude is used.

Output:

• Returns dictionary with name of the frequency domain object and value the significant amplitudes as float, the frequencies as float and phase angles as float, in [deg].

get_average_amplitudes() → Tuple[List[float], List[float]]

Method calculates the average amplitudes across all FrequencyDomainData objects in the collection.

Output:

• Returns tuple of lists with the average amplitudes and frequencies.

get_average_power_density() → Tuple[List[float], List[float]]

Calculate the average power density of all the FrequencyDomainData objects in the FrequencyDomainCollection.

Output:

• Returns tuple of two lists of floats, the average power densities and frequencies.

plot(spectra_type: str | List[str] = None, log_scale_x: bool = False, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | str | None = None, show: bool = True, line_width: float = 1.0, plot_max_values: bool = False) → List[Path] | None

Method to plot the specified spectra type(s) of the FrequencyDomainData objects in the collection.

Input:

• spectra_type (str or list of str): The type(s) of spectra to plot. Options are: ‘amplitude’, ‘power density’ or ‘psd’, ‘energy density’ or ‘esd’, and ‘rms’ or ‘linear’. If None, all spectra types are plotted.

• log_scale_x (bool): Select to set the x-axis to a logarithmic scale. Default value is False.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• line_width (float): Change line width, default = 1.

• plot_max_values (bool): Select to calculate the maximum y value for each line and add it to the plot. Default value is False.

Output:

• Returns the paths of the files if the plots were selected to be saved to a file, otherwise returns None.

plot_octaves(third_octave: bool = False, level_type: str | None = None, log_scale_y: bool = False, x_lim: List[float] | None = None, y_lim: List[float] | None = None, file: Path | str | None = None, show: bool = True, bar_width: float = 1, show_bar_values: bool = True, decimals_displayed: int = 2) → Path | None

Plot the octave or third-octave bands for all FrequencyDomainData objects in the collection.

Input:

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

• level_type (str): Specifies the method used to compute the level of each frequency band. Options include ‘peak’, ‘energy’, ‘power’, and ‘RMS’. Default value is ‘RMS’.

• log_scale_y (bool): Select to set the y-axis to a logarithmic scale. Default value is False.

• x_lim (list of float): Optional list to set limits [bottom limit, top limit] for the x-axis. Default value is None.

• y_lim (list of float): Optional list to set limits [bottom limit, top limit] for the y-axis. Default value is None.

• file (Path): Provide the full path and filename for the image of the graph to be created. The image is a png-file, if the suffix is omitted it will be added. An error will occur if the picture format is set to a non-supported format. It is also possible to provide the folder only, the title is used as filename.

• show (bool): Select to plot the graph in the environment when running the script. Default value True.

• bar_width (float): The width of the bars. Default value is 1.

• show_bar_values (bool): Select to display the labels on the bars. Default value is True.

• decimals_displayed (int): The number of decimal places for formatting values. Default value is 2.

Output:

• Returns the path of the file if the plot was selected to be saved to a file, otherwise returns None.

haskoning_atr_tools.signal_processing_tool.frequency_domain.create.create_frequency_domain_collection(project, name: str, frequency_domain_data_list: List[FrequencyDomainData]) → FrequencyDomainCollection

Creates a new frequency domain collection and adds it to the project.

Input:

• name (str): The name of the new frequency domain collection.

• frequency_domain_data_list (list of obj): A list of frequency domain data objects to include in the collection.

Output:

• Returns the newly created frequency domain collection.

• The collection is added to the frequency domain collections in project.

haskoning_atr_tools.signal_processing_tool.frequency_domain.create.create_frequency_domain_data(project, name: str, values: List[float], frequencies: List[float], amplitude_type: str, value_units: str, phase_angles: List[float] = None, spectrum_type: str = 'amplitude', frequency_units: str = 'Hz', phase_angle_units: str = 'degrees', signal_duration: float = None, window_used: str = None, collection_name: str = 'Unknown') → FrequencyDomainData

Creates a new frequency domain data object and adds it to the specified collection in the project.

Input:

• project (obj): Project object containing collections of objects and project variables.

• name (str): The name of the new frequency domain data.

• values (list of floats): A list of values for the frequency domain data. These can be amplitudes, power density, or energy density.

• frequencies (list of floats): A list of frequencies corresponding to the values.

• amplitude_type (str): The type of the frequency domain data. For example: velocity, acceleration, or pressure.

• value_units (str): The units of the values.

• phase_angles (list of floats): Optional input for the phase angle values for the frequency domain data. Default value is None.

• spectrum_type (str): The type of spectrum, select from ‘amplitude’, ‘power’, ‘psd’, ‘energy’, or ‘esd’. Default value is ‘amplitude’.

• frequency_units (str): The units of the frequency values. Default value is ‘Hz’.

• phase_angle_units (str): The units of the phase angles. Default value ‘degrees’.

• signal_duration (float): Optional input for the duration of the signal, in [s]. Default value is None.

• window_used (str): Optional input for the window used if used in conversion from time domain to frequency domain. Default value is None.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created frequency domain data object based on the provided spectrum values.

haskoning_atr_tools.signal_processing_tool.frequency_domain.create.create_frequency_domain_data_from_file(project, file: str | Path, frequency_column: str | int, value_column: str | int, value_units: str, name: str | None = None, spectrum_type: str = 'amplitude', amplitude_type: str = 'Spectrum', frequency_units: str = 'Hz', skip_rows: int = 0, header: bool = True, signal_duration: float | None = 10, collection_name: str = 'Unknown Collection') → FrequencyDomainData

Creates a FrequencyDomainData object from a file (CSV or Excel).

Input:

• project (obj): Project object containing collections of objects and project variables.

• file (Path or str): The file path to the data file.

• frequency_column (str or int): The name or index of the column containing frequency values.

• value_column (str or int): The name or index of the column containing values for the spectrum.

• value_units (str): The units of the values.

• name (str): The name of the new frequency domain data. Default value is the name of the file.

• spectrum_type (str): The type of spectrum, select from ‘amplitude’, ‘power’, ‘psd’, ‘energy’, or ‘esd’. Default value is ‘amplitude’.

• amplitude_type (str): The type of the frequency domain data. Default value is ‘Spectrum’.

• frequency_units (str): The units of the frequency values. Default value is ‘Hz’.

• skip_rows (int): Optional input for the number of rows to skip at the beginning of the file. Defaults to 0.

• header (bool): Select whether the file contains a header row. Defaults to True.

• duration (float): Optional input for the duration of the signal, in [s]. Default value is 10 seconds.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created frequency domain data object based on the imported spectrum.

• FrequencyDomainData is added to the specified FrequencyDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.frequency_domain.create.create_harmonic_spectrum_frequency_domain_data(project, name: str, amplitudes: float | List[float], frequencies: float | List[float], amplitude_units: str, phase_angles: float | List[float] | None = None, lowest_frequency: float = 0.1, highest_frequency: float = 1000, sampling_rate: float = 0.1, amplitude_type: str = 'Harmonic Spectrum', frequency_units: str = 'Hz', phase_angle_units: str = 'degrees', signal_duration: float = None, window_used: str = None, collection_name: str = 'Unknown Collection') → FrequencyDomainData

Creates a harmonic spectrum FrequencyDomainData object.

Input:

• project (obj): Project object containing collections of objects and project variables.

• name (str): The name of the new frequency domain data.

• amplitudes (float or list of floats): Amplitudes of the harmonics. Can be provided as a single float or a list of floats.

• frequencies (float or list of floats): Frequencies of the harmonics. Can be provided as a single float or a list of floats.

• amplitude_units (str): The units of the amplitudes.

• phase_angles (float or list of floats): Optional input for the phase angle values for the harmonics. Can be a single float or a list of floats. Defaults to None.

• lowest_frequency (float): Lowest frequency in the spectrum. Defaults to 0.1 Hz.

• highest_frequency (float): Highest frequency in the spectrum. Defaults to 1000 Hz.

• sampling_rate (float): Frequency sampling rate. Defaults to 0.1.

• amplitude_type (str): The type of the frequency domain data. Default value is ‘Harmonic Spectrum’.

• spectrum_type (str): The type of spectrum, select from ‘amplitude’, ‘power’, ‘psd’, ‘energy’, or ‘esd’. Default value is ‘amplitude’.

• frequency_units (str): The units of the frequency values. Default value is ‘Hz’.

• phase_angle_units (str): The units of the phase angles. Default value ‘degrees’.

• signal_duration (float): Optional input for the duration of the signal, in [s]. Default value is None.

• window_used (str): Optional input for the window used if used in conversion from time domain to frequency domain. Default value is None.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created frequency domain data object based on the harmonic spectrum.

• FrequencyDomainData is added to the specified FrequencyDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.frequency_domain.create.create_white_noise_spectrum_frequency_domain_data(project, name: str, amplitude_units: str, lowest_frequency: float = 0.1, highest_frequency: float = 1000, sampling_rate: float = 0.1, noise_amplitude: float = 1, amplitude_type: str = 'White Noise Spectrum', frequency_units: str = 'Hz', signal_duration: float = None, window_used: str = None, collection_name: str = 'Unknown Collection') → FrequencyDomainData

Creates a white noise spectrum FrequencyDomainData object.

Input:

• project (obj): Project object containing collections of objects and project variables.

• name (str): The name of the new frequency domain data.

• amplitude_units (str): The units of the amplitudes.

• lowest_frequency (float): Lowest frequency in the spectrum, in [Hz]. Defaults to 0.1 Hz.

• highest_frequency (float): Highest frequency in the spectrum, in [Hz]. Defaults to 1000 Hz.

• sampling_rate (float): Frequency sampling rate, in [Hz]. Defaults to 0.1 Hz.

• noise_amplitude (float): Amplitude of the white noise. Defaults to 1.

• amplitude_type (str): The type of the frequency domain data. Default value is ‘White Noise Spectrum’.

• frequency_units (str): The units of the frequency values. Default value is ‘Hz’.

• signal_duration (float): Optional input for the duration of the signal, in [s]. Default value is None.

• window_used (str): Optional input for the window used if used in conversion from time domain to frequency domain. Default value is None.

• collection_name (str): The name of the collection to which this data will be added. Defaults to ‘Unknown Collection’.

Output:

• Returns the newly created frequency domain data object based on the white noise spectrum.

• FrequencyDomainData is added to the specified FrequencyDomainCollection in the project.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.convert_double_sided_to_real_single_sided_spectrum(spectrum_values: ndarray, frequencies: ndarray) → Tuple[ndarray, ndarray, ndarray]

Function to convert a complex double-sided spectrum to a real single-sided spectrum.

In the case of spectrum form FFT: If the input signal is not complex, a FT creates a spectrum mirrored around the DC frequency, and it goes up to +- nyquist frequency. So the negative frequency section is redundant.

Note

This function assumes that the positive frequencies are in order. This matches with NumPy and SciPy FFT functions.

Input:

• spectrum_values (numpy array): The double-sided spectrum values.

• frequencies (numpy array): The double-sided spectrum frequencies.

Output:

• Returns tuple with three numpy arrays: Single-sided amplitude spectrum, corresponding phase angles in degrees and corresponding positive frequencies.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.find_max_amplitude(amplitudes: List[float], frequencies: List[float], frequency_range: List[float] | None = None) → Tuple[float, float]

Function to find the maximum amplitude within a given frequency range.

Input:

• amplitudes (list of floats): The list of amplitudes.

• frequencies (list of floats): The list of frequencies.

• frequency_range (list of floats): Optional input for the frequency range to search for the maximum amplitude. Default value is None, the entire range will be used.

Output:

• Returns tuple with the maximum amplitude as float and its corresponding frequency as float.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.identify_significant_amplitudes(amplitudes: List[float], frequencies: List[float], phase_angles: List[float] | None = None, amplitude_threshold: float = None) → List[Tuple[float, float, float | None]]

Function to identify significant local maxima amplitudes and their respective frequency and phase angle pairs.

Input:

• amplitudes (list of floats): List of amplitude values.

• frequencies (list of floats): List of frequency values.

• phase_angles (list of floats): List of phase angles in radians. Default value is None.

• amplitude_threshold (float): Optional input for the threshold for significant amplitudes. Defaults value is None, which defaults to 10% of max amplitude.

Output:

• Returns list of tuples containing significant amplitudes, frequencies and phase angles (if provided).

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.octave_form_frequency_domain_data(quantities: List[float], frequencies: List[float], calculation_method: str = 'cumulative', third_octave: bool = False) → Dict[float, float]

Calculate octave or third-octave bands directly from frequency domain content.

Input:

• quantities (list of floats): The quantities in frequency domain.

• frequencies (list of floats): The frequency values.

• calculation_method (str): The calculation method, select from ‘peak’, ‘mean’, or ‘cumulative’. Default value is ‘cumulative’.

• third_octave (bool): Input determines the frequency resolution of the output bands. When third-octave is selected the function calculates third-octave bands, which divide each octave into three narrower bands. Default value is False, the function calculates standard octave bands, which group frequencies more broadly.

Output:

• A dictionary with center frequencies as keys and corresponding band values as values.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.power_density_form_amplitude_spectrum(amplitude_spectrum: List[float], frequencies: List[float], window_used: str = 'rectangular') → list[float]

Function to calculate the power spectral density (PSD) from the amplitude spectrum. The PSD is the square of the amplitude spectrum.

Input:

• amplitude_spectrum (list of floats): The amplitude spectrum values.

• frequencies (list of floats): The list of frequencies.

• window_used (str): Optional input for the window used for the FFT. Default value is ‘rectangular’ which is same as no windowing.

Output:

• Returns list of power spectral density (PSD) values as floats.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.reconstruct_2sided_complex_spectrum(spectrum_values: List[float], phase_angle: List[float] | None = None, frequencies: List[float] | None = None) → Tuple[List[float], List[float]]

Function to reconstruct the complete complex spectrum from real amplitudes and phase angles, form the positive frequencies. If frequencies are provided, they are also mirrored on the negative side.

Input:

• spectrum_values (list of floats): The real values in the frequency domain, form the positive frequencies.

• phase_angle (list of floats): Optional input for the phase angles in the frequency domain, form the positive frequencies. Default value is None, in which case an array of zeros will be used.

• frequencies (list of floats): Optional input for the frequency values in the frequency domain, form the positive frequencies. Default value is None, in which case only the complex spectrum is returned.

Output:

• Returns tuple with the complete complex spectrum as list of floats and the mirrored frequencies as list of floats.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.rms_from_psd(power_density_spectrum_segment: List[float], freq_increment: float) → float

Function to calculate the root-mean-square (RMS) value from a segment of the power spectral density (PSD). If the entries PSD is provided, the RMS is the square root of the integral of the PSD. The RMS is the square root of the integral of the PSD segment.

Input:

• power_density_spectrum_segment (list of floats): The power spectral density values.

• freq_increment (float): The frequency increment or Delta f.

Output:

• Returns the root-mean-square (RMS) value as float.

haskoning_atr_tools.signal_processing_tool.frequency_domain.tools.time_domain_data_from_frequency_domain(amplitudes: List[float], phase_angle: List[float], frequencies: List[float]) → Tuple[List[float], List[float]]

Function to perform IFFT on the frequency domain data and manipulated to obtain time domain data.

Input:

• amplitudes (list of floats): The amplitude values of the signal in the frequency domain.

• phase_angle (list of floats): The phase angles of the signal in the frequency domain.

• frequencies (list of floats): The frequencies of the signal in the frequency domain.

Output:

• Returns tuple with the time stamps and the IFFT values of the signal in the time domain.