Metadata-Version: 2.4
Name: physio_cassette
Version: 0.2.16
Summary: Storage structures for signals (mostly physiological data), metadata and event annotations
Project-URL: homepage, https://codeberg.org/LucaCerina/physio-cassette
Project-URL: Bug Tracker, https://codeberg.org/LucaCerina/physio-cassette/issues
Keywords: data storage,physiological signals,event records
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>2.0
Requires-Dist: openpyxl<=3.1
Requires-Dist: openpyxl-dictreader>=0.1.9
Requires-Dist: xlrd>=2.0.2
Requires-Dist: pyedflib>=0.1.40
Requires-Dist: pymatreader>=1.0.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: scipy>=1.16
Requires-Dist: traces>=0.5.1
Requires-Dist: wfdb>=4.3.0
Requires-Dist: xmltodict>=0.13.0
Dynamic: license-file

# Physio Cassette: Storage structures for signals, metadata and event annotations
Managing signals in physiology and associated metadata can be a pain.

You want abstraction, but not much from any underlying Numpy array holding them.

You want annotations in signals, but not obscure proprietary representations.

Physio Cassette is just that: Numpy arrays and dictionaries with flair. Physio Cassette provides also automatic caching operations using pickle and matlab storage


### Basic data structures
- Signal: a numpy array with associated sampling frequency, timestamps and minor metadata. Zero-cost abstraction, the data can be accessed directly
- EventRecord: a class for time annotated events based on [traces](https://github.com/datascopeanalytics/traces) TimeSeries with support for binary, trains, and multilevel events

Signals can be iterated using EventRecord events as anchor points and viceversa Events can be converted to a sampled Signal

### Containers
- DataHolder: your box of cables based on Python dictionary. Parent class of SignalFrame and EventFrame.
- SignalFrame: A container for Signal data structures.
- EventFrame: A container for EventRecord structures, with support to merge operations (e.g. events annotated across multiple channels).

### Supported Inputs
Physio-cassette aims to support seamlessly different file and data formats. All parsers can be customized without additional code to support more exotic / less interoperable data representations.

XML format is currently based on NSRR interpretation of data annotations.

Some functionalities will be added in the future. Other format specific features (e.g. physical/digital ranges in EDF and WFDB) are absent on purpose.

| Structure   | Numpy arrays       | CSV/columnar files | Matlab files                       | EDF files          | Physionet WFDB     | XML                |
|-------------|--------------------|--------------------|------------------------------------|--------------------|--------------------|--------------------|
| Signal      | YES                |                    | YES                                | (use SignalFrame)  | (use SignalFrame)  |                    |
| SignalFrame | YES                |                    | YES                (1 file/signal) | YES                | YES                |                    |
| EventRecord | YES                | YES                |                                    |                    | YES                | YES                |
| EventFrame  | (use EventRecords) | YES                |                                    |                    | YES                | YES                |

### Caching
To cache an operation simply do:
```python
from physio_cassette import autocache

def your_function(x:int) -> bool:
    # Some long operation you want to cache
    return True

result = autocache(your_function, '~/path_to_cache_folder', 'desired_cache_file')(1)
```

## Installation
To install PhysioCassette run:
```bash
$ pip install physio_cassette
```

## Dependencies
- Numpy
- Scipy (Matlab IO)
- [traces](https://github.com/datascopeanalytics/traces)
- [openpyxl-dictreader](https://pypi.org/project/openpyxl-dictreader/) (excel files IO)
- [xlrd](https://pypi.org/project/xlrd/) (old excel format)
- [pyedflib](https://github.com/holgern/pyedflib)
- [pymatreader](https://pypi.org/project/pymatreader/)
- [dateutil](https://pypi.org/project/python-dateutil/)
- [wfdb](https://pypi.org/project/wfdb/)
- [xmltodict](https://pypi.org/project/xmltodict/)


#### Contributing
Looking for people more experienced in writing unit tests and overall beta-testers to help with the reliability of the library

If you feel generous and this library helped your project:

[![Buy me a coffee][buymeacoffee-shield]][buymeacoffee]

[buymeacoffee]: https://www.buymeacoffee.com/u2Vb3kO
[buymeacoffee-shield]: https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png
