EphAsad commited on
Commit
e63bf0b
·
verified ·
1 Parent(s): 8d86457

Research checkpoint v0.3 — restricted research use and evaluation

Browse files
README.md ADDED
@@ -0,0 +1,224 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ tags:
3
+ - ecg
4
+ - single-lead-ecg
5
+ - onnx
6
+ - atrial-fibrillation
7
+ - time-series-classification
8
+ - research
9
+ metrics:
10
+ - f1
11
+ ---
12
+ # SatellaRhythm-Edge v0.3
13
+
14
+ **Experimental single-lead ECG rhythm and signal-quality model — research use only.**
15
+
16
+ > **NOT FOR CLINICAL USE.** Do not use this checkpoint for diagnosis, screening, triage, treatment,
17
+ > medical decisions, or reassurance that a recording is normal. The predefined research
18
+ > acceptance gate was **NOT MET**. No patient-independent, new-device or prospective clinical
19
+ > validation has been demonstrated. Even a `NORMAL` prediction cannot rule out a heart problem.
20
+
21
+ **Creator:** Zain Asad (`EphraimAsad`)
22
+ **GitHub source:** https://github.com/EphraimAsad/SatellaRhythm
23
+ **Hugging Face model:** https://huggingface.co/EphAsad/SatellaRhythm-Edge-v0.3
24
+
25
+ ## What the model does
26
+
27
+ SatellaRhythm-Edge is a small **2,867,109-parameter** dual-head 1D residual CNN.
28
+ It accepts short **single-lead ECG voltage waveforms** (not optical PPG/pulse data, ECG images,
29
+ heart-rate numbers or R-peaks) and provides two independent outputs:
30
+
31
+ - **Rhythm head:** `NORMAL`, `ATRIAL_FIBRILLATION`, `OTHER_RHYTHM`.
32
+ - **Quality head:** `INTERPRETABLE`, `UNINTERPRETABLE`.
33
+
34
+ A research-only postprocessing policy may emit `REVIEW_UNINTERPRETABLE` if quality risk
35
+ or confidence fails a validation-selected threshold. This is **not** an adequate clinical safety mechanism.
36
+ Predicted probabilities are uncalibrated model scores, **not** clinical probabilities.
37
+
38
+ ### Architecture and numerical input
39
+
40
+ | Property | Value |
41
+ |---|---|
42
+ | Architecture | Dual-head temporal ResNet with mean and max pooling |
43
+ | Parameters | 2,867,109 |
44
+ | Inference window | 10 seconds, one lead |
45
+ | Native sampling | 300 Hz (3,000 float32 samples/window) |
46
+ | ONNX input | `ecg`: `[batch, 1, 3000]` |
47
+ | ONNX outputs | `rhythm_logits`: `[batch, 3]`; `quality_logits`: `[batch, 2]` |
48
+ | Preprocessing | Subtract median; divide by 90th-percentile absolute value; clip to [-6, 6] |
49
+ | Inference | Five windows over a recording, averaged probabilities |
50
+ | Quality risk | 0.7 × mean uninterpretable probability + 0.3 × maximum window probability |
51
+ | Output rejection threshold | `0.45` quality risk |
52
+ | Rhythm confidence threshold | `0.00` |
53
+ | Normal confidence threshold | `0.00` |
54
+
55
+ In this checkpoint both rhythm and normal confidence thresholds selected as `0.0`,
56
+ so confidence-based rejection is **not active**; the final policy relies on the quality-risk threshold.
57
+
58
+ ## Quick start: download and run locally (ONNX CPU)
59
+
60
+ No API service, Hub Space or GPU is required for inference. Python 3.10+ is recommended.
61
+
62
+ ```bash
63
+ pip install huggingface_hub numpy scipy onnxruntime
64
+ ```
65
+
66
+ ```python
67
+ from pathlib import Path
68
+ import sys
69
+ import numpy as np
70
+ from huggingface_hub import snapshot_download
71
+
72
+ folder = snapshot_download(
73
+ repo_id="EphAsad/SatellaRhythm-Edge-v0.3",
74
+ repo_type="model",
75
+ allow_patterns=["satellarhythm_edge_v03.onnx", "config_research.json", "infer_onnx.py"],
76
+ )
77
+ sys.path.insert(0, folder)
78
+ from infer_onnx import RhythmEdge
79
+
80
+ model = RhythmEdge(folder)
81
+ # Replace with a locally stored, lawfully obtained single-lead ECG waveform.
82
+ # Example .npy file contains only 1D float32 sample amplitudes, NOT an ECG image.
83
+ ecg = np.load("path/to/your_ecg_waveform.npy", allow_pickle=False)
84
+ result = model.predict(ecg, sample_rate_hz=300, n_windows=5)
85
+ print(result) # Experimental research output, not diagnostic advice.
86
+ ```
87
+
88
+ `sample_rate_hz` must describe the input sample rate accurately. The wrapper resamples
89
+ supported rates to 300 Hz. It rejects invalid, flatlined, excessively short or overly long inputs;
90
+ its validity checks are NOT reliable detection of all real-world artefacts. For 10-second inputs,
91
+ window positions may overlap; the validation configuration is not a streaming continuous monitor.
92
+
93
+ ### Low-level ONNX Runtime access
94
+
95
+ ```python
96
+ import onnxruntime as ort
97
+ import numpy as np
98
+
99
+ session = ort.InferenceSession("satellarhythm_edge_v03.onnx", providers=["CPUExecutionProvider"])
100
+ # `x` must already be a correctly preprocessed 3000-sample window.
101
+ x = np.zeros((1, 1, 3000), dtype=np.float32) # Shape test ONLY; no clinical interpretation.
102
+ rhythm_logits, quality_logits = session.run(None, {"ecg": x})
103
+ assert rhythm_logits.shape == (1, 3) and quality_logits.shape == (1, 2)
104
+ ```
105
+
106
+ **Do not** pass unnormalised raw data directly to ONNX. The high-level `RhythmEdge` wrapper
107
+ implements the training-time preprocessing and aggregation. The zero-input snippet above only
108
+ verifies an inference interface and is not a meaningful ECG example.
109
+
110
+ ## Training data and process
111
+
112
+ 1. [PhysioNet/CinC Challenge 2017](https://physionet.org/content/challenge-2017/1.0.0/):
113
+ portable AliveCor single-lead recordings with v3 labels `N`, `A`, `O`, `~`; rhythm plus quality.
114
+ The `~` records are NOT assigned artificial rhythm labels.
115
+ 2. [PhysioNet/CinC Challenge 2011 Set A](https://physionet.org/content/challenge-2011/1.0.0/):
116
+ 12-lead recordings; lead I extracted and resampled for auxiliary quality supervision.
117
+ Labels indicate acceptability of the **entire 12-lead recording**, not necessarily its lead I.
118
+
119
+ No synthetic noisy recordings were used for training. AFDB training extension was **disabled**.
120
+ Waveforms were deduplicated for exact matches before a stratified recording-disjoint split.
121
+ **Patient-disjoint separation is not verified.** The same corpus was analysed in earlier
122
+ SatellaRhythm experiments, so this held-out split is not a fully untouched independent evaluation.
123
+ No external wearable manufacturer, population, paediatric cohort or prospective clinical set was tested.
124
+
125
+ Training stages: (1) rhythm-only warm-up, then (2) joint rhythm/quality refinement using
126
+ lower auxiliary quality-loss weights. Two predefined recipes were compared on validation data only;
127
+ `quality_moderate` was selected. Rejection thresholds were chosen on validation data.
128
+ Final test scoring was performed after freezing the model within this run.
129
+
130
+ ## Measured research performance
131
+
132
+ All values below are from the completed v0.3 notebook, **not** externally verified clinical results.
133
+ The four-class policy test uses **1,279 recordings** from the PhysioNet 2017 recording-disjoint test split.
134
+
135
+ | Metric (policy output) | Value |
136
+ |---|---:|
137
+ | Four-class macro F1 | **0.7027** |
138
+ | Four-class weighted F1 | 0.7925 |
139
+ | AF precision | 0.7518 |
140
+ | AF sensitivity/recall | 0.9115 |
141
+ | Other-rhythm sensitivity | 0.6529 |
142
+ | Normal sensitivity | 0.8226 |
143
+ | Real noisy-signal rejection recall | 0.8333 |
144
+ | Interpretable recording coverage | 0.9329 |
145
+ | AF or Other incorrectly reported NORMAL | **0.1597** |
146
+ | Auxiliary 2011 quality balanced accuracy on lead I | 0.6616 |
147
+
148
+ Before abstention, the raw three-rhythm classifier had macro F1 **0.8116**,
149
+ AF precision **0.7536**, AF sensitivity **0.9204**, and
150
+ Other-rhythm sensitivity **0.6970**.
151
+
152
+ ### Confusion matrix (policy)
153
+
154
+ True classes are rows and predicted classes are columns, in order
155
+ `NORMAL`, `ATRIAL_FIBRILLATION`, `OTHER_RHYTHM`, `REVIEW_UNINTERPRETABLE`.
156
+
157
+ ```text
158
+ 626 8 72 55
159
+ 0 103 7 3
160
+ 76 25 237 25
161
+ 4 1 2 35
162
+ ```
163
+
164
+ ### Research gate (NOT MET)
165
+
166
+ Predefined target: macro F1 ≥ 0.72; achieved **0.7027**.
167
+ Predefined target: abnormal rhythms reported NORMAL ≤ 0.15; achieved **0.1597**.
168
+ Other research checks passed in the notebook, but these two failed. No research acceptance claim is made.
169
+ Passing any experimental gate would still NOT demonstrate clinical safety.
170
+
171
+ ### ONNX parity and latency
172
+
173
+ - PyTorch/ONNX parity (checked logit difference): **7.15e-07**.
174
+ - ONNX CPU median latency on the **Colab L4 runtime's CPU**: **3.97 ms**
175
+ for one 10-second window; **16.83 ms** for a batch of five windows.
176
+ - These timings exclude acquisition and some preprocessing overhead and are **not** watch/phone benchmarks.
177
+
178
+ ## Limitations and intended use
179
+
180
+ Intended: offline ECG signal-processing **research, reproducibility and engineering investigation**.
181
+ Not intended: diagnosis, screening, clinical alerts, remote monitoring, medical device integration,
182
+ medical decisions or statements reassuring individuals that they do not have a cardiac abnormality.
183
+
184
+ - Missed AF or other abnormal rhythms and false `NORMAL` outputs are possible.
185
+ - `OTHER_RHYTHM` aggregates heterogeneous conditions; it does not identify specific conditions.
186
+ - Signal-quality performance may change drastically with device, lead position, wearer motion,
187
+ electrode contact, sampling format, prevalence and underlying population.
188
+ - The 2011 12-lead quality labels are imperfect auxiliary labels for the extracted single lead.
189
+ - The small noisy category gives imprecise sensitivity estimates.
190
+ - Output values are not calibrated clinical risk probabilities.
191
+ - All performance figures are from a within-project dataset, not an external prospective cohort.
192
+ - Neither model approval nor regulatory clearance is implied. Independent patient-disjoint,
193
+ multi-device and clinically reviewed validation would be required for any health application.
194
+
195
+ ## Privacy and data protection
196
+
197
+ This repository contains a model and **no training ECG waveforms, personal medical records,
198
+ identifiers, tokens, Colab execution outputs or individual-patient predictions**. Source metadata
199
+ was regenerated from a whitelist and ONNX optional metadata was cleared before upload.
200
+ Model weights cannot be proven free of all memorised training information merely by scanning files.
201
+ Applications must protect any real ECG data provided at inference time.
202
+
203
+ ## Datasets, attribution, and redistribution
204
+
205
+ Both Challenge 2017 and Challenge 2011 dataset pages identify the **Open Data Commons
206
+ Attribution License (ODC-By 1.0)** for the source datasets; respect the original attribution
207
+ and terms. This release does not redistribute the raw datasets and **does not claim** that
208
+ training-data terms automatically grant unrestricted commercial or medical-device rights to
209
+ model weights. A separate model-weight licence has not been asserted pending rights review.
210
+
211
+ - [2017 Challenge original publication](https://doi.org/10.22489/CinC.2017.065-469)
212
+ - [PhysioNet standard citation](https://physionet.org/about/cite/)
213
+ - [2011 Challenge publication and attribution](https://physionet.org/content/challenge-2011/1.0.0/)
214
+
215
+ ## Files
216
+
217
+ - `model.safetensors`: PyTorch neural-network weights (not a Transformers checkpoint).
218
+ - `satellarhythm_edge_v03.onnx`: two-output CPU-capable ONNX graph.
219
+ - `infer_onnx.py`: full preprocessing, aggregation and research decision policy.
220
+ - `config_research.json`: windowing, label order and rejection thresholds.
221
+ - `metrics.json`: minimal, numeric summary and gate outcome (no raw traces or logs).
222
+ - `requirements.txt`: runtime libraries.
223
+
224
+ **Do not use this model in any application where predictions can affect a person's health or safety.**
config_research.json ADDED
@@ -0,0 +1,37 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "name": "SatellaRhythm-Edge v0.3",
3
+ "architecture": "dual_head_1d_resnet_mean_max_pool",
4
+ "parameters": 2867109,
5
+ "sampling_rate_hz": 300,
6
+ "window_seconds": 10,
7
+ "window_samples": 3000,
8
+ "preprocessing": "median subtraction; 90th-percentile magnitude normalisation; clip [-6,6]",
9
+ "inference_windows": 5,
10
+ "rhythm_classes": [
11
+ "NORMAL",
12
+ "ATRIAL_FIBRILLATION",
13
+ "OTHER_RHYTHM"
14
+ ],
15
+ "quality_classes": [
16
+ "INTERPRETABLE",
17
+ "UNINTERPRETABLE"
18
+ ],
19
+ "quality_risk": "0.7*mean(p_uninterpretable) + 0.3*max(p_uninterpretable)",
20
+ "thresholds": {
21
+ "max_quality_risk": 0.45,
22
+ "min_rhythm_confidence": 0.0,
23
+ "min_normal_confidence": 0.0
24
+ },
25
+ "selected_recipe": "quality_moderate",
26
+ "training_datasets": [
27
+ "PhysioNet Challenge 2017 v3",
28
+ "PhysioNet Challenge 2011 Set A"
29
+ ],
30
+ "no_synthetic_noise": true,
31
+ "research_gate_pass": false,
32
+ "research_only": true,
33
+ "patient_disjoint_verified": false,
34
+ "external_device_tested": false,
35
+ "medical_device_approved": false,
36
+ "weights_sha256": "17f11497e272ab3d3f7c9e4a6a31baf1850157d6c43f19df5c9526ef92f270bc"
37
+ }
infer_onnx.py ADDED
@@ -0,0 +1,49 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # SatellaRhythm-Edge v0.3 — experimental ONNX single-lead ECG inference.
2
+ # Not for diagnosis, screening, treatment, triage or health reassurance.
3
+ # Requires numpy, scipy, onnxruntime. Usage: from infer_onnx import RhythmEdge
4
+ import json
5
+ from pathlib import Path
6
+ from fractions import Fraction
7
+ import numpy as np
8
+ from scipy.signal import resample_poly
9
+ import onnxruntime as ort
10
+
11
+ class RhythmEdge:
12
+ def __init__(self, folder):
13
+ folder=Path(folder)
14
+ self.cfg=json.loads((folder/'config_research.json').read_text(encoding='utf-8'))
15
+ self.session=ort.InferenceSession(str(folder/'satellarhythm_edge_v03.onnx'),providers=['CPUExecutionProvider'])
16
+ self.fs=int(self.cfg['sampling_rate_hz']);self.win=int(self.cfg['window_samples'])
17
+ self.thr=self.cfg['thresholds']
18
+ def _window(self,x,start):
19
+ y=np.asarray(x[start:start+self.win],dtype=np.float32)
20
+ if y.size<self.win:y=np.pad(y,(0,self.win-y.size),mode='reflect')
21
+ y=y-np.median(y)
22
+ scale=max(float(np.percentile(np.abs(y),90)),1e-6)
23
+ return np.clip(y/scale,-6,6).astype(np.float32)
24
+ @staticmethod
25
+ def _softmax(a):
26
+ a=a-a.max(axis=-1,keepdims=True)
27
+ e=np.exp(a);return e/e.sum(axis=-1,keepdims=True)
28
+ def predict(self,ecg,sample_rate_hz=300,n_windows=5):
29
+ fs=float(sample_rate_hz)
30
+ if fs<=0 or fs>2000:return {'status':'UNSUPPORTED_SAMPLE_RATE','research_only':True}
31
+ try:x=np.asarray(ecg,dtype=np.float32).reshape(-1)
32
+ except Exception:return {'status':'INVALID_INPUT','research_only':True}
33
+ if not np.isfinite(x).all() or len(x)<int(8.5*fs) or len(x)>int(120*fs) or np.std(x)<1e-5:
34
+ return {'status':'INVALID_OR_INSUFFICIENT_SIGNAL','research_only':True}
35
+ if fs!=self.fs:
36
+ rat=Fraction(self.fs,1)/Fraction(str(fs)).limit_denominator(10000)
37
+ x=resample_poly(x,rat.numerator,rat.denominator).astype(np.float32)
38
+ starts=np.linspace(0,max(0,len(x)-self.win),int(n_windows),dtype=int)
39
+ inp=np.stack([self._window(x,int(s)) for s in starts])[:,None,:]
40
+ rl,ql=self.session.run(None,{'ecg':inp})
41
+ rp=self._softmax(rl).mean(0);qs=self._softmax(ql)
42
+ risk=.7*float(qs[:,1].mean())+.3*float(qs[:,1].max())
43
+ label=int(rp.argmax());low_conf=float(rp.max())<self.thr['min_rhythm_confidence']
44
+ if label==0 and float(rp[0])<self.thr['min_normal_confidence']:low_conf=True
45
+ if risk>=self.thr['max_quality_risk'] or low_conf:label=3
46
+ names=self.cfg['rhythm_classes']+['REVIEW_UNINTERPRETABLE']
47
+ return {'status':'EXPERIMENTAL_RESEARCH_ONLY','prediction':names[label],
48
+ 'rhythm_probabilities':dict(zip(self.cfg['rhythm_classes'],rp.astype(float).round(4).tolist())),
49
+ 'quality_risk':round(risk,4),'not_for_diagnosis_or_reassurance':True}
metrics.json ADDED
@@ -0,0 +1,65 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "dataset": "PhysioNet Challenge 2017 v3 (held-out recordings, not patient-disjoint verified)",
3
+ "test_recordings_2017": 1279,
4
+ "confusion_matrix_row_true_col_pred_N_AF_OTHER_UNINTERPRETABLE": [
5
+ [
6
+ 626,
7
+ 8,
8
+ 72,
9
+ 55
10
+ ],
11
+ [
12
+ 0,
13
+ 103,
14
+ 7,
15
+ 3
16
+ ],
17
+ [
18
+ 76,
19
+ 25,
20
+ 237,
21
+ 25
22
+ ],
23
+ [
24
+ 4,
25
+ 1,
26
+ 2,
27
+ 35
28
+ ]
29
+ ],
30
+ "raw_three_class_metrics": {
31
+ "raw_rhythm_macro_f1": 0.8116203990271087,
32
+ "raw_rhythm_weighted_f1": 0.8325617002183704,
33
+ "raw_af_precision": 0.7536231884057971,
34
+ "raw_af_recall": 0.9203539823008849,
35
+ "raw_other_recall": 0.696969696969697
36
+ },
37
+ "four_class_policy_metrics": {
38
+ "macro_f1": 0.7027444104363546,
39
+ "weighted_f1": 0.792507786502381,
40
+ "af_precision": 0.7518248175182481,
41
+ "af_recall": 0.911504424778761,
42
+ "other_recall": 0.6528925619834711,
43
+ "normal_recall": 0.8226018396846255,
44
+ "noise_rejection_recall": 0.8333333333333334,
45
+ "clean_coverage": 0.9329021827000809,
46
+ "abnormal_reported_normal_rate": 0.15966386554621848
47
+ },
48
+ "auxiliary_2011_quality_balanced_accuracy": 0.6616379310344828,
49
+ "cpu_onnx_colab_l4_latency_median_ms": {
50
+ "single_10s_window": 3.970982000055301,
51
+ "five_window_batch": 16.830873999992946
52
+ },
53
+ "onnx_parity_max_abs_logit_error": 7.152557373046875e-07,
54
+ "validation_selected_thresholds": {
55
+ "max_quality_risk": 0.45,
56
+ "min_rhythm_confidence": 0.0,
57
+ "min_normal_confidence": 0.0
58
+ },
59
+ "research_release_gate": "NOT MET",
60
+ "failed_test_gates": [
61
+ "four_way_macro_f1_ge_0_72",
62
+ "abnormal_reported_normal_le_0_15"
63
+ ],
64
+ "medical_device_validation": false
65
+ }
model.safetensors ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:17f11497e272ab3d3f7c9e4a6a31baf1850157d6c43f19df5c9526ef92f270bc
3
+ size 11506012
requirements.txt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ numpy>=1.24,<3
2
+ scipy>=1.11,<2
3
+ onnxruntime>=1.18,<2
satellarhythm_edge_v03.onnx ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:6e8117e9a707fb35670215d69bb8d2a205f4efe05a91d227ecf2e7e4f3bdc826
3
+ size 11468954