Tyee: Unified Physiological ML Toolkit
- Tyee is a unified toolkit streamlining physiological machine learning workflows by standardizing data ingestion, preprocessing, and experimental configuration.
- It features a modular, extensible architecture that integrates diverse modalities and tasks across 13 benchmark datasets.
- The toolkit enables reproducible, scalable experimentation with YAML-driven configurations and dynamic module instantiation.
Searching arXiv for the specified paper to ground the article. Tyee is a unified, modular, and fully-integrated configurable toolkit for intelligent physiological healthcare, introduced to address four persistent impediments in physiological signal analysis: heterogeneous formats, inconsistent preprocessing, fragmented pipelines, and non-reproducibility. It is designed around a unified data interface, a configurable preprocessing pipeline, a modular and extensible layered architecture, and end-to-end workflow configuration for reproducible and scalable experimentation. In the reported benchmark suite, it is demonstrated on 12+ physiological signal modalities across 13 datasets and 11 tasks, and it matches or exceeds official baselines on 12 of 13 datasets (Zhou et al., 27 Dec 2025).
1. Concept and problem setting
Tyee targets the technical bottlenecks that arise when physiological machine learning workflows span datasets with incompatible storage conventions, modality-specific preprocessing requirements, and task-specific training code. The motivating examples are concrete: EEG corpora such as TUEV and TUAB commonly use EDF with varying channel orders and sampling rates; ECoG datasets such as BCIC-4 use higher-rate formats and different metadata; wearable datasets such as PPG-DaLiA combine PPG with 3D accelerometry at multiple sampling rates. In such settings, researchers often need to repeatedly implement dataset-specific loaders, converters, preprocessing logic, and evaluation scripts, which complicates fair comparison and exact experiment reconstruction (Zhou et al., 27 Dec 2025).
The toolkit’s response is to standardize the lifecycle of physiological ML experiments without prescribing a single model family or a single task formulation. Its stated design priorities are unification, modularity, extensibility, and full integration. Concretely, it exposes a common interface for data ingestion and transformation, a YAML-driven configuration system for preprocessing and training, and a layered software organization that standardizes how datasets, models, criteria, optimizers, schedulers, and metrics are wired together.
A plausible implication is that Tyee is best understood not as a task-specific benchmark package but as an orchestration layer for physiological ML experimentation. That interpretation is consistent with the emphasis on declarative preprocessing, dynamic component instantiation, and multi-task coverage.
2. Unified data abstraction and configurable preprocessing
A central contribution of Tyee is a unified data interface that hides file-format and dataset idiosyncrasies behind four abstractions: read_record(), offline_transform, online_transform, and __getitem__(). The dataset-specific parser read_record() returns signal arrays and labels or annotations. offline_transform denotes transformations applied at standardization or preprocessing time, such as resampling, filtering, and windowing. online_transform denotes lightweight transforms applied at batch or sampling time, such as normalization. __getitem__() standardizes sample retrieval across tasks by returning signals, labels, and metadata (Zhou et al., 27 Dec 2025).
The supported file formats explicitly include .edf, .mat, .cnt, and .bdf, and users can add parsers for new formats by implementing read_record(). The paper further states that metadata, channel naming, and annotation conventions are abstracted via the dataset class, but it does not prescribe a fixed schema for channel names or annotation taxonomies. This is significant because many physiological benchmarks differ not only in sampling rate and modality composition but also in annotation granularity and naming conventions.
The configurable preprocessing pipeline is implemented through BaseTransform subclasses and configured in YAML. The core capabilities enumerated in the paper are reading and standardization via read_record(), resampling, filtering, normalization, windowing or segmentation, denoising or artifact handling, and baseline correction. The distinction between offline_transform and online_transform is treated as foundational: the former is statically applied during dataset preparation, whereas the latter is per-sample and applied at fetch or training time.
The benchmark suite exhibits the breadth of this preprocessing problem. Typical sampling rates include EEG at 100 Hz in SleepEDFx, 200 Hz in KaggleERN, 256 Hz in TUEV and TUAB, and 1,000 Hz in SEED-V; ECoG at 1,000 Hz in BCIC-4; ECG at 360 Hz in MIT-BIH; EMG at 200 Hz in Ninapro DB5; PPG and 3D accelerometer at 64 Hz and 32 Hz, respectively, in PPG-DaLiA; multimodal sleep signals at 200 Hz in CinC2018; and DEAP at 512 Hz. The paper’s examples therefore emphasize modality- and task-specific resampling and filtering, such as bringing EEG from 256 Hz to 100 Hz for sleep staging (Zhou et al., 27 Dec 2025).
Tyee is demonstrated on the following physiological signal modalities in the 13 benchmark datasets: EEG, ECoG, ECG, EMG, PPG, 3D accelerometer (IMU), EOG, GSR/EDA, respiration, skin temperature, and SaO2. The paper also describes the toolkit as covering 12+ modalities, indicating that the benchmarked set is representative rather than exhaustive.
3. Layered architecture and extensibility
Tyee’s architecture is decomposed into four layers: Entity, Task, Training, and Configuration. This layered design standardizes the full workflow while preserving the ability to replace components independently (Zhou et al., 27 Dec 2025).
At the Entity Layer, datasets implement read_record(), offline_transform, online_transform, and __getitem__(). Preprocessors subclass BaseTransform and implement transform(). Models are standard PyTorch nn.Module objects with __init__() and forward(). Criteria, optimizers, schedulers, and metrics are provided as built-ins and configured in YAML.
At the Task Layer, dataset, model, criterion, and metrics are dynamically instantiated from module and class paths given in the configuration. The layer exposes train_step() and valid_step() for customization of task-specific logic. This dynamic loading mechanism is central to the toolkit’s modularity because it decouples experiment specification from imperative glue code.
At the Training Layer, Tyee orchestrates initialization, epoch and step loops, checkpointing, and logging. The paper specifies support for distributed training using standard PyTorch distributed strategies. At the Configuration Layer, settings are centralized in YAML under sections such as common, dataset, model, optimizer, task, trainer, and distributed, with a command-line interface that loads YAML and supports runtime overrides.
The extensibility pattern is explicit. New modalities or datasets are added by creating a dataset class with read_record() and a metadata map, then registering it in YAML. New transforms are added by subclassing BaseTransform, implementing transform(), and referencing the class in offline_transform or online_transform. New models are added as PyTorch nn.Module implementations whose forward() signatures match the expected task inputs and outputs. This suggests that the toolkit’s principal abstraction boundary is the YAML configuration plus module/class registration, rather than a monolithic fixed API.
4. Workflow configuration, task formulations, and execution semantics
Tyee’s experiment workflow is end-to-end and configuration-driven. A complete experiment YAML can define the random seed, working directory, dataset class and transforms, model class and hyperparameters, optimizer, task type and metrics, training schedule, checkpoint criteria, logging frequency, and distributed training backend and devices. The command-line interface accepts a configuration file and runtime overrides, for example to change trainer.batch_size, optimizer.lr, model.module, model.class, or optimizer.class without modifying code (Zhou et al., 27 Dec 2025).
The task formulations reported in the evaluation span classification, detection, and regression. For classification and detection, the typical input-output form is stated as
The metrics used include BA, Accuracy, WF1, F1, AUROC, AUPRC, and (Cohen’s kappa). For regression, the reported tasks are finger movement in BCIC-4, evaluated with Mean correlation coefficient, and heart-rate estimation in PPG-DaLiA, evaluated with MAE reported through the scaling
The paper explicitly lists the evaluated tasks as EEG event classification, EEG abnormal detection, ERN detection, P300 recognition, arrhythmia detection, gesture recognition, emotion recognition, sleep staging, finger movement regression, and heart-rate estimation. It also states that while the architecture naturally accommodates segmentation, forecasting, and anomaly detection, the experiments focus on the classification, detection, and regression tasks above. This distinction matters: support at the architectural level is broader than empirical validation in the paper.
5. Benchmark suite and empirical profile
The benchmark suite comprises 13 datasets, with eight unimodal and five multimodal cases. The unimodal datasets are TUEV, TUAB, BCIC-2A, BCIC-4, KaggleERN, PhysioP300, MIT-BIH, and Ninapro DB5. The multimodal datasets are PPG-DaLiA, SEED-V, DEAP, SleepEDFx (39-subject split), and CinC2018 (Zhou et al., 27 Dec 2025).
| Dataset | Modality and task | Model |
|---|---|---|
| TUEV | EEG; Event classification | LaBraM |
| TUAB | EEG; Abnormal detection | LaBraM |
| BCIC-2A | EEG; Motor imagery | EEGConformer |
| BCIC-4 | ECoG; Finger movement (regression) | FingerFlex |
| KaggleERN | EEG; ERN detection | EEGPT |
| PhysioP300 | EEG; P300 recognition | EEGPT |
| MIT-BIH | ECG; Arrhythmia detection | ECGResNet34 |
| Ninapro DB5 | EMG; Gesture recognition | EMGBench |
| PPG-DaLiA | PPG + 3D accelerometer; Heart-rate estimation | BeliefPPG |
| SEED-V | EEG + EOG; Emotion recognition | G2G-ResNet18 |
| DEAP | GSR + PPG + Resp + Temp; Emotion recognition | MLSTM-FCN |
| SleepEDFx | EEG + EOG; Sleep staging | SalientSleepNet |
| CinC2018 | EEG + EOG + ECG + SaO2 + Respiration; Sleep staging | SleepFM |
The paper also reports dataset-specific subject counts, sampling rates, sample counts, and metrics. Examples include TUEV with 2,383 subjects, 256 Hz, and 112,491 samples; TUAB with 288 subjects, 256 Hz, and 409,455 samples; BCIC-4 with 3 subjects, 1,000 Hz, and 39,726 samples; PPG-DaLiA with 15 subjects, 64/32 Hz, and 64,607 samples; and CinC2018 with 1,985 subjects, 200 Hz, and 221,939 samples. These values situate Tyee’s evaluation across both small-subject, high-rate paradigms and larger cohort benchmarks.
The empirical summary given in the paper is qualitative rather than tabular. Tyee matches or exceeds the official baselines on 12 of 13 datasets, with state-of-the-art results on 12 of 13 datasets in the sense of reproducing or surpassing published baselines within this benchmark suite. The paper notes strong advantages on PhysioP300 and BCIC-4, improvements on SEED-V, SleepEDFx, and especially DEAP, and a slightly weaker but not significantly different result on PPG-DaLiA. At the same time, no per-dataset numeric results, confidence intervals, or significance tests are reported; comparison is presented qualitatively via radar plots. This constrains the granularity of empirical interpretation (Zhou et al., 27 Dec 2025).
6. Reproducibility, scalability, software distribution, and limitations
Reproducibility is a primary objective of Tyee’s design. The toolkit uses configuration-driven experiments to specify datasets, transforms, models, optimizers and schedulers, metrics, training schedules, and distributed settings. The Training Layer provides checkpointing and logging, and the Task Layer dynamically instantiates components from module and class names, which makes experiment composition explicit and repeatable. The paper emphasizes these reproducibility benefits but does not list deterministic kernels or fixed random seed policies, and it directs readers to the repository for seed management and deterministic settings (Zhou et al., 27 Dec 2025).
Scalability is addressed through multi-GPU training via standard PyTorch distributed strategies, specifically DDP, configured through the distributed section in YAML. However, the paper does not report speed, memory, or throughput benchmarks. As a result, its scalability claim is architectural and implementation-oriented rather than performance-characterized.
The toolkit is released with Conda and Docker support, and the repository is hosted at https://github.com/SmileHnu/Tyee. The license is CC BY-NC 4.0, and the project is described as actively maintained. Supported operating systems and hardware are not explicitly enumerated in the paper; it states that standard PyTorch-supported Linux, Windows, macOS, and CPU or GPU environments apply.
Several limitations are stated or directly implied. The paper does not include ablation studies on preprocessing choices, model components, or augmentations; it does not report robustness checks for missing data, noise, or cross-domain conditions; it does not provide speed benchmarks; it reports metrics qualitatively rather than with per-dataset numeric tables and significance analysis; and it does not describe built-in visualization or interpretability tools such as spectrogram viewers or saliency maps. Future directions suggested by the toolkit’s design include expanding modality coverage and standardized metadata schemas, adding first-class operators for advanced denoising or artifact removal, enriching visualization and explainability, conducting comprehensive ablations and robustness evaluation, and broadening ready-to-use support for segmentation, forecasting, and anomaly detection. This suggests that Tyee’s current contribution is strongest as an integrated experimental substrate for physiological ML, with several evaluation and tooling dimensions left open for subsequent work.