paradigma 0.3.2__py3-none-any.whl → 0.4.1__py3-none-any.whl

paradigma/pipelines/tremor_pipeline.py

@@ -0,0 +1,299 @@
+import tsdf
+import json
+import pandas as pd
+import numpy as np
+from pathlib import Path
+from scipy import signal
+from scipy.stats import gaussian_kde
+
+from paradigma.classification import ClassifierPackage
+from paradigma.constants import DataColumns
+from paradigma.config import TremorConfig
+from paradigma.feature_extraction import compute_mfccs, compute_power_in_bandwidth, compute_total_power, extract_frequency_peak, \
+    extract_tremor_power
+from paradigma.segmenting import tabulate_windows, WindowedDataExtractor
+from paradigma.util import get_end_iso8601, write_df_data, read_metadata, aggregate_parameter
+
+
+def extract_tremor_features(df: pd.DataFrame, config: TremorConfig) -> pd.DataFrame:
+    """
+    This function groups sequences of timestamps into windows and subsequently extracts 
+    tremor features from windowed gyroscope data.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The input DataFrame containing sensor data, which includes time and gyroscope data. The data should be
+        structured with the necessary columns as specified in the `config`.
+
+    config : TremorConfig
+        Configuration object containing parameters for feature extraction, including column names for time, gyroscope data,
+        as well as settings for windowing, and feature computation.
+
+    Returns
+    -------
+    pd.DataFrame
+        A DataFrame containing extracted tremor features and a column corresponding to time.
+    
+    Notes
+    -----
+    - This function groups the data into windows based on timestamps.
+    - The input DataFrame must include columns as specified in the `config` object for proper feature extraction.
+
+    Raises
+    ------
+    ValueError
+        If the input DataFrame does not contain the required columns as specified in the configuration or if any step in the feature extraction fails.
+    """
+    # group sequences of timestamps into windows
+    windowed_cols = [DataColumns.TIME] + config.gyroscope_cols
+    windowed_data = tabulate_windows(df, windowed_cols, config.window_length_s, config.window_step_length_s, config.sampling_frequency)
+
+    extractor = WindowedDataExtractor(windowed_cols)
+
+    # Extract the start time and gyroscope data from the windowed data
+    idx_time = extractor.get_index(DataColumns.TIME)
+    idx_gyro = extractor.get_slice(config.gyroscope_cols)
+
+    # Extract data
+    start_time = np.min(windowed_data[:, :, idx_time], axis=1)
+    windowed_gyro = windowed_data[:, :, idx_gyro]
+
+    df_features = pd.DataFrame(start_time, columns=[DataColumns.TIME])
+    
+    # transform the signals from the temporal domain to the spectral domain and extract tremor features
+    df_spectral_features = extract_spectral_domain_features(windowed_gyro, config)
+
+    # Combine spectral features with the start time
+    df_features = pd.concat([df_features, df_spectral_features], axis=1)
+
+    return df_features
+
+
+def detect_tremor(df: pd.DataFrame, config: TremorConfig, full_path_to_classifier_package: str | Path) -> pd.DataFrame:
+    """
+    Detects tremor in the input DataFrame using a pre-trained classifier and applies a threshold to the predicted probabilities.
+
+    This function performs the following steps:
+    1. Loads the pre-trained classifier and scaling parameters from the provided directory.
+    2. Scales the relevant features in the input DataFrame (`df`) using the loaded scaling parameters.
+    3. Makes predictions using the classifier to estimate the probability of tremor.
+    4. Applies a threshold to the predicted probabilities to classify whether tremor is detected or not.
+    5. Checks for rest tremor by verifying the frequency of the peak and below tremor power.
+    6. Adds the predicted probabilities and the classification result to the DataFrame.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The input DataFrame containing extracted tremor features. The DataFrame must include
+        the necessary columns as specified in the classifier's feature names.
+
+    config : TremorConfig
+        Configuration object containing settings for tremor detection, including the frequency range for rest tremor.
+
+    full_path_to_classifier_package : str | Path
+        The path to the directory containing the classifier file, threshold value, scaler parameters, and other necessary input
+        files for tremor detection.
+
+    Returns
+    -------
+    pd.DataFrame
+        The input DataFrame (`df`) with two additional columns:
+        - `PRED_TREMOR_PROBA`: Predicted probability of tremor based on the classifier.
+        - `PRED_TREMOR_LOGREG`: Binary classification result (True for tremor, False for no tremor), based on the threshold applied to `PRED_TREMOR_PROBA`.
+        - `PRED_TREMOR_CHECKED`: Binary classification result (True for tremor, False for no tremor), after performing extra checks for rest tremor on `PRED_TREMOR_LOGREG`.
+        - `PRED_ARM_AT_REST`: Binary classification result (True for arm at rest or stable posture, False for significant arm movement), based on the power below tremor.
+
+    Notes
+    -----
+    - The threshold used to classify tremor is loaded from a file and applied to the predicted probabilities.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the classifier, scaler, or threshold files are not found at the specified paths.
+    ValueError
+        If the DataFrame does not contain the expected features for prediction or if the prediction fails.
+
+    """
+
+    # Load the classifier package
+    clf_package = ClassifierPackage.load(full_path_to_classifier_package)
+
+    # Set classifier
+    clf = clf_package.classifier
+    feature_names_scaling = clf_package.scaler.feature_names_in_
+    feature_names_predictions = clf.feature_names_in_
+
+    # Apply scaling to relevant columns
+    scaled_features = clf_package.transform_features(df.loc[:, feature_names_scaling])
+
+    # Replace scaled features in a copy of the relevant features for prediction
+    X = df.loc[:, feature_names_predictions].copy()
+    X.loc[:, feature_names_scaling] = scaled_features
+
+    # Get the tremor probability 
+    df[DataColumns.PRED_TREMOR_PROBA] = clf_package.predict_proba(X)
+
+    # Make prediction based on pre-defined threshold
+    df[DataColumns.PRED_TREMOR_LOGREG] = (df[DataColumns.PRED_TREMOR_PROBA] >= clf_package.threshold).astype(int)
+
+    # Perform extra checks for rest tremor 
+    peak_check = (df['freq_peak'] >= config.fmin_rest_tremor) & (df['freq_peak']<=config.fmax_rest_tremor) # peak within 3-7 Hz
+    df[DataColumns.PRED_ARM_AT_REST] = (df['below_tremor_power'] <= config.movement_threshold).astype(int) # arm at rest or in stable posture
+    df[DataColumns.PRED_TREMOR_CHECKED] = ((df[DataColumns.PRED_TREMOR_LOGREG]==1) & (peak_check==True) & (df[DataColumns.PRED_ARM_AT_REST] == True)).astype(int)
+    
+    return df
+
+
+def aggregate_tremor(df: pd.DataFrame, config: TremorConfig):
+    """
+    Quantifies the amount of tremor time and tremor power, aggregated over all windows in the input dataframe.
+    Tremor time is calculated as the number of the detected tremor windows, as percentage of the number of windows 
+    without significant non-tremor movement (at rest). For tremor power the following aggregates are derived:
+    the median, mode and percentile of tremor power specified in the configuration object. 
+    
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The input DataFrame containing extracted tremor features. The DataFrame must include
+        the necessary columns as specified in the classifier's feature names.
+
+    config : TremorConfig
+        Configuration object containing the percentile for aggregating tremor power.
+
+    Returns
+    -------
+    dict
+        A dictionary with the aggregated tremor time and tremor power measures, as well as the total number of windows
+        available in the input dataframe, and the number of windows at rest.
+
+    Notes
+    -----
+    - Tremor power is converted to log scale, after adding a constant of 1, so that zero tremor power
+    corresponds to a value of 0 in log scale.
+    - The modal tremor power is computed based on gaussian kernel density estimation.
+  
+    """
+
+    nr_windows_total = df.shape[0] # number of windows in the input dataframe
+
+    # remove windows with detected non-tremor arm movements to control for the amount of arm activities performed
+    df_filtered = df.loc[df.pred_arm_at_rest == 1]
+    nr_windows_rest = df_filtered.shape[0] # number of windows without non-tremor arm movement
+
+    # calculate tremor time
+    perc_windows_tremor= np.sum(df_filtered['pred_tremor_checked']) / nr_windows_rest * 100 # as percentage of total measured time without non-tremor arm movement
+
+    # calculate aggregated tremor power measures
+    tremor_power = df_filtered.loc[df_filtered['pred_tremor_checked'] == 1, 'tremor_power']
+    tremor_power = np.log10(tremor_power+1) # convert to log scale
+    aggregated_tremor_power = {}
+    
+    for aggregate in config.aggregates_tremor_power:
+        aggregate_name = f"{aggregate}_tremor_power"
+        if aggregate == 'mode':
+            # calculate modal tremor power
+            bin_edges = np.linspace(0, 6, 301)
+            kde = gaussian_kde(tremor_power)
+            kde_values = kde(bin_edges)
+            max_index = np.argmax(kde_values)
+            aggregated_tremor_power['modal_tremor_power'] = bin_edges[max_index]
+        else: # calculate te other aggregates (e.g. median and 90th percentile) of tremor power
+            aggregated_tremor_power[aggregate_name] = aggregate_parameter(tremor_power, aggregate)
+    
+    # store aggregates in json format
+    d_aggregates = {
+        'metadata': {
+            'nr_windows_total': nr_windows_total,
+            'nr_windows_rest': nr_windows_rest
+        },
+        'aggregated_tremor_measures': {
+            'perc_windows_tremor': perc_windows_tremor,
+            'median_tremor_power': aggregated_tremor_power['median_tremor_power'],
+            'modal_tremor_power': aggregated_tremor_power['modal_tremor_power'],
+            '90p_tremor_power': aggregated_tremor_power['90p_tremor_power']
+        }
+    }
+
+    return d_aggregates
+
+
+def extract_spectral_domain_features(data: np.ndarray, config) -> pd.DataFrame:
+    """
+    Compute spectral domain features from the gyroscope data.
+
+    This function computes Mel-frequency cepstral coefficients (MFCCs), the frequency of the peak, 
+    the tremor power, and the below tremor power based on the total power spectral density of the windowed gyroscope data.
+
+    Parameters
+    ----------
+    data : numpy.ndarray
+        A 2D numpy array where each row corresponds to a window of gyroscope data.
+    config : object
+        Configuration object containing settings such as sampling frequency, window type, 
+        and MFCC parameters.
+    
+    Returns
+    -------
+    pd.DataFrame
+        The feature dataframe containing the extracted spectral features, including 
+        MFCCs, the frequency of the peak, the tremor power and below tremor power for each window.
+    """
+
+    # Initialize a dictionary to hold the results
+    feature_dict = {}
+
+    # Initialize parameters
+    sampling_frequency = config.sampling_frequency
+    segment_length_s = config.segment_length_s
+    overlap_fraction = config.overlap_fraction
+    spectral_resolution = config.spectral_resolution
+    window_type = 'hann'
+
+    # Compute the power spectral density
+    segment_length_n = sampling_frequency * segment_length_s
+    overlap_n = segment_length_n * overlap_fraction
+    window = signal.get_window(window_type, segment_length_n, fftbins=False)
+    nfft = sampling_frequency / spectral_resolution
+
+    freqs, psd = signal.welch(
+        x=data, 
+        fs=sampling_frequency, 
+        window=window, 
+        nperseg=segment_length_n,
+        noverlap=overlap_n, 
+        nfft=nfft, 
+        detrend=False, 
+        scaling='density',
+        axis=1
+    )
+
+    # Compute total power in the PSD (over the three axes)
+    total_psd = compute_total_power(psd)
+
+    # Compute the MFCC's
+    config.mfcc_low_frequency = config.fmin_mfcc
+    config.mfcc_high_frequency = config.fmax_mfcc
+    config.mfcc_n_dct_filters = config.n_dct_filters_mfcc
+    config.mfcc_n_coefficients = config.n_coefficients_mfcc
+
+    mfccs = compute_mfccs(
+        total_power_array=total_psd,
+        config=config,
+        multiplication_factor=1
+    )
+
+    # Combine the MFCCs into the features DataFrame
+    mfcc_colnames = [f'mfcc_{x}' for x in range(1, config.mfcc_n_coefficients + 1)]
+    for i, colname in enumerate(mfcc_colnames):
+        feature_dict[colname] = mfccs[:, i]
+
+    # Compute the frequency of the peak, non-tremor power and tremor power
+    feature_dict['freq_peak'] = extract_frequency_peak(freqs, total_psd, config.fmin_peak_search, config.fmax_peak_search)
+    feature_dict['below_tremor_power'] = compute_power_in_bandwidth(freqs, total_psd, config.fmin_below_rest_tremor, config.fmax_below_rest_tremor, 
+                                                                include_max=False, spectral_resolution=config.spectral_resolution, 
+                                                                cumulative_sum_method='sum')
+    feature_dict['tremor_power'] = extract_tremor_power(freqs, total_psd, config.fmin_rest_tremor, config.fmax_rest_tremor)
+
+    return pd.DataFrame(feature_dict)

paradigma/preprocessing.py

@@ -0,0 +1,363 @@
+import json
+import numpy as np
+import pandas as pd
+import tsdf
+from pathlib import Path
+from scipy import signal
+from scipy.interpolate import interp1d
+from typing import List, Tuple, Union
+from datetime import datetime
+
+from paradigma.constants import TimeUnit, DataColumns
+from paradigma.config import PPGConfig, IMUConfig
+from paradigma.util import write_df_data, read_metadata, invert_watch_side
+
+
+def resample_data(
+    df: pd.DataFrame,
+    time_column : str,
+    values_column_names: List[str],
+    resampling_frequency: int,
+) -> pd.DataFrame:
+    """
+    Resamples sensor data to a specified frequency using cubic interpolation.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The input DataFrame containing the sensor data.
+    time_column : str
+        The name of the column containing the time data.
+    values_column_names : List[str]
+        A list of column names that should be resampled.
+    resampling_frequency : int
+        The frequency to which the data should be resampled (in Hz).
+
+    Returns
+    -------
+    pd.DataFrame
+        A DataFrame with the resampled data, where each column contains resampled values.
+        The time column will reflect the new resampling frequency.
+
+    Raises
+    ------
+    ValueError
+        If the time array is not strictly increasing.
+
+    Notes
+    -----
+    The function uses cubic interpolation to resample the data to the specified frequency.
+    It requires the input time array to be strictly increasing.
+    """
+
+    # Extract time and values from DataFrame
+    time_abs_array = np.array(df[time_column])
+    values_array = np.array(df[values_column_names])
+
+    # Ensure the time array is strictly increasing
+    if not np.all(np.diff(time_abs_array) > 0):
+        raise ValueError("time_abs_array is not strictly increasing")
+
+    # Resample the time data using the specified frequency
+    t_resampled = np.arange(time_abs_array[0], time_abs_array[-1], 1 / resampling_frequency)
+    
+    # Interpolate the data using cubic interpolation
+    interpolator = interp1d(time_abs_array, values_array, axis=0, kind="cubic")
+    resampled_values = interpolator(t_resampled)
+
+    # Create a DataFrame with the resampled data
+    df_resampled = pd.DataFrame(resampled_values, columns=values_column_names)
+    df_resampled[time_column] = t_resampled
+
+    # Return the DataFrame with columns in the correct order
+    return df_resampled[[time_column] + values_column_names]
+
+
+def butterworth_filter(
+    data: np.ndarray,
+    order: int,
+    cutoff_frequency: Union[float, List[float]],
+    passband: str,
+    sampling_frequency: int,
+):
+    """
+    Applies a Butterworth filter to 1D or 2D sensor data.
+
+    This function applies a low-pass, high-pass, or band-pass Butterworth filter to the 
+    input data. The filter is designed using the specified order, cutoff frequency, 
+    and passband type. The function can handle both 1D and 2D data arrays.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        The sensor data to be filtered. Can be 1D (e.g., a single signal) or 2D 
+        (e.g., multi-axis sensor data).
+    order : int
+        The order of the Butterworth filter. Higher values result in a steeper roll-off.
+    cutoff_frequency : float or List[float]
+        The cutoff frequency (or frequencies) for the filter. For a low-pass or high-pass filter, 
+        this is a single float. For a band-pass filter, this should be a list of two floats, 
+        specifying the lower and upper cutoff frequencies.
+    passband : str
+        The type of passband to apply. Options are:
+        - 'hp' : high-pass filter
+        - 'lp' : low-pass filter
+        - 'band' : band-pass filter
+    sampling_frequency : int
+        The sampling frequency of the data in Hz. This is used to normalize the cutoff frequency.
+
+    Returns
+    -------
+    np.ndarray
+        The filtered sensor data. The shape of the output is the same as the input data.
+
+    Raises
+    ------
+    ValueError
+        If the input data has more than two dimensions, or if an invalid passband is specified.
+
+    Notes
+    -----
+    The function uses `scipy.signal.butter` to design the filter and `scipy.signal.sosfiltfilt`
+    to apply it using second-order sections (SOS) to improve numerical stability.
+    """
+    # Design the filter using second-order sections (SOS)
+    sos = signal.butter(
+        N=order,
+        Wn=cutoff_frequency,
+        btype=passband,
+        analog=False,
+        fs=sampling_frequency,
+        output="sos",
+    )
+
+    # Apply the filter to the data
+    if data.ndim == 1:  # 1D data case
+        return signal.sosfiltfilt(sos, data)
+    elif data.ndim == 2:  # 2D data case
+        return signal.sosfiltfilt(sos, data, axis=0)
+    else:
+        raise ValueError("Data must be either 1D or 2D.")
+
+def preprocess_imu_data(df: pd.DataFrame, config: IMUConfig, sensor: str, watch_side: str) -> pd.DataFrame:
+    """
+    Preprocesses IMU data by resampling and applying filters.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The DataFrame containing raw accelerometer and/or gyroscope data.
+    config : IMUConfig
+        Configuration object containing various settings, such as time column name, accelerometer and/or gyroscope columns,
+        filter settings, and sampling frequency.
+    sensor: str
+        Name of the sensor data to be preprocessed. Must be one of:
+        - "accelerometer": Preprocess accelerometer data only.
+        - "gyroscope": Preprocess gyroscope data only.
+        - "both": Preprocess both accelerometer and gyroscope data.
+    watch_side: str
+        The side of the watch where the data was collected. Must be one of:
+        - "left": Data was collected from the left wrist.
+        - "right": Data was collected from the right wrist.
+
+    Returns
+    -------
+    pd.DataFrame
+        The preprocessed accelerometer and or gyroscope data with the following transformations:
+        - Resampled data at the specified frequency.
+        - Filtered accelerometer data with high-pass and low-pass filtering applied.
+    
+    Notes
+    -----
+    - The function applies Butterworth filters to accelerometer data, both high-pass and low-pass.
+    """
+
+    # Extract sensor column
+    if sensor == 'accelerometer':
+        values_colnames = config.accelerometer_cols
+    elif sensor == 'gyroscope':
+        values_colnames = config.gyroscope_cols
+    elif sensor == 'both':
+        values_colnames = config.accelerometer_cols + config.gyroscope_cols
+    else:
+        raise('Sensor should be either accelerometer, gyroscope, or both')
+        
+    # Resample the data to the specified frequency
+    df = resample_data(
+        df=df,
+        time_column=DataColumns.TIME,
+        values_column_names = values_colnames,
+        resampling_frequency=config.sampling_frequency
+    )
+
+    # Invert the IMU data if the watch was worn on the right wrist
+    df = invert_watch_side(df, watch_side)
+    
+    if sensor in ['accelerometer', 'both']:
+      
+        # Extract accelerometer data for filtering
+        accel_data = df[config.accelerometer_cols].values
+
+        # Define filter configurations for high-pass and low-pass
+        filter_renaming_configs = {
+        "hp": {"result_columns": config.accelerometer_cols, "replace_original": True},
+        "lp": {"result_columns": [f'{col}_grav' for col in config.accelerometer_cols], "replace_original": False},
+        }
+
+        # Apply filters in a loop
+        for passband, filter_config in filter_renaming_configs.items():
+            filtered_data = butterworth_filter(
+            data=accel_data,
+            order=config.filter_order,
+            cutoff_frequency=config.lower_cutoff_frequency,
+            passband=passband,
+            sampling_frequency=config.sampling_frequency,
+            )
+
+            # Replace or add new columns based on configuration
+            df[filter_config["result_columns"]] = filtered_data
+
+        values_colnames += config.gravity_cols
+
+    df = df[[DataColumns.TIME, *values_colnames]]
+
+    return df
+
+
+def preprocess_ppg_data(df_ppg: pd.DataFrame, df_acc: pd.DataFrame, ppg_config: PPGConfig, 
+                        imu_config: IMUConfig, start_time_ppg: str, start_time_imu: str) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Preprocess PPG and IMU (accelerometer only) data by resampling, filtering, and aligning the data segments.
+
+    Parameters
+    ----------
+    df_ppg : pd.DataFrame
+        DataFrame containing PPG data.
+    df_acc : pd.DataFrame
+        DataFrame containing accelerometer from IMU data.
+    ppg_config : PPGPreprocessingConfig
+        Configuration object for PPG preprocessing.
+    imu_config : IMUPreprocessingConfig
+        Configuration object for IMU preprocessing.
+    start_time_ppg : str
+        iso8601 formatted start time of the PPG data.
+    start_time_imu : str
+        iso8601 formatted start time of the IMU data.
+
+    Returns
+    -------
+    Tuple[pd.DataFrame, pd.DataFrame]
+        Preprocessed PPG and IMU data as DataFrames.
+    
+    """
+
+    # Extract overlapping segments
+    df_ppg_overlapping, df_acc_overlapping = extract_overlapping_segments(df_ppg, df_acc, start_time_ppg, start_time_imu)
+    
+    # Resample accelerometer data
+    df_acc_proc = resample_data(
+        df=df_acc_overlapping,
+        time_column=DataColumns.TIME,
+        values_column_names = list(imu_config.d_channels_accelerometer.keys()),
+        resampling_frequency=imu_config.sampling_frequency
+    )
+
+    # Resample PPG data
+    df_ppg_proc = resample_data(
+        df=df_ppg_overlapping,
+        time_column=DataColumns.TIME,
+        values_column_names = list(ppg_config.d_channels_ppg.keys()),
+        resampling_frequency=ppg_config.sampling_frequency
+    )
+
+
+    # Extract accelerometer data for filtering
+    accel_data = df_acc_proc[imu_config.accelerometer_cols].values
+
+    # Define filter configurations for high-pass and low-pass
+    filter_renaming_configs = {
+    "hp": {"result_columns": imu_config.accelerometer_cols, "replace_original": True}}
+
+    # Apply filters in a loop
+    for passband, filter_config in filter_renaming_configs.items():
+        filtered_data = butterworth_filter(
+        data=accel_data,
+        order=imu_config.filter_order,
+        cutoff_frequency=imu_config.lower_cutoff_frequency,
+        passband=passband,
+        sampling_frequency=imu_config.sampling_frequency,
+        )
+
+        # Replace or add new columns based on configuration
+        df_acc_proc[filter_config["result_columns"]] = filtered_data
+    
+    # Extract accelerometer data for filtering
+    ppg_data = df_ppg_proc[ppg_config.ppg_colname].values
+
+    # Define filter configurations for high-pass and low-pass
+    filter_renaming_configs = {
+    "bandpass": {"result_columns": ppg_config.ppg_colname, "replace_original": True}}
+
+    # Apply filters in a loop
+    for passband, filter_config in filter_renaming_configs.items():
+        filtered_data = butterworth_filter(
+        data=ppg_data,
+        order=ppg_config.filter_order,
+        cutoff_frequency=[ppg_config.lower_cutoff_frequency, ppg_config.upper_cutoff_frequency],
+        passband=passband,
+        sampling_frequency=ppg_config.sampling_frequency,
+        )
+
+        # Replace or add new columns based on configuration
+        df_ppg_proc[filter_config["result_columns"]] = filtered_data
+    
+    return df_ppg_proc, df_acc_proc
+
+
+
+
+def extract_overlapping_segments(df_ppg: pd.DataFrame, df_acc: pd.DataFrame, start_time_ppg: str, start_time_acc: str) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Extract DataFrames with overlapping data segments between accelerometer (from the IMU) and PPG datasets based on their timestamps.
+
+    Parameters
+    ----------
+    df_ppg : pd.DataFrame
+        DataFrame containing PPG data.
+    df_acc : pd.DataFrame
+        DataFrame containing accelerometer data from the IMU.
+    start_time_ppg : str
+        iso8601 formatted start time of the PPG data.
+    start_time_acc : str
+        iso8601 formatted start time of the accelerometer data.
+
+    Returns
+    -------
+    Tuple[pd.DataFrame, pd.DataFrame]
+        DataFrames containing the overlapping segments (time and values) of PPG and accelerometer data.
+    """
+    # Convert start times to Unix timestamps
+    datetime_ppg_start = datetime.fromisoformat(start_time_ppg.replace("Z", "+00:00"))
+    start_unix_ppg = int(datetime_ppg_start.timestamp())
+    datetime_acc_start = datetime.fromisoformat(start_time_acc.replace("Z", "+00:00"))
+    start_acc_ppg = int(datetime_acc_start.timestamp())
+
+    # Calculate the time in Unix timestamps for each dataset because the timestamps are relative to the start time
+    ppg_time = df_ppg[DataColumns.TIME] + start_unix_ppg
+    acc_time = df_acc[DataColumns.TIME] + start_acc_ppg
+
+    # Determine the overlapping time interval
+    start_time = max(ppg_time.iloc[0], acc_time.iloc[0])
+    end_time = min(ppg_time.iloc[-1], acc_time.iloc[-1])
+
+    # Extract indices for overlapping segments
+    ppg_start_index = np.searchsorted(ppg_time, start_time, 'left')
+    ppg_end_index = np.searchsorted(ppg_time, end_time, 'right') - 1
+    acc_start_index = np.searchsorted(acc_time, start_time, 'left')
+    acc_end_index = np.searchsorted(acc_time, end_time, 'right') - 1
+
+    # Extract overlapping segments from DataFrames
+    df_ppg_overlapping = df_ppg.iloc[ppg_start_index:ppg_end_index + 1]
+    df_acc_overlapping = df_acc.iloc[acc_start_index:acc_end_index + 1]
+
+    return df_ppg_overlapping, df_acc_overlapping