README.md

---
license: apache-2.0
language:
- en
metrics:
- precision
- recall
- f1
- brier_score
- auroc
- auprc
- accuracy
pipeline_tag: tabular-classification
tags:
- tensorflow
- keras
- transformers
- ohcaprediction
- cvdpredict
- ohca_predictor
library_name: cvdpredict
---

# CVDGaurd: A Cross-Attention 17 Million Parameter Deep Neural Network for the Early Prediciton of Out-Of-Hospital Cardiac Arrest

This repository contains a deep multimodal cardiovascular risk monitoring architecture designed to predict Out-of-Hospital Cardiac Arrest (OHCA) events using simultaneous time-series physiological waveforms and static clinical tabular baselines. 

The model is built using TensorFlow/Keras and is wrapped into the global Hugging Face ecosystem via the unified AutoModel entry point using custom remote code execution. 

### Model Details

* **Architecture Name:** TFCVDPredictorForOHCADetection
* **Domain:** Cardiovascular Disease (CVD) & Emergency Medicine
* **Task:** Binary classification / Risk estimation of impending Out-of-Hospital Cardiac Arrest (OHCA)
* **Framework:** TensorFlow 2.16+ / Keras 3 - CVDPredict Library 
* **Primary Inputs:** Continuous 1D/2D sensor waveforms (ECG, PPG, Accelerometer, Gyroscope, Vitals) + Patient tabular metadata

### Performance Metrics (Validation Cohort)

Evaluated independently on a standardized clinical baseline cohort (196 validation samples, post-rate = 28.1%): 


| Metric | Value |
| ------ | ----- |
| **AUROC** | 0.932 [0.895 - 0.972] |
| **AUPRC** | 0.892 [0.828 - 0.949] |
| **Optimal Risk Threshold**  |0.302 |
| **Sensitivity @ Optimal** | 0.855 |
| **Specificity @ Optimal** | 0.844 |
| **Brier Score** | 0.0904| 

*Note: The cross-attention transformer components are highly sensitive to physiological anomalies and morphological variations in raw continuous wave signals.* 

### Data Schema & Input Specifications

To initialize prediction profiles properly or prevent pipeline shape truncation errors, inputs should be structured around a ~185-second monitoring window (window_duration_hours ≈ 0.05138) conforming to the following target sampling specs: 

#### 1. Continuous Time-Series Signals (Waveforms)

| Parameter Name | Dimension | Frequency | Description / Layout |
| -------------- | --------- | --------- | -------------------- |
| ecgShape       | (24050,)  | 130 HzRaw | continuous 1D ECG trace array |
| ppgShape | (9250,)| 50 Hz | Continuous photoplethysmogram wave |
| accelerometer | (9620, 3)| 52 Hz| 3-axis continuous accelerometer matrix |
| gyroscope | (9620, 3) | 52 Hz|3-axis continuous gyroscope telemetry |
| respiration | (4625,) | 25 Hz | Continuous chest expansion respiration belt wave |
| spo2Shape (1850,) | 10 Hz | Continuous blood oxygen saturation array stream |
| temperature | (185,) | 1 Hz | Continuous core body temperature array log |

#### 2. Clinical Context Vectors (Tabular Baseline Matrices)

* demographics: NumPy array of shape (24,) — Normalized age, sex, and baseline physiological markers.
* medications: NumPy array of shape (14,) — Encoded binary medication history indicators.
* comorbidities: NumPy array of shape (14,) — Encoded binary chronic disease matrix.
* lab_values: NumPy array of shape (8,) — Standardized baseline blood chemistry values.

#### 3. Vital Parameter Scalars

* heart_rate (float), rhythm (int), activity_state (int)
* spo2_mean (float), sbp_mean (float), dbp_mean (float), respiration_mean (float)

#### Quickstart / Deployment Usage

#### Prerequisites

Before running inference, you must have your matching domain execution library (CVDPredict/ohca_predictor), transformers, and tensorflow installed on your host system: 

```bash
pip install git+https://github.com/sharktide/CVD-Predict.git@v1.0.0
pip install "transformers>=5"
# Install tensorflow for your system by following the instructions at https://tensorflow.org/install
```

### Inference Code Example

You can load the model directly from the internet via the standard Hugging Face pipeline in just a few lines of code: 

```python
import numpy as np
import warnings
warnings.filterwarnings("ignore")

from transformers import AutoModel
from ohca_predictor.utils.io_utils import WindowSample
# 1. Download and map the custom model wrapper from the cloud Hub repository
model = AutoModel.from_pretrained("sharktide/ohca-predictor-v1", trust_remote_code=True)
```
#### 2. Package raw incoming data streams into a structured WindowSample instance
```python
patient_record = WindowSample(
    ecg=np.random.randn(24050).astype(np.float32), 
    accelerometer=np.zeros((9620, 3), dtype=np.float32),
    gyroscope=np.zeros((9620, 3), dtype=np.float32),
    ppg=np.random.randn(9250).astype(np.float32),
    respiration=np.zeros(4625, dtype=np.float32),
    spo2=np.zeros(1850, dtype=np.float32),
    temperature=np.zeros(185, dtype=np.float32),
    demographics=np.zeros(24, dtype=np.float32),
    medications=np.zeros(14, dtype=np.float32),
    comorbidities=np.zeros(14, dtype=np.float32),
    lab_values=np.zeros(8, dtype=np.float32),
    heart_rate=72.0, rhythm=0, activity_state=0,
    spo2_mean=97.5, sbp_mean=120.0, dbp_mean=80.0,
    patient_id="live-monitor-case-001", signal_quality={"ecg": 1.0},
    window_start_hours=0.0, window_duration_hours=0.05138,
    ohca_label=0.0, event_indicator=0.0, time_to_event=0.0
)

# 3. Dispatches forward pass execution natively
prediction = model(patient_record)

print(f"Prediction Success!")
print(f"Calculated Patient OHCA Risk: {prediction['ohca_risk'].numpy().item():.4f}")
```

### Security Notice

This model relies on **Custom Remote Code Execution (trust_remote_code=True)** to execute the pipeline routing files (modeling_ohca.py and configuration_ohca.py) directly from the Hugging Face hub. Always ensure you are requesting a pinned repository commit hash if deploying this wrapper framework inside production or clinical environments.