In this article, you learn everything you need to know about the data specifications of the exported OpenSignals acquisition files in the ASCII (.TXT) format.
TXT as CSV Option
This tab-delimited .TXT file provides the same functionality as .CSV files for data export to third-party software.
You can download sample files containing real sensor data in the following article:
biosignalsplux Sensor Sample Signals Samples
Overview of OpenSignals Sensor File
OpenSignals ASCII text files have two parts, namely a Header Section and Data Section.
Header Section: Acquisition Metadata
The header section has 3 header lines, each starting with the pound (#) character, given that it is automatically ignored by ASCII text file loading functions in common scientific computing programming languages (e.g. loadtxt in Python).
The header section begins after the line with the content “# OpenSignals Text File Format” and ends after the line “# EndOfHeader”.
The second line has the metadata stored as a JSON object containing each device’s MAC address as top-level keys as shown in the following example:
# OpenSignals Text File Format
# {"00:07:80:79:6F:DB": {"sensor": ["ECG"], "device name": "00:07:80:79:6F:DB", "column": ["nSeq", "DI", "PORT1_CHN1"], "sync interval": 2, "time": "10:29:43.249", "comments": "", "device connection": "BTH00:07:80:79:6F:DB", "channels": [1], "keywords": "", "convertedValues": 0, "mode": 0, "digital IO": [0, 1], "firmware version": 773, "device": "channeller", "position": 0, "sampling rate": 1000, "label": ["PORT1_CHN1"], "resolution": [16], "date": "2018-7-5", "special": [{}, {}, {}, {}, {}, {}, {}]}}
# EndOfHeaderIn a more human-readable representation, the header content is organised as follows:
For each top-level key, there is a JSON object as value, containing the acquisition settings used for that.
Device Information
| Top-Level Key | Description |
|---|---|
| device | Type of recording device used to collect the data (e.g. biosignalsplux, BITalino (r)evolution) |
| device name | Friendly name manually assigned by the user to the device (default: device’s MAC-address) |
| device connection | Logical device communication (BTH: Bluetooth, BLE: Bluetooth Low Energy) |
| firmware version | Firmware version of the device |
| position | Order in which the block of columns corresponding to a given device appears in each line of the file (0 – First sequence of columns; 1 – Second sequence of columns; etc.), relevant for multi-device acquisitions. |
Acquisition Datetime
| Top-Level Key | Description |
|---|---|
| date | Day, month and year in which the file was recorded |
| time | Time at which the first sample was received by the software |
Acquisition Setup
| Top-Level Key | Description |
|---|---|
| sensor | Array with the type of sensor connected to each analog port (e.g. as selected from the options available in the device configuration panel on OpenSignals) |
| channels | Set of analog inputs selected for acquisition in the recording session that generated this file (last columns of the file) |
| resolution | Sampling resolution of each sensor channel |
| sampling rate | Sampling frequency of each sensor channel |
| column | Meaning of each column (left to right) |
| label | Array with labels manually assigned by the user to each of the analogs channels |
| digital IO | Set of digital channels available in this device: 0 – Input 1 – Output |
| mode | Specifies the acquisition mode in which the device was used: 0 – Regular acquisition; 1 – Multiple synchronized devices; 2 – Started by a triggering signal |
| sync interval | Time interval (in seconds) at which a digital signal is sent by a “pacemaker” thread to a single device (used when the sync mode in on OpenSignals for synchronized data acquisition using multiple devices) |
| special | List of non-standard channels acquired (e.g. SpO2 sensors with I2C interface connected on biosignalsplux hubs). |
Other Parameters
| Top-Level Key | Description |
|---|---|
| convertedValues | Format of the sensor data in the acquisition file: 0 – Raw digital sensor values * 1 – Sensor values listed in their respective physical units * you can find transfer functions to convert raw digital sensor values in the sensor documentation |
| keywords | File key words (optional) |
| comments | Acquisition comments (optional) |
Data Section: Acquisition Sensor Data
Sequence Number (Sample Number)
Regardless of the number of sensors used, OpenSignals files contain a sequence number series (nSeq column array in the header file) that attributes a sample/sequence number to the acquired sensor data:
# OpenSignals Text File Format. Version 1
[...]
"column": ["nSeq", "DI", "ECG"],
[...]
# EndOfHeaderThe sequential series is stored in the first column of the OpenSignals file as highlighted in the following example in bold:
# EndOfHeader
0 0 32647
1 0 32632
2 0 32616
3 0 32608
4 0 32602
5 0 32605
... ... ...Digital I/O States
Some devices, such as BITalino devices and biosignalsplux Hubs have digital input/output (I/0) channels (e.g. accessory ports) that allow you to record manual inputs from PLUX accessories (e.g. trigger buttons) or input/output synchronization signals.
The states of the digital I/O channels are recorded along with the acquired sensor data and stored in the columns in-between the Sequence Numbers and the Sensor Data.
As the number of digital I/O varies between devices, it’s important to consult the column information in the acquisition metadata to identify all available digital I/O channels, as in the following example containing only one Digital I/O channel.
# OpenSignals Text File Format. Version 1
[...]
"column": ["nSeq", "DI", "ECG"],
[...]
# EndOfHeaderThe digital I/O states are stored as follows: 0 -> no input/output signal available; 1 -> input/output signal available.
An example of the recorded states is highlighted in bold below:
# EndOfHeader
0 0 32647
1 0 32632
2 0 32616
3 0 32608
4 1 32602
5 1 32605
... ... ...Sensor Data
Sensor data is stored in the data section after the Sequence Number and Digital I/O states. The number of columns of sensor data matches the number of sensors used during the acquisition.
For instance, a single sensor acquisition using a biosignalsplux ECG results in the following header information:
# OpenSignals Text File Format. Version 1
[...]
"device": "biosignalsplux",
"sensor": ["ECG"],
"column": ["nSeq", "DI", "ECG"],
[...]
# EndOfHeaderThe acquisition results are listed as follows, where the first column represents the sample number (nSeq), the second column the digital I/O-state (DI) and the third-column the acquired ECG sensor values.
# EndOfHeader
0 0 32647
1 0 32632
2 0 32616
3 0 32608
4 0 32602
5 0 32605
... ... ...As previously stated, the number of columns of sensor data matches the number of sensors used during the acquisition. In an example of a multi-sensor acquisition using an ECG and an EMG sensor, the metadata would look as follows:
# OpenSignals Text File Format. Version 1
[...]
"device": "biosignalsplux",
"sensor": ["ECG", "EMG"],
"column": ["nSeq", "DI", "ECG", "EMG"],
[...]
# EndOfHeaderThe data section gains an additional column which lists the acquired sensor data as organised in the column metadata where the ECG data is listed in the penultimate column and the EMG data listed in the last column:
# EndOfHeader
0 0 32647 32672
1 0 32632 32632
2 0 32616 32514
3 0 32608 32539
4 0 32602 32616
5 0 32605 32492
... ... ... ...Raw vs. Converted Sensor Data
OpenSignals is capable of exporting both digital sensor data and sensor data converted into their respective physical units.
Digital sensor data is the result of digitisation of the analog sensor signals which results in sensor values ranging between 0 and 2^n-1 (n: sampling resolution). At a 16-bit resolution, this corresponds to sensor values between 0 and 65.535, while converted signals often have much lower ranges (e.g. -1.5mV to 1.5mV in case of an ECG signal).
Although digital values are often sufficient for further digital processing, these values are unpractical for physiological analysis.
The convertedValues parameter describes whether the presented file content is in raw digital sensor data (0, example on the left digital ECG data) or in the respective physical units (1, example on the right ECG in MV).
# OpenSignals Text File Format.
[...]
"device": "biosignalsplux",
"sensor": ["ECG"],
"column": ["nSeq", "DI", "ECG"],
"convertedValues": 0,
[...]
# EndOfHeader
0 0 32647
1 0 32632
2 0 32616
3 0 32608
4 0 32602
5 0 32605
... ... ...# OpenSignals Text File Format.
[...]
"device": "biosignalsplux",
"sensor": ["ECG"],
"column": ["nSeq", "DI", "ECG"],
"convertedValues": 1,
[...]
# EndOfHeader
0.0 0.0 -0.00544
1.0 0.0 -0.00611
2.0 0.0 -0.00683
3.0 0.0 -0.00719
4.0 0.0 -0.00746
5.0 0.0 -0.00732
... ... ...