openseize 1.3.0

Digital Signal Processing for Big EEG Datasets

Digital Signal Processing for Big EEGs

Key Features | Installation | Dependencies | Documentation | Attribution | Contributions | Issues | License | Acknowledgements

---

• Source Code: https://github.com/mscaudill/openseize
• White Paper: 10.21105/joss.05126

---

Key Features

Recent innovations in EEG recording technologies make it possible to perform high channel count recordings at high sampling frequencies spanning many days. This results in big EEG data sets that are often not addressable to virtual memory. Worse yet, current digital signal processing (DSP) packages that rely on Matlab© or Scipy's DSP routines require the data to be a contiguous in-memory array. Openseize is a fully iterative DSP Python package that can scale to the largest of EEG data sets. It accomplishes this by storing DSP operations, such as filtering, as on-the-fly iterables that "produce" DSP results one fragment of the data at a time. Additionally, Openseize is built using time-tested software design principles that support extensions while maintaining a simple interface. Finally, Openseize's documentation features in-depth discussions of iterative DSP processing and its implementation.

• Construct sequences of DSP steps that operate completely 'out-of-core' to process data too large to fit into memory.
• DSP pipelines are constructed using a familiar Scipy-like API, so you can start quickly without sweating the details.
• Supports processing of data from multiple file types including the popular European Data Format (EDF).
• Supports 'masking' to filter data sections by artifacts, behavioral states or any externally measured signals or annotations.
• Efficiently process large data using the amount of memory you choose to use.
• DSP tools currently include a large number of FIR & IIR Filters, polyphase decomposition resamplers, and spectral estimation tools for both stationary and non-stationary data.
• Built using a developer-friendly object-oriented approach to support extensibility.

Installation

For each installation guide below, we strongly recommend creating a virtual environment. This environment will isolate external dependencies that may conflict with packages you already have installed on your system. Python comes installed with a virtual environment manager called venv. Additionally, there are environment managers like conda that can check for package conflicts when the environment is created or updated. For more information please see:

• Python Virtual Environments
• Conda Environments

Python Virtual Environment

1. Create your virtual environment, Here we name it my_venv.

$ python3 -m venv my_venv

2. Activate your 'my_venv' environment

$ source my_venv/bin/activate

3. Install openseize into your virtual environment

(my_venv)$ pip install openseize

Conda

The conda environment manager is more advanced than venv. When a conda environment is updated, conda simultaneously looks at all the packages to be installed to reduce package conflicts. Having said that, conda and pip, the tool used to install Openseize from pypi, do not always work well together. The developers of conda recommend installing all possible packages from conda repositories before installing non-conda packages using pip. To ensure this order of installs, Openseize's source code includes an environment configuration file (yml) that will build an openseize conda environment. Once built you can then use pip to install the openseize package into this environment. Here are the steps:

1. Download the openseize environment configuration yaml

2. Create a conda openseize environment.

$ conda env create --file environment.yml

3. Activate the openseize environment.

$ conda activate openseize

4. Install openseize from pypi into your openseize environment.

(openseize)$ pip install openseize

From Source

If you would like to develop Openseize further, you'll need the source code and all development dependencies. Here are the steps:

1. Create a virtual environment with latest pip version.

$ python3 -m venv env
$ source env/bin/activate
$ pip install --upgrade pip

2. Get the source code

$ git clone https://github.com/mscaudill/openseize.git

3. CD into the directory containing the pyproject.toml and create an editable install with pip

$ pip install -e .[dev]

Dependencies

Openseize requires Python ≥ 3.12 and has the following dependencies:

package	pypi	conda
requests	https://pypi.org/project/requests/	✓
wget	https://pypi.org/project/wget/	✓
numpy	https://pypi.org/project/numpy/	✓
scipy	https://pypi.org/project/scipy/	✓
matplotlib	https://pypi.org/project/matplotlib/	✓
ipython	https://pypi.org/project/ipython/	✓
notebook	https://pypi.org/project/jupyter/	✓
pytest	https://pypi.org/project/pytest/	✓
psutil	https://pypi.org/project/psutil/	✓

Documentation

Openseize documentation site has a quickstart guide, extensive tutorials and reference pages for all publicly available modules, classes and functions.

Attribution

Please see the Cite this repository under the About section or the citation file.

And if you really like Openseize, you can star the repository ⭐!

Contributions

Contributions are what makes open-source fun and we would love for you to contribute. Please check out our contribution guide to get started.

Issues

Openseize provides custom issue templates for filing bugs, requesting feature enhancements, suggesting documentation changes, or just asking questions. Ready to discuss? File an issue here.

License

Openseize is licensed under the terms of the 3-Clause BSD License.

Acknowledgements

This work is generously supported through the Ting Tsung and Wei Fong Chao Foundation and the National Institute of Neurological Disorders and Stroke (Grant 2R01 NS100738-05A1).