yuntian wu commited on
Upload README.md with huggingface_hub
Browse files
README.md
CHANGED
|
@@ -1,3 +1,170 @@
|
|
| 1 |
---
|
| 2 |
license: apache-2.0
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 3 |
---
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
---
|
| 2 |
license: apache-2.0
|
| 3 |
+
library_name: pytorch
|
| 4 |
+
pipeline_tag: time-series-forecasting
|
| 5 |
+
tags:
|
| 6 |
+
- sensor-time-series
|
| 7 |
+
- physiological-signal
|
| 8 |
+
- generative-model
|
| 9 |
+
- flow-matching
|
| 10 |
+
- scalable-interpolant-transformer
|
| 11 |
+
- ecg
|
| 12 |
+
- ppg
|
| 13 |
+
- blood-pressure
|
| 14 |
+
- vitaldb
|
| 15 |
+
- mimic-iv
|
| 16 |
+
- sensorgen
|
| 17 |
+
language:
|
| 18 |
+
- en
|
| 19 |
+
datasets:
|
| 20 |
+
- physionet/mimic-iv-ecg
|
| 21 |
---
|
| 22 |
+
|
| 23 |
+
# SensorGen-SiT
|
| 24 |
+
|
| 25 |
+
> Scalable Interpolant Transformer (SiT-B/1d) reference models for the
|
| 26 |
+
> SensorGen benchmark on real-world sensor time series.
|
| 27 |
+
|
| 28 |
+
This repository hosts five trained checkpoints used in the SensorGen study
|
| 29 |
+
("*Signal or Noise? Understanding Generative Models for Real-World Sensor
|
| 30 |
+
Time Series*"). All checkpoints share the same SiT-B/1d backbone (12
|
| 31 |
+
transformer blocks, hidden 768, 1-D patch size 20) and were trained on 4Γ
|
| 32 |
+
NVIDIA GH200 120 GB with a constant 1e-4 learning rate, EMA decay 0.9998,
|
| 33 |
+
and hard FP32 precision.
|
| 34 |
+
|
| 35 |
+
| Checkpoint | Task | Dataset | Step | Notes |
|
| 36 |
+
|------------|------|---------|-------|-------|
|
| 37 |
+
| `sit_b1d_mimic_text2ecg_50k.pt` | Text-to-ECG | MIMIC-IV ECG | 50,000 | Paper-aligned step |
|
| 38 |
+
| `sit_b1d_mimic_text2ecg_200k.pt` | Text-to-ECG | MIMIC-IV ECG | 200,000 | Extended training |
|
| 39 |
+
| `sit_b1d_vitaldb_bp_translation_50k.pt` | PPG β invasive BP | VitalDB | 50,000 | Paper-aligned step |
|
| 40 |
+
| `sit_b1d_vitaldb_forecast_18k.pt` | Medication-aware forecasting | VitalDB | 18,000 | Best-validation step (paper-aligned) |
|
| 41 |
+
| `sit_b1d_vitaldb_forecast_200k.pt` | Medication-aware forecasting | VitalDB | 200,000 | Extended training |
|
| 42 |
+
|
| 43 |
+
For VitalDB forecasting we observed a U-shape in validation loss past ~20K
|
| 44 |
+
steps; the **18K best-validation checkpoint** is what we use to report paper
|
| 45 |
+
numbers. The 200K extended checkpoint is provided as a reference for
|
| 46 |
+
practitioners who prefer the longer-trained generator at the cost of mild
|
| 47 |
+
overfit on the validation set.
|
| 48 |
+
|
| 49 |
+
|
| 50 |
+
## Usage
|
| 51 |
+
|
| 52 |
+
Pair this checkpoint repository with the GitHub code release at
|
| 53 |
+
**[GitaTReNt/SensorGen](https://github.com/GitaTReNt/SensorGen)**.
|
| 54 |
+
|
| 55 |
+
### Download a single checkpoint
|
| 56 |
+
|
| 57 |
+
```python
|
| 58 |
+
from huggingface_hub import hf_hub_download
|
| 59 |
+
|
| 60 |
+
ckpt_path = hf_hub_download(
|
| 61 |
+
repo_id="Run33/SensorGen-SiT",
|
| 62 |
+
filename="sit_b1d_mimic_text2ecg_50k.pt",
|
| 63 |
+
)
|
| 64 |
+
```
|
| 65 |
+
|
| 66 |
+
### Download all checkpoints (β26 GB)
|
| 67 |
+
|
| 68 |
+
```bash
|
| 69 |
+
hf download Run33/SensorGen-SiT --local-dir ./ckpts
|
| 70 |
+
```
|
| 71 |
+
|
| 72 |
+
### Run inference (text-to-ECG)
|
| 73 |
+
|
| 74 |
+
```bash
|
| 75 |
+
# After cloning https://github.com/GitaTReNt/SensorGen
|
| 76 |
+
torchrun --nproc_per_node=1 wrapper/run.py \
|
| 77 |
+
--model sit \
|
| 78 |
+
--config wrapper/configs/sit_mimic_generation.yaml \
|
| 79 |
+
--ckpt ./ckpts/sit_b1d_mimic_text2ecg_50k.pt \
|
| 80 |
+
--evaluate-only \
|
| 81 |
+
--global-batch-size 16 \
|
| 82 |
+
--results-dir ./samples_text_to_ecg
|
| 83 |
+
```
|
| 84 |
+
|
| 85 |
+
This loads the EMA weights, runs flow-matching ODE sampling on the
|
| 86 |
+
MIMIC-IV ECG test-split reports, and writes 12-lead ECG signals of shape
|
| 87 |
+
`(B, 12, 1000)` to `./samples_text_to_ecg/`. On first use the SD3 text
|
| 88 |
+
encoder (~12 GB) is downloaded automatically from Hugging Face Hub.
|
| 89 |
+
|
| 90 |
+
Equivalent commands for the other two tasks are in the repository
|
| 91 |
+
[README](https://github.com/GitaTReNt/SensorGen#-usage).
|
| 92 |
+
|
| 93 |
+
|
| 94 |
+
## Model details
|
| 95 |
+
|
| 96 |
+
| Field | Value |
|
| 97 |
+
|-------|-------|
|
| 98 |
+
| Architecture | SiT-B/1d (Scalable Interpolant Transformer, 1-D variant) |
|
| 99 |
+
| Depth Γ width | 12 transformer blocks Γ hidden 768 |
|
| 100 |
+
| Patchification | `Conv1d(in_channels=C, kernel=20, stride=20)`; `C β {12, 1, 7}` per task |
|
| 101 |
+
| Trained parameters | β260 M (text-to-ECG, excluding frozen SD3 text encoder) / β273 M (BP, forecasting) |
|
| 102 |
+
| Path / prediction | Linear interpolant, velocity-parameterised flow matching |
|
| 103 |
+
| Precision | Hard FP32 (TF32 disabled) |
|
| 104 |
+
| Optimizer | AdamW, constant LR 1e-4, no warmup |
|
| 105 |
+
| EMA decay | 0.9998 |
|
| 106 |
+
| Batch size | Global 256 (per-rank 64 on 4Γ GH200 120 GB) |
|
| 107 |
+
| Training time | ~24β96 GPU-hours per task |
|
| 108 |
+
|
| 109 |
+
|
| 110 |
+
## Task specifications
|
| 111 |
+
|
| 112 |
+
| Task | Target `x` | C Γ T | `c_1` (sparse) | `c_2` (dense) |
|
| 113 |
+
|------|------------|-------|----------------|---------------|
|
| 114 |
+
| Text-to-ECG | 12-lead ECG, 10 s @ 100 Hz | 12 Γ 1,000 | Free-text ECG report (CLIP-encoded) | β |
|
| 115 |
+
| PPG β invasive BP | Arterial blood pressure, 30 s @ 50 Hz | 1 Γ 1,500 | 6-D non-invasive BP statistics | PPG waveform, 1 Γ 1,500 |
|
| 116 |
+
| Medication-aware forecasting | 7 future physiological waveforms, 10 s @ 100 Hz | 7 Γ 1,000 | β | Past 7 waveforms (20 s) + 21 medication channels (30 s) |
|
| 117 |
+
|
| 118 |
+
|
| 119 |
+
## Datasets
|
| 120 |
+
|
| 121 |
+
Neither MIMIC-IV ECG nor VitalDB are redistributed in this repository.
|
| 122 |
+
Credentialed access is required from the original data providers:
|
| 123 |
+
|
| 124 |
+
- **MIMIC-IV ECG** β [PhysioNet credentialed access](https://physionet.org/content/mimic-iv-ecg/)
|
| 125 |
+
- **VitalDB** β [vitaldb.net](https://vitaldb.net)
|
| 126 |
+
|
| 127 |
+
Preprocessing pipelines that convert the raw releases into the HDF5
|
| 128 |
+
layout consumed by these checkpoints are documented in the GitHub README.
|
| 129 |
+
|
| 130 |
+
|
| 131 |
+
## Limitations and responsible use
|
| 132 |
+
|
| 133 |
+
- The MIMIC-IV ECG generator is conditioned on free-text reports authored
|
| 134 |
+
by clinicians. Generated 12-lead ECG waveforms reflect statistical
|
| 135 |
+
patterns in the training corpus and **must not be used for clinical
|
| 136 |
+
diagnosis or as a substitute for real patient recordings**.
|
| 137 |
+
- The VitalDB blood-pressure translation and forecasting models rely on
|
| 138 |
+
intra-operative monitoring data from anaesthetised surgical cases and
|
| 139 |
+
may not generalise to ambulatory or out-of-hospital settings.
|
| 140 |
+
- Patient overlap was controlled at preprocessing time but the exact
|
| 141 |
+
protocol differs across datasets; see the paper appendix for
|
| 142 |
+
per-dataset split details.
|
| 143 |
+
- These models are released for *research use*. They are not approved
|
| 144 |
+
medical devices and have not been evaluated for clinical safety or
|
| 145 |
+
efficacy.
|
| 146 |
+
|
| 147 |
+
|
| 148 |
+
## Citation
|
| 149 |
+
|
| 150 |
+
If you use any of these checkpoints, please cite the SensorGen paper:
|
| 151 |
+
|
| 152 |
+
```bibtex
|
| 153 |
+
@article{shuai2026sensorgen,
|
| 154 |
+
title={Signal or Noise? Understanding Generative Models for Real-World
|
| 155 |
+
Sensor Time Series},
|
| 156 |
+
author={Shuai, Zitao and Xu, Zongzhe and Wu, Yuntian and Li, Sirui and
|
| 157 |
+
Li, Tianhong and Yang, Yuzhe},
|
| 158 |
+
journal={arXiv preprint arXiv:TODO},
|
| 159 |
+
year={2026}
|
| 160 |
+
}
|
| 161 |
+
```
|
| 162 |
+
|
| 163 |
+
|
| 164 |
+
## License
|
| 165 |
+
|
| 166 |
+
This release is distributed under the Apache License 2.0.
|
| 167 |
+
|
| 168 |
+
The downstream SD3 text encoder weights (downloaded at runtime for the
|
| 169 |
+
text-to-ECG task only) are governed by Stability AI's Community License;
|
| 170 |
+
please review that license before commercial deployment.
|