biopsykit.protocols.mist module¶
Module representing the Montreal Imaging Stress Task (MIST) protocol.
- class biopsykit.protocols.mist.MIST(name=None, structure=None, **kwargs)[source]¶
Bases:
biopsykit.protocols.base.BaseProtocol
Class representing the Montreal Imaging Stress Task (MIST) protocol and data collected within a MIST study.
The general structure of the MIST can be specified by passing a
structure
dict to the constructor.Up to three nested structure levels are supported:
1st level:
study part
: Different parts of the study where the MIST was conducted, such as: “Pre”, “MIST”, and “Post”2nd level:
phase
: Different MIST phases that belong to the same study part, such as: “MIST1”, “MIST2”, “MIST3” (for study part “MIST”) or “Questionnaires”, “Rest”, “Training” (for study part “Pre”)3rd level:
subphase
: Different MIST subphases that belong to the same phase, such as: “Baseline”, “Arithmetic Task”, “Feedback”
- Parameters
name (str, optional) – name of protocol or
None
to use “MIST” as default name. Default:None
structure (dict, optional) –
nested dictionary specifying the structure of the MIST study.
Up to three nested structure levels are supported:
1st level:
study part
: Different parts of the study where the MIST was conducted, such as: “Pre”, MIST”, and “Post”2nd level:
phase
: Different MIST phases that belong to the same study part, such as: “MIST1”, “MIST2”, “MIST3” (for study part “MIST”) or “Questionnaires”, “Rest”, “Training” (for study part “Pre”)3rd level:
subphase
: Different MIST subphases that belong to the same phase, such as: “Baseline”, “Arithmetic Task”, “Feedback”
If a study part has no division into finer phases (or a phase has no division into finer subphases) the dictionary value can be set to
None
.**kwargs –
additional parameters to be passed to
MIST
and its superclass,BaseProtocol
, such as:saliva_plot_params
: dictionary with parameters to stylesaliva_plot()
hr_mean_plot_params
: dictionary with parameters to stylehr_mean_plot()
hr_ensemble_plot_params
: dictionary with parameters to stylehr_ensemble_plot()
Examples
>>> from biopsykit.protocols import MIST >>> # Example: MIST study consisting of three parts. Only the MIST part consists of different >>> # phases and subphases >>> structure = { >>> "Before": None, >>> "MIST": { >>> "MIST1": {"BL": 60, "AT": 240, "FB": 120}, >>> "MIST2": {"BL": 60, "AT": 240, "FB": 120}, >>> "MIST3": {"BL": 60, "AT": 240, "FB": 120} >>> }, >>> "After": None >>> } >>> MIST(name="MIST", structure=structure)
References
Dedovic, K., Renwick, R., Mahani, N. K., Engert, V., Lupien, S. J., & Pruessner, J. C. (2005). The Montreal Imaging Stress Task: Using functional imaging to investigate the effects of perceiving and processing psychosocial stress in the human brain. Journal of Psychiatry and Neuroscience, 30(5), 319-325.
- hr_ensemble_plot(ensemble_id, subphases=None, **kwargs)[source]¶
Draw heart rate ensemble plot.
- Parameters
ensemble_id (str) – identifier of the ensemble data to be plotted. Ensemble data needs to be computed using
compute_hr_ensemble()
first.subphases (dict, optional) – dictionary with phases (keys) and subphases (values - dict with subphase names and subphase durations) or
None
to retrieve MIST information fromstructure
dict. When passingNone
, it is assumed that the study part containing the MIST is namedMIST
.**kwargs (dict, optional) – optional arguments for plot configuration to be passed to
hr_ensemble_plot()
.
- Returns
fig (
matplotlib.figure.Figure
) – figure objectax (
matplotlib.axes.Axes
) – axes object
- Return type
See also
compute_hr_ensemble()
compute heart rate ensemble data
hr_ensemble_plot()
Heart rate ensemble plot
- 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 toNone
.
- 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 inadd_saliva_data()
or by extracting it from the saliva data (if atime
column is present).
- saliva_data: Dict[str, SalivaRawDataFrame]¶
Dictionary with saliva data collected during the study.
Data in
SalivaRawDataFrame
format can be added usingadd_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 toStudy
(to ensure consistent dictionary structure).Data in
HeartRateSubjectDataDict
format can be added usingadd_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 toStudy
(to ensure consistent dictionary structure).Data in
SubjectDataDict
format can be added usingadd_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
usingcompute_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
usingcompute_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
usingcompute_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
usingcompute_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
usingcompute_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