piel.analysis.signals.time ========================== .. py:module:: piel.analysis.signals.time Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/piel/analysis/signals/time/core/index /autoapi/piel/analysis/signals/time/integration/index Functions --------- .. autoapisummary:: piel.analysis.signals.time.compose_pulses_into_signal piel.analysis.signals.time.resize_data_time_signal_units piel.analysis.signals.time.extract_peak_to_peak_metrics_list piel.analysis.signals.time.extract_signal_above_threshold piel.analysis.signals.time.extract_pulses_from_signal piel.analysis.signals.time.is_pulse_above_threshold piel.analysis.signals.time.extract_rising_edges piel.analysis.signals.time.offset_time_signals piel.analysis.signals.time.separate_per_pulse_threshold piel.analysis.signals.time.split_compose_per_pulse_threshold piel.analysis.signals.time.offset_to_first_rising_edge piel.analysis.signals.time.create_off_state_generator piel.analysis.signals.time.extract_off_state_section piel.analysis.signals.time.extract_off_state_generator_from_off_state_section piel.analysis.signals.time.extract_off_state_generator_from_full_state_data piel.analysis.signals.time.remove_before_first_rising_edge piel.analysis.signals.time.extract_peak_to_peak_metrics_after_split_pulses Package Contents ---------------- .. py:function:: compose_pulses_into_signal(pulses: List[piel.types.TimeSignalData], baseline: float = 0.0, noise_std: Optional[float] = None, data_time_signal_kwargs: Optional[dict] = None, start_time_s: Optional[float] = None, end_time_s: Optional[float] = None) -> piel.types.TimeSignalData Composes a full signal from a list of pulses by inserting them into a continuous time array and filling gaps with generated noise. :param pulses: List of pulse signals to be inserted. :type pulses: List[TimeSignalData] :param baseline: Baseline value of the signal. Defaults to 0.0. :type baseline: float, optional :param noise_std: Standard deviation of the noise to be generated in gaps. If not provided, it is estimated from the pulses. :type noise_std: float, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :param start_time_s: Start time of the composed signal. If not provided, uses the first pulse's start time. :type start_time_s: float, optional :param end_time_s: End time of the composed signal. If not provided, uses the last pulse's end time. :type end_time_s: float, optional :returns: The composed full signal with pulses and noise. :rtype: TimeSignalData .. py:function:: resize_data_time_signal_units(waveform: piel.types.TimeSignalData, time_unit: piel.types.Unit, data_unit: piel.types.Unit, corrected_name_suffix: str = '_corrected') -> piel.types.TimeSignalData Applies unit corrections to the time and data arrays of a TimeSignalData object. Parameters: - waveform: The original waveform data. - time_unit: The unit to apply to the time axis. - data_unit: The unit to apply to the data. - corrected_name_suffix: Suffix to append to the data name after correction. Returns: - A new TimeSignalData object with corrected time and data. .. py:function:: extract_peak_to_peak_metrics_list(multi_data_time_signal: piel.types.MultiTimeSignalData, metric_kwargs_list: list[dict] = None, **kwargs) -> piel.types.ScalarMetricCollection Extracts peak-to-peak metrics from a collection of signals. The peak-to-peak value is defined as the difference between the maximum and minimum values of the signal. :param multi_data_time_signal: A collection of time signals to analyze. :type multi_data_time_signal: MultiTimeSignalData :returns: A collection of ScalarMetric instances containing the peak-to-peak values for each signal. :rtype: ScalarMetricCollection :raises ValueError: If the input list is empty or any signal has an empty data array. .. py:function:: extract_signal_above_threshold(signal_data: piel.types.TimeSignalData, threshold: float, min_pulse_width_s: float = 0.0, noise_floor: float = 0.0) -> piel.types.MultiTimeSignalData Extracts all pulses from the input signal that exceed the specified threshold. :param signal_data: The original signal data containing time and data arrays. :type signal_data: TimeSignalData :param threshold: The data value threshold to identify pulses. :type threshold: float :param min_pulse_width_s: The minimum duration (in seconds) for a pulse to be considered valid. Pulses shorter than this duration will be ignored. Defaults to 0.0. :type min_pulse_width_s: float, optional :param noise_floor: The value to assign to non-pulse regions in the extracted pulses. Defaults to 0.0. :type noise_floor: float, optional :returns: A list of DataTimeSignalData instances, each representing a detected pulse. :rtype: MultiTimeSignalData .. py:function:: extract_pulses_from_signal(full_data: piel.types.TimeSignalData, pre_pulse_time_s: float = 0.01, post_pulse_time_s: float = 0.01, noise_std_multiplier: float = 3.0, min_pulse_height: Optional[float] = None, min_pulse_distance_s: Optional[float] = None, data_time_signal_kwargs: Optional[dict] = None) -> List[piel.types.TimeSignalData] Detects and extracts pulses from a DataTimeSignalData instance, including segments before and after each pulse up to the noise floor. :param full_data: The input signal data containing multiple pulses. :type full_data: TimeSignalData :param pre_pulse_time_s: Time (in seconds) to include before each detected pulse. :type pre_pulse_time_s: float :param post_pulse_time_s: Time (in seconds) to include after each detected pulse. :type post_pulse_time_s: float :param noise_std_multiplier: Multiplier for noise standard deviation to set detection threshold. :type noise_std_multiplier: float :param min_pulse_height: Minimum height of a pulse to be detected. If not provided, it is set to noise_std_multiplier * noise_std. :type min_pulse_height: float, optional :param min_pulse_distance_s: Minimum distance (in seconds) between consecutive pulses. If not provided, it is set based on the pre_pulse_time and post_pulse_time. :type min_pulse_distance_s: float, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :returns: A list of DataTimeSignalData instances, each representing an extracted pulse. :rtype: List[TimeSignalData] .. py:function:: is_pulse_above_threshold(pulse: piel.types.TimeSignalData, threshold: float) -> bool Determines if the pulse's amplitude exceeds the specified threshold. :param pulse: The pulse data to evaluate. :type pulse: TimeSignalData :param threshold: The amplitude threshold. :type threshold: float :returns: True if the pulse's maximum amplitude is greater than or equal to the threshold, False otherwise. :rtype: bool .. py:function:: extract_rising_edges(signal: piel.types.TimeSignalData, lower_threshold_ratio: float = 0.1, upper_threshold_ratio: float = 0.9) -> piel.types.MultiTimeSignalData Extracts rising edges from a signal defined as transitions from lower_threshold to upper_threshold. :param signal: The input signal data. :type signal: TimeSignalData :param lower_threshold_ratio: Lower threshold as a fraction of signal amplitude (default 0.1). :type lower_threshold_ratio: float :param upper_threshold_ratio: Upper threshold as a fraction of signal amplitude (default 0.9). :type upper_threshold_ratio: float :returns: A list of DataTimeSignalData instances, each representing a rising edge. :rtype: MultiTimeSignalData .. py:function:: offset_time_signals(multi_signal: piel.types.MultiTimeSignalData) -> piel.types.MultiTimeSignalData Offsets the time_s array of each TimeSignalData in the MultiTimeSignalData to start at 0. :param multi_signal: List of rising edge signals. :type multi_signal: MultiTimeSignalData :returns: New list with offset time_s arrays. :rtype: MultiTimeSignalData .. py:function:: separate_per_pulse_threshold(signal_data: piel.types.TimeSignalData, first_signal_threshold: float, second_signal_threshold: float, trigger_delay_s: float, trigger_window_s: float = 2.5e-08, first_pre_pulse_time_s: float = 1e-09, first_post_pulse_time_s: float = 1e-09, second_pre_pulse_time_s: float = 1e-09, second_post_pulse_time_s: float = 1e-09, noise_std_multiplier: float = 3.0, data_time_signal_kwargs: Optional[Dict] = None) -> List[piel.types.MultiTimeSignalData] Separates pulses in a signal into two categories based on two threshold values. :param signal_data: The input signal data containing multiple pulses. :type signal_data: TimeSignalData :param first_signal_threshold: The higher threshold to categorize pulses. :type first_signal_threshold: float :param second_signal_threshold: The lower threshold to categorize pulses. :type second_signal_threshold: float :param trigger_delay_s: Minimum time (in seconds) between pulses to prevent overlap. :type trigger_delay_s: float :param first_pre_pulse_time_s: Time (in seconds) to include before each detected pulse. Defaults to 0.01. :type first_pre_pulse_time_s: float, optional :param first_post_pulse_time_s: Time (in seconds) to include after each detected pulse. Defaults to 0.01. second_pre_pulse_time_s (float, optional): Time (in seconds) to include before each detected pulse. Defaults to 0.01. :type first_post_pulse_time_s: float, optional :param second_post_pulse_time_s: Time (in seconds) to include after each detected pulse. Defaults to 0.01. :type second_post_pulse_time_s: float, optional :param noise_std_multiplier: Multiplier for noise standard deviation to set detection threshold. Defaults to 3.0. :type noise_std_multiplier: float, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :returns: A list containing a single `MultiTimeSignalData` instance: - `high_threshold_pulses`: List of `DataTimeSignalData` for pulses above `first_signal_threshold`. - `low_threshold_pulses`: List of `DataTimeSignalData` for pulses above `second_signal_threshold` but below `first_signal_threshold`. :rtype: List[MultiTimeSignalData] .. py:function:: split_compose_per_pulse_threshold(signal_data: piel.types.TimeSignalData, first_signal_threshold: float, second_signal_threshold: float, trigger_delay_s: float, first_pre_pulse_time_s: float = 1e-09, first_post_pulse_time_s: float = 1e-09, second_pre_pulse_time_s: float = 1e-09, second_post_pulse_time_s: float = 1e-09, noise_std_multiplier: float = 3.0, start_time_s: Optional[float] = None, end_time_s: Optional[float] = None, data_time_signal_kwargs: Optional[Dict] = None) -> piel.types.MultiTimeSignalData Separates pulses in a signal into two categories based on two threshold values. :param signal_data: The input signal data containing multiple pulses. :type signal_data: TimeSignalData :param first_signal_threshold: The higher threshold to categorize pulses. :type first_signal_threshold: float :param second_signal_threshold: The lower threshold to categorize pulses. :type second_signal_threshold: float :param trigger_delay_s: Minimum time (in seconds) between pulses to prevent overlap. :type trigger_delay_s: float :param first_pre_pulse_time_s: Time (in seconds) to include before each detected first pulse. Defaults to 0.01. :type first_pre_pulse_time_s: float, optional :param first_post_pulse_time_s: Time (in seconds) to include after each detected first pulse. Defaults to 0.01. :type first_post_pulse_time_s: float, optional :param second_pre_pulse_time_s: Time (in seconds) to include before each detected second pulse. Defaults to 0.01. :type second_pre_pulse_time_s: float, optional :param second_post_pulse_time_s: Time (in seconds) to include after each detected second pulse. Defaults to 0.01. :type second_post_pulse_time_s: float, optional :param noise_std_multiplier: Multiplier for noise standard deviation to set detection threshold. Defaults to 3.0. :type noise_std_multiplier: float, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :param start_time_s: Start time of the composed signal. If not provided, uses the first pulse's start time. :type start_time_s: float, optional :param end_time_s: End time of the composed signal. If not provided, uses the last pulse's end time. :type end_time_s: float, optional :returns: The composed full signals as [low_threshold_pulse_signal, high_threshold_pulse_signal] :rtype: List[TimeSignalData] .. py:function:: offset_to_first_rising_edge(waveform: piel.types.TimeSignalData, lower_threshold_ratio: float = 0.1, upper_threshold_ratio: float = 0.9) -> piel.types.TimeSignalData Offsets the waveform's time axis so that the first rising edge occurs at time zero. A rising edge is defined as the point where the signal transitions from below the lower threshold to above the upper threshold. :param waveform: The input waveform data. :type waveform: TimeSignalData :param lower_threshold_ratio: Lower threshold as a ratio of the amplitude range. :type lower_threshold_ratio: float :param upper_threshold_ratio: Upper threshold as a ratio of the amplitude range. :type upper_threshold_ratio: float :returns: A new waveform with the time offset applied. :rtype: TimeSignalData :raises ValueError: If no rising edge is found in the waveform. .. py:function:: create_off_state_generator(noise_std: float = 0.01, sampling_rate: float = 1000.0, baseline: float = 0.0, data_name: str = 'off_state', data_time_signal_kwargs: Optional[Dict] = None) -> Callable[[float, Optional[int]], piel.types.TimeSignalData] Creates a generator function for the equivalent off state signal with noise. :param noise_std: Standard deviation of the Gaussian noise. :type noise_std: float :param sampling_rate: Sampling rate in Hz. :type sampling_rate: float :param baseline: Baseline signal level for the off state. :type baseline: float :param data_name: Name of the data signal. :type data_name: str :param data_time_signal_kwargs: Additional keyword arguments for TimeSignalData. :type data_time_signal_kwargs: dict, optional :returns: A function that takes duration_s (in seconds) and returns TimeSignalData. :rtype: Callable[[float, Optional[int]], TimeSignalData] .. py:function:: extract_off_state_section(full_time_signal_data: piel.types.TimeSignalData, baseline: Optional[float] = None, threshold: Optional[float] = None, min_duration_s: Optional[float] = None, sampling_rate: Optional[float] = None, data_time_signal_kwargs: Optional[Dict] = None) -> piel.types.TimeSignalData Extracts the off state segments from a DataTimeSignalData instance containing multiple on and off states. :param full_time_signal_data: The input signal data containing multiple states. :type full_time_signal_data: TimeSignalData :param baseline: The baseline value representing the off state. If not provided, it is computed as the mean of the data. :type baseline: float, optional :param threshold: The maximum deviation from the baseline to consider as off state. If not provided, it is computed as 2 * standard deviation of the data. :type threshold: float, optional :param min_duration_s: The minimum duration_s (in seconds) for a segment to be considered. Segments shorter than this duration_s will be ignored. :type min_duration_s: float, optional :param sampling_rate: The sampling rate in Hz. If not provided, it is calculated from time_s. :type sampling_rate: float, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :returns: A new DataTimeSignalData instance containing only the off state segments. :rtype: TimeSignalData .. py:function:: extract_off_state_generator_from_off_state_section(off_state_data: piel.types.TimeSignalData, data_name: Optional[str] = None, data_time_signal_kwargs: Optional[Dict] = None) -> Callable[[float], piel.types.TimeSignalData] Extracts parameters from an existing off state DataTimeSignalData and creates a generator function. :param off_state_data: The existing off state signal data. :type off_state_data: TimeSignalData :param data_name: Name for the new data signal. Defaults to the original data_name. :type data_name: str, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :returns: A generator function configured with extracted parameters. :rtype: Callable[[float], DataTimeSignalData] .. py:function:: extract_off_state_generator_from_full_state_data(full_time_signal_data: piel.types.TimeSignalData, baseline: Optional[float] = None, threshold: Optional[float] = None, min_duration_s: Optional[float] = None, sampling_rate: Optional[float] = None, data_name: Optional[str] = None, data_time_signal_kwargs: Optional[Dict] = None) -> Callable[[float, Optional[int]], piel.types.TimeSignalData] Extracts parameters from an existing off state DataTimeSignalData and creates a generator function. :param full_time_signal_data: The input signal data containing multiple states. :type full_time_signal_data: TimeSignalData :param baseline: The baseline value representing the off state. If not provided, it is computed as the mean of the data. :type baseline: float, optional :param threshold: The maximum deviation from the baseline to consider as off state. If not provided, it is computed as 2 * standard deviation of the data. :type threshold: float, optional :param min_duration_s: The minimum duration_s (in seconds) for a segment to be considered. Segments shorter than this duration_s will be ignored. :type min_duration_s: float, optional :param sampling_rate: The sampling rate in Hz. If not provided, it is calculated from time_s. :type sampling_rate: float, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :param data_name: Name for the new data signal. Defaults to the original data_name. :type data_name: str, optional :param data_time_signal_kwargs: Additional keyword arguments for DataTimeSignalData. :type data_time_signal_kwargs: dict, optional :returns: A generator function configured with extracted parameters. :rtype: Callable[[float], DataTimeSignalData] .. py:function:: remove_before_first_rising_edge(waveform: piel.types.TimeSignalData, lower_threshold_ratio: float = 0.1, upper_threshold_ratio: float = 0.9) -> piel.types.TimeSignalData Removes all data points before the first rising edge in the waveform. A rising edge is defined as the point where the signal transitions from below the lower threshold to above the upper threshold. :param waveform: The input waveform data. :type waveform: TimeSignalData :param lower_threshold_ratio: Lower threshold as a ratio of the amplitude range. :type lower_threshold_ratio: float :param upper_threshold_ratio: Upper threshold as a ratio of the amplitude range. :type upper_threshold_ratio: float :returns: A new waveform with data points before the first rising edge removed. :rtype: TimeSignalData :raises ValueError: If no rising edge is found in the waveform. .. py:function:: extract_peak_to_peak_metrics_after_split_pulses(full_signal: piel.types.TimeSignalData, pre_pulse_time_s: float = 1e-09, post_pulse_time_s: float = 1e-09, noise_std_multiplier: float = 3.0, min_pulse_height: Optional[float] = None, min_pulse_distance_s: Optional[float] = None, data_time_signal_kwargs: Optional[dict] = None, metrics_kwargs: Optional[dict] = None) -> piel.types.ScalarMetricCollection Extracts pulses from the full signal and computes peak-to-peak metrics. Parameters: - full_signal (TimeSignalData): The complete time signal data to be analyzed. - pre_pulse_time_s (float): Time in seconds before the pulse to include. - post_pulse_time_s (float): Time in seconds after the pulse to include. - noise_std_multiplier (float): Multiplier for noise standard deviation to detect pulses. - min_pulse_height (Optional[float]): Minimum height of a pulse to be considered. - min_pulse_distance_s (Optional[float]): Minimum distance in seconds between pulses. - data_time_signal_kwargs (Optional[dict]): Additional keyword arguments for pulse extraction. - metrics_kwargs (Optional[dict]): Additional keyword arguments for metric extraction. Returns: - ScalarMetricCollection: Collection of extracted scalar metrics.