piel.analysis.signals.time

Submodules

• piel.analysis.signals.time.core
• piel.analysis.signals.time.integration

Functions

compose_pulses_into_signal(→ piel.types.TimeSignalData)	Composes a full signal from a list of pulses by inserting them into a continuous time array
resize_data_time_signal_units(→ piel.types.TimeSignalData)	Applies unit corrections to the time and data arrays of a TimeSignalData object.
extract_peak_to_peak_metrics_list(...)	Extracts peak-to-peak metrics from a collection of signals. The peak-to-peak value is defined as the
extract_signal_above_threshold(...)	Extracts all pulses from the input signal that exceed the specified threshold.
extract_pulses_from_signal(...)	Detects and extracts pulses from a DataTimeSignalData instance, including segments
is_pulse_above_threshold(→ bool)	Determines if the pulse's amplitude exceeds the specified threshold.
extract_rising_edges(→ piel.types.MultiTimeSignalData)	Extracts rising edges from a signal defined as transitions from lower_threshold to upper_threshold.
offset_time_signals(→ piel.types.MultiTimeSignalData)	Offsets the time_s array of each TimeSignalData in the MultiTimeSignalData to start at 0.
separate_per_pulse_threshold(...)	Separates pulses in a signal into two categories based on two threshold values.
split_compose_per_pulse_threshold(...)	Separates pulses in a signal into two categories based on two threshold values.
offset_to_first_rising_edge(→ piel.types.TimeSignalData)	Offsets the waveform's time axis so that the first rising edge occurs at time zero.
create_off_state_generator(→ Callable[[float, ...)	Creates a generator function for the equivalent off state signal with noise.
extract_off_state_section(→ piel.types.TimeSignalData)	Extracts the off state segments from a DataTimeSignalData instance containing multiple on and off states.
extract_off_state_generator_from_off_state_section(...)	Extracts parameters from an existing off state DataTimeSignalData and creates a generator function.
extract_off_state_generator_from_full_state_data(...)	Extracts parameters from an existing off state DataTimeSignalData and creates a generator function.
remove_before_first_rising_edge(...)	Removes all data points before the first rising edge in the waveform.
extract_peak_to_peak_metrics_after_split_pulses(...)	Extracts pulses from the full signal and computes peak-to-peak metrics.

Package Contents

compose_pulses_into_signal(pulses: List[piel.types.TimeSignalData], baseline: float = 0.0, noise_std: float | None = None, data_time_signal_kwargs: dict | None = None, start_time_s: float | None = None, end_time_s: float | None = 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.

Parameters:

• pulses (List[TimeSignalData]) – List of pulse signals to be inserted.

• baseline (float, optional) – Baseline value of the signal. Defaults to 0.0.

• noise_std (float, optional) – Standard deviation of the noise to be generated in gaps. If not provided, it is estimated from the pulses.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

• start_time_s (float, optional) – Start time of the composed signal. If not provided, uses the first pulse’s start time.

• end_time_s (float, optional) – End time of the composed signal. If not provided, uses the last pulse’s end time.

Returns:

The composed full signal with pulses and noise.

Return type:

TimeSignalData

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.

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.

Parameters:

multi_data_time_signal (MultiTimeSignalData) – A collection of time signals to analyze.

Returns:

A collection of ScalarMetric instances containing the peak-to-peak values

for each signal.

Return type:

ScalarMetricCollection

Raises:

ValueError – If the input list is empty or any signal has an empty data array.

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.

Parameters:

• signal_data (TimeSignalData) – The original signal data containing time and data arrays.

• threshold (float) – The data value threshold to identify pulses.

• min_pulse_width_s (float, optional) – The minimum duration (in seconds) for a pulse to be considered valid. Pulses shorter than this duration will be ignored. Defaults to 0.0.

• noise_floor (float, optional) – The value to assign to non-pulse regions in the extracted pulses. Defaults to 0.0.

Returns:

A list of DataTimeSignalData instances, each representing a detected pulse.

Return type:

MultiTimeSignalData

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: float | None = None, min_pulse_distance_s: float | None = None, data_time_signal_kwargs: dict | None = 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.

Parameters:

• full_data (TimeSignalData) – The input signal data containing multiple pulses.

• pre_pulse_time_s (float) – Time (in seconds) to include before each detected pulse.

• post_pulse_time_s (float) – Time (in seconds) to include after each detected pulse.

• noise_std_multiplier (float) – Multiplier for noise standard deviation to set detection threshold.

• min_pulse_height (float, optional) – Minimum height of a pulse to be detected. If not provided, it is set to noise_std_multiplier * noise_std.

• min_pulse_distance_s (float, optional) – Minimum distance (in seconds) between consecutive pulses. If not provided, it is set based on the pre_pulse_time and post_pulse_time.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

Returns:

A list of DataTimeSignalData instances, each representing an extracted pulse.

Return type:

List[TimeSignalData]

is_pulse_above_threshold(pulse: piel.types.TimeSignalData, threshold: float) → bool

Determines if the pulse’s amplitude exceeds the specified threshold.

Parameters:

• pulse (TimeSignalData) – The pulse data to evaluate.

• threshold (float) – The amplitude threshold.

Returns:

True if the pulse’s maximum amplitude is greater than or equal to the threshold, False otherwise.

Return type:

bool

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.

Parameters:

• signal (TimeSignalData) – The input signal data.

• lower_threshold_ratio (float) – Lower threshold as a fraction of signal amplitude (default 0.1).

• upper_threshold_ratio (float) – Upper threshold as a fraction of signal amplitude (default 0.9).

Returns:

A list of DataTimeSignalData instances, each representing a rising edge.

Return type:

MultiTimeSignalData

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.

Parameters:

multi_signal (MultiTimeSignalData) – List of rising edge signals.

Returns:

New list with offset time_s arrays.

Return type:

MultiTimeSignalData

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: Dict | None = None) → List[piel.types.MultiTimeSignalData]

Separates pulses in a signal into two categories based on two threshold values.

Parameters:

• signal_data (TimeSignalData) – The input signal data containing multiple pulses.

• first_signal_threshold (float) – The higher threshold to categorize pulses.

• second_signal_threshold (float) – The lower threshold to categorize pulses.

• trigger_delay_s (float) – Minimum time (in seconds) between pulses to prevent overlap.

• first_pre_pulse_time_s (float, optional) – Time (in seconds) to include before each detected pulse. Defaults to 0.01.

• first_post_pulse_time_s (float, optional) –

  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.

• second_post_pulse_time_s (float, optional) – Time (in seconds) to include after each detected pulse. Defaults to 0.01.

• noise_std_multiplier (float, optional) – Multiplier for noise standard deviation to set detection threshold. Defaults to 3.0.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

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.

Return type:

List[MultiTimeSignalData]

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: float | None = None, end_time_s: float | None = None, data_time_signal_kwargs: Dict | None = None) → piel.types.MultiTimeSignalData

Separates pulses in a signal into two categories based on two threshold values.

Parameters:

• signal_data (TimeSignalData) – The input signal data containing multiple pulses.

• first_signal_threshold (float) – The higher threshold to categorize pulses.

• second_signal_threshold (float) – The lower threshold to categorize pulses.

• trigger_delay_s (float) – Minimum time (in seconds) between pulses to prevent overlap.

• first_pre_pulse_time_s (float, optional) – Time (in seconds) to include before each detected first pulse. Defaults to 0.01.

• first_post_pulse_time_s (float, optional) – Time (in seconds) to include after each detected first pulse. Defaults to 0.01.

• second_pre_pulse_time_s (float, optional) – Time (in seconds) to include before each detected second pulse. Defaults to 0.01.

• second_post_pulse_time_s (float, optional) – Time (in seconds) to include after each detected second pulse. Defaults to 0.01.

• noise_std_multiplier (float, optional) – Multiplier for noise standard deviation to set detection threshold. Defaults to 3.0.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

• start_time_s (float, optional) – Start time of the composed signal. If not provided, uses the first pulse’s start time.

• end_time_s (float, optional) – End time of the composed signal. If not provided, uses the last pulse’s end time.

Returns:

The composed full signals as [low_threshold_pulse_signal, high_threshold_pulse_signal]

Return type:

List[TimeSignalData]

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.

Parameters:

• waveform (TimeSignalData) – The input waveform data.

• lower_threshold_ratio (float) – Lower threshold as a ratio of the amplitude range.

• upper_threshold_ratio (float) – Upper threshold as a ratio of the amplitude range.

Returns:

A new waveform with the time offset applied.

Return type:

TimeSignalData

Raises:

ValueError – If no rising edge is found in the waveform.

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: Dict | None = None) → Callable[[float, int | None], piel.types.TimeSignalData]

Creates a generator function for the equivalent off state signal with noise.

Parameters:

• noise_std (float) – Standard deviation of the Gaussian noise.

• sampling_rate (float) – Sampling rate in Hz.

• baseline (float) – Baseline signal level for the off state.

• data_name (str) – Name of the data signal.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for TimeSignalData.

Returns:

A function that takes duration_s (in seconds) and returns TimeSignalData.

Return type:

Callable[[float, Optional[int]], TimeSignalData]

extract_off_state_section(full_time_signal_data: piel.types.TimeSignalData, baseline: float | None = None, threshold: float | None = None, min_duration_s: float | None = None, sampling_rate: float | None = None, data_time_signal_kwargs: Dict | None = None) → piel.types.TimeSignalData

Extracts the off state segments from a DataTimeSignalData instance containing multiple on and off states.

Parameters:

• full_time_signal_data (TimeSignalData) – The input signal data containing multiple states.

• baseline (float, optional) – The baseline value representing the off state. If not provided, it is computed as the mean of the data.

• threshold (float, optional) – The maximum deviation from the baseline to consider as off state. If not provided, it is computed as 2 * standard deviation of the data.

• min_duration_s (float, optional) – The minimum duration_s (in seconds) for a segment to be considered. Segments shorter than this duration_s will be ignored.

• sampling_rate (float, optional) – The sampling rate in Hz. If not provided, it is calculated from time_s.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

Returns:

A new DataTimeSignalData instance containing only the off state segments.

Return type:

TimeSignalData

extract_off_state_generator_from_off_state_section(off_state_data: piel.types.TimeSignalData, data_name: str | None = None, data_time_signal_kwargs: Dict | None = None) → Callable[[float], piel.types.TimeSignalData]

Extracts parameters from an existing off state DataTimeSignalData and creates a generator function.

Parameters:

• off_state_data (TimeSignalData) – The existing off state signal data.

• data_name (str, optional) – Name for the new data signal. Defaults to the original data_name.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

Returns:

A generator function configured with extracted parameters.

Return type:

Callable[[float], DataTimeSignalData]

extract_off_state_generator_from_full_state_data(full_time_signal_data: piel.types.TimeSignalData, baseline: float | None = None, threshold: float | None = None, min_duration_s: float | None = None, sampling_rate: float | None = None, data_name: str | None = None, data_time_signal_kwargs: Dict | None = None) → Callable[[float, int | None], piel.types.TimeSignalData]

Extracts parameters from an existing off state DataTimeSignalData and creates a generator function.

Parameters:

• full_time_signal_data (TimeSignalData) – The input signal data containing multiple states.

• baseline (float, optional) – The baseline value representing the off state. If not provided, it is computed as the mean of the data.

• threshold (float, optional) – The maximum deviation from the baseline to consider as off state. If not provided, it is computed as 2 * standard deviation of the data.

• min_duration_s (float, optional) – The minimum duration_s (in seconds) for a segment to be considered. Segments shorter than this duration_s will be ignored.

• sampling_rate (float, optional) – The sampling rate in Hz. If not provided, it is calculated from time_s.

• data_time_signal_kwargs (dict, optional) – Additional keyword arguments for DataTimeSignalData.

• data_name (str, optional) – Name for the new data signal. Defaults to the original data_name.

• data_time_signal_kwargs – Additional keyword arguments for DataTimeSignalData.

Returns:

A generator function configured with extracted parameters.

Return type:

Callable[[float], DataTimeSignalData]

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.

Parameters:

• waveform (TimeSignalData) – The input waveform data.

• lower_threshold_ratio (float) – Lower threshold as a ratio of the amplitude range.

• upper_threshold_ratio (float) – Upper threshold as a ratio of the amplitude range.

Returns:

A new waveform with data points before the first rising edge removed.

Return type:

TimeSignalData

Raises:

ValueError – If no rising edge is found in the waveform.

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: float | None = None, min_pulse_distance_s: float | None = None, data_time_signal_kwargs: dict | None = None, metrics_kwargs: dict | None = 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.