biopsykit.protocols.cft module¶

Module representing the Cold Face Test (CFT) protocol.

class biopsykit.protocols.cft.CFT(name=None, structure=None, **kwargs)[source]¶

Bases: biopsykit.protocols.base.BaseProtocol

Class representing the Cold Face Test (CFT) and data collected while conducting the CFT.

The typical structure of the CFT consists of three phases:

“Baseline”: Time at rest before applying cold face stimulus

“CFT”: Application of cold face stimulus

“Recovery”: Time at rest after applying cold face stimulus

Parameters

name (str) – name of protocol or None to use “CFT” as default name. Default: None
structure (dict, optional) –
nested dictionary specifying the structure of the CFT.

The typical structure of the CFT consists of three phases:
- ”Baseline”: Time at rest before applying cold face stimulus
- ”CFT”: Application of cold face stimulus
- ”Recovery”: Time at rest after applying cold face stimulus
The duration of each phase is specified in seconds. Typical durations are: 60s for Baseline, 120s for CFT, 60s for Recovery

The start and duration of the CFT Exposure (cft_start and cft_duration) will be automatically extracted from the structure dictionary.
**kwargs –
additional parameters to be passed to CFT and its superclass, BaseProcessor, such as:
- cft_plot_params: dictionary with parameters to style cft_plot()

Examples

>>> from biopsykit.protocols import CFT
>>> # Example: CFT procedure consisting of three parts.
>>>
>>> structure = {
>>>     "Baseline": 60,
>>>     "CFT": 120,
>>>     "Recovery": 60
>>> }
>>> CFT(name="CFT", structure=structure)

cft_start: int¶: Start of Cold Face Exposure in seconds. It is assumed that the time between the beginning of the recording and the start of the Cold Face Exposure is the Baseline. Default: 60 seconds

cft_duration: int¶

120 seconds

Type: Duration of the Cold Face Exposure in seconds. Default

cft_plot_params: Dict[str, Any]¶

compute_cft_parameter(data, index=None, return_dict=False)[source]¶

Compute CFT parameter.

This function computes the following CFT parameter and returns the result in a dataframe (or, optionally, as dictionary):

Baseline Heart Rate (see baseline_hr() for further information)
CFT Onset (see onset() for further information)
Peak Bradycardia (see peak_bradycardia() for further information)
Mean Bradycardia (see mean_bradycardia() for further information)
Polynomial Fit on CFT Reaction (see poly_fit() for further information)

Parameters

data (DataFrame) – input data
index (str, optional) – index value of resulting dataframe. Not needed if dictionary should be returned.
return_dict (bool, optional) – True to return a dictionary with CFT parameters, False to return a dataframe. Default: False

Returns

dataframe or dictionary with CFT parameter

Return type

DataFrame or dict

baseline_hr(data)[source]¶

Compute mean heart rate during Baseline Interval.

The Baseline Interval is data in the interval [0, cft_start].

Warning

If cft_start is 0, it is assumed that no Baseline is present and the first heart rate value in the dataframe is used as CFT Baseline.

Parameters: data (DataFrame) – input data
Returns: mean heart rate during Baseline Interval
Return type: float
Raises: FeatureComputationError – if data is shorter than the expected duration of the Baseline interval

extract_cft_interval(data)[source]¶

Extract interval during which CFT was applied.

This function extracts only the part of the data during the “actual” Cold Face Test, i.e., the time during which the cold face stimulus was applied.

Parameters: data (DataFrame) – input data
Returns: data during application of cold face stimulus
Return type: DataFrame

onset(data, is_cft_interval=False, compute_baseline=True, hr_baseline=None)[source]¶

Compute CFT onset.

The CFT onset is defined as the time point after beginning of the CFT Interval where three consecutive heart beats are lower than the Baseline heart rate (typically the Interval directly before the CFT).

This function computes the following CFT onset parameter:

onset: location of CFT onset. This value is the same datatype as the index of data (i.e., either a absolute datetime timestamp or a relative timestamp in time since recording).
onset_latency: CFT onset latency, i.e., the duration between beginning of the CFT Interval and CFT onset in seconds.
onset_idx: location of CFT onset as array index
onset_hr: heart rate at CFT onset in bpm
onset_hr_brady_percent: bradycardia at CFT onset, i.e., relative change of CFT onset heart rate compared to Baseline heart rate in percent.
onset_slope: Slope between Baseline heart rate and CFT onset heart rate, computed as: onset_slope = (onset_hr - baseline_hr) / onset_latency

Parameters

data (DataFrame) – input data
is_cft_interval (bool, optional) – True if the heart rate data passed via data contains only the CFT Interval, False if it contains the data during the whole CFT procedure. Default: False
compute_baseline (bool, optional) – True if Baseline Interval is included in data passed via data and Baseline heart rate should be computed or False if Baseline heart rate is passed separately via hr_baseline. Default: True
hr_baseline (float, optional) – mean heart rate during Baseline Interval or None if Baseline interval is present in data and Baseline heart rate is computed from there. Default: None

Returns

dictionary with CFT onset parameter

Return type

dict

peak_bradycardia(data, is_cft_interval=False, compute_baseline=True, hr_baseline=None)[source]¶

Compute CFT peak bradycardia.

The CFT peak bradycardia is defined as the maximum bradycardia (i.e., the minimum heart rate) during the CFT Interval.

This function computes the following CFT peak bradycardia parameter:

peak_brady: location of CFT peak bradycardia. This value is the same datatype as the index of data (i.e., either a absolute datetime timestamp or a relative timestamp in time since recording).
peak_brady_latency: CFT peak bradycardia latency, i.e., the duration between beginning of the CFT Interval and CFT peak bradycardia in seconds.
peak_brady_idx: location of CFT peak bradycardia as array index
peak_brady_bpm: CFT peak bradycardia in bpm
peak_brady_percent: Relative change of CFT peak bradycardia heart rate compared to Baseline heart rate in percent.
peak_brady_slope: Slope between Baseline heart rate and CFT peak bradycardia heart rate, computed as: peak_brady_slope = (peak_brady_bpm - baseline_hr) / peak_brady_latency

Parameters

data (DataFrame) – input data
is_cft_interval (bool, optional) – True if the heart rate data passed via data contains only the CFT Interval, False if it contains the data during the whole CFT procedure. Default: False
compute_baseline (bool, optional) – True if Baseline Interval is included in data passed via data and Baseline heart rate should be computed or False if Baseline heart rate is passed separately via hr_baseline. Default: True
hr_baseline (float, optional) – mean heart rate during Baseline Interval or None if Baseline interval is present in data and Baseline heart rate is computed from there. Default: None

Returns

dictionary with CFT peak bradycardia parameter

Return type

dict

mean_bradycardia(data, is_cft_interval=False, compute_baseline=True, hr_baseline=None)[source]¶

Compute CFT mean bradycardia.

The CFT mean bradycardia is defined as the mean bradycardia (i.e., the mean decrease of heart rate) during the CFT Interval.

This function computes the following CFT mean bradycardia parameter:

mean_hr_bpm: average heart rate during CFT Interval in bpm
mean_brady_bpm: average bradycardia during CFT Interval, computed as: mean_brady_bpm = mean_hr_bpm - hr_baseline
mean_brady_percent: relative change of CFT mean bradycardia heart rate compared to Baseline heart rate in percent

Parameters

data (DataFrame) – input data
is_cft_interval (bool, optional) – True if the heart rate data passed via data contains only the CFT Interval, False if it contains the data during the whole CFT procedure. Default: False
compute_baseline (bool, optional) – True if Baseline Interval is included in data passed via data and Baseline heart rate should be computed or False if Baseline heart rate is passed separately via hr_baseline. Default: True
hr_baseline (float, optional) – mean heart rate during Baseline Interval or None if Baseline interval is present in data and Baseline heart rate is computed from there. Default: None

Returns

dictionary with CFT mean bradycardia parameter

Return type

dict

poly_fit(data, is_cft_interval=False, compute_baseline=True, hr_baseline=None)[source]¶

Compute CFT polynomial fit.

The CFT polynomial fit is computed by applying a 2nd order least-squares polynomial fit to the heart rate during the CFT Interval because the CFT-induced bradycardia and the following recovery is assumed to follow a polynomial function.

This function computes the following CFT polynomial fit parameter:

poly_fit_a{0-2}: constants of the polynomial p(x) = p[2] * x**deg + p[1]* x + p[0]

Parameters

data (DataFrame) – input data
is_cft_interval (bool, optional) – True if the heart rate data passed via data contains only the CFT Interval, False if it contains the data during the whole CFT procedure. Default: False
compute_baseline (bool, optional) – True if Baseline Interval is included in data passed via data and Baseline heart rate should be computed or False if Baseline heart rate is passed separately via hr_baseline. Default: True
hr_baseline (float, optional) – mean heart rate during Baseline Interval or None if Baseline interval is present in data and Baseline heart rate is computed from there. Default: None

Returns

dictionary with CFT polynomial fit parameter

Return type

dict

cft_plot(data, **kwargs)[source]¶

Draw Cold Face Test (CFT) plot.

Parameters

data (DataFrame) – input data
**kwargs (dict, optional) –
optional parameters to be passed to the plot, such as:
- time_baseline : duration of Baseline Interval to include in plot or None to include the whole Baseline Interval in the plot.
- time_recovery : duration of Recovery Interval to include in plot or None to include the whole Recovery Interval in the plot.
- plot_datetime_index : True to plot x axis with absolute time (DatetimeIndex), or False to plot data with relative time (starting from second 0). Default: False
- ax: pre-existing axes for the plot. Otherwise, a new figure and axes object is created and returned.
- figsize: tuple specifying figure dimensions
- ylims: list to manually specify y axis limits, float to specify y axis margin (see matplotlib.axes.Axes.margins() for further information), or None to automatically infer y axis limits.
- plot_onset: whether to plot CFT onset annotations or not: Default: True
- plot_peak_brady: whether to plot CFT peak bradycardia annotations or not: Default: True
- plot_mean: whether to plot CFT mean bradycardia annotations or not. Default: True
- plot_baseline: whether to plot heart rate baseline annotations or not. Default: True
- plot_poly_fit: whether to plot CFT polynomial fit annotations or not. Default: True

Returns

fig (Figure) – figure object
ax (Axes) – axes object

Return type

Tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes]

name: str¶: Study or protocol name

structure: Dict[str, Any]¶

Structure of protocol, i.e., whether protocol is divided into different parts, phases, or subphases.

If protocol is not divided into different parts protocol_structure is set to None.

saliva_types: Sequence[str]¶: List of saliva data types present in the study.

test_times: Sequence[int]¶

Start and end time of psychological test (in minutes).

If no psychological test was performed in the protocol test_times is set to [0, 0].

sample_times: Dict[str, Sequence[int]]¶

Dictionary with sample times of saliva samples (in minutes).

Sample times are either provided explicitly using the sample_times parameter in add_saliva_data() or by extracting it from the saliva data (if a time column is present).

saliva_data: Dict[str, SalivaRawDataFrame]¶

Dictionary with saliva data collected during the study.

Data in SalivaRawDataFrame format can be added using add_saliva_data().

hr_data: Dict[str, HeartRateSubjectDataDict]¶

Dictionary with heart rate data collected during the study. If the study consists of multiple study parts each part has its own HeartRateSubjectDataDict. If the study has no individual study parts (only different phases), the name of the one and only study part defaults to Study (to ensure consistent dictionary structure).

Data in HeartRateSubjectDataDict format can be added using add_hr_data().

rpeak_data: Dict[str, SubjectDataDict]¶

Dictionary with R peak data collected during the study. If the study consists of multiple study parts each part has its own SubjectDataDict. If the study has no individual study parts (only different phases), the name of the one and only study part defaults to Study (to ensure consistent dictionary structure).

Data in SubjectDataDict format can be added using add_hr_data().

hr_results: Dict[str, pd.DataFrame]¶

Dictionary with heart rate results.

Dict keys are the identifiers that are specified when computing results from hr_data using compute_hr_results().

hr_above_baseline_results: Dict[str, pd.DataFrame]¶

Dictionary with heart rate above baseline results.

Dict keys are the identifiers that are specified when computing results from hr_data using compute_hr_above_baseline().

hrv_results: Dict[str, pd.DataFrame]¶

Dictionary with heart rate variability ensemble.

Dict keys are the identifiers that are specified when computing ensemble from rpeak_data using compute_hrv_results().

hrv_above_baseline_results: Dict[str, pd.DataFrame]¶

Dictionary with heart rate variability above baseline results.

Dict keys are the identifiers that are specified when computing results from rpeak_data using compute_hrv_above_baseline().

hr_ensemble: Dict[str, Dict[str, pd.DataFrame]]¶

Dictionary with merged heart rate data for heart rate ensemble plot.

Dict keys are the identifiers that are specified when computing ensemble HR data from hr_data using compute_hr_ensemble().

See also

hr_ensemble_plot(): heart rate ensemble plot

saliva_plot_params: Dict[str, Any]¶

Plot parameters for customizing the general saliva plot for a specific psychological protocol.

See also

saliva_plot(): saliva plot

hr_mean_plot_params: Dict[str, Any]¶

Plot parameters for customizing the general HR mean plot for a specific psychological protocol.

See also

hr_mean_plot(): HR mean plot

hr_ensemble_plot_params: Dict[str, Any]¶

Plot parameters for customizing the general HR ensemble plot for a specific psychological protocol.

See also

hr_ensemble_plot(): HR ensemble plot

biopsykit.protocols.car module biopsykit.protocols.mist module