# pulselabteam/pulsedb architecture

> Architecture diagram of the GitHub repository pulselabteam/pulsedb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pulselabteam/pulsedb
- Repository: https://github.com/pulselabteam/pulsedb

## Overview

#### Purpose and entry points
PulseDB is a dataset repository plus a reproducibility pipeline for cuff-less blood-pressure estimation from 10-second ECG/PPG waveform segments. Its operational entry points are MATLAB subset generation (`Generate_Subsets.m`) and Python model training (`Model_Training/Model_Training.py`).

#### Source data boundary
Raw PulseDB content is downloaded separately and placed beneath the data staging directories. It combines MIMIC-III waveform-derived and VitalDB-derived MATLAB data, subject to distinct licenses. Repository code assumes these files are locally available rather than fetching data at runtime.
Paths: `Segment_Files/`, `Info_Files/`, `Supplementary_Info_Files/`, `LICENSE_PulseDB_MIMIC`, `LICENSE_PulseDB_Vital`.

#### Segment representation
The dataset consists of cleaned 10-second signal segments. Version 2 adds absolute per-sample timestamps and non-normalized raw/filtered ECG and PPG records, while retaining normalized `ECG_F`/`PPG_F` fields used by the supplied subset generator. This is a compatibility boundary: changing input fields in `Generate_Subsets.m` is required to train on new non-normalized signals.
Paths: `Generate_Subsets.m`, `Supplementary Materials.pdf`.

#### Subset-construction stage
`Generate_Subsets.m` joins segment files with split-definition/info files and writes compact, matrix-oriented MATLAB v7.3 subset artifacts. Outputs represent training plus calibration-based and calibration-free testing partitions; supplementary subsets cover VitalDB-derived data.
Paths: `Generate_Subsets.m`, `Segment_Files/`, `Info_Files/`, `Subset_Files/`, `Supplementary_Subset_Files/`.

#### Training data contract
Training consumes generated MAT files, not individual source segments. Expected records expose waveform `Signals`, BP labels such as SBP/DBP, and demographics (age, gender, height, weight). MAT v7.3 requires a compatible Python loader such as `mat73`; MIMIC height/weight may be absent/NaN. The split files form the key evaluation boundary between calibration-based and calibration-free cohorts.
Paths: `Subset_Files/`, `Supplementary_Subset_Files/`, `Model_Training/Model_Training.py`.

#### Model and training orchestration
`Model_Training.py` is the executable experiment driver: its local paths select Train, CalBased-Test, and CalFree-Test subset files and its target selection chooses SBP or DBP. It builds datasets, instantiates the ResNet definition, and delegates optimization/evaluation behavior to the trainer module.
Paths: `Model_Training/Model_Training.py`, `Model_Training/Model_Def/ResNet.py`, `Model_Training/Model_Def/Trainer.py`.

#### Observability and runtimes
The pipeline spans MATLAB (data preparation) and Python deep-learning training. TensorBoard is the experiment-observability backend; committed event files preserve prior SBP and DBP runs and track training/test loss, mean error, R², and standard deviation across both test modes. No service or web runtime is present; external dependencies are dataset hosts (Box, Google Drive, OneDrive, Kaggle) and the upstream MIMIC-III/VitalDB datasets.
Paths: `Model_Training/TensorBoard/`, `Model_Training/TensorBoard/2022_0725_170136(SBP)/`, `Model_Training/TensorBoard/2022_0726_221554(DBP)/`.

Main entry points: [`Model_Training/Model_Training.py`](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Training.py) (Training driver), [`Generate_Subsets.m`](https://github.com/pulselabteam/pulsedb/blob/main/Generate_Subsets.m) (Generate subsets), [`Model_Training/Model_Def/ResNet.py`](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Def/ResNet.py) (ResNet), [`Model_Training/Model_Def/Trainer.py`](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Def/Trainer.py) (Trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset artifacts"]
  node_raw_sources[("MIMIC-III + VitalDB sources<br/>external datasets")]
  node_segment_files[("Segment files<br/>MATLAB segment data")]
  node_info_files["Split and info files<br/>MATLAB metadata"]
  node_supplementary_info["Supplementary info<br/>MATLAB metadata"]
  node_licenses["Dataset licenses<br/>license boundary"]
  node_subset_files[("Primary subsets<br/>MAT v7.3 artifacts")]
  node_supplementary_subsets[("VitalDB subsets<br/>MAT v7.3 artifacts")]
end

subgraph group_matlab["MATLAB preparation"]
  node_subset_generator{{"Generate subsets<br/>MATLAB entry point<br/>[Generate_Subsets.m]"}}
end

subgraph group_python["Python training"]
  node_training_driver{{"Training driver<br/>Python entry point<br/>[Model_Training.py]"}}
  node_mat_loader_contract["MAT training contract<br/>dataset loader<br/>[Model_Training.py]"]
  node_resnet["ResNet<br/>model definition<br/>[ResNet.py]"]
  node_trainer["Trainer<br/>optimization and evaluation<br/>[Trainer.py]"]
end

subgraph group_observability["Experiment records"]
  node_tensorboard[("TensorBoard events<br/>experiment telemetry")]
  node_sbp_run["SBP run<br/>committed event files"]
  node_dbp_run["DBP run<br/>committed event files"]
end

node_raw_sources -->|"downloaded and staged"| node_segment_files
node_raw_sources -->|"downloaded and staged"| node_info_files
node_licenses -.->|"governs use"| node_raw_sources
node_segment_files -->|"waveform input"| node_subset_generator
node_info_files -->|"splits and metadata"| node_subset_generator
node_supplementary_info -->|"supplementary metadata"| node_subset_generator
node_subset_generator -->|"writes primary partitions"| node_subset_files
node_subset_generator -->|"writes VitalDB partitions"| node_supplementary_subsets
node_subset_files -->|"Train / CalBased / CalFree MAT files"| node_training_driver
node_supplementary_subsets -->|"supplementary MAT files"| node_training_driver
node_training_driver -->|"builds datasets"| node_mat_loader_contract
node_mat_loader_contract -->|"waveform batches"| node_resnet
node_training_driver -->|"instantiates"| node_resnet
node_training_driver -->|"delegates experiment"| node_trainer
node_resnet -->|"model"| node_trainer
node_trainer -->|"metrics and losses"| node_tensorboard
node_tensorboard -->|"preserved SBP events"| node_sbp_run
node_tensorboard -->|"preserved DBP events"| node_dbp_run

click node_licenses "https://github.com/pulselabteam/pulsedb/blob/main/LICENSE_PulseDB_MIMIC"
click node_subset_generator "https://github.com/pulselabteam/pulsedb/blob/main/Generate_Subsets.m"
click node_training_driver "https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Training.py"
click node_mat_loader_contract "https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Training.py"
click node_resnet "https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Def/ResNet.py"
click node_trainer "https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Def/Trainer.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_raw_sources,node_segment_files,node_info_files,node_supplementary_info,node_licenses,node_subset_files,node_supplementary_subsets toneBlue
class node_subset_generator toneAmber
class node_training_driver,node_mat_loader_contract,node_resnet,node_trainer toneMint
class node_tensorboard,node_sbp_run,node_dbp_run toneRose
```

## Components

### Dataset artifacts

Locally staged PulseDB data and generated subsets.

- **MIMIC-III + VitalDB sources**: external datasets · Downloaded separately under their distinct licenses.
- **Segment files**: MATLAB segment data · Cleaned 10-second ECG/PPG waveform segments.
- **Split and info files**: MATLAB metadata · Defines cohort splits and segment metadata.
- **Supplementary info**: MATLAB metadata · Metadata for supplementary data.
- [Dataset licenses](https://github.com/pulselabteam/pulsedb/blob/main/LICENSE_PulseDB_MIMIC): license boundary · MIMIC and VitalDB content has distinct license terms. · `LICENSE_PulseDB_MIMIC`
- **Primary subsets**: MAT v7.3 artifacts · Training, calibration-based, and calibration-free partitions.
- **VitalDB subsets**: MAT v7.3 artifacts · Supplementary VitalDB-derived partitions.

### MATLAB preparation

Subset generation runtime.

- [Generate subsets](https://github.com/pulselabteam/pulsedb/blob/main/Generate_Subsets.m): MATLAB entry point · Joins segments and splits into compact v7.3 MAT artifacts. · `Generate_Subsets.m`

### Python training

Model experiment runtime.

- [Training driver](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Training.py): Python entry point · Selects SBP or DBP target and Train/CalBased/CalFree files. · `Model_Training/Model_Training.py`
- [MAT training contract](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Training.py): dataset loader · Loads Signals, BP labels, and demographics from v7.3 MAT files. · `Model_Training/Model_Training.py`
- [ResNet](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Def/ResNet.py): model definition · `Model_Training/Model_Def/ResNet.py`
- [Trainer](https://github.com/pulselabteam/pulsedb/blob/main/Model_Training/Model_Def/Trainer.py): optimization and evaluation · Runs optimization and both evaluation modes. · `Model_Training/Model_Def/Trainer.py`

### Experiment records

Committed TensorBoard outputs.

- **TensorBoard events**: experiment telemetry · Records loss, mean error, R², and standard deviation.
- **SBP run**: committed event files
- **DBP run**: committed event files

## Connections

- MIMIC-III + VitalDB sources → Segment files: downloaded and staged
- MIMIC-III + VitalDB sources → Split and info files: downloaded and staged
- Dataset licenses → MIMIC-III + VitalDB sources: governs use
- Segment files → Generate subsets: waveform input
- Split and info files → Generate subsets: splits and metadata
- Supplementary info → Generate subsets: supplementary metadata
- Generate subsets → Primary subsets: writes primary partitions
- Generate subsets → VitalDB subsets: writes VitalDB partitions
- Primary subsets → Training driver: Train / CalBased / CalFree MAT files
- VitalDB subsets → Training driver: supplementary MAT files
- Training driver → MAT training contract: builds datasets
- MAT training contract → ResNet: waveform batches
- Training driver → ResNet: instantiates
- Training driver → Trainer: delegates experiment
- ResNet → Trainer: model
- Trainer → TensorBoard events: metrics and losses
- TensorBoard events → SBP run: preserved SBP events
- TensorBoard events → DBP run: preserved DBP events