Metadata-Version: 2.4
Name: readmanager
Version: 1.2.1
Summary: Read, write and convert OpenBCI signal recordings (.raw/.xml/.tag)
Author: Faculty of Physics, University of Warsaw
Author-email: BrainTech <admin@braintech.pl>
License-Expression: GPL-3.0-or-later
Keywords: bci,eeg,obci,signal,readmanager
Classifier: Development Status :: 4 - Beta
Classifier: Natural Language :: English
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Provides-Extra: mne
Requires-Dist: mne>=1.5; extra == "mne"
Provides-Extra: balance
Requires-Dist: scipy; extra == "balance"
Requires-Dist: matplotlib; extra == "balance"
Provides-Extra: all
Requires-Dist: readmanager[balance,mne]; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: pytest-timeout; extra == "test"
Requires-Dist: readmanager[all]; extra == "test"

# readmanager

Read, write and convert [OBCI](https://gitlab.com/fuw_software/obci) signal
recordings stored in the OBCI file format (`.raw` / `.xml` / `.tag`).

## Installation

```bash
pip install readmanager            # core (numpy only)
pip install readmanager[mne]       # + MNE-Python conversion
pip install readmanager[balance]   # + Wii Balance Board analysis (scipy)
pip install readmanager[all]       # everything
```

Requires Python 3.10+.

## Quick start

```python
from obci_readmanager.signal_processing.read_manager import ReadManager

# Open a recording (three files: .raw, .xml, .tag)
mgr = ReadManager(
    "recording.obci.xml",
    "recording.obci.raw",
    "recording.obci.tag",
)

# Access signal parameters
print(mgr.get_param("sampling_frequency"))
print(mgr.get_param("channels_names"))

# Get all samples as a numpy array (channels x samples)
samples = mgr.get_samples()

# Get samples for a single channel
fp1 = mgr.get_channel_samples("Fp1")

# Get samples in microvolts (applies gain and offset calibration)
uv = mgr.get_microvolt_samples()

# Iterate over tags (event markers)
for tag in mgr.iter_tags():
    print(tag["name"], tag["start_timestamp"])
```

## Smart tags

Smart tags extract signal segments aligned to event markers:

```python
from obci_readmanager.signal_processing.smart_tags_manager import SmartTagsManager
from obci_readmanager.signal_processing.tags.smart_tag_definition import SmartTagDurationDefinition

# Define: 1 second of signal after each "stimulus" tag
tag_def = SmartTagDurationDefinition(
    start_tag_name="stimulus",
    start_offset=0.0,
    end_offset=0.0,
    duration=1.0,
)

smart_mgr = SmartTagsManager(
    tag_def,
    "recording.obci.xml",
    "recording.obci.raw",
    "recording.obci.tag",
)

for smart_tag in smart_mgr.iter_smart_tags():
    data = smart_tag.get_samples()  # channels x samples for this epoch
    print(data.shape)
```

## MNE-Python conversion

```python
# ReadManager -> MNE Raw
raw_mne = mgr.get_mne_raw()

# MNE Raw -> ReadManager
mgr2 = ReadManager.from_mne(raw_mne)

# Smart tags -> MNE Epochs
epochs = smart_mgr.get_mne_epochs()
```

## OBCI file format

An OBCI recording consists of three files:

| File | Content |
|------|---------|
| `.obci.raw` | Binary signal data (channels interleaved, float64 by default) |
| `.obci.xml` | Recording metadata: channel names, sampling frequency, gains, offsets |
| `.obci.tag` | Event markers in XML format (name, timestamp, duration, description) |

## Part of the OBCI ecosystem

`readmanager` is used by [OBCI](https://gitlab.com/fuw_software/obci) for
signal file replay and post-recording correction.  Related packages:

- [obci-server](https://gitlab.com/fuw_software/obci) — EEG acquisition server (depends on readmanager)
- [obci-desktop](https://gitlab.com/fuw_software/obci-desktop) — desktop launcher and LSL streaming
- [obci-psychopy](https://gitlab.com/fuw_software/obci-psychopy) — PsychoPy tag integration
- [SVAROG4](https://gitlab.com/fuw_software/svarog4) — Java signal viewer/recorder

## License

GNU General Public License v3 or later (GPLv3+).

Originally developed by [BrainTech](http://www.braintech.pl) and the
Faculty of Physics, University of Warsaw.
