PMI Data File Format

This file documents the data file format used in V2.0 of the PMI toolbox. Because it includes details about the experimental geometry such as source and detector positions, this is the preferred format for archiving instrument data.

The general format of the data file consists of two parts: a text header followed by the binary data (see Figure 1 for an example). The text header is parsed line by line. Each line contains a single keyword=value pair. Blank lines are ignored. Comments are introduced by the "%" character and continue to the end of the current line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Data generated by the WhizBang CW Imager
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

DetPos(1) = [  10  10   0 ]        % Four detectors
DetPos(2) = [  10 -10   0 ]
DetPos(3) = [ -10 -10   0 ]
DetPos(4) = [ -10  10   0 ]

SrcPos(1) = [   0   0   0 ]       % One Source

Lambda(1) = 690     % Two wavelengths
Lambda(2) = 830

Frequency = 0

DataPrecision = 'unsigned short'; % 16-bit data
DataType(1)   = { 'Amplitude' };  % data is an amplitude

% Each frame of binary data has eight measurements
Meas(1) = [ 1 1 1 ]
Meas(2) = [ 1 2 1 ]
Meas(3) = [ 1 3 1 ]
Meas(4) = [ 1 4 1 ]
Meas(5) = [ 1 1 2 ]
Meas(6) = [ 1 2 2 ]
Meas(7) = [ 1 3 2 ]
Meas(8) = [ 1 4 2 ]

% Begin experimental data, must contain an integer
%  number of frames of data
BeginData

1. Text Keywords

There are a number of keywords that define the imager parameters and the experimental geometry. See Table 1 for a complete list of keywords. PMI structured data files are read into the PMI toolbox using the Matlab function readPMIData(). This function returns a PMI structure initialized using the information in the text header and a matrix containing the data in the binary portion. Most (but, unfortunately, not all) the keywords were selected to have the same name and meaning as the fields within the PMI structure.

2. Imaging Parameters

Each of the imaging keywords (defined below) require an index number as part of the keyword declaration (e.g., SrcPos(1) declares the location of source one). If there is exactly one possible value, the index may be left off (SrcPos) and a value of `1' will implicitly be used. Imaging parameters may be declared in any order, as long as they are defined before being used in a measurement. If an index is used more than once, the last declaration seen by the parser will be used. If an index is not used, the behavior of the parser is undefined.

Keywords that are not applicable to a specific imager should not be specified in the header. There are no default values; fields not mentioned in the header are left undefined.

2.1. Fiber Locations

The SrcPos and DetPos keywords define the position of the source and detector optodes respectively. Their argument is the position of the optode (including the surrounding square brackets; the separating commas are optional). For example,

SrcPos(1) = [ 0, 0, 0 ]

2.2. Imager configuration

The ModFreq keyword defines the source modulation frequency for frequency-domain imaging. Its value should be given in Megahertz.

The ExcitationWavelength and EmissionWavelength keywords define the wavelength of the light used for fluorescence imaging. Their value should be given in nanometers. Lambda is used for non-fluorescence image. Currently, Lambda and ExcitationWavelength are completely equivalent. This could change in the future, though, so please use whichever keyword is appropriate for your specific application (fluorescence or non-fluorescence imaging).

The keywords TimeDelay, TimeGateWidth, and CorrelationTime are used with time-domain imagers. Their values should be specified in seconds. TimeDelay specifies the electronic delay introduced between the source pulse and the start of data collection. TimeGateWidth specifies either the gate width of a gated time-domain imager or the bin width of a photon counting system. CorrelationTime is the correlation time for systems that return that information.

2.3. Other Configuration Parameters

The DataType keyword is covered below.

The final imaging parameter, ImagerOption, is special. The argument to ImagerOption is a text string enclosed in single quotes and surrounded by curly brackets "{}". ImagerOption is stored in the PMI structure as a text string—no attempt is made to assign any special meaning to the argument. The intended use of ImagerOption is two-fold. First, it provides a stop-gap means to record essential imager data until the PMI toolbox can be extended with the appropriate fields. Second, it provides a means for the imager to include information that is important enough to be worth record, but will not be used to calculate the forward problem (e.g., sampling rate for time-course data).

3. Measurement Lists

The measurement list holds the mapping between the individual data elements and the various imaging parameters (Section 2). Every data element must have a corresponding Meas declaration. While measurements and imager option may be interleaved, we recommend placing measurements at the end of the file (after the imager parameters) for the sake of clarity.

Each measurement is declared using the Meas keyword; its argument is a list of indices into the imager parameters, surrounded by square brackets, e.g.

Meas(3) = [ 1 3 5 ]

While the do not need to be defined in order, there must not be any gaps in the final list of measurements. That is, if Meas(10) is declared in the file, measurements Meas(1) through Meas(9) must also be declared somewhere in the file. The behavior of the toolbox when presented with an incomplete measurement list is undefined.

The order of the fields is fixed (see Table 2). After reading the entire text header, the parser pads out the given measurements into a full measurement list. Undeclared fields are assigned a value of `0'. Fields that take a single value are implicitly set to `1' and should not be explicitly declared inside a Meas statement.

4. Data Parameters

There are three parameters that define the formatting of the data in the binary portion of the file. The first, DataPrecision, specifies the binary format of the data. It's value is any of the precision strings understood by Matlab (for example `float32'; type help fread to get a complete list of precision strings). All measurements are assumed to have the same precision. The default data precision is `float32', which corresponds to C's built-in ``float'' data type.

The second data parameter keyword is DataType which gives the semantic content of the data. That is to say, DataType tells the toolbox what meaning should be assigned to data as it is read in. Similar to ImagerOption, DataType is followed by an index in parenthesis and its argument is enclosed in single quotes, surrounded by a pair of curly brackets. This option is not yet implemented by the toolbox. DataType does not have a default value. Possible arguments to DataType are given in Table 3.

The final keyword is BeginData. This keyword takes no arguments and signals the parser that it has reached the end of the text header. The data portion begins immediately after the closing newline.

5. Binary Data

Data is stored in the binary portion of the file in one or more frames. A frame is defined as a complete set of measurements, as specified using Meas. The size of each data element is given by DataPrecision. Frames are read sequentially; the data portion of the file must contain an integer number of data frames. The data portion ends when the file ends.