jomy-kk/ltbio

Python library for easy managing and processing of large Long-Term Biosignals. Based on top of Biosspy.

IT - Long Term Biosignals Framework

Description

Python library for easy managing and processing of large Long-Term Biosignals. This repository is object of evaluation of some Master's and Doctoral's theses.

Contribute!

• 🪲 Report bugs here.
• 💡 Suggest features here.
• 💬 Community Q&A here.

Informal Documentation

📑 Acess to the Wiki.

Full reference documentarion comming soon.

Getting Started

Installing the Package

This framework was developed and tested on Python 3.10.4, so make sure you have an interperter >= 3.10.4.

If you are familired with pip, you can download and install the package by running:

pip install LongTermBiosignals

If not, you may download the latest stable GitHub release here and place a copy of the ltbio directory (which is inside src) on your project's root.

Dependencies

See Python dependencies in requirements.txt.

You may consider installing the following on your machine if needed:

• graphviz to plot Pipeline diagrams (sudo apt-get install graphviz or brew install graphviz)
• h5py to read HDF5 files if running on an Apple Sillicon machine (brew install hdf5 && export HDF5_DIR=/opt/homebrew/bin/brew/Cellar/hdf5/<version>)

Simple Use Case

Let's create a sequence of samples using Timeseries:

from ltbio.biosignals import Timeseries

ts = Timeseries([1, 2, 3, 4, 5], initial_datetime = datetime.datetime.now(), sampling_frequency = 360.0)

Add let's pretend this was a 1-lead ECG 🫀:

from ltbio.biosignals.modalities import ECG
 
my_ecg = ECG({'Left': ts})

Simple, right? There's loads of more stuff to customize like sources, body locations, physical units, events, etc. Explore it in this notebook 📓 and in the Wiki.

---

Copyright Notice

There is no license for the content of this repository.

2022, All rights reserved. This means content of this repository cannot be reproduced nor distributed, and no work can be derived from this work without explicit and written permission from the authors.

ltbio's Issues

[BUG] Reading E4 should account to find directories inside each given directory, each representing a Segment

Describe the bug
The way E4._read is implemented it expects csv files to be right on the given directory, but it should not.
Inside the given directory, it should expect subdirectories (probably named after the start timestamp), and each should be considered a Segment in time.

Example of tree:
--- given_path
    | ---- 1655923195_A0200B
        | ---- ACC.csv
        | ---- BVP.csv
    | ---- 1656324824_A0200B
        | ---- ACC.csv
        | ---- BVP.csv
    | ...

Modules
biosignals

To Reproduce
Instructions that reproduce the behavior:

E4._read(given_path, EDA)

Terminal/Console Error

Files were not found in path given_path

Expected behavior
To read files inside subdirectories, and consider each subdirectory as a Segment.

Python Version
3.10.4

HRV features

Extraction/ Calculation

Fix HSM tests

Integrate Pytorch models

Fix events when restructuring domain

Create clinical concepts: BodyLocation, Medication, SurgicalProcedure

Create MultimodalBiosignal class

Extends Biosignal and should hold Timeseries from different modalities.

Will this be useful when requiring multimodality in ML training?

Fix Biosignal tests

Create biosignal source: HEM

Create medical condition: Epilepsy

Create biosignal source: ScientISST SENSE

Create biosignal source: Bitalino

Implement 'resampling'

Fix HEM tests

Integrate Filters truly as Pipeline Units. Add metrics and plot comparison in a report

• apply method
• SNR
• MSE / RMSE
• Plot before/after
• Bode plots

Useful features

• x
• y
• [ ]

Integrate IO code

Create concept of Unit

Personalised ML Reports

Add easy way of getting number of samples of each channel

Make Bitalino' read/write generic using JSON config files.

Add transfer functions

Motivation

Currently, data from ScientISST SENSE files are being read as raw. And it is supposed to have data in mV, uS, G, whatever, depending on the biosignal modality. That can be solved by implementing transfer functions.

Specification

Transfer functions are relative to the source device from where the data was acquired, so source-specific transfer functions should be implemented for each BiosignalSource subclass. The class BiosignalSource demands _transfer to be implemented, so that's where the transfer functions will reside.

The signature of _transfer is the following:

@staticmethod
_transfer(samples: array, type) -> array

One can read it as "transfer these samples to the default unit of this biosignal type".

Arguments:

• samples: a numpy array of one dimension with some samples of a segment in floats;
• type: A subclass of Biosginal.

It should return a numpy array with the samples converted to the default unit. The default Unit of each biosignal type is maintained in a class-constant called DEFAULT_UNIT in each subclass.

>> To check if the implemented feature is complying with Specification, all tests should pass.

Example of Use

_transfer([1.0, 2.0, 3.0, ...], ECG)

should output

[0.82, 2.23, 2.87, ...]  # merely illustrational values

Branch

Use units branch to work on this issue.

Experiment different preictal periods

Des-Segmenter

Add easy way of creating ML targets

Make ML designs private. If they're set the training history must be deleted.

Create clinical concept: Patient

ECG New Features

• Filter Signal
• Calculate R peaks
• Calculate Heart Rate
• Smooth Heart Rate Signal
• Do this process for signal1
• Do this process for signal2
• Correlation Value with Adaptive Sliding Window
• Return offset temporal deviation between signal 1 and 2

Fix Bitalino tests

Create biosignal source: HSM

Create concepts of Biosignal, TImeseries, and Segment

[BUG] Segments overlapped in plot

Describe the bug
When plotting an ECG of 5 Segments in each channel, from the 3rd Segment and on they start to overlap on the plot.

Modules
biosignals

To Reproduce
Instructions that reproduce the behavior:

ecg = ECG(data_path, Sense('run_chest'), Patient('ME93'))
ecg.plot()

Expected behavior
Segments should be visibly separated.

Screenshots

Python Version
3.10.4

[BUG] TimeDomainFilter does not perform overlap

Describe the bug
Overlap is ignored.

Modules
biosignals

To Reproduce
Instructions that reproduce the behavior:

x = Biosignal.load(biosignal_path)
median_filter1 = TimeDomainFilter(ConvolutionOperation.MEDIAN, timedelta(seconds=3), timedelta(seconds=3*0))
median_filter2 = FrequencyDomainFilter(ConvolutionOperation.MEDIAN, timedelta(seconds=3), timedelta(seconds=3*0.9))
y1 = median_filter1(x)
y1 = median_filter2(x)

The Problem
y1 and y2 are equal

Expected behavior
They should be different, because the overlap of each filter is different.

Python Version
3.11

Create clinical concept: MedicalCondition

Add events and onsets