yuntian wu commited on
Commit
e8a6f1e
Β·
verified Β·
1 Parent(s): 30b4d5d

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +167 -0
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.