Open eXtensible Data Format

The fundamental motivation behind OpenXDF is to provide a standard, open, and easily extensible data format to be used by the medical community to share time-series data. To accomplish this, OpenXDF couples a header file with one or more raw data files where the header file describes the format of the raw data file(s) using a standardized syntax. This added layer of abstraction allows OpenXDF to be used with most existing polygraph formats (§2.2.3) and allows multiple formats to coexist and act as one data file. The OpenXDF header can also be used to exchange common information ancillary to the raw data file(s) such as scoring results, patient information, annotations, and display montages with or without a raw data file.

The OpenXDF header file must be a valid XML document declared, with the XML version and text encoding scheme specified as follows:

<?xml version="1.0" encoding="utf-8" ?>

</OpenXDF>

The header file, in its most basic form, will provide the information necessary to find and interpret the raw data file(s). The exact contents of the header file required to conform to the OpenXDF standard are discussed in the next section. Beyond the required contents, the header may contain any information the implementation requires.

2.0 – Acceptance Standards

The acceptance standards are organized into levels which allow implementers to include or exclude standard information from their format without risking total incompatibility. The acceptance levels are further divided into System, Header, and Miscellaneous Requirements sections. The system requirements define the responsibilities of a software system that claims compatibility with a format at the same level, and the header requirements define the minimum information required in the OpenXDF header for each level.

Each acceptance level builds on the previous level. Specifications from the previous level are shaded with a gray background while additions are highlighted with a blue border.

Acceptance levels may be branched when the requirements of a new level do not build on the requirements of the previous level. For instance, if Level X and Level Y build on Level 2, but neither X nor Y builds on the other, then X and Y would be Level 3 branches (Level 3.X and Level 3.Y).

Branches are named using the level number followed by a period and the branch name. For instance, “Level 3.PSG” is the polysomnogram branch of Acceptance Level 3, whereas “Level 3.EEG” (not yet specified) would be the EEG branch of Acceptance Level 3.

The purpose of branches is to keep the OpenXDF specification from becoming monolithic. Every discipline has its own requirements, and such requirements do not always include the requirements of another discipline. Therefore, it does not make sense for EEG requirements to build on the requirements for PSG, etc.

Changes from the version immediately preceding the current version are highlighted in red. Features shaded with diagonal hashing will be removed in the next version.

In the header structure tables, Required, Optional and interval notation are used to express the cardinality of a given tag. A required tag must occur exactly once in its scope, and an optional tag may occur at most once in its scope. Interval notation is used to express all other possible cardinalities.

Tag names that begin with the “@” symbol are attributes of their parent tag. For instance, consider the tag “Foo” and its child “@Bar.” “@Bar” is an attribute of “Foo” as shown below:

2.1 – Acceptance Level 0

Acceptance level 0 indicates that, regardless of a format’s underlying level of conformance with the OpenXDF standard, it is not compatible with any software system except the one for which it was designed.

Acceptance level 0 allows for proprietary implementations of OpenXDF. It is reasonable to assume that Company A may want their software to record EEG using OpenXDF, but may not want their records to be compatible with Company B’s software. In this scenario, Company A may encrypt its files in some proprietary manner to keep Company B from using compatibility with Company A as a selling point. Company A can then easily offer an export feature that produces an unencrypted copy of a given recording that is compatible with any OpenXDF compliant system, thus allowing its users to remain compatible with the EEG community at large.

2.2 – Acceptance Level 1

Acceptance level 1 is the most basic implementation of an OpenXDF compatible format.

2.2.1 – System Requirements

An OpenXDF system implementation must employ a XML parser that adheres to the XML version 1.0 standards (http://www.w3c.org/xml). The two most important goals of this requirement are to make sure that a system claiming compatibility is capable of parsing any valid XML document and that the system is capable of decoding all of the text encoding schemes specified in the XML standard. Text encoding schemes such as the 8-bit and 16-bit varieties of the Unicode Transformation Format (UTF-8 and UTF-16) allow OpenXDF header information to be multilingual (header XML tags must always be in English as specified in this document). The reference implementations provided with this specification use parsers based on the Simple API for XML (SAX) and were developed with Microsoft’s XML Core Services (MSXML) 4.0.

Systems must be backward and forward compatible with all versions of the OpenXDF specification.

Systems must not rely on the tag order shown in this document, sibling tags can appear in any order in an OpenXDF header. Systems may only rely on the specified hierarchy.

Unless otherwise specified, a system may rely on the order of list elements, unless the order is specifically indicated (timestamp, epoch number, etc.). For instance, if “A1” precedes “C3” in the source list of an OpenXDF header, then “A1” precedes “C3” in the raw data file.

Systems must not rely on case-sensitivity. Unless otherwise specified in this document, all values are case-insensitive.

When implementing a montage interface, an OpenXDF system is required to provide the user with a ground source. This implied ground source shall always be referred to as “GND” in the system and shall not be included in the source list.

Systems may ignore raw data tags (FileData, SourceData, SessionData, etc.) as their contents are only relevant to the system for which the OpenXDF format was designed.

2.2.2 – Header Requirements

For level 1 acceptance, an OpenXDF header is required to have the following minimal structure (Refer to §4.1):

OpenXDF
Tag	Type	Presence	Description
Version	String	Optional	Proprietary format version string. This string shall not be used to indicate the inclusion/exclusion of standard information, but may be used to control proprietary information.
DataFiles	Data File List	Optional	Defines a list of raw data files referenced by the header.

DataFile		[ 0 … +inf. )
Tag	Type	Presence	Description
File	String	Required	The raw data file name. Because OpenXDF is not limited to any one operating system, partially- or fully-qualified path names shall not be used. To avoid incompatible path naming conventions, the header and raw data file(s) shall be kept in the same path and only the raw data file name(s) shall be specified.
FrameLength	Frame Length Type	Required	Frame length in seconds (§2.2.3).
FileData	Base 64 Encoded Binary	Optional	Proprietary file data.
Sources	Source List	Optional	Defines a list of sources in the raw data file.
Sessions	Session List	Required	Defines a list of recording sessions in the raw data file. At least one session must be specified. Sessions shall be unique across all data files specified in the header; no two sessions shall be allowed to overlap.

Source		[ 0 … +inf. )
Tag	Type	Presence	Description
Ignore	Boolean	Optional	Signifies whether or not the source shall be excluded. Absence of the tag implies that the source will be included. If a source is to be ignored, SampleName, SampleWidth, and SampleFrequency must be specified so that a system can calculate how much data to ignore, and all other source tags may be omitted. If the source to be ignored is not a signal source (such as an EDF annotation channel), the sample frequency and sample width can be arbitrary as long as their product equals the number of bytes to ignore.
SourceName	String	Required	A name that uniquely identifies this source.
Signed	Boolean	Optional	Indicates whether or not a sample is stored as a signed or unsigned number. This value is true by default.
SampleWidth	Sample Width Type	Required	Sample size in bytes.
SampleFrequency	Sample Frequency Type	Required	The frequency, in Hz, at which this source was sampled.
DigitalMax	Floating-point (double precision)	Required	Maximum value of the digital signal.
DigitalMin	Floating-point (double precision)	Required	Minimum value of the digital signal.
PhysicalMax	Floating-point (double precision)	Required	Maximum value of the physical signal.
PhysicalMin	Floating-point (double precision)	Required	Minimum value of the physical signal.
Calibration	Floating-point (double precision)	Optional	Specifies the amplifier’s calibration scale factor for this signal. Consider an amplifier with a DC input that returns 0.01V increments represented by signed, 8-bit samples. The full range of the input is: [-128, 127] ~ [-1.28V, 1.27V]. Now consider a CPAP machine that outputs 0V to 1V representing 0cmH2O, 20cmH2O. To properly display the data, the OpenXDF source would have a physical min and max of 0 and 20 respectively, and the digital min and max would be 0 and 100 respectively. The calibration factor specified here would be 0.01, and would be used to convert between a digital value in the data file and a voltage.
Unit	Floating-point (double precision)	Optional	Specifies the unit of the physical signal as a factor of Volts. For instance, millivolts would be expressed as 0.001. This value has no meaning for non-Voltage signals (SpO₂ stored as a percentage, for instance). This value is 1.0 by default.
SourceData	Base 64 Encoded Binary	Optional	Proprietary source data.

Session		[ 1 … +inf. )
Tag	Type	Presence	Description
Offset	Unsigned Long Integer