nucleuskit-toolkit 2.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- nucleuskit_toolkit/__init__.py +3 -0
- nucleuskit_toolkit/__main__.py +60 -0
- nucleuskit_toolkit/app.py +34 -0
- nucleuskit_toolkit/camera/__init__.py +9 -0
- nucleuskit_toolkit/camera/processing.py +374 -0
- nucleuskit_toolkit/config.py +86 -0
- nucleuskit_toolkit/hermes/__init__.py +0 -0
- nucleuskit_toolkit/hermes/constants.py +77 -0
- nucleuskit_toolkit/hermes/realtime/__init__.py +8 -0
- nucleuskit_toolkit/hermes/realtime/proxy.py +652 -0
- nucleuskit_toolkit/logging_utils.py +68 -0
- nucleuskit_toolkit/mqtt/__init__.py +5 -0
- nucleuskit_toolkit/mqtt/mqtt_controller.py +256 -0
- nucleuskit_toolkit/pipeline.py +194 -0
- nucleuskit_toolkit/position/__init__.py +5 -0
- nucleuskit_toolkit/position/gps_processor.py +91 -0
- nucleuskit_toolkit/session_job.py +28 -0
- nucleuskit_toolkit/shimmer/__init__.py +5 -0
- nucleuskit_toolkit/shimmer/constants.py +32 -0
- nucleuskit_toolkit/shimmer/realtime/__init__.py +5 -0
- nucleuskit_toolkit/shimmer/realtime/proxy.py +279 -0
- nucleuskit_toolkit/tools/__init__.py +1 -0
- nucleuskit_toolkit/tools/eeg_regression.py +91 -0
- nucleuskit_toolkit/tools/recording_merger.py +437 -0
- nucleuskit_toolkit/ui/__init__.py +1 -0
- nucleuskit_toolkit/ui/icons.py +165 -0
- nucleuskit_toolkit/ui/main_window.py +465 -0
- nucleuskit_toolkit/ui/offline_job.py +144 -0
- nucleuskit_toolkit/ui/pages/__init__.py +1 -0
- nucleuskit_toolkit/ui/pages/about_page.py +88 -0
- nucleuskit_toolkit/ui/pages/channel_fixer_page.py +205 -0
- nucleuskit_toolkit/ui/pages/channel_gain_page.py +362 -0
- nucleuskit_toolkit/ui/pages/eeg_regression_page.py +385 -0
- nucleuskit_toolkit/ui/pages/mqtt_controller_page.py +394 -0
- nucleuskit_toolkit/ui/pages/offline_page.py +754 -0
- nucleuskit_toolkit/ui/pages/playback_page.py +1524 -0
- nucleuskit_toolkit/ui/pages/ppg_fixer_page.py +199 -0
- nucleuskit_toolkit/ui/pages/realtime_viewer_page.py +954 -0
- nucleuskit_toolkit/ui/pages/recording_merge_page.py +395 -0
- nucleuskit_toolkit/ui/pages/revert_original_page.py +128 -0
- nucleuskit_toolkit/ui/pages/settings_page.py +69 -0
- nucleuskit_toolkit/ui/pages/tools_menu_page.py +42 -0
- nucleuskit_toolkit/ui/plot_style.py +155 -0
- nucleuskit_toolkit/ui/realtime_eeg_plot.py +244 -0
- nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py +162 -0
- nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py +101 -0
- nucleuskit_toolkit/ui/realtime_shimmer_plot.py +135 -0
- nucleuskit_toolkit/ui/resources/__init__.py +1 -0
- nucleuskit_toolkit/ui/resources/branding/__init__.py +1 -0
- nucleuskit_toolkit/ui/resources/branding/logo.png +0 -0
- nucleuskit_toolkit/ui/session_inspect.py +226 -0
- nucleuskit_toolkit/ui/theme.py +330 -0
- nucleuskit_toolkit/ui/widgets.py +190 -0
- nucleuskit_toolkit-2.2.0.dist-info/METADATA +351 -0
- nucleuskit_toolkit-2.2.0.dist-info/RECORD +59 -0
- nucleuskit_toolkit-2.2.0.dist-info/WHEEL +5 -0
- nucleuskit_toolkit-2.2.0.dist-info/entry_points.txt +2 -0
- nucleuskit_toolkit-2.2.0.dist-info/licenses/LICENSE +675 -0
- nucleuskit_toolkit-2.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: nucleuskit-toolkit
|
|
3
|
+
Version: 2.2.0
|
|
4
|
+
Summary: Nucleus-Kit offline processing toolkit (Hermes EEG/EMG, Shimmer PPG/EDA)
|
|
5
|
+
Author: RE-AK Technologies Inc.
|
|
6
|
+
License-Expression: GPL-3.0-or-later
|
|
7
|
+
Project-URL: Homepage, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline
|
|
8
|
+
Project-URL: Source, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline
|
|
9
|
+
Project-URL: Issues, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/CHANGELOG.md
|
|
11
|
+
Keywords: EEG,EMG,EDA,PPG,Nucleus-Kit,Hermes,Shimmer,biosignals
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
Requires-Dist: re-ak-core<1.1,>=1.0.1
|
|
25
|
+
Requires-Dist: numpy>=2.5
|
|
26
|
+
Requires-Dist: pandas>=2.3
|
|
27
|
+
Requires-Dist: scipy<1.18,>=1.17
|
|
28
|
+
Requires-Dist: matplotlib>=3.11
|
|
29
|
+
Requires-Dist: opencv-python>=5.0
|
|
30
|
+
Requires-Dist: scikit-learn==1.6.*
|
|
31
|
+
Provides-Extra: dev
|
|
32
|
+
Requires-Dist: pytest>=9; extra == "dev"
|
|
33
|
+
Requires-Dist: ruff>=0.17; extra == "dev"
|
|
34
|
+
Provides-Extra: gui
|
|
35
|
+
Requires-Dist: PySide6>=6.12; extra == "gui"
|
|
36
|
+
Requires-Dist: bleak>=3.0; extra == "gui"
|
|
37
|
+
Requires-Dist: pyqtgraph>=0.14; extra == "gui"
|
|
38
|
+
Requires-Dist: pyserial>=3.5; extra == "gui"
|
|
39
|
+
Requires-Dist: paho-mqtt>=1.6; extra == "gui"
|
|
40
|
+
Dynamic: license-file
|
|
41
|
+
|
|
42
|
+
# Nucleus-Kit Processing Toolkit
|
|
43
|
+
|
|
44
|
+
Desktop application for **Nucleus-Kit** sessions: **offline** analytics (ingest session folders on disk, run the bundled processing steps, write outputs under each session's `features/` and `results/`), plus real-time streaming, playback review, and MQTT device control. The **offline** pipeline can be run from the GUI or from the command line.
|
|
45
|
+
|
|
46
|
+
Since version 2.0.0 the processing itself (heart dynamics, arousal, cognition, emotions, events, emotion models and the RMS / PPG repair tools) is [re-ak-core](https://github.com/fs-re-ak/re-ak-core), RE-AK's open processing core, shared with the re-akcas cloud processor. Nucleus-Kit adds the desktop application and its local steps: POV movie conversion, session video rotation and GPS. Every change in the results compared with Nucleus-Kit 1.1 is listed in re-ak-core's [CHANGELOG](https://github.com/fs-re-ak/re-ak-core/blob/main/CHANGELOG.md).
|
|
47
|
+
|
|
48
|
+
## Table of contents
|
|
49
|
+
|
|
50
|
+
- [Hardware mapping](#hardware-mapping)
|
|
51
|
+
- [Graphical interface](#graphical-interface)
|
|
52
|
+
- [Tools submenu](#tools-submenu)
|
|
53
|
+
- [Requirements](#requirements)
|
|
54
|
+
- [Install](#install)
|
|
55
|
+
- [From PyPI](#from-pypi)
|
|
56
|
+
- [From source (development)](#from-source-development)
|
|
57
|
+
- [Upgrade and uninstall](#upgrade-and-uninstall)
|
|
58
|
+
- [Run](#run)
|
|
59
|
+
- [Desktop shortcut (Windows)](#desktop-shortcut-windows)
|
|
60
|
+
- [Troubleshooting](#troubleshooting)
|
|
61
|
+
- [Session layout](#session-layout)
|
|
62
|
+
- [Top-level folders](#top-level-folders)
|
|
63
|
+
- [rawData/ — typical inputs](#rawdata--typical-inputs)
|
|
64
|
+
- [features/ — notable outputs](#features--notable-outputs)
|
|
65
|
+
- [results/ — primary toolkit tables](#results--primary-pipeline-tables)
|
|
66
|
+
- [Optional POV / ffmpeg configuration](#optional-pov--ffmpeg-configuration)
|
|
67
|
+
- [Technical documentation](#technical-documentation)
|
|
68
|
+
- [Trust and bundled models](#trust-and-bundled-models)
|
|
69
|
+
- [Tests](#tests)
|
|
70
|
+
- [License](#license)
|
|
71
|
+
|
|
72
|
+
## Hardware mapping
|
|
73
|
+
|
|
74
|
+
| Device | Signals |
|
|
75
|
+
|--------|---------|
|
|
76
|
+
| **Hermes headset** | EEG and EMG (including features used by the emotion model) |
|
|
77
|
+
| **Shimmer wristband** | PPG and EDA (GSR processing in code maps to the Shimmer EDA channel) |
|
|
78
|
+
|
|
79
|
+
## Graphical interface
|
|
80
|
+
|
|
81
|
+
After `python -m nucleuskit_toolkit` (or `nucleuskit-toolkit`), the window shows a sidebar on the left and the selected
|
|
82
|
+
page on the right. Every page has a title, a one-line description and a **Help** link to this documentation. A page
|
|
83
|
+
opened for the first time shows a loading screen while its libraries load (a few seconds on the first launch); they
|
|
84
|
+
are also loaded in the background right after start-up.
|
|
85
|
+
|
|
86
|
+
| Sidebar item | Purpose |
|
|
87
|
+
|------|---------|
|
|
88
|
+
| **Process** | Run the pipeline on one session folder or on every session of a dataset folder. The selected folder is checked as you type (read only): session name, duration and recorded signals, or for a dataset the number of sessions and how many are incomplete. Run is enabled once the folder is valid; while running it becomes **Cancel**, which finishes the step in progress and skips the rest. In a dataset, a failing session does not stop the others. |
|
|
89
|
+
| **Real-time viewer** | Connect to a Hermes headset over BLE (devices appear in the list as soon as the scan sees them) and an optional Shimmer over serial: stream, plot EEG / motion / Shimmer signals, and record into a session-style folder. |
|
|
90
|
+
| **Playback** | Review a processed session: optional `rawData/video.mp4` plus time-aligned plots from `results/*.csv`, with editable event annotations when available. |
|
|
91
|
+
| **Tools** | Maintenance utilities for processed sessions (see below). |
|
|
92
|
+
| **MQTT Controller** | Connect to a broker (e.g. Vizia Mobile), discover devices from status traffic, and send recording-related MQTT commands. |
|
|
93
|
+
| **Settings** | Theme (light, dark, or system), persisted under **REAK / NucleusKitToolkit** via `QSettings`. |
|
|
94
|
+
| **Documentation** | Opens the technical documentation in the browser. |
|
|
95
|
+
| **About** | Nucleus-Kit and re-ak-core versions, available emotion models, license and links. |
|
|
96
|
+
|
|
97
|
+
Leaving a page is refused while it is busy (a run in progress, a device connected or connecting, unsaved playback
|
|
98
|
+
annotations are offered for saving first).
|
|
99
|
+
|
|
100
|
+
### Tools submenu
|
|
101
|
+
|
|
102
|
+
| Item | Purpose |
|
|
103
|
+
|------|---------|
|
|
104
|
+
| **Channel Fixer** | Repair a single bad RMS channel in an already-processed session using the bundled channel-fix model. |
|
|
105
|
+
| **Channel gain adjustment** | Adjust per-channel RMS gain and zero offset against a reference distribution; updates working emotion RMS features. |
|
|
106
|
+
| **Revert to original** | Restore working RMS features from the frozen baseline under `features/emotions/original/`. |
|
|
107
|
+
| **PPG Fixer** | Re-run PPG artifact rejection and HRV computation on an already-processed session (useful when tuning rejection thresholds without reprocessing the full pipeline). |
|
|
108
|
+
| **EEG Regression Denoising** | Remove shared muscle noise from the EEG by regression on the EMG reference channels, then recompute the cognition outputs. |
|
|
109
|
+
| **Recording Merger** | Join up to 5 recordings into one session, with empty CSV rows and black video for the gaps. |
|
|
110
|
+
|
|
111
|
+
## Requirements
|
|
112
|
+
|
|
113
|
+
- **Python 3.10, 3.11 or 3.12** (3.12 recommended). Check with `python --version` (`py --version` on Windows).
|
|
114
|
+
On Windows, install it from [python.org](https://www.python.org/downloads/windows/) and tick **Add python.exe to
|
|
115
|
+
PATH** in the installer.
|
|
116
|
+
- **ffmpeg** (optional): only for POV movie conversion and session video rotation. Point Nucleus-Kit to it with
|
|
117
|
+
`ffmpeg_dir` (see [Optional POV / ffmpeg configuration](#optional-pov--ffmpeg-configuration)).
|
|
118
|
+
- Dependencies are declared in [`pyproject.toml`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/pyproject.toml);
|
|
119
|
+
[`requirements.txt`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/requirements.txt) pins the
|
|
120
|
+
exact versions that were tested, GUI extras included.
|
|
121
|
+
|
|
122
|
+
Install Nucleus-Kit in its **own virtual environment**: its emotion models need scikit-learn 1.6, which must not be
|
|
123
|
+
upgraded by another tool installed next to it.
|
|
124
|
+
|
|
125
|
+
## Install
|
|
126
|
+
|
|
127
|
+
### From PyPI
|
|
128
|
+
|
|
129
|
+
**Windows (PowerShell)**
|
|
130
|
+
|
|
131
|
+
```powershell
|
|
132
|
+
python -m venv "$env:USERPROFILE\nucleuskit"
|
|
133
|
+
& "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install --upgrade pip
|
|
134
|
+
& "$env:USERPROFILE\nucleuskit\Scripts\python.exe" -m pip install "nucleuskit-toolkit[gui]"
|
|
135
|
+
& "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe" --help
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**macOS / Linux**
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
python3 -m venv ~/nucleuskit
|
|
142
|
+
~/nucleuskit/bin/python -m pip install --upgrade pip
|
|
143
|
+
~/nucleuskit/bin/python -m pip install "nucleuskit-toolkit[gui]"
|
|
144
|
+
~/nucleuskit/bin/nucleuskit-toolkit --help
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The `gui` extra installs the desktop interface (PySide6 / Qt 6), Bluetooth and serial streaming and MQTT. Without it
|
|
148
|
+
only headless processing (`--session`) is available. [re-ak-core](https://github.com/fs-re-ak/re-ak-core), the
|
|
149
|
+
processing core, is installed automatically.
|
|
150
|
+
|
|
151
|
+
With [pipx](https://pipx.pypa.io), which creates the environment for you and puts the commands on your PATH:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
pipx install "nucleuskit-toolkit[gui]"
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### From source (development)
|
|
158
|
+
|
|
159
|
+
Clone this repository and [re-ak-core](https://github.com/fs-re-ak/re-ak-core) side by side, then install both in
|
|
160
|
+
editable mode (changes in either clone apply without reinstalling). This is also the way to install before a version is
|
|
161
|
+
published on PyPI.
|
|
162
|
+
|
|
163
|
+
**Windows (PowerShell)**
|
|
164
|
+
|
|
165
|
+
```powershell
|
|
166
|
+
git clone https://github.com/fs-re-ak/re-ak-core.git
|
|
167
|
+
git clone https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline.git
|
|
168
|
+
cd NucleusKit-ProcessingPipeline
|
|
169
|
+
python -m venv .venv
|
|
170
|
+
.\.venv\Scripts\python.exe -m pip install --upgrade pip
|
|
171
|
+
.\.venv\Scripts\python.exe -m pip install -e ..\re-ak-core
|
|
172
|
+
.\.venv\Scripts\python.exe -m pip install -e ".[dev,gui]"
|
|
173
|
+
.\.venv\Scripts\python.exe -m pytest
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**macOS / Linux**
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
git clone https://github.com/fs-re-ak/re-ak-core.git
|
|
180
|
+
git clone https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline.git
|
|
181
|
+
cd NucleusKit-ProcessingPipeline
|
|
182
|
+
python3 -m venv .venv
|
|
183
|
+
.venv/bin/python -m pip install --upgrade pip
|
|
184
|
+
.venv/bin/python -m pip install -e ../re-ak-core
|
|
185
|
+
.venv/bin/python -m pip install -e ".[dev,gui]"
|
|
186
|
+
.venv/bin/python -m pytest
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
The re-ak-core clone satisfies Nucleus-Kit's `re-ak-core>=1.0.1,<1.1` requirement, so pip keeps it instead of
|
|
190
|
+
downloading the published one. To reproduce the tested environment exactly, install `requirements.txt` instead of the
|
|
191
|
+
`[dev,gui]` extras (it needs re-ak-core on PyPI).
|
|
192
|
+
|
|
193
|
+
### Upgrade and uninstall
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
python -m pip install --upgrade "nucleuskit-toolkit[gui]"
|
|
197
|
+
python -m pip uninstall nucleuskit-toolkit re-ak-core
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Use the environment's `python` (for example `"$env:USERPROFILE\nucleuskit\Scripts\python.exe"`), or delete the
|
|
201
|
+
environment folder to remove everything. With pipx: `pipx upgrade nucleuskit-toolkit` / `pipx uninstall nucleuskit-toolkit`.
|
|
202
|
+
|
|
203
|
+
## Run
|
|
204
|
+
|
|
205
|
+
Run the commands with the environment's executables (as below), or activate the environment first
|
|
206
|
+
(`.\.venv\Scripts\Activate.ps1` in PowerShell, `source .venv/bin/activate` on macOS / Linux) and drop the path.
|
|
207
|
+
|
|
208
|
+
**Graphical mode** (see [Graphical interface](#graphical-interface); needs the `gui` extra):
|
|
209
|
+
|
|
210
|
+
```powershell
|
|
211
|
+
& "$env:USERPROFILE\nucleuskit\Scripts\nucleuskit-toolkit.exe"
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
The same as `python -m nucleuskit_toolkit`. From a source checkout, `launch_app.bat` runs `python -m nucleuskit_toolkit`
|
|
215
|
+
with the first `python` on the PATH: activate the environment before running it.
|
|
216
|
+
|
|
217
|
+
**Headless mode** (one session, then exit; for automation and CI):
|
|
218
|
+
|
|
219
|
+
```powershell
|
|
220
|
+
nucleuskit-toolkit --session "D:\path\to\session_folder"
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Options:
|
|
224
|
+
|
|
225
|
+
| Option | Effect |
|
|
226
|
+
|---|---|
|
|
227
|
+
| `--session DIR` | Process this session folder and exit (no GUI) |
|
|
228
|
+
| `--config JSON` | Optional POV / ffmpeg settings, merged after the config files of the current directory |
|
|
229
|
+
| `--emotion-model NAME` | Emotion model release (default `classical-emotion-2.6.0`; `nucleuskit-toolkit --help` lists them) |
|
|
230
|
+
|
|
231
|
+
Outputs are written inside the session folder (see [Session layout](#session-layout)). Existing outputs are reused:
|
|
232
|
+
delete a file under `results/` to recompute that step.
|
|
233
|
+
|
|
234
|
+
Replace the packaged logo anytime with your own PNG at [`nucleuskit_toolkit/ui/resources/branding/logo.png`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/nucleuskit_toolkit/ui/resources/branding/logo.png) (same path in an installed package).
|
|
235
|
+
|
|
236
|
+
### Desktop shortcut (Windows)
|
|
237
|
+
|
|
238
|
+
1. Right-click the desktop, **New → Shortcut**.
|
|
239
|
+
2. Location: the environment's `pythonw.exe` followed by `-m nucleuskit_toolkit`, for example
|
|
240
|
+
`C:\Users\<you>\nucleuskit\Scripts\pythonw.exe -m nucleuskit_toolkit` (`pythonw` opens no console window).
|
|
241
|
+
3. Name it **Nucleus-Kit**, then in **Properties → Start in**, choose the folder that holds your
|
|
242
|
+
`nucleuskit_toolkit_config.json`, if you use one.
|
|
243
|
+
|
|
244
|
+
### Troubleshooting
|
|
245
|
+
|
|
246
|
+
| Problem | Fix |
|
|
247
|
+
|---|---|
|
|
248
|
+
| `Activate.ps1 cannot be loaded because running scripts is disabled` | Call the environment's `python.exe` / `nucleuskit-toolkit.exe` by its path, as above, instead of activating |
|
|
249
|
+
| `No matching distribution found for re-ak-core` | That version is not on PyPI yet: install [from source](#from-source-development) |
|
|
250
|
+
| pip reports a conflict on `scikit-learn` | Another package needs a newer scikit-learn: install Nucleus-Kit in its own environment |
|
|
251
|
+
| `ModuleNotFoundError: No module named 'PySide6'` | Install the `gui` extra: `pip install "nucleuskit-toolkit[gui]"` |
|
|
252
|
+
| `python` is not recognized (Windows) | Use `py -3.12` instead of `python`, or reinstall Python with **Add python.exe to PATH** |
|
|
253
|
+
|
|
254
|
+
## Session layout
|
|
255
|
+
|
|
256
|
+
The pipeline treats the **session root** as a single directory (the folder you select on the Process page or pass to `--session`).
|
|
257
|
+
|
|
258
|
+
### Top-level folders
|
|
259
|
+
|
|
260
|
+
| Folder | Role |
|
|
261
|
+
|--------|------|
|
|
262
|
+
| **`rawData/`** | Canonical location for recordings and acquisition-side files. The GUI expects this folder to exist and be non-empty after any automatic layout fix (see below). |
|
|
263
|
+
| **`features/`** | Intermediate and traceability outputs: meta summary, per-processor feature exports, processed events, optional playback annotation seed. |
|
|
264
|
+
| **`results/`** | Primary analytics tables, logs, and optional playback-side annotation copies. |
|
|
265
|
+
| **`meta/`** | Reserved for session-level assets such as preview images (created when needed). |
|
|
266
|
+
| **`experimentConfigs/`** | Reserved for experiment or run configuration artifacts. |
|
|
267
|
+
|
|
268
|
+
On startup, if **`rawData/` is missing**, the pipeline may **create it and move** every other top-level entry into it, except the reserved names above (`rawData`, `features`, `results`, `meta`, `experimentConfigs`). That normalizes older layouts where files lived at the session root.
|
|
269
|
+
|
|
270
|
+
### `rawData/` — typical inputs
|
|
271
|
+
|
|
272
|
+
Exact filenames vary by firmware and recording path; common patterns include:
|
|
273
|
+
|
|
274
|
+
- **Hermes EEG / EMG:** `rawEEG_0.csv` or `eeg.tmp`
|
|
275
|
+
- **Shimmer:** `shimmer.csv`, or legacy `rawShimmer_0.csv` / `gsr.tmp`
|
|
276
|
+
- **Video:** `video.mp4` (used for playback and optional one-time 180° rotation during processing)
|
|
277
|
+
- **Events:** `rawEvents.csv` (processed into `features/events/processedFeatureEvents.csv` and related); `event.csv` (used to seed `features/events/playback_annotations.json` when that file does not yet exist)
|
|
278
|
+
- **Position:** GPS CSV as expected by the GPS processor (under `rawData/`)
|
|
279
|
+
|
|
280
|
+
### `features/` — notable outputs
|
|
281
|
+
|
|
282
|
+
- **`features/metainfo.json`** — session duration and stream presence flags from meta extraction
|
|
283
|
+
- **`features/ppg/`** — PPG intermediate files: `ppg_resampled.csv` (artifact-cleaned signal), `ppg_normalized.csv` (rolling z-score used for peak detection), `ppg_resample_report.txt`, and diagnostic figures `ppg_rejected.png`, `ppg_overview.png`, `ppg_spectrogram.png`
|
|
284
|
+
- **`features/eda/`** — EDA intermediate files: `eda_resampled.csv` (resistance in kΩ), `eda_resample_report.txt`, `eda_overview.png`, and `SCR_events.csv` (discrete skin conductance response events)
|
|
285
|
+
- **`features/cognition/`** — EEG band powers (`powerBands.csv`), bilateral temporal averages (`temporalBandPowers.csv`), epoch-level artefact rejection summary (`artefactStats.csv`), per-epoch signal metrics (`epochMetrics.csv`), and artefact waveform plot (`eegArtefactPlot.png`)
|
|
286
|
+
- **`features/emotions/`** — e.g. `rmsSignals.csv`, `emotionClassifierInputs.csv`, plus `original/` when using RMS editing tools
|
|
287
|
+
- **`features/events/playback_annotations.json`** — point/zone annotations for playback (seeded from `rawData/event.csv` once, then user-editable in the app)
|
|
288
|
+
- **`features/events/processedFeatureEvents.csv`** / **`features/events/processedWebFeatureEvents.csv`** — derived from `rawData/rawEvents.csv` when present
|
|
289
|
+
|
|
290
|
+
Other steps may still write auxiliary artifacts directly under `features/`.
|
|
291
|
+
|
|
292
|
+
### `results/` — primary toolkit tables
|
|
293
|
+
|
|
294
|
+
Written by the default offline pipeline (when the corresponding raw inputs exist). Existing outputs are reused: delete them to recompute a step.
|
|
295
|
+
|
|
296
|
+
- **`processingLog.txt`** — append-only run log
|
|
297
|
+
- **`Emotions.csv`**, **`Cognition.csv`**, **`Arousal.csv`**, **`HeartDynamics.csv`**
|
|
298
|
+
- **`emotion_model.json`** — emotion model and post-processing used for `Emotions.csv`
|
|
299
|
+
- **`processing.json`** — re-ak-core version, model, status of each step and a signal-quality summary
|
|
300
|
+
- **`gpsDf.csv`** (GPS)
|
|
301
|
+
|
|
302
|
+
Playback mode looks for metric CSVs here and, for synchronized video, uses **`rawData/video.mp4`**. Event annotations are **loaded** from **`features/events/playback_annotations.json`**. When you edit annotations in Playback and save, the app writes that file and **mirrors** the same JSON to **`results/playback_annotations.json`** for convenience.
|
|
303
|
+
|
|
304
|
+
## Optional POV / ffmpeg configuration
|
|
305
|
+
|
|
306
|
+
POV movie conversion uses optional settings from, in order:
|
|
307
|
+
|
|
308
|
+
1. `hermes_standalone_config.json` in the **current working directory** (legacy name, still supported)
|
|
309
|
+
2. `nucleuskit_pipeline_config.json` in the **current working directory** (legacy name, still supported)
|
|
310
|
+
3. `nucleuskit_toolkit_config.json` in the **current working directory** (overrides legacy keys if both exist)
|
|
311
|
+
4. An extra JSON path passed with `--config` (CLI only)
|
|
312
|
+
5. Environment variables: `HERMES_POV_DATA_ROOT`, `HERMES_FFMPEG_DIR`, `HERMES_POV_SCREEN_ID`
|
|
313
|
+
|
|
314
|
+
A run from the **Process** page uses the same merge rules from the **process working directory** and environment; it does not prompt for a config file path.
|
|
315
|
+
|
|
316
|
+
JSON keys: `pov_data_root`, `ffmpeg_dir`, `screen_id`.
|
|
317
|
+
|
|
318
|
+
## Technical documentation
|
|
319
|
+
|
|
320
|
+
The [`doc/`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/tree/main/doc/) folder contains detailed technical descriptions of each processing toolkit for traceability and scientific reference. The heart, arousal, cognition, emotions and events processing now lives in re-ak-core: those pages describe Nucleus-Kit 1.1 and will move to re-ak-core's documentation; re-ak-core's CHANGELOG lists what changed since.
|
|
321
|
+
|
|
322
|
+
| File | Pipeline |
|
|
323
|
+
|------|----------|
|
|
324
|
+
| [`doc/overview.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/overview.md) | Pipeline orchestration, step order, session layout, shared 2 Hz timebase |
|
|
325
|
+
| [`doc/pipeline_heart.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_heart.md) | Shimmer PPG → Heart Rate Dynamics (SQI + MAD artifact rejection, NeuroKit2, HRV) |
|
|
326
|
+
| [`doc/pipeline_arousal.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_arousal.md) | Shimmer EDA → Arousal (cvxEDA tonic/phasic decomposition, SCR detection) |
|
|
327
|
+
| [`doc/pipeline_cognition.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_cognition.md) | Hermes EEG → Cognitive Indexes (Welch power bands, epoch-level artefact rejection, Engagement) |
|
|
328
|
+
| [`doc/pipeline_emotions.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_emotions.md) | Hermes EMG → Emotion Classification (AVG_RMS artefact gate, two-stage LDA/KNN classifier) |
|
|
329
|
+
| [`doc/pipeline_events.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_events.md) | Raw Events → Feature / Web Events + Playback Annotations |
|
|
330
|
+
| [`doc/pipeline_positioning.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/pipeline_positioning.md) | GPS Positioning |
|
|
331
|
+
| [`doc/mqtt_interface.md`](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/doc/mqtt_interface.md) | Vizia Mobile MQTT interface — status, commands, and tags |
|
|
332
|
+
|
|
333
|
+
## Trust and bundled models
|
|
334
|
+
|
|
335
|
+
The emotion models are shipped by re-ak-core as **joblib/pickle** artifacts, checked against the checksums of their release manifest before loading. Treat them like executable data: only use models shipped with re-ak-core or that you trust.
|
|
336
|
+
|
|
337
|
+
## Tests
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
pytest
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
`tests/test_open_core_references.py` checks that Nucleus-Kit gives exactly re-ak-core's outputs on re-ak-core's synthetic sessions; it needs a `re-ak-core` checkout next to this repository (or `RE_AK_CORE=<path>`) and is skipped otherwise.
|
|
344
|
+
|
|
345
|
+
## License
|
|
346
|
+
|
|
347
|
+
Copyright (C) 2026 RE-AK Technologies Inc.
|
|
348
|
+
|
|
349
|
+
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See [LICENSE](https://github.com/fs-re-ak/NucleusKit-ProcessingPipeline/blob/main/LICENSE) for the full text.
|
|
350
|
+
|
|
351
|
+
SPDX-License-Identifier: `GPL-3.0-or-later`. Versions up to 1.1 were released under the MIT License.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
nucleuskit_toolkit/__init__.py,sha256=lQbBSaR_om_B88pRtZIn5IvGfg8Uj5kQBIe6jaIiFnM,107
|
|
2
|
+
nucleuskit_toolkit/__main__.py,sha256=6-PlcuaQkVyhUQDGk4NR7I0RuhkPqzwfmQhhqAGmbWk,1631
|
|
3
|
+
nucleuskit_toolkit/app.py,sha256=n3IIhVL-gU3-RcYNRhpCxqOX8HVOM6tAZlf5ogdloW4,1056
|
|
4
|
+
nucleuskit_toolkit/config.py,sha256=i0CnmZRpzdPJUXGyqloIQxrFGQgDHDMGpma8KRAQ13U,3101
|
|
5
|
+
nucleuskit_toolkit/logging_utils.py,sha256=3ao5QdM9kHI8STtHNzDl9H80LRqv_RtZykuFAwx4N_g,2055
|
|
6
|
+
nucleuskit_toolkit/pipeline.py,sha256=dpzWKuE-imJeSaX6StIfAhePawxJyUNFQTNIxjdfOek,7177
|
|
7
|
+
nucleuskit_toolkit/session_job.py,sha256=fmoOEF3agFx8ut2jBZaDTakp3anW267BmC-FmEHdpf4,868
|
|
8
|
+
nucleuskit_toolkit/camera/__init__.py,sha256=yzT_Xqp5ICs6axZ8mczmEIHTl6hK7-mzujJ8trxxkPA,335
|
|
9
|
+
nucleuskit_toolkit/camera/processing.py,sha256=3l4x4ulFjiz_qv9PkCJSd2qVIX8piBQ_BXoera0riU8,14109
|
|
10
|
+
nucleuskit_toolkit/hermes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
11
|
+
nucleuskit_toolkit/hermes/constants.py,sha256=0N6nTOzwfeSn78PJ613Ghg7Bglt2wr-X9nFkh2ID_mI,2317
|
|
12
|
+
nucleuskit_toolkit/hermes/realtime/__init__.py,sha256=E32tV89YVNfW94VoVyRtGM3I-okSgBu0q8L93ViSJm4,211
|
|
13
|
+
nucleuskit_toolkit/hermes/realtime/proxy.py,sha256=HhQGG_jDhwXJJiUaul6rzUWd9zKEvCqYq5ZQ2970O2Q,27047
|
|
14
|
+
nucleuskit_toolkit/mqtt/__init__.py,sha256=C7exc0mpFfQsDGolSNwjwkzHRCPMKUaMtYgMTEu_rzM,149
|
|
15
|
+
nucleuskit_toolkit/mqtt/mqtt_controller.py,sha256=h0vLWbM4gngcuYIt-JskztlObfGPz3BNxdVfrnKttzs,10330
|
|
16
|
+
nucleuskit_toolkit/position/__init__.py,sha256=qAfuAovtIkh8YM9p3AAZoymePcpAGKrnW5WdM0CHsx0,136
|
|
17
|
+
nucleuskit_toolkit/position/gps_processor.py,sha256=yImUcf35HPMQw6UfBP4m-TmR4lQhbN7egPHq4PA3c88,2641
|
|
18
|
+
nucleuskit_toolkit/shimmer/__init__.py,sha256=Jhf96tOi1vAr5zkboljbOIR5C8r_bKNg-gno2y2rYmg,172
|
|
19
|
+
nucleuskit_toolkit/shimmer/constants.py,sha256=HTyBRNu4I0LSlpJ34KXRLwCnxJmOvnfU-pxnXqLwcFY,698
|
|
20
|
+
nucleuskit_toolkit/shimmer/realtime/__init__.py,sha256=7ng6tne_xj8KwsgSAjx8T5rowMjGtkTwXGDua3JZFS8,185
|
|
21
|
+
nucleuskit_toolkit/shimmer/realtime/proxy.py,sha256=QlmSkVvWRyceqd3-u8V6e5vgnjq4atVE7C927YYDIXU,9855
|
|
22
|
+
nucleuskit_toolkit/tools/__init__.py,sha256=tWkn2nsEl1pWgQWzG3R5gxCINgZClipsN4kGOb3YFo8,60
|
|
23
|
+
nucleuskit_toolkit/tools/eeg_regression.py,sha256=yxCpHYytN97ObzvTafU6cFtSGbAAfOaqB0PAYq21xSU,3686
|
|
24
|
+
nucleuskit_toolkit/tools/recording_merger.py,sha256=UbAfGZyOpG_usbbpPQi2YpmrxP3jkGyyOJO_nZGmLeo,15792
|
|
25
|
+
nucleuskit_toolkit/ui/__init__.py,sha256=IkZOifdUuJbHt-2U5aThFS9Ox5Pl_AmgSsKVMQgzR3A,50
|
|
26
|
+
nucleuskit_toolkit/ui/icons.py,sha256=0oE0hlIpeavEC3b_VoJ3hGvGT5zIKNWOpHoajGWeqiI,6919
|
|
27
|
+
nucleuskit_toolkit/ui/main_window.py,sha256=7DsGHWjLhDdruxyt7tabMyufqBtGiYjkaYuPrGH7wYU,18016
|
|
28
|
+
nucleuskit_toolkit/ui/offline_job.py,sha256=Ncwjh0QWC0fEe3g_Zg9bgA2eNVY0yASR1Sr-KN4MXh8,5203
|
|
29
|
+
nucleuskit_toolkit/ui/plot_style.py,sha256=w3PrK-PZmOG6v3KZoYATYEmp7iLIAy-G5q6OyY073qg,5357
|
|
30
|
+
nucleuskit_toolkit/ui/realtime_eeg_plot.py,sha256=piFFhT7aFHGzNyadYvjOCtkQ-0YNF3t1_f0c5QAJDvw,10236
|
|
31
|
+
nucleuskit_toolkit/ui/realtime_hermes_motion_plot.py,sha256=cp7bUaWImBmy5rTK-tzqx1qf5zUf1Y2mhrsmnSHzN9M,5574
|
|
32
|
+
nucleuskit_toolkit/ui/realtime_nlms_config_dialog.py,sha256=59T2ohXEuTXSp3A88objYFRMA51hw8JEpwVbtisr128,3545
|
|
33
|
+
nucleuskit_toolkit/ui/realtime_shimmer_plot.py,sha256=f_MXjA05cFjkdZ3agmgyfXw30AAdcd2SKTtR3kaqR5U,4951
|
|
34
|
+
nucleuskit_toolkit/ui/session_inspect.py,sha256=0Lv0DbxcSLlOJ9An2noraAWzrQg5EGvt3IIZ05fV83o,8027
|
|
35
|
+
nucleuskit_toolkit/ui/theme.py,sha256=aAJNZ0qwqcwRYG6bFmj9HSrwVCE70qAgdFin37vuWVQ,15801
|
|
36
|
+
nucleuskit_toolkit/ui/widgets.py,sha256=3Et4Qk1oXxgz-MEZTK_cZD3opNcQLuJRMWksLQfSZKo,6645
|
|
37
|
+
nucleuskit_toolkit/ui/pages/__init__.py,sha256=68B1QjTMVac4hGegvLDwJv63IFVMwt9OTqpR0u4YIE8,24
|
|
38
|
+
nucleuskit_toolkit/ui/pages/about_page.py,sha256=MIphIhAGczwrYK87vszU-8n-GyTIglNW_ivBDCaGCaU,3396
|
|
39
|
+
nucleuskit_toolkit/ui/pages/channel_fixer_page.py,sha256=DBR3NaQ83fYhy_BwkPdorcVpit-SFRWKt1KNNvlgW7k,6514
|
|
40
|
+
nucleuskit_toolkit/ui/pages/channel_gain_page.py,sha256=iwU7UfYzUyKR1Jw2FKr2EBGoO4d74fLnohY95FxbOLk,12618
|
|
41
|
+
nucleuskit_toolkit/ui/pages/eeg_regression_page.py,sha256=Q1NKOY28dkWAvTrzpyzwq_PMXcwCTk-ZaUOezwW4Nc0,16252
|
|
42
|
+
nucleuskit_toolkit/ui/pages/mqtt_controller_page.py,sha256=UDekm1kRLXSxNgBaWGGnaIPrXEosORopW-eVs-0FwDw,14985
|
|
43
|
+
nucleuskit_toolkit/ui/pages/offline_page.py,sha256=kr4sYOJ0_09QIfE5adPI7OQpLErGUKGUbc9-nNhVxbo,31375
|
|
44
|
+
nucleuskit_toolkit/ui/pages/playback_page.py,sha256=V0wylrEprN4R8s-B5DjAGO45QvLwCS721EMOnQo97O4,56851
|
|
45
|
+
nucleuskit_toolkit/ui/pages/ppg_fixer_page.py,sha256=WrMBNOcFIQTJbv0eaj01UeCHTBIfDonjnm-YmlxaFlg,7014
|
|
46
|
+
nucleuskit_toolkit/ui/pages/realtime_viewer_page.py,sha256=gRDh-jw0-oFEiOrYp4hIyff2r-sFGXV88e4JU3OIXxU,36917
|
|
47
|
+
nucleuskit_toolkit/ui/pages/recording_merge_page.py,sha256=GPGYmA3USZLHq2hz-DXdNxphMyeqKqLaKRlLKAI-n9I,15551
|
|
48
|
+
nucleuskit_toolkit/ui/pages/revert_original_page.py,sha256=lHZ6hhUI7pv5MvduDnsxkDFUlgZeeHwYViRmE9cpLQM,4051
|
|
49
|
+
nucleuskit_toolkit/ui/pages/settings_page.py,sha256=6ISXcJw7-t0zTIt2vvHKZkjXmyCI7dLZRbhEUlOK144,2351
|
|
50
|
+
nucleuskit_toolkit/ui/pages/tools_menu_page.py,sha256=_RY2ZbgpmAFNtXRza4BgKzzKlGAnK1bbTVit2DgBaBs,1761
|
|
51
|
+
nucleuskit_toolkit/ui/resources/__init__.py,sha256=oacbF_wvH97MJeQ_RhHCiZuBh_BG6qtHgUzVWbmBo_g,42
|
|
52
|
+
nucleuskit_toolkit/ui/resources/branding/__init__.py,sha256=exU_kZEShc6WGAMUd4JOMoROaiBefmmMRB3kDDC2p5k,48
|
|
53
|
+
nucleuskit_toolkit/ui/resources/branding/logo.png,sha256=Ol6Rq3E9JkI3TVMevugFS3PnscchyLWTD-bzT4Rnn_g,122259
|
|
54
|
+
nucleuskit_toolkit-2.2.0.dist-info/licenses/LICENSE,sha256=5X8cMguM-HmKfS_4Om-eBqM6A1hfbgZf6pfx2G24QFI,35150
|
|
55
|
+
nucleuskit_toolkit-2.2.0.dist-info/METADATA,sha256=XsXInBJvKrp7YI_08pnaZM4r7icdhUCzcKdsuHGEFEs,21264
|
|
56
|
+
nucleuskit_toolkit-2.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
57
|
+
nucleuskit_toolkit-2.2.0.dist-info/entry_points.txt,sha256=-GflPBCvqvZe8BTNt6ijwB2L1teCmjIQ9jwBUQqpC3M,72
|
|
58
|
+
nucleuskit_toolkit-2.2.0.dist-info/top_level.txt,sha256=-ffGtSPqLbvSnQ6TE0ZAKdLObHwlFUHM7ZZ4KeTO9rE,19
|
|
59
|
+
nucleuskit_toolkit-2.2.0.dist-info/RECORD,,
|