eegFloss: EEG Flow & Sleep Analysis

• eegFloss is a dual-application concept, combining real-time ear-EEG flow detection during cognitive tasks with a Python toolkit for sleep EEG preprocessing.
• The ear-EEG framework employs discrete cEEGrid sensors and statistical modeling to capture subtle flow states in naturalistic work settings.
• The sleep package uses LightGBM classifiers and feature extraction methods to identify artifacts and estimate sleep metrics efficiently.

Searching arXiv for the specified eegFloss papers and closely related context. eegFloss denotes two distinct constructs in the recent EEG literature: a conceptual framework for real-time, ear-EEG-based detection of flow during natural knowledge work, derived from the study “Exploring Flow in Real-World Knowledge Work Using Discreet cEEGrid Sensors,” and an open-source Python package for refining sleep EEG recordings using machine learning models (Knierim et al., 31 Jan 2025, Sikder et al., 8 Jul 2025). The former centers on state estimation in ecological human–computer interaction settings using around-the-ear EEG, whereas the latter operationalizes artifact detection, time-in-bed estimation, filtering, and sleep-summary generation for polysomnographic and headband recordings. The shared label reflects a common concern with improving the interpretability and usability of EEG in realistic settings, but the two usages differ in domain, signal regime, and methodological objective.

1. Nomenclature and scope

Within the cited literature, the name eegFloss is not attached to a single canonical system. In one usage, it is a synthesized framework name applied to flow detection with discreet cEEGrid sensors during academic writing and programming. In the other, it is the formal name of a Python toolkit for sleep EEG preprocessing and quality control (Knierim et al., 31 Jan 2025, Sikder et al., 8 Jul 2025).

Usage	Source	Primary role
eegFloss as framework	Knierim et al. synthesis	Real-time, ear-EEG-based flow detection in knowledge work
eegFloss as package	Python toolkit paper	Sleep EEG artifact handling, TIB detection, filtering, hypnograms, statistics

This dual usage can create terminological ambiguity. A common misconception is to treat eegFloss as a single software platform spanning both cognitive-state monitoring and sleep analysis. The available evidence instead supports a narrower interpretation: one branch is a conceptual extension of a field HCI experiment, and the other is a concrete software package for sleep EEG preprocessing. This suggests that the shared name identifies a workflow orientation—cleaning or structuring EEG for downstream inference—rather than a unified codebase or benchmark.

2. Ear-EEG flow detection in natural knowledge work

The flow-oriented eegFloss framework is grounded in a semi-controlled field experiment in which participants wore gelled cEEGrid arrays with 10 electrodes per ear connected to an OpenBCI Cyton + Daisy amplifier with 16 channels at 250 Hz over an entire home-office day (Knierim et al., 31 Jan 2025). Participants ($N = 21$) performed four 1-hour natural knowledge-work sessions, two before and two after lunch, on a self-selected academic thesis or software project chosen for existing expertise and moderate challenge. During each session, flow was probed three times at random, 10 or 20 minutes into the work period, using the Flow Short Scale with 10 items, NASA-TLX with 5 items, and a valence/arousal manikin.

The same study included a lab-reference task consisting of mental arithmetic with three difficulty levels—easy, optimal/adaptive, and hard—presented twice, at the start and end of day. Each trial lasted at most 18 seconds and was interleaved by 4-second breaks; flow, workload, valence, and arousal were sampled after each block. At the start of each session, participants performed a 10-second nod, 90-second eyes-open rest, and 90-second eyes-closed rest to establish EEG baselines and verify signal quality, including the Berger effect.

The central empirical result is that natural work tasks elicited more intense flow than artificial tasks, but with smaller experiential contrasts. Peak flow intensity, defined as top-2 math versus top-4 work probes per participant, was 5.51 for math and 5.74 for work on a 1–7 scale, with $F(1,20)=4.92$ and $p=.028$. By contrast, the flow range per session, measured as max–min, was greater in math with $EMM = 1.88$ than in work with $EMM = 1.03$, $p<.001$, reflecting more low-flow moments only in the controlled paradigm. In practical terms, the work setting produced stronger but less contrastive flow states, which is consequential for any real-time detector trained on ecologically valid signals.

3. Signal-processing and statistical characterization of flow

For each 170-second segment preceding a probe, the preprocessing pipeline applied line-noise removal via ZapLine and a 2–30 Hz bandpass FIR filter without overlap, followed by bad-channel detection and interpolation using a Riemannian ASR routine with threshold $= 20$, re-referencing to the average of two mastoid-proximal electrodes $L5$ and $R5$, and Artifact Subspace Reconstruction trained on eyes-open rest (Knierim et al., 31 Jan 2025). Spectral estimation used Welch PSD with 2-second windows and no overlap, producing relative spectral power per 1 Hz bin by dividing power by total 2–30 Hz power. Features were aggregated globally and by left-ear and right-ear regions of interest. The frequency bands were theta $4\text{–}7$ Hz, alpha $F(1,20)=4.92$0 Hz, and beta $F(1,20)=4.92$1 Hz.

Hemispheric beta asymmetry was defined as

$F(1,20)=4.92$2

All regressions were ordinary least squares, two-tailed, and fitted separately per predictor to avoid multicollinearity. Participants were treated as independent observations in these OLS analyses, although random intercepts in mixed models were used for task comparisons. The theta–flow relationship was modeled quadratically in both paradigms:

$F(1,20)=4.92$3

For the math task, the reported coefficients were $F(1,20)=4.92$4 with $F(1,20)=4.92$5 and $F(1,20)=4.92$6 with $F(1,20)=4.92$7. For natural work, the fitted coefficients were $F(1,20)=4.92$8 with $F(1,20)=4.92$9 and $p=.028$0 with $p=.028$1, where $p=.028$2 denotes trend-level $p=.028$3.

Natural work additionally exhibited a quadratic relationship between beta asymmetry and flow:

$p=.028$4

The fitted coefficients were $p=.028$5 with $p=.028$6 and $p=.028$7 with $p=.028$8. The study interprets the theta result as the well-known inverted-U relationship between theta power and flow across tasks. It further reports a novel quadratic relationship between beta asymmetry and flow during complex, real-world tasks: flow peaks when $p=.028$9, meaning balanced left/right beta, and declines when one hemisphere dominates. The effect held for both flow sub-dimensions, fluency and absorption, and was reported as unconfounded by valence, arousal, workload, or task type.

4. eegFloss as a sleep EEG preprocessing package

The package usage of eegFloss is an open-source Python toolkit designed to “floss” sleep EEG recordings by automatically identifying and flagging artifact-contaminated segments, estimating time-in-bed boundaries, filtering certain artifacts, and producing cleaned hypnograms and standard sleep statistics (Sikder et al., 8 Jul 2025). It occupies the preprocessing stage of sleep analysis, where artifacts can degrade automatic sleep staging and complicate downstream analyses of sleep architecture and microstructure.

Its core comprises two LightGBM-based classifiers. The first, eegUsability, labels each 10-second epoch of single-channel EEG, optionally augmented with corresponding tri-axial accelerometer data, as either usable or one of four artifact types: No Data, High Noise, Spiky Noise, or M-shaped Noise. The second, eegMobility, labels each 10-second epoch of accelerometry into Idle, Lying, Stationary, or Mobile and uses those labels to estimate Lights Out and Lights On from sustained lying periods.

The eegUsability model uses gradient-boosted decision trees implemented with LightGBM and a leaf-wise growth strategy. Each epoch is built from single-channel raw EEG bandpass filtered at 0.3–30 Hz and segmented into 2,560 samples at $EMM = 1.88$0 Hz, the Euclidean magnitude of tri-axial accelerometry,

$EMM = 1.88$1

spectrogram features obtained from STFT magnitude squared over 11 time windows and 129 frequency bins for EEG and $EMM = 1.88$2, yielding $EMM = 1.88$3 features, and 390 TSFEL features per signal, yielding 780 TSFEL features. The total per epoch is therefore 3,618 features. Training data comprised 127 nights from 15 healthy volunteers wearing the Zmax headband, with manual annotation producing approximately 735k ten-second samples and class ratios of approximately Good $EMM = 1.88$4, No Data $EMM = 1.88$5, High Noise $EMM = 1.88$6, Spiky $EMM = 1.88$7, and M-shaped $EMM = 1.88$8. Class balancing undersampled usable epochs to approximately $EMM = 1.88$9, then redistributed remaining artifacts roughly equally.

Model fitting used categorical cross-entropy loss,

$EMM = 1.03$0

where $EMM = 1.03$1, with LightGBM’s gradient and Hessian updates. Reported hyperparameters included learning_rate = 0.01, 80 % feature fraction, and 70 % bagging fraction per 10 rounds. In inference, each epoch is assigned a label

$EMM = 1.03$2

The eegMobility model uses 1,170 TSFEL features from three 10-second ACC channels. Its training data consisted of approximately 23 hours of protocolled ACC from eight activities, including two full nights of sleep in the Zmax headband, grouped into the four activity classes with ratios of approximately $EMM = 1.03$3, $EMM = 1.03$4, $EMM = 1.03$5, and $EMM = 1.03$6. Time-in-bed detection is derived from the first and last occurrences of at least 2 minutes of consecutive Lying:

$EMM = 1.03$7

$EMM = 1.03$8

$EMM = 1.03$9

5. Workflow, performance, and deployment characteristics

The sleep-package preprocessing pipeline is explicitly staged: bandpass filter raw EEG at 0.3–30 Hz and compute ACC magnitude; slide a 10-second window without overlap to create epochs; compute STFT spectrogram features for each epoch using 11 windows and 129 frequency bins; extract 390 TSFEL features per signal segment for EEG and ACC magnitude; concatenate features; and feed them to eegUsability and/or eegMobility (Sikder et al., 8 Jul 2025). The package API exposes eegfloss.eegUsability, eegfloss.eegMobility, aggregate_scores, detect_TIB, filter_spiky, plot_hypnogram, and compute_stats. Distribution is available from PyPI via pip install eegfloss and from source via the GitHub repository https://github.com/Niloy333/eegFloss.git.

On held-out test data for eegUsability version 1.0, the weighted mean precision was $p<.001$0, recall $p<.001$1, F1 $p<.001$2, AUC $p<.001$3, and Cohen’s $p<.001$4. Usable-class recall was $p<.001$5. For eegMobility, weighted mean precision, recall, and F1 were $p<.001$6, AUC was $p<.001$7, and $p<.001$8. The package paper also reports, at the abstract level, an F1-score of approximately $p<.001$9, Cohen’s kappa of $= 20$0, and a recall rate of approximately $= 20$1 in identifying channel-wise usable EEG data.

Generality beyond the Zmax headband is treated cautiously. eegUsability was tested qualitatively on PSG systems including Brain Quick® and SOMNOscreen® plus, as well as the Bitbrain Ikon textile headband. Across more than 400 non-Zmax usability graphs, Good, No Data, High Noise, and Spiky epochs were detected consistently, whereas the M-shaped artifact appears Zmax-specific. If ACC is unavailable, eegUsability will still run but may conflate movement artifacts with High Noise. The package further advises that artifact-free EEG amplitude scaling should be comparable to approximately $= 20$2, that 256 Hz is the recommended sampling rate because the models were trained at $= 20$3 Hz, and that at least 2 minutes of continuous data are needed for reliable TIB detection. Processing-time guidance distinguishes full models with TSFEL, which take approximately 35 seconds per 8-hour recording on a modern 8-core CPU, from lite versions using spectrogram features only, which run in approximately 3 seconds.

6. Limitations, misconceptions, and research directions

The flow-oriented framework and the sleep-oriented package each foreground a different set of limitations. In the cEEGrid flow study, gelled electrodes achieved high SNR but were described as impractical for daily consumer use; dry or semi-dry ear electrodes would introduce more noise and drift, making robust artefact cleaning such as adaptive rASR thresholds critical (Knierim et al., 31 Jan 2025). Natural tasks also yielded narrower flow ranges, so real-time models would need sensitivity to small band-power changes around the inverted-U peak. Inter-day and inter-subject EEG variability were identified as requiring personalized calibration or domain-adaptation layers, including semi-supervised learning and transfer learning. Suggested extensions included frontal theta asymmetry, cross-band coupling such as theta–beta, machine-learning regressors such as ridge and random forest with combined alpha, theta, and beta features for continuous flow scoring, event-related potentials to irrelevant auditory probes as a secondary marker, and just-in-time adaptive interventions such as flow breaks or difficulty adjustments in headphone prototypes.

In the sleep package, limitations arise from device specificity, input availability, and artifact taxonomy. The M-shaped artifact appears Zmax-specific, ACC absence can degrade discrimination of movement-related contamination, and epoching assumptions require compatible 10-second usability and mobility windows and 30-second sleep-scoring epochs (Sikder et al., 8 Jul 2025). The package can disable TIB detection for shorter recordings, but its default formulation presumes sustained lying segments. These caveats matter because sleep preprocessing pipelines are often deployed at scale, where silent failure modes can propagate into autoscorers and sleep-summary statistics.

A recurrent misconception is that eegFloss denotes either only the sleep package or only the ear-EEG flow monitor. The literature supports neither exclusivity claim. Rather, the term currently spans two EEG-processing trajectories: one for ecological cognitive-state inference and one for sleep-recording refinement. This suggests a broader methodological family in which artifact suppression, epoch-level labeling, and compact wearable sensing are central design concerns, even though the downstream targets—flow versus sleep usability—remain distinct.