pyHL7 aECG — HL7 Annotated ECG Export

A small Python module that exports an ECG recording to the HL7 v3 / FDA Annotated ECG (aECG) XML format — the format used to submit digital ECG data to the FDA in clinical trials.

Overview

You build an ECG object, load one or more of the 12 standard leads with their sample values, set the time and amplitude resolution, and call exportHL7aECGTemplate(). It writes a schema‑shaped aECG XML file containing:

• an AnnotatedECG root coded CPT‑4 93000 ("Electrocardiogram");
• trial / subject / timepoint metadata (clinical trial, trial subject, demographics, relative timepoint, device manufacturer and model);
• a sequenceSet with a GLIST_TS time sequence and an SLIST_PQ waveform sequence (origin, scale, and the digits string).

On export the waveform is converted from mV to µV and divided by the amplitude resolution, because the aECG digits field carries integer counts that are multiplied back by scale.

Classes

Example

example.py fills lead I with a sample waveform, sets a 20 ms time resolution (50 Hz) and a 0.05 mV amplitude resolution, and writes output/ecg.xml:

The example lead‑I waveform that gets exported.

import ecg, numpy as np

e = ecg.ECG()
lead = e.getLead("I")
lead.setAmplitudValues(volt, "mV")   # volt: np.array of samples
lead.setTimeResolution(20)           # ms  -> 50 Hz
lead.setAmplitudResolution(0.05)     # mV
e.exportHL7aECGTemplate("output/ecg.xml", "I")

The output is HL7 v3 aECG, e.g. the waveform block:

<sequence>
  <code code="MDC_ECG_LEAD_I" codeSystem="2.16.840.1.113883.6.24" .../>
  <value xsi:type="SLIST_PQ">
    <origin value="0.000" unit="uV"/>
    <scale value="50.0" unit="uV"/>
    <digits>9 19 19 19 ...</digits>
  </value>
</sequence>

Notes

• The XML is assembled by string templating, not validated against the aECG schema — run the output through an aECG validator before relying on it.
• One lead per export call; the ID / time / subject / device fields default to the sample values baked into ECG.__init__ and should be set for real data.
• Amplitude values are mutated in place during export — pass a copy to keep the originals.