biopsykit.io.ecg module¶
I/O functions for files related to ECG processing.
- biopsykit.io.ecg.load_hr_phase_dict(file_path, assert_format=True)[source]¶
Load Excel file containing time series heart rate data of one subject.
The returned dictionary will be a
HeartRatePhaseDict
, i.e., a dict with heart rate data from one subject split into phases (as exported bywrite_hr_phase_dict()
orwrite_hr_phase_dict_csv()
).- Parameters
- Returns
Dict with heart rate data split into phases
- Return type
- Raises
ValidationError – if file in
file_path
is not aHeartRatePhaseDict
(ifassert_format
isTrue
)FileExtensionError – if file is no Excel file (.xls or .xlsx)
See also
HeartRatePhaseDict
Dictionary format
write_hr_phase_dict
Write
HeartRatePhaseDict
to file
- biopsykit.io.ecg.load_hr_phase_dict_folder(base_path, filename_pattern, subfolder_pattern=None)[source]¶
Load a folder with multiple
HeartRatePhaseDict
and concatenate them into aHeartRateSubjectDataDict
.This functions looks for all files that match the
file_pattern
in the folder specified bybase_path
and loads the files that are all expected to beHeartRatePhaseDict
.Subject IDs are extracted from the file name. Hence,
file_pattern
needs to be a regex including a capture group, e.g. “ecg_results_(\w+).xlsx”.Alternatively, if the files are stored in subfolders, the name pattern of these subfolders can be specified by
subject_folder_pattern
. Then, it is expected that the subfolder names correspond to the subject IDs.The returned dictionary will be a
HeartRateSubjectDataDict
with the following format:{
subject_id
:HeartRatePhaseDict
}- Parameters
base_path – path to top-level folder containing all subject folders
filename_pattern (str) – filename pattern of exported
HeartRatePhaseDict
. Must be a regex string with capture group to extract subject IDs, or a regular regex string (without capture group) ifsubfolder_pattern
is specifiedsubfolder_pattern (str, optional) – subfolder name pattern if files are stored in subfolders. Then,
filename_pattern
does not need to be a regex with a capture group because it is assumed that the names of the subfolders correspond to the subject IDs.
- Returns
HeartRateSubjectDataDict
, i.e., a dictionary withHeartRatePhaseDict
of multiple subjects- Return type
- Raises
ValidationError – if any file that matches
filename_pattern
is not aHeartRatePhaseDict
FileNotFoundError – if no files match
filename_pattern
or no subfolders matchsubfolder_pattern
See also
get_subject_dirs
Filter for subject subfolders in a given folder
load_hr_phase_dict
Load
HeartRatePhaseDict
for one subject
Examples
>>> from biopsykit.io.ecg import load_hr_phase_dict_folder >>> base_path = "./ecg_results/" >>> # Option 1: all files are stored in `base_path`, subject IDs are extracted from the file names >>> dict_hr_subjects = load_hr_phase_dict_folder( >>> base_path, >>> filename_pattern=r"ecg_result_(\\w+).xlsx") >>> print(dict_hr_subjects) { 'Vp01': {}, # one single HeartRatePhaseDict 'Vp02': {}, # ... } >>> # Option 2: files are stored in subfolders, the name of the subfolders is the corresponding subject ID >>> dict_hr_subjects = load_hr_phase_dict_folder( >>> base_path, >>> filename_pattern=r"ecg_result*.xlsx", >>> subfolder_pattern="Vp*") >>> print(dict_hr_subjects) { 'Vp01': {}, # one single HeartRatePhaseDict 'Vp02': {}, # ... }
- biopsykit.io.ecg.load_hr_phase_dict_csv(folder_path, file_pattern, phase_order=None, assert_format=True)[source]¶
Load csv file with time series HR data of one subject from folder and combine it into a
HeartRatePhaseDict
.The returned dictionary will be a
HeartRatePhaseDict
, i.e., a dict with heart rate data from one subject split into phases (as exported bywrite_hr_phase_dict()
).- Parameters
folder_path (
Path
or str) – folder path to export csv filesfile_pattern (
Path
or str) – file pattern of the csv files. file_pattern must include a regex capture group (see Examples) which is used to extract the phase name from the file name.phase_order (list of str, optional) – list of phase names to order resulting
HeartRatePhaseDict
orNone
to order phases according to the file name ordering infolder_path
. Default:None
assert_format (bool, optional) – whether to check if the imported dict is in the right format or not
- Returns
Dict with heart rate data split into phases
- Return type
- Raises
ValidationError – if file in
file_path
is not aHeartRatePhaseDict
(ifassert_format
isTrue
)FileExtensionError – if file is no Excel file (.xls or .xlsx)
See also
HeartRatePhaseDict
Dictionary format
write_hr_phase_dict_csv
Write
HeartRatePhaseDict
to a series of csv files
- biopsykit.io.ecg.write_hr_phase_dict(hr_phase_dict, file_path)[source]¶
Write
HeartRatePhaseDict
to an Excel file.The
HeartRatePhaseDict
is a dictionary with heart rate time series data split into phases.Each of the phases in the dictionary will be a separate sheet in the Excel file.
- Parameters
hr_phase_dict (
HeartRatePhaseDict
) – aHeartRatePhaseDict
containing pandas dataframes with heart rate datafile_path (
Path
or str) – path to export file
See also
HeartRatePhaseDict
Dictionary format
load_hr_phase_dict
Load
HeartRatePhaseDict
written to filewrite_pandas_dict_excel
Write dictionary with pandas dataframes to Excel file
- biopsykit.io.ecg.write_hr_phase_dict_csv(hr_phase_dict, folder_path, file_pattern)[source]¶
Write
HeartRatePhaseDict
to a series of csv files.The
HeartRatePhaseDict
is a dictionary with heart rate time series data split into phases.Each of the phases in the dictionary will be a separate csv file.
- Parameters
hr_phase_dict (
HeartRatePhaseDict
) – aHeartRatePhaseDict
containing pandas dataframes with heart rate datafolder_path (
Path
or str) – folder path to export csv filesfile_pattern (
Path
or str) – file pattern to save. The file pattern must include a placeholder “{}” which will be filled with the name of the phase.
- Raises
ValueError – if
file_pattern
does not include a placeholder “{}” that can be filled with the phase nameValidationError – if
hr_phase_dict
is not aHeartRatePhaseDict
FileExtensionError – if
file_pattern
is no csv file
See also
HeartRatePhaseDict
Dictionary format
load_hr_phase_dict_csv
Load
HeartRatePhaseDict
written to csv files