Poly5 32 File Format provider
Overview
Reads and writes Poly5 (also known as Poly5/TMS32) files that store multi-channel 32-bit floating point measurement values.The format versions that are supported for reading have one of these file headers:
POLY SAMPLE FILEversion 2.03or
POLY SAMPLE FILE version 2.04
Polybench writes Poly5 files in version 2.03.
Note that Poly5 that stores data in 16-bit sample resolution is another stream provider: "Poly5 16 File Format provider"
Details
Description
Basic features
File extension when stored: .poly5.File extensions that are recognized for reading: .poly5 and .S00.
If the sample stream contains event markers, then the events are stored in a separate .CSV file that generally has the same name as the Poly5 file. You can open this file in a simple text viewer, or in most spreadsheet programs.
The Poly5 file format cannot store signals with a sample rate less than 1 S/s. Sample rates that are not a natural number are truncated to the first integer value less than the set sample rate.
Theoretically, the format can store over 16000 signal channels, and 2 Giga samples per channel.
Storage efficiency is very good, so that this file format is suitable for online recording of large amounts of data, for example for high-resolution EEG measurements.
The recoverability of the Poly5 format is quite good; in cases of accidental deletion or broken indices of storage systems, Poly5 files have a good chance to be recovered. Please contact us if you are facing such a challenge.
Format specification
In the past, both TMSI International B.V. and Applied Biosignals GmbH have changed the original standard slightly in order to better support modern measurement systems. This documentation specifies the format as it is used to store data in Polybench.General file structure
- File header
- Descriptors for each signal channel
- One or more Sample Data Blocks (each block contains a certain number of sample periods; each sample period contains one sample value for each channel).
File header
(sizes is bytes)
Offset Size Data type Notes Description
---------|---|-----------|-------|--------------------------------------
0 0x00 31 Text ID File identifier:
'POLY SAMPLE FILEversion 2.03
+CR(13)+LF(10)+EOF(26)'
31 0x1F 2 Integer 203 Version number; must match the
number in the identifier
(203 or 0xCB)
33 0x21 81 PascalStr Measurement short name with
readible start date and time
114 0x72 2 signed int Sampling rate in Samples/sec
116 0x74 2 signed int SR Storage rate (in Polybench equal
to 'Sample frequency')
118 0x76 1 zero Storage type (0=Hz; 1=Hz-1).
Always 0 in Polybench
119 0x77 2 signed int NS Number of signal channels times 2
121 0x79 4 signed int NP Total number of sample periods
125 0x7D 4 zero Reserved for extension of previous
field to 8 bytes
129 0x81 14 DosTime MS Start date and time of the measurement
143 0x8F 4 signed int NB Number of Sample Data Blocks
147 0x93 2 unsigned PB Sample periods per Sample Data Block
(multiple of 16)
149 0x95 2 unsigned SD Size of sample data in one Block in
bytes; header not included
151 0x97 2 zero Delta compression flag
(not used; is zero)
153 0x99 64 Reserved (Filled with zero)
Notes:
- Duration of measurement in seconds = NP/SR
- NS is twice the number of visible channels, because in order to store 32-bit values, for each value two 16-bit channels are used
- NB = NP/PB rounded upwards to a whole number of blocks
- SD = PB * NS * 2
- The recommended value for SD is 8192 bytes
- The sampling rate is equal for all signal channels
Channel descriptor for one 16-bit channel
(sizes is bytes)
Offset Size Data type Notes Description
-------|---|-----------|-------|----------------------------------
N+0 41 PascalStr SN Channel name
N+41 4 zero Reserved (in Polybench zero)
N+45 11 PascalStr UN Unit name (for example 'uV')
N+56 4 float UL Unit low (in Polybwench 0)
N+60 4 float UH Unit high (in Polybench 1000)
N+64 4 float AL ADC low (in Polybwench 0)
N+68 4 float AH ADC high (in Polybench 1000)
N+72 2 SI Index in channel list
N+74 2 zero Cache offset (in Polybench zero)
N+76 60 Reserved (in Polybench zero)
Notes:
- N = Byte offset of this description within sample file = 217 + SI*136
- SI = Zero bases signal index: 0 for first signal description; 1 for second; … (NS-1) for last signal
Because a signal stored as a 32-bit floating point value uses two 16-bit channels, there are also two signal descriptions for such a signal. The 'Unit name', 'Unit low', 'Unit high', 'ADC low' and 'ADC high' fields in these two signal descriptions are filled with the same info. SI is incremented for each half-description.
To recognise 32-bit floating point signals in stead of 16-bit integer signal values, for a 32-bit floating point signal SN (signal name) is preceded by the text '(Lo) ' for the first description and by '(Hi) ' for the second.
Although Poly5 supports mixing of 32-bit floating point signals with 16-bit integer signals, Polybench only writes 32-bit floating point values.
For these floating point values, unit high and low and ADC high and low are omitted.
Layout of a Sample Data Block
(sizes is bytes)
Offset Size Data type Notes Description
-------|---|-----------|-------|----------------------------------
N+0 4 signed int PI Sample period index
N+4 4 zero Reserved for extension of
previous field to 8 bytes
N+8 14 DosTime BT Time of first sample in this block
N+22 64 zero Reserved
N+86 SD data Sample data, divided into
sample periods
Notes:
- N = Byte offset of this data block within sample file = 217 + NS*136 + BI*(86+SD)
- PI = BI * PB
- BI = Zero bases block index: 0 for first sample data block; 1 for second; ... (NB-1) for last block
- according to the original standard, BT (block time) = MS (start time of measurement) incremented with (PI/SR) in seconds. Polybench in stead writes the same date/time that is written in the file header. This makes it easier to find data blocks of one file in case of recovery scenarios; more over, Polybench does not support variable sample timing, so exact timing information per block will not be used anyway.
Special data types
PascalStr (used for 'Measurement name', 'Channel name' and 'Unit name') is a so called Pascal type string (as used in the ancient Pascal programming language). The first byte is the length of the text and from the second byte it is filled with characters of the text itself. Originally, the format has used ASCII-characters, but Polybench writes UTF-8 texts, so that also non-Western languages can be used for texts.
The DosTime type consists of 7 integers:
(sizes is bytes)
Offset Size Data type Notes Description
-------|---|-----------|--------|----------------------------------
0 2 integer Year 0..9999
2 2 integer Month 1= January .. 12=December
4 2 integer Day 1..31
6 2 integer Day/Week 0=Sunday .. 6=Saturday
8 2 integer Hour 0..23
10 2 integer Minute 0..59
12 2 integer Second 0..59
Poly5 history
The Poly4 and Poly5 file formats were designed in the late 1980s in a cooperation of the University of Groningen, Amsterdam Medical Center and the company Inspector Research Systems BV. The format was initially used by the data analysis software Poly.In the late 1990s, the company TMS International BV (TMSi) adapted the format for 32-bit computers and named the format Poly5/TMS32. It was used by their software PortiLab.
Then, mid 2000s, the company Applied Biosignals GmbH adapted the 32-bit variant of the format for use in Polybench. This variant has later also been used by TMS International BV.