.. _atr_signal_processing-label: ======================== Signal processing module ======================== The Signal Processing Tool is a Python library for signal processing, specifically focusing on time and frequency domain analysis. It provides a framework for creating, importing, editing, manipulating and analysing signals. The tool is developed by the Advanced Technology and Research (ATR) Competence Center team of Haskoning as part of the AT&R package. .. warning:: The Signal Processing Tool is currently under active development. Functionality may change in future updates, and formal validation is still pending. Please verify your results carefully before using them in critical applications. Purpose and Key Features ======================== The primary purpose of the Signal Processing Tool is to simplify and streamline the process of signal processing. Key features include: - Time Domain Analysis: Tools for creating, importing, editing, manipulating, and analysing time domain signals. - Frequency Domain Analysis: Functions for converting time domain signals to frequency domain and analysing frequency spectra. - Signal Manipulation: Utilities for filtering, cropping, stitching and combining signals. - Visualisation: Functions for plotting time and frequency domain data. Quick Start Guide ================= Before you start with the Signal Processing Tool, make sure to install the latest version of the AT&R package. Refer to :ref:`ATR installation guide`. Start the project with the following code: .. code-block:: python from haskoning_atr_tools import ATRProject project = ATRProject(name='My Project', location='Building location', project_code='P-BH1999') Basic Usage Example Time Signal ------------------------------- Continuing from the previous step in this section examples are provided for processing time signals. Step 1 - Create TimeDomainData object ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In this step you need to provide or create a signal and add the time domain data to your project. You can create a signal to use, import a signal from a file or use one of the built-in signal creators. The options for creating the time domain data object are: A. **Manual creation of signal**: Specify the amplitude values and time stamps in lists. .. code-block:: python my_time_domain_data = project.create_time_domain_data( name='Manual Time Data', amplitude_type='velocity', amplitudes=[0.1, 0.2, 0.3, 0.4], time_stamps=[0, 1, 2, 3], amplitude_units='m/s', time_stamps_units='s', collection_name='Collection #1') B. **Import signal**: Use a method to import a file with time domain data. .. code-block:: python my_time_domain_data = project.create_time_domain_data_from_sigicom_csv( file='path/to/your/sigicom_file.csv', name='Sigicom Time Domain Data', amplitude_type='velocity', amplitude_units='mm/s', time_stamps_units='seconds', collection_name='Example Collection') C. **Use built in signal creators**: Use a method to create a signal. .. code-block:: python my_time_domain_data = my_project.create_sinusoidal_time_domain_data( name='Example Sinusoidal Signal', harmonic_amplitudes=[1.0, 0.3], harmonic_frequencies=[10.0, 20.0], harmonic_phase_shift=[0.0, 45.0], duration=5.0, sampling_rate=100, collection_name='Example Collection', amplitude_type='displacement', amplitude_units='mm', time_stamps_units='seconds') More options available for the user to create time domain data are described in the advanced section on :ref:`creating signals`. Step 2 - Edit and Manipulate Time Domain Data ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The tool provides different options to edit the input signal. Tools to crop, combine, scale, shift, rotate, filter and other manipulations are available: .. code-block:: python cropped_time_domain_data = my_time_domain_data.crop_time_domain(from_front=True, time_amount=2) More functions available for the user to edit and manipulate time domain data are described in the advanced section :ref:`edit and manipulate signals`. Step 3 - Convert to Frequency Domain ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The most common method to convert time domain data to frequency domain is the **Fourier Transform**. For discrete signals (e.g., sampled data), we use the **Discrete Fourier Transform (DFT)**, often computed using the **Fast Fourier Transform (FFT)** algorithm. With the following syntax the time domain data is converted to frequency domain: .. code-block:: python frequency_data = my_time_domain_data.convert_to_frequency_domain(window_type='Hanning') More options available for the user when converting time domain data to frequency domain are described in the advanced section :ref:`conversion to frequency domain`. Step 4 - Signal Properties ^^^^^^^^^^^^^^^^^^^^^^^^^^ You can extract specific properties of the signal in either the time domain or the frequency domain, depending on your analysis needs. Commonly requested properties include: - Significant amplitudes - Peak values - Root Mean Square (RMS) - Dominant frequencies - Energy content For example, to retrieve significant amplitudes from the frequency domain data: .. code-block:: python significant_amplitudes = freq_data.find_significant_amplitudes(amplitude_threshold=0.1) Methods for more properties of the frequency domain data are described in the advanced section :ref:`details on the time and frequency domain properties`. Step 5 - Plot the Data ^^^^^^^^^^^^^^^^^^^^^^ The signal processing tool provides built-in functionality to visualise both time domain and frequency domain data. To generate plots, simply call the `plot` method on the respective data object: .. code-block:: python my_time_domain_data.plot() frequency_data.plot() All settings available for plotting results of the signal processing tool are described in the advanced section :ref:`plotting`. .. note:: The procedure in the quick start guide shows a basic workflow. Different signals can be combined in the collections attribute of Project, where most of the methods are available to apply on all the signals in a collection and create combined plots. .. note:: It is also possible to create a spectrum and convert it to time domain data. Refer to the advanced section :ref:`creating spectra` for more information. This tool is designed to help you extract meaningful insights with ease when you're working with vibration data, seismic signals, or custom time series. We’re continuously improving the tool and welcome your feedback, ideas, and contributions. If you’ve developed new features, discovered interesting use cases, or have suggestions for enhancements, we’d love to hear from you! .. tip:: **Get involved:** Share your developments, report issues, or contribute via our `Azure repository `_. Advanced topics =============== In the quick-guide the basic steps to create and process a time domain signal were provided. More details on each step are provided in the following sections. .. toctree:: :maxdepth: 2 creating_signals creating_spectra edit_signals transform_signals signal_properties plotting Background information ====================== This section provides a brief theoretical overview of signal processing concepts to help you better understand the tool’s methods and capabilities. It also supports selecting the most suitable settings for your specific use case. .. toctree:: :maxdepth: 2 theoretical_background References ========== The following sections provide detailed documentation of the available classes, methods, and functions within the signal processing tool. .. toctree:: :maxdepth: 1 code_references