biopsykit.io.nilspod module¶

Module for importing data recorded by NilsPod sensors.

biopsykit.io.nilspod.load_dataset_nilspod(file_path=None, dataset=None, datastreams=None, handle_counter_inconsistency='raise', **kwargs)[source]¶

Load NilsPod recording and convert into dataframe.

To load a dataset either a Dataset object (via dataset parameter) or the path to the binary file (via file_path variable) can be passed.

Parameters

file_path (Path or str, optional) – path to binary file
dataset (Dataset, optional) – Dataset object
datastreams (str or list of str, optional) – list of datastreams if only specific datastreams of the dataset object should be imported or None to load all datastreams. Datastreams that are not part of the current dataset will be silently ignored. Default: None
handle_counter_inconsistency ({"raise", "warn", "ignore"}, optional) –
how to handle if counter of dataset is not monotonously increasing, which might be an indicator for a corrupted dataset:
- ”raise” (default): raise an error
- ”warn”: issue a warning but still return a dataframe
- ”ignore”: ignore the counter check result
**kwargs –
optional arguments passed to from_bin_file(), such as:
legacy_support{“error”, “warn”, “resolve”}, optional
Flag indicating how to deal with older NilsPod firmware versions:
- ”error”: raise an error if an unsupported version is detected
- ”warn”: issue a warning and parse the file without modification
- ”resolve” (default): perform a legacy conversion to load old files. If no suitable conversion is found, an error is raised. See the nilspodlib.legacy package and the README of nilspodlib to learn more about available conversions.
timezonestr or datetime.tzinfo, optional
timezone of the acquired data, either as string of as tzinfo object. Default: “Europe/Berlin”

Returns

dfDataFrame: dataframe of imported dataset
fsfloat: sampling rate

Return type

tuple

Raises

FileExtensionError – if file_path is specified and file is not a binary (.bin) file
ValueError – if neither file_path nor dataset are supplied as parameter, if handle_counter_inconsistency is raise and Dataset counter is inconsistent (not monotonously increasing), if legacy_support is raise and so suitable conversion can be found for this file version.

See also

Dataset: NilsPod Dataset

Examples

>>> from biopsykit.io.nilspod import load_dataset_nilspod
>>> # Option 1: Import data by passing file name
>>> file_path = "./<filename-of-nilspod-data>.bin"
>>> # load dataset with all datastreams
>>> df, fs = load_dataset_nilspod(file_path=file_path)
>>> # load only ECG data of dataset
>>> df, fs = load_dataset_nilspod(file_path=file_path, datastreams=['ecg'])
>>>
>>> # Option 2: Import data by passing Dataset object imported from NilsPodLib
>>> # (in this example, only acceleration data)
>>> from nilspodlib import Dataset
>>> dataset = Dataset.from_bin_file("<filename>.bin")
>>> df, fs = load_dataset_nilspod(dataset=dataset, datastreams='acc')

biopsykit.io.nilspod.load_synced_session_nilspod(folder_path, datastreams=None, handle_counter_inconsistency='raise', **kwargs)[source]¶

Load a synchronized session of NilsPod recordings and convert into dataframes.

Parameters

folder_path (Path or str, optional) – folder path to session files
datastreams (list of str, optional) – list of datastreams if only specific datastreams of the datasets in the session should be imported or None to load all datastreams. Datastreams that are not part of the current datasets will be silently ignored. Default: None
handle_counter_inconsistency ({"raise", "warn", "ignore"}, optional) –
how to handle if counter of dataset is not monotonously increasing, which might be an indicator for a corrupted dataset:
- ”raise” (default): raise an error
- ”warn”: issue a warning but still return a dataframe
- ”ignore”: ignore the counter check result
**kwargs –
optional arguments passed to from_folder_path(), such as:
legacy_support{“error”, “warn”, “resolve”}, optional
Flag indicating how to deal with older NilsPod firmware versions:
- ”error”: raise an error if an unsupported version is detected
- ”warn”: issue a warning and parse the file without modification
- ”resolve” (default): perform a legacy conversion to load old files. If no suitable conversion is found, an error is raised. See the nilspodlib.legacy package and the README of nilspodlib to learn more about available conversions.
timezonestr or datetime.tzinfo, optional
timezone of the acquired data, either as string of as tzinfo object. Default: “Europe/Berlin”

Returns

dfDataFrame: concatenated dataframe of imported session
fsfloat: sampling rate

Return type

tuple

Raises

ValueError – if handle_counter_inconsistency is raise and counter of any dataset is inconsistent (not monotonously increasing). If legacy_support is raise and so suitable conversion can be found for the files in the session. If sampling rate is not the same for all datasets in the session ValueError If folder_path does not contain any NilsPod files If the sampling rates of the files in the folder are not the same

See also

Dataset: NilsPod Dataset
load_dataset_nilspod(): load a single NilsPod dataset

biopsykit.io.nilspod.load_csv_nilspod(file_path=None, datastreams=None, timezone=<DstTzInfo 'Europe/Berlin' LMT+0:53:00 STD>, filename_regex=None, time_regex=None)[source]¶

Convert a csv file recorded by NilsPod into a dataframe.

By default, this function expects the file name to have the following pattern: “NilsPodX-<sensor-id>_YYYYMMDD_hhmmss.csv”. The time information in the file name is used to infer the start time of the recording and add absolute time information to return a dataframe with a DatetimeIndex.

If no start time can be extracted the index of the resulting dataframe is a TimedeltaIndex, not a DatetimeIndex.

Parameters

file_path (Path or str, optional) – path to binary file
datastreams (list of str, optional) – list of datastreams if only specific datastreams of the file should be imported or None to load all datastreams. Datastreams that are not part of the current dataset will be silently ignored. Default: None
timezone (str or datetime.tzinfo, optional) – timezone of the acquired data, either as string or as tzinfo object. Default: ‘Europe/Berlin’
filename_regex (str, optional) – regex string to extract time substring from file name or None to use default file name pattern. Default: None
time_regex (str, optional) – regex string specifying format of time substring or None to use default time format. Default: None

Returns

df (DataFrame) – dataframe of imported dataset
fs (float) – sampling rate

Raises

FileExtensionError – if file is no csv file

Return type

Tuple[pandas.core.frame.DataFrame, float]

See also

Dataset: NilsPod Dataset
None: load a single NilsPod dataset from binary file

biopsykit.io.nilspod.load_folder_nilspod(folder_path, phase_names=None, **kwargs)[source]¶

Load all NilsPod datasets from one folder, convert them into dataframes, and combine them into a dictionary.

This function can for example be used when single NilsPod sessions (datasets) were recorded for different study phases.

Parameters

folder_path (Path or str, optional) – folder path to files
phase_names (list, optional) – list of phase names corresponding to the files in the folder. Must match the number of recordings. If None phase names will be named Part{1-x}. Default: None
**kwargs – additional arguments that are passed to load_dataset_nilspod()

Returns

dataset_dict (dict) – dictionary with phase names as keys and pandas dataframes with sensor recordings as values
fs (float) – sampling rate of sensor recordings

Raises

ValueError – if folder_path does not contain any NilsPod files, the number of phases does not match the number of datasets in the folder, or if the sampling rates of the files in the folder are not the same

Return type

Tuple[Dict[str, pandas.core.frame.DataFrame], float]

See also

load_dataset_nilspod(): load single NilsPod dataset

Examples

>>> from biopsykit.io.nilspod import load_folder_nilspod
>>> folder_path = "./nilspod"
>>> # load all datasets from the selected folder with all datastreams
>>> dataset_dict, fs = load_folder_nilspod(folder_path)
>>> # load only ECG data of all datasets from the selected folder
>>> dataset_dict, fs = load_folder_nilspod(folder_path, datastreams=['ecg'])
>>> # load all datasets from the selected folder with correspondng phase names
>>> dataset_dict, fs = load_folder_nilspod(folder_path, phase_names=['VP01','VP02','VP03'])

biopsykit.io.nilspod.check_nilspod_dataset_corrupted(dataset)[source]¶

Check if a NilsPod dataset is potentially corrupted.

A dataset is potentially corrupted if the counter is not monotonously increasing.

Parameters: dataset (Dataset) – dataset to check
Returns: flag indicating whether a NilsPod dataset is potentially corrupted or not
Return type: bool

biopsykit.io.nilspod.get_nilspod_dataset_corrupted_info(dataset, file_path)[source]¶

Get information about the corruption state of a NilsPod dataset.

Corruption information include the information:

“name”: recording date and time

“percent_corrupt”: Amount of corrupted data in percent

“condition”: Condition of the dataset. Can be one of:

“fine”: if dataset is not corrupted

“lost”: if more than 90% of all samples are corrupted

“parts”: if between 50% and 90% of all samples are corrupted

“start_only”: if less than 50% of all samples are corrupted and corrupted samples are only in the first third of the dataset

“end_only”: if less than 50% of all samples are corrupted and corrupted samples are only in the last third of the dataset

Parameters

dataset (Dataset, optional) – Dataset object
file_path (Path or str, optional) – path to binary file

Returns

dictionary with corruption information

Return type

dict

biopsykit.io.io module biopsykit.io.psg module