cibrrig.preprocess.physiology

Code to process physiological signals. This module is general in that it does no I/O, only processing. Arbitrarily sourced data that has been shaped into numpy arrays can be processed

Functions

burst_stats_dia(integrated, sr[, dia_thresh, ...])

Calculate diaphragm burst features.

remove_EKG(x, sr[, thresh, heartbeats])

Remove EKG artifacts from the diaphragm signal.

_remove_EKG_explicit(x, sr, heartbeats)

Remove the EKG signal from an ephys trace using a Bayesian Gaussian Mixture (BGM) classifier.

_remove_EKG_inferred(x, sr, thresh)

Remove EKG artifacts from an ephys trace by inferring heartbeat times.

get_hr_from_dia(pks, dia_df, sr)

Compute heart rate from diaphragm signal.

extract_hr_from_ekg(x, sr[, thresh, min_distance, ...])

Finds heartbeats in an EKG trace using a bandpass filter and peak detection.

compute_avg_hr(heartbeats[, smoothing_window, dt, ...])

Compute the mean heart rate from detected hearteats using a sliding average window.

compute_sighs(breath_times, auc[, thresh, win])

Use a rolling Median Absolute Deviation (MAD) to identify sighs based on the AUC of the diaphragm.

compute_obstructive_apneas(breath_times, inhale_onsets)

Identify obstructive apneas based on the absence of detected inhale onsets.

compute_dia_phase(ons[, offs, t_start, t_stop, dt, ...])

Computes breathing phase based on the diaphragm signal

Module Contents

cibrrig.preprocess.physiology.burst_stats_dia(integrated, sr, dia_thresh=1, rel_height=0.9, min_distance=0.1, min_width=0.025)[source]

Calculate diaphragm burst features.

Parameters:

  • integrated (np.ndarray) – Integrated diaphragm trace.

  • sr (float) – Sample rate of the integrated diaphragm trace.

  • dia_thresh (int, optional) – Prominence threshold (z-score). Defaults to 1.

  • rel_height (float, optional) – Relative height to use when finding onset times. Defaults to 0.9.

  • min_distance (float, optional) – Minimum time between breaths in seconds. Effectively sets the maximum breathing rate. Defaults to 0.1.

  • min_width (float, optional) – Minimum time duration to consider a breath in seconds. Defaults to 0.025.

Returns:

DataFrame containing burst statistics.

Return type:

pd.DataFrame

cibrrig.preprocess.physiology.remove_EKG(x, sr, thresh=2, heartbeats=None)[source]

Remove EKG artifacts from the diaphragm signal. Can either infer the heartbeat times from the signal to clean (e.g., diaphragm), or take an explicit set of heartbeat times Remove the EKG from an ephys trace using a BGM classifier

Parameters:

  • signal (np.ndarray) – Input diaphragm signal.

  • sr (float) – Sampling rate of the input signal.

  • thresh (float, optional) – Threshold for EKG detection. Defaults to 2.

  • heartbeats (np.ndarray, optional) – Precomputed heartbeats. Defaults to None.

Returns:

A tuple containing:

  • np.ndarray: Diaphragm signal with EKG artifacts removed.

  • np.ndarray: Detected heartbeats.

Return type:

tuple

cibrrig.preprocess.physiology._remove_EKG_explicit(x, sr, heartbeats)[source]

Remove the EKG signal from an ephys trace using a Bayesian Gaussian Mixture (BGM) classifier.

This function removes EKG artifacts from an electrophysiological signal by using pre-detected heartbeat times. It extracts segments around each heartbeat. It then classifies them as during a breath or not using a BGM classifier, It then subtracts the EKG artifact from the original signal.

Parameters:

  • x (np.ndarray) – Signal to remove EKG from.

  • sr (float) – Sampling rate of the signal in samples per second.

  • heartbeats (np.ndarray) – Times in seconds of the detected heartbeats.

Returns:

Signal with EKG artifacts removed.

Return type:

np.ndarray

cibrrig.preprocess.physiology._remove_EKG_inferred(x, sr, thresh)[source]

Remove EKG artifacts from an ephys trace by inferring heartbeat times.

This function applies a bandpass filter [5,500] to isolate the EKG signal, detects heartbeats, and then removes the EKG artifacts from the original signal.

Parameters:

  • x (np.ndarray) – Ephys trace to clean (e.g., diaphragm or other EMG).

  • sr (float) – Sampling rate in samples per second.

  • thresh (int, optional) – Threshold in standard deviations to detect a heartbeat. Defaults to 2.

Returns:

A tuple containing:

  • np.ndarray: Ephys trace with the EKG filtered out. Has the same timestamps as the input trace.

  • np.ndarray: Indices of the detected heartbeats.

Return type:

tuple

cibrrig.preprocess.physiology.get_hr_from_dia(pks, dia_df, sr)[source]

Compute heart rate from diaphragm signal. Not as good as getting it from a dedicated channel

Parameters:

  • pulse (np.ndarray) – Pulse signal.

  • dia_df (pd.DataFrame) – DataFrame containing diaphragm burst statistics.

  • sr (float) – Sampling rate of the input signal.

Returns:

A tuple containing:

  • np.ndarray: Heart rate values.

  • np.ndarray: Detected heartbeats.

Return type:

tuple

cibrrig.preprocess.physiology.extract_hr_from_ekg(x, sr, thresh=5, min_distance=0.05, low=100, high=1000, in_samples=False, filter=False)[source]

Finds heartbeats in an EKG trace using a bandpass filter and peak detection.

Parameters:

  • x (np.ndarray) – EKG trace.

  • sr (float) – Sampling rate in samples per second.

  • thresh (int, optional) – Prominence threshold in standard deviations to identify peaks. Defaults to 5.

  • min_distance (float, optional) – Minimum time between detected heartbeats in seconds. Effectively sets a maximum heart rate. Defaults to 0.05.

  • low (int, optional) – Low cut frequency in the bandpass filter (Hz). Defaults to 100.

  • high (int, optional) – High cut frequency in the bandpass filter (Hz). Defaults to 1000.

  • in_samples (bool, optional) – If True, return the peaks as sample indices. If False, return the peaks as time in seconds. Defaults to False.

  • filter (bool, optional) – If True, apply a bandpass filter to the EKG signal. Defaults to False.

Returns:

Detected heartbeats. If in_samples is True, returns the sample indices of the heartbeats. Otherwise, returns the time in seconds of the heartbeats.

Return type:

np.ndarray

cibrrig.preprocess.physiology.compute_avg_hr(heartbeats, smoothing_window='10s', dt=0.1, t_target=None)[source]

Compute the mean heart rate from detected hearteats using a sliding average window. First performs a median filter to remove large instantaneous outliers Then performs a mean filter to smooth out the average.

Can pass t_target to interpolate to a new time basis. Otherwise defualts to a 100ms window If both t_target and dt are None - outputs the smoothed heart rate only with length (# heartbeats) Created with the help of ChatGPT3.5

Parameters:

  • heartbeats (np.ndarray) – Timestamps of detected heartbeats.

  • smoothing_window (str, optional) – Smoothing window for the heart rate computation. Defaults to “10s”.

  • dt (float, optional) – Time step for the heart rate computation. Defaults to 0.1.

  • t_target (np.ndarray, optional) – Target time vector for the heart rate computation. Defaults to None.

Returns:

A tuple containing:

  • np.ndarray: Time vector for the average heart rate.

  • np.ndarray: Smoothed heart rate values.

Return type:

tuple

cibrrig.preprocess.physiology.compute_sighs(breath_times, auc, thresh=7, win='20s')[source]

Use a rolling Median Absolute Deviation (MAD) to identify sighs based on the AUC of the diaphragm.

This function calculates the rolling MAD of the diaphragm’s area under the curve (AUC) and identifies breaths that exceed a specified threshold as sighs.

Parameters:

  • breath_times (np.ndarray) – Times of each breath in seconds.

  • auc (np.ndarray) – Area under the curve of the diaphragm for each breath.

  • thresh (int, optional) – Multiplier for the MAD to set the threshold for sigh detection. Defaults to 7.

  • win (str, optional) – Window size for the rolling MAD calculation. Defaults to ’20s’.

Returns:

Boolean array indicating which breaths are identified as sighs.

Return type:

np.ndarray

cibrrig.preprocess.physiology.compute_obstructive_apneas(breath_times, inhale_onsets)[source]

Identify obstructive apneas based on the absence of detected inhale onsets.

This function determines periods of obstructive apnea by checking for missing inhale onsets while breath onsets are present.

Parameters:

  • breath_times (np.ndarray) – Times of breath onsets (not used, but required to ensure diaphragm data is provided).

  • inhale_onsets (np.ndarray) – Times of inhale onsets.

Returns:

Boolean array indicating where obstructive apneas are detected.

Return type:

np.ndarray

cibrrig.preprocess.physiology.compute_dia_phase(ons, offs=None, t_start=0, t_stop=None, dt=1 / 1000, transform=True)[source]

Computes breathing phase based on the diaphragm signal Phase is [0,1] where 0 is diaphragm onset, 0.5 is diaphragm offset, and 1 is diaphragm onset again,

  • NB: Technically can generalize to any on/off signal, but standard usage should be diaphragm

  • By default, the phase is transformed to the range [-pi, pi]

If no offset is given, the phase is linearly spaced between onsets If no stop time is given, the phase is computed until the last offset Defaults to a signal sampled at 1kHz

Parameters:

  • ons (np.ndarray) – Onset times of the diaphragm bursts.

  • offs (np.ndarray, optional) – Offset times of the diaphragm bursts. Defaults to None.

  • t_start (float, optional) – Start time for the phase computation. Defaults to 0.

  • t_stop (float, optional) – Stop time for the phase computation. Defaults to None.

  • dt (float, optional) – Time step for the output phase signal. Defaults to 1/1000.

  • transform (bool, optional) – If True, transform the phase to the range [-pi, pi]. Defaults to True.

Returns:

A tuple containing:

  • np.ndarray: Time vector for the phase.

  • np.ndarray: Phase values.

Return type:

tuple