📖 CardioAnnotate Help

3.1 Input File Formats

WFDB Format (.hea + .dat/.mat)

The PhysioNet standard format for physiological signals, consisting of two files:

Header File (.hea) Structure:

record_name n_signals sampling_frequency n_samples
filename format gain baseline units resolution 0 0 channel_name
filename format gain baseline units resolution 0 0 channel_name
...
# Optional comment lines starting with #

Example .hea file:

100 2 360 650000
100.dat 212 200 1024 mV 11 0 0 MLII
100.dat 212 200 1024 mV 11 0 0 V5
# Age: 69  Sex: M

Field descriptions:

Signal File (.dat) Structure:

• Binary file containing interleaved signal samples
• Format 212: 12-bit samples, 2 samples packed in 3 bytes (little-endian)
• Format 16: 16-bit signed integers, 2 bytes per sample (little-endian)
• Format 80: 8-bit unsigned with offset 128
• Physical value = (ADC_value − baseline) / gain

CSV Format (.csv)

Comma-separated values with a header row.

Structure:

fs,time_s,MLII,V1,V5
360,0.000000,0.123,-0.045,0.089
360,0.002778,0.125,-0.043,0.091
360,0.005556,0.128,-0.041,0.094
360,0.008333,0.132,-0.038,0.098
...

Required columns (one of the following):

Signal columns:

• Any numeric column not in the exclude list becomes a channel
• Excluded column names: fs, sampling_rate, sampling_frequency, time_s, time, index, sample
• Values should be in physical units (e.g., mV)

NPZ Bundle Format (.npz)

Compressed NumPy archive containing signal data and metadata.

Structure:

{
  "signals": numpy.ndarray,     // Shape: (n_channels, n_samples), dtype: float64
  "meta": JSON string           // Metadata as serialized JSON
}

Meta JSON structure:

{
  "fs": 360,                              // Sampling frequency in Hz
  "channelNames": ["MLII", "V1", "V5"],   // Array of channel names
  "units": ["mV", "mV", "mV"],            // Units per channel (optional)
  "recordBase": "100",                    // Original record name (optional)
  "annotations": {                        // Peak annotations
    "R": {
      "0": [                              // Channel index as string key
        {"index": 77, "type": "N"},       // R-peaks: objects with index and type
        {"index": 370, "type": "N"},
        {"index": 662, "type": "V"}
      ],
      "1": [{"index": 79, "type": "N"}]
    },
    "P": {
      "0": [30, 320, 610],                // Other peaks: arrays of sample indices
      "1": [32, 322]
    },
    "Q": {"0": [70, 363, 655]},
    "S": {"0": [85, 378, 670]},
    "T": {"0": [180, 475, 765]},
    "U": {"0": []}
  }
}

Legacy bundles that use peaks for the annotation map may still be loaded when supported by the importer.

Annotation JSON Format (.json)

JSON file containing peak annotations only (no signal data).

Structure:

{
  "fs": 360,
  "channelNames": ["MLII", "V1"],
  "annotations": {
    "R": {
      "0": [
        {"index": 77, "type": "N"},
        {"index": 370, "type": "N"},
        {"index": 662, "type": "V"},
        {"index": 955, "type": "A"}
      ],
      "1": [
        {"index": 79, "type": "N"},
        {"index": 372, "type": "N"}
      ]
    },
    "P": {
      "0": [30, 320, 610, 905],
      "1": [32, 322, 612]
    },
    "Q": {
      "0": [70, 363, 655, 948],
      "1": []
    },
    "S": {
      "0": [85, 378, 670, 963],
      "1": []
    },
    "T": {
      "0": [180, 475, 765, 1060],
      "1": [182, 477]
    },
    "U": {
      "0": [],
      "1": []
    }
  }
}

Key points:

• The top-level annotation map is named annotations, following the ecg-annotator-json-v2 schema
• R-peaks: Array of objects with {"index": sample_number, "type": "beat_code"}
• P, Q, S, T, U peaks: Arrays of sample indices (integers)
• Channel indices are string keys ("0", "1", "2", ...)
• JSON files that use the legacy top-level peaks key are also supported for import
• Legacy format (R-peaks as simple integer arrays) is also supported for import

Annotation CSV Format (.csv)

Tabular format for peak annotations.

Structure:

channel_index,label,index,time_s,beat_type
0,R,77,0.214,N
0,R,370,1.028,N
0,R,662,1.839,V
0,R,955,2.653,A
0,P,30,0.083,
0,P,320,0.889,
0,Q,70,0.194,
0,S,85,0.236,
0,T,180,0.500,
1,R,79,0.219,N
1,P,32,0.089,

Column descriptions:

*Either index or time_s is required.

WFDB Annotation Import Files (.atr / wave annotations)

WFDB annotation files can be imported after a signal is loaded. The file picker accepts all file extensions so that non-standard WFDB annotation extensions remain selectable.

Supported import forms:

Recognized extension variants are mapped by their extension name. Imported WFDB annotations are merged into all loaded channels.

3.2 Output File Formats

Annotation JSON Export

Same structure as input JSON, with added export timestamp and the annotations top-level key.

Structure:

{
  "exportedAt": "2026-01-15T10:30:00.000Z",
  "fs": 360,
  "channelNames": ["MLII", "V1"],
  "annotations": {
    "R": {
      "0": [
        {"index": 77, "type": "N"},
        {"index": 370, "type": "V"}
      ]
    },
    "P": {"0": [30, 320]},
    "Q": {"0": [70, 363]},
    "S": {"0": [85, 378]},
    "T": {"0": [180, 475]},
    "U": {"0": []}
  }
}

Annotation CSV Export

Tabular export with full metadata per peak.

Structure:

peak_type,channel_index,channel_name,sample_index,time_s,beat_type
R,0,MLII,77,0.214,N
R,0,MLII,370,1.028,V
R,0,MLII,662,1.839,A
P,0,MLII,30,0.083,
P,0,MLII,320,0.889,
Q,0,MLII,70,0.194,
S,0,MLII,85,0.236,
T,0,MLII,180,0.500,
R,1,V1,79,0.219,N

Column descriptions:

ECG Signal CSV Export

Exports the current (possibly processed) signal data.

Structure:

fs,time_s,MLII,V1,V5
360,0.000000,0.123,-0.045,0.089
360,0.002778,0.125,-0.043,0.091
360,0.005556,0.128,-0.041,0.094
360,0.008333,0.132,-0.038,0.098
...

Notes:

• fs column contains the sampling frequency (repeated each row)
• time_s is computed as sample_index / fs
• Signal columns contain values after any processing (filtering, resampling)

NPZ Bundle Export

Signal-and-annotation bundle with processed signals and all annotations.

Structure:

numpy.savez_compressed("export.npz",
  signals=numpy.array(...),  // Shape: (n_channels, n_samples), dtype: float64
  meta=json.dumps({
    "fs": 360,
    "channelNames": ["MLII", "V1"],
    "units": ["mV", "mV"],
    "recordBase": "100",
    "annotations": { ... }   // Same structure as annotation JSON
  })
)

{
  "sessionVersion": "full-state-v1",
  "exportedAt": "2026-01-15T10:30:00.000Z",
  "signals": {
    "processed": [[...]],
    "original": [[...]],
    "fs": 360,
    "channelNames": ["MLII", "V1"],
    "units": ["mV", "mV"],
    "recordBase": "100"
  },
  "annotations": { ... },
  "corrections": {
    "flaggedRR": [...],
    "gpCorrectedRR": [...]
  },
  "settings": { ... },
  "view": {
    "activeChannel": 0,
    "xRange": [0.0, 10.5]
  },
  "results": {
    "sqi": { ... },
    "hrv": { ... },
    "adf": { ... },
    "summary": { ... }
  }
}

WFDB Export

PhysioNet-compatible format with header, signal, and annotation files.

Files created:

Header file (record.hea):

export 2 360 650000
export.dat 16 200(0) 0 16 0 0 0 MLII
export.dat 16 200(0) 0 16 0 0 0 V1

Signal file (record.dat):

• Format 16: 16-bit signed integers, little-endian
• Gain: 200 ADC units per mV (fixed)
• Baseline: 0
• Channels interleaved sample-by-sample

Annotation file(s) - Single file mode (.atr):

Binary WFDB annotation format containing:
- Sample number (delta-encoded)
- Annotation type code
- Subtype (beat classification for R-peaks)
- Channel number

Peak type to WFDB code mapping:

Annotation files - Separate files mode:

4.1 R-Peak Beat Classification

CardioAnnotate supports comprehensive beat-by-beat R-peak classification following WFDB annotation standards. Each R-peak can be classified into one of 19 different beat types for arrhythmia analysis.

How to Classify R-Peaks

Supported Beat Types

Visual Feedback

R-peaks are color-coded by beat type on the plot:

• Red — Normal beats
• Amber — Bundle branch blocks
• Emerald — Supraventricular beats
• Dark Red — Ventricular beats
• Violet — Escape beats
• Indigo — Paced beats
• Gray — Unknown/unclassified

The R-peaks badge in the Stats panel shows a breakdown of counts by beat type (e.g., "N:245, V:12, A:3").

4.2 Keyboard Shortcuts

Speed up your workflow with keyboard shortcuts for R-peak classification:

4.3 Automatic Peak Detection

CardioAnnotate provides two automatic peak detection algorithms that can be used for any peak type:

Detection Scope

• Full signal: Process the entire recording
• Visible segment: Process only the current zoom window

Options

• Replace existing (in scope): If checked, removes existing peaks of the target type before detection

7.1 Basic ECG Metrics

The Statistics panel automatically computes common ECG metrics based on your peak annotations:

Available Metrics

• Duration: Total signal length in seconds
• Avg RR (ms): Average R-R interval duration (time between consecutive R-peaks)
• HR (bpm): Heart rate calculated from average RR interval (60000 / RR_ms)
• Avg PR (ms): Average P-R interval (from P-peak to next R-peak)
• Avg QT (ms): Average Q-T interval (from Q-wave to T-peak, or R-peak to T-peak if no Q annotations)
• Avg QRS (ms): Average QRS duration (from Q-wave to S-wave if both are annotated, otherwise estimated from R-peak to S-wave)

Badge Counters

The colored badges show total peak counts across all channels:

• Signal: Current processing state (original, resampled, filtered, modified)
• R-peaks: Total R-peaks with breakdown by beat type (e.g., "N:245, V:12, A:3")
• P-peaks: Total P-peaks
• Q-waves: Total Q-waves
• S-waves: Total S-waves
• T-peaks: Total T-peaks
• U-waves: Total U-waves

7.2 Signal Quality Indices (SQI)

Signal quality metrics help assess the reliability of the ECG signal for analysis. These are computed on the currently visible window of the active channel.

7.3 Heart Rate Variability (HRV)

HRV metrics are computed from R-peaks within the current zoom window. The segment range is displayed (e.g., "Segment: 0.0–10.5s").

Time-Domain Metrics

Frequency-Domain Metrics

Computed using Welch's method (Hann window, 50% overlap):

Nonlinear Metrics

Derived from the Poincaré plot of successive NN intervals (RR_n versus RR_n+1) and from the sample entropy of the NN series. A Poincaré plot can be opened in a separate window using the Poincaré plot button; the SD1/SD2 dispersion ellipse, centered at the mean NN, is overlaid on the scatter.

Stationarity (ADF Test)

The Augmented Dickey-Fuller test assesses whether the RR interval series is stationary:

• Stationary (p < 0.05) — RR intervals show stable statistical properties; HRV metrics are reliable
• Non-stationary — RR intervals show trends or drifts; interpret HRV metrics with caution

7.4 RR Error Detection & GP Correction

CardioAnnotate includes advanced RR interval quality control using Gaussian Process (GP) regression for detecting and correcting outliers. This is essential for reliable HRV analysis.

Detection Modes

Gaussian Process Kernels

Choose a GP kernel for RR interval interpolation:

• Rational Quadratic (RQ) — Default; flexible, handles multiple length scales. Best general-purpose choice.
• Matérn 3/2 — Once-differentiable, allows rougher variations
• Matérn 5/2 — Twice-differentiable, smoother than 3/2
• Periodic — For regular heartbeat patterns with periodic structure
• Brownian — For trending RR series (non-stationary)

Default GP Hyperparameters

Kernel defaults use optimized mean values from the Harmonizing Heartbeats RR-correction model. Each kernel applies its variance term, σ², as a scale factor.

Workflow

1. Configure detection parameters (min/max RR, max change α)
2. Select a GP kernel and adjust the GP hyperparameters sliders if needed
3. Click "🧪 Detect RR outliers" to flag implausible intervals
4. Review the flagged count in the display
5. Click "✨ GP-correct flagged RR" to estimate corrected values using GP regression
6. Optionally click "🗑 Remove flagged RR" to delete the R-peaks associated with flagged intervals