biosppy.storage¶

This module provides several data storage methods.

copyright:

2015-2026 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

Functions

`alloc_h5`(path)	Prepare an HDF5 file.
`deserialize`(path)	Deserialize data from a file using sklearn's joblib.
`dumpJSON`(data, path)	Save JSON data to a file.
`loadJSON`(path)	Load JSON data from a file.
`load_carto_study`(filename[, verbose])	Loads a CARTO study from a .xml file.
`load_edf`(path)	Load data from an EDF+ (European Data Format) file.
`load_h5`(path, label)	Load data from an HDF5 file.
`load_txt`(path)	Load data from a text file.
`pack_zip`(files, path[, recursive, forceExt])	Pack files into a zip archive.
`serialize`(data, path[, compress])	Serialize data and save to a file using sklearn's joblib.
`store_h5`(path, label, data)	Store data to HDF5 file.
`store_txt`(path, data[, sampling_rate, ...])	Store data to a simple text file.
`unpack_zip`(zip_path, path)	Unpack a zip archive.
`zip_write`(fid, files[, recursive, root])	Write files to zip archive.

Classes

HDF([path, mode])

Wrapper class to operate on BioSPPy HDF5 files.

class biosppy.storage.HDF(path=None, mode='a')[source]¶

Bases: object

Wrapper class to operate on BioSPPy HDF5 files.

Parameters:

path (str) – Path to the HDF5 file.
mode (str, optional) –
File mode; one of:
- ’a’: read/write, creates file if it does not exist;
- ’r+’: read/write, file must exist;
- ’r’: read only, file must exist;
- ’w’: create file, truncate if it already exists;
- ’w-’: create file, fails if it already esists.

add_event(ts=None, values=None, mdata=None, group='', name=None, compress=False)[source]¶

Add an event to the file.

Parameters:

ts (array) – Array of time stamps.
values (array, optional) – Array with data for each time stamp.
mdata (dict, optional) – Event metadata.
group (str, optional) – Destination event group.
name (str, optional) – Name of the dataset to create.
compress (bool, optional) – If True, the data will be compressed with gzip.

Returns:

group (str) – Destination group.
name (str) – Name of the created event dataset.

add_header(header=None)[source]¶

Add header metadata.

Parameters:: header (dict) – Header metadata.

add_signal(signal=None, mdata=None, group='', name=None, compress=False)[source]¶

Add a signal to the file.

Parameters:

signal (array) – Signal to add.
mdata (dict, optional) – Signal metadata.
group (str, optional) – Destination signal group.
name (str, optional) – Name of the dataset to create.
compress (bool, optional) – If True, the signal will be compressed with gzip.

Returns:

group (str) – Destination group.
name (str) – Name of the created signal dataset.

close()[source]¶: Close file descriptor.

del_event(group='', name=None)[source]¶

Delete an event from the file.

Parameters:

group (str, optional) – Event group.
name (str) – Name of the event dataset.

del_event_group(group='')[source]¶

Delete all events in a file group.

Parameters:

str (group) – Event group.
optional – Event group.

del_signal(group='', name=None)[source]¶

Delete a signal from the file.

Parameters:

group (str, optional) – Signal group.
name (str) – Name of the dataset.

del_signal_group(group='')[source]¶

Delete all signals in a file group.

Parameters:: group (str, optional) – Signal group.

get_event(group='', name=None)[source]¶

Retrieve an event from the file.

Parameters:

group (str, optional) – Event group.
name (str) – Name of the event dataset.

Returns:

ts (array) – Array of time stamps.
values (array) – Array with data for each time stamp.
mdata (dict) – Event metadata.

Notes

Loads the entire event data into memory.

get_header()[source]¶

Retrieve header metadata.

Returns:: header (dict) – Header metadata.

get_signal(group='', name=None)[source]¶

Retrieve a signal from the file.

Parameters:

group (str, optional) – Signal group.
name (str) – Name of the signal dataset.

Returns:

signal (array) – Retrieved signal.
mdata (dict) – Signal metadata.

Notes

Loads the entire signal data into memory.

list_events(group='', recursive=False)[source]¶

List events in the file.

Parameters:

group (str, optional) – Event group.
recursive (bool, optional) – If True, also lists events in sub-groups.

Returns:

events (list) – List of (group, name) tuples of the found events.

list_signals(group='', recursive=False)[source]¶

List signals in the file.

Parameters:

group (str, optional) – Signal group.
recursive (bool, optional) – If True, also lists signals in sub-groups.

Returns:

signals (list) – List of (group, name) tuples of the found signals.

biosppy.storage.alloc_h5(path)[source]¶

Prepare an HDF5 file.

Parameters:: path (str) – Path to file.

biosppy.storage.deserialize(path)[source]¶

Deserialize data from a file using sklearn’s joblib.

Parameters:: path (str) – Source path.
Returns:: data (object) – Deserialized object.

biosppy.storage.dumpJSON(data, path)[source]¶

Save JSON data to a file.

Parameters:

data (dict) – The JSON data to dump.
path (str) – Destination path.

biosppy.storage.loadJSON(path)[source]¶

Load JSON data from a file.

Parameters:: path (str) – Source path.
Returns:: data (dict) – The loaded JSON data.

biosppy.storage.load_carto_study(filename, verbose=1)[source]¶

Loads a CARTO study from a .xml file. The function extracts the relevant information about the maps, points, and signals, and saves them as .csv files in a subfolder for each map.

Adapted to Python from original MATLAB code written by the OpenEP team [OpenEP] [OpenEP2]. Available at: https://github.com/openep/openep-core

Parameters: filename : str

Path to the CARTO .xml file.

References

[OpenEP]

Williams SE and Linton NWF (Feb. 2026). OpenEP/openep-core: v1.0.03 (Version v1.0.03). Zenodo. https://doi.org/10.5281/zenodo.4471318

[OpenEP2]

Williams SE, Roney CH, Connolly A, Sim I, Whitaker J, O’Hare D, Kotadia I, O’Neill L, Corrado C, Bishop M, Niederer SA, Wright M, O’Neill M and Linton NWF (2021) OpenEP: A Cross-Platform Electroanatomic Mapping Data Format and Analysis Platform for Electrophysiology Research. Front. Physiol. 12:646023. doi: 10.3389/fphys.2021.646023

biosppy.storage.load_edf(path)[source]¶

Load data from an EDF+ (European Data Format) file.

Parameters:

path (str) – Path to the EDF file.

Returns:

signals (array) – Array of signals read from the EDF file. Each column represents a signal.
mdata (dict) – Metadata extracted from the EDF file, including: - version : str - patient_id : str - recording_id : str - start_date : str - start_time : str - header_bytes : str - reserved : str - num_data_records : int - duration_per_data_record : float - num_signals : int - labels : list of str - units : list of str - sampling_rates : list of int - physical_min : list of float - physical_max : list of float - digital_min : list of int - digital_max : list of int - annotations : list of tuples (onset, duration, annotation)

Notes

This function reads the EDF file header and data records, scales the signals into physical units, and parses the annotations according to the EDF+ specification.

biosppy.storage.load_h5(path, label)[source]¶

Load data from an HDF5 file.

Parameters:

path (str) – Path to file.
label (hashable) – Data label.

Returns:

data (array) – Loaded data.

biosppy.storage.load_txt(path)[source]¶

Load data from a text file.

Parameters:

path (str) – Path to file.

Returns:

data (array) – Loaded data.
mdata (dict) – Metadata.

biosppy.storage.pack_zip(files, path, recursive=True, forceExt=True)[source]¶

Pack files into a zip archive.

Parameters:

files (iterable) – List of files or directories to pack.
path (str) – Destination path.
recursive (bool, optional) – If True, sub-directories and sub-folders are also written to the archive.
forceExt (bool, optional) – Append default extension.

Returns:

zip_path (str) – Full path to created zip archive.

biosppy.storage.serialize(data, path, compress=3)[source]¶

Serialize data and save to a file using sklearn’s joblib.

Parameters:

data (object) – Object to serialize.
path (str) – Destination path.
compress (int, optional) – Compression level; from 0 to 9 (highest compression).

biosppy.storage.store_h5(path, label, data)[source]¶

Store data to HDF5 file.

Parameters:

path (str) – Path to file.
label (hashable) – Data label.
data (array) – Data to store.

biosppy.storage.store_txt(path, data, sampling_rate=1000.0, resolution=None, date=None, labels=None, precision=6)[source]¶

Store data to a simple text file.

Parameters:

path (str) – Path to file.
data (array) – Data to store (up to 2 dimensions).
sampling_rate (int, float, optional) – Sampling frequency (Hz).
resolution (int, optional) – Sampling resolution.
date (datetime, str, optional) – Datetime object, or an ISO 8601 formatted date-time string.
labels (list, optional) – Labels for each column of data.
precision (int, optional) – Precision for string conversion.

Raises:

ValueError – If the number of data dimensions is greater than 2.
ValueError – If the number of labels is inconsistent with the data.

biosppy.storage.unpack_zip(zip_path, path)[source]¶

Unpack a zip archive.

Parameters:

zip_path (str) – Path to zip archive.
path (str) – Destination path (directory).

biosppy.storage.zip_write(fid, files, recursive=True, root=None)[source]¶

Write files to zip archive.

Parameters:

fid (file-like object) – The zip file to write into.
files (iterable) – List of files or directories to pack.
recursive (bool, optional) – If True, sub-directories and sub-folders are also written to the archive.
root (str, optional) – Relative folder path.

Notes

Ignores non-existent files and directories.