Tutorial 2 EDF Annotation Translator - nsrr/edf-editor-translator GitHub Wiki

Annotation files contain information about scored events during a sleep study. Each polysomnography recording vendor uses a different file format for annotation files. Also, each sleep laboratory employs its own event names for those events. For example, an obstructive apnea sleep event can be called as obstructive apnea, OA, or obstructive apnea event. This tool aims at converting annotation files from vendor-specific formats to a standardized XML format and from lab-specific event names to concepts in NSRR Common Data Dictionary (CDD) developed as part of the NSRR project. CDD is an extension of the Sleep Domain Ontology (SDO) which was developed as part of the Physiomimi project.

This Annotation translator supports annotation files from four vendors:

• Compumedics
• Embla
• Respironics
• Sandman

• All operating systems are supported.
• For source code and compiled version: Java Runtime Environment (JRE) 1.7

1. Kinds of Apache Commons: (http://commons.apache.org/proper/commons-io/)

• commons-cli-1.2.jar
• commons-io-2.4.jar

2. Kinds of jgoodies: (http://www.jgoodies.com/downloads/libraries/)

• jgoodies-animation-1.4.3.jar
• jgoodies-binding-2.10.0.jar
• jgoodies-common-1.7.0.jar
• jgoodies-forms-1.7.2.jar
• jgoodies-looks-2.5.3.jar:
• jgoodies-validation-2.5.0.jar

3. javahelp-2.0.05.jar: (https://javahelp.java.net/)
4. xercesImpl.jar: Download Xerces2 Java from http://xerces.apache.org/mirrors.cgi#binary
5. miglayout-4.0.jar: Download from http://www.java2s.com/Code/Jar/m/miglayout.htm
6. xml-apis-1.4.01.jar: Download from http://mvnrepository.com/artifact/xml-apis/xml-apis/1.4.01

Canonical Data Dictionary (CDD) helps resolve semantic heterogeneity in signal data annotations provided by different vendors. Sleep data annotations are classified into event groups such as respiratory, staging, arousal, cardiac and limb movement. However, the semantics of these terms are different across vendors. For example Embla classifies the staging events as SLEEP-S0, SLEEP-S1, SLEEP-S2, SLEEP-S3, SLEEP-S4, SLEEP-REM, and SLEEP-UNSCORED, whereas Compumedics classifes these events as 0-6 sleep stages, '5' represents Rapid Eye Movement, '6' represents time spent in movement

The annotation translator tool provides mapping files to configure mapping of vendor-specific events to the CDD terminology. Compumedics and Embla vendor mappings to CDD are shown below.

Compumedics Event Mappings to CDD

Embla Event Mappings to CDD

The original XML files exported from different vendor software are translated to a standarized XML based annotation file with CDD terminology. For instance, the desaturation event of Embla, Compumedics and translated XML are shown below to demonstrate the translation process.

Compumedics to CDD-translated XML

Before Translation:

<ScoredEvent>
	<LowestSpO2>92</LowestSpO2>
	<Desaturation>6</Desaturation>
	<Name>SpO2 desaturation</Name>
	<Start>6741</Start>
	<Duration>19</Duration>
	<Input>SAO2</Input>
</ScoredEvent>

After Translation:

<ScoredEvent>
  <EventType>Respiratory|Respiratory</EventType>
  <EventConcept>SpO2 desaturation|SpO2 desaturation</EventConcept>
  <Start>6741</Start>
  <Duration>19</Duration>
  <SignalLocation>SaO2</SignalLocation>
  <SpO2Nadir>92</SpO2Nadir>
  <SpO2Baseline>98.0</SpO2Baseline>
</ScoredEvent>

Embla to CDD-translated XML

Before Translation:

<Event>
	<Type dt="string">DESAT</Type>
	<Location dt="string">SpO2.Averaged-Probe</Location>
	<StartTime dt="string">2010-01-26T23:48:05.551671</StartTime>
	<StopTime dt="string">2010-01-26T23:48:24.218338</StopTime>
	<Parameters>
		<Parameter>
			<Key dt="string">Sub Classification History</Key>
			<Value>
				<Parameters>
					<Parameter>
						<Key dt="string">1</Key>
						<Value>
							<Parameters>
								<Parameter>
									<Key dt="string">is manual</Key>
									<Value dt="boolean">0</Value>
								</Parameter>
								<Parameter>
									<Key dt="string">supertype</Key>
									<Value dt="string">DESAT</Value>
								</Parameter>
								<Parameter>
									<Key dt="string">type</Key>
									<Value dt="string">DESAT</Value>
								</Parameter>
							</Parameters>
						</Value>
					</Parameter>
				</Parameters>
			</Value>
		</Parameter>
		<Parameter>
			<Key dt="string">UserVariables</Key>
			<Value>
				<Parameters>
					<Parameter>
						<Key dt="string">Begin of desat</Key>
						<Value dt="r8">98</Value>
					</Parameter>
					<Parameter>
						<Key dt="string">End of desat</Key>
						<Value dt="r8">94</Value>
					</Parameter>
					<Parameter>
						<Key dt="string">SpO2 drop</Key>
						<Value dt="r8">4</Value>
					</Parameter>
				</Parameters>
			</Value>
		</Parameter>
	</Parameters>
</Event>

After Translation:

<ScoredEvent>
  <EventType>Respiratory|Respiratory</EventType>
  <EventConcept>SpO2 desaturation|DESAT</EventConcept>
  <Start>8286.5</Start>
  <Duration>18.7</Duration>
  <SignalLocation>SpO2</SignalLocation>
  <SpO2Nadir>94</SpO2Nadir>
  <SpO2Baseline>98</SpO2Baseline>
</ScoredEvent>

EDF-Translator has been integrated as a part of EDF-Editor, and it can be invoked inside the EDF-Editor.

Access EDF-Translator:

1. Open the EDF-Editor first.
2. Click the Tools on the top menu, point to the arrow next to 'EDF Annotation Translator' and then click to start the EDF-Translator up.

Launch EDF Annotation Translator Tool

Users specify where the vendor-specific mapping file, and EDF, Annotation, Stage (only for Respironics) files locate at; give where the translated files should be put; and design how output filename looks like.

1. All settings start with vendor selection. Users need to select one out of four vendors (including Embla, Compumedics, Respironics, Sandman) from the dropdown list.

Selection of Vendor Format

2. Having chosen a vendor, all other fields are enabled to fill with. Users are asked to specify the location of vendor-specific mapping file, and input directories of EDF, Annotation and Stage files, respecively. All EDF files contained in the chosen folder and its nested sub-folders will be shown on the box of 'List of EDF files'. Note that, the EDF-Translator assumes that the Annotation and Stage files corresponding to EDF files should have the exact same file name and sub-folder path as EDF files but different extensions. Note that the field of 'input-directory of Stage files' is enabled only if user select Respironics as vendor from the dropdown list.

Selection of Input Parameters

3. Users then are asked to specify the output-directory of translated files and to design the name pattern for the translated files. Users may include Vender name, Data and Time as suggested into part of translated filename; users may also give any name of their interest. An example filename will shown immediately below the name design panel. Please do not include '[EdfName]', '[Vendor]', '[Date]' and '[Time]' into filename since they are reserved by EDF-Translator.

4. Next, users need to select a sample of EDF files from the box of 'List of EDF files' for translation. Users can select either individual or multiple EDF files. Ctrl-A is a keyboard shortcut that selects all EDF files in the box.

5. Click the button 'Convert' to conduct EDF translation. This process may take some times when the number of EDF files become huge. A list of the translated/generated files will be shown in the box of 'List of Output files'. Any successful and failed message with regard to parameter settings and EDF translation will be shown in the 'Quick Log Viewer' at the bottom

Translation Output

1. Users can examine the translated file by clicking filename of the interest in the box of 'List of Output files'. The content of translated file will be shown in a separate tab

View Translated Files

2. A complete log can be read in the tab of 'Complete Log Viewer' which records the running events of EDF-Translator in the history

Log Viewer

If you have any problem about the tool or would like to contribute to the tool, please contact us by email: [email protected].