FCS 2.0 File Format: 0. CONVENTIONS The file is assumed to be divided into a stream of 8-bit characters. 1. HEADER 1.0 The file must start with the 10-character-code (IDENTIFIER): "FCS2.0 ", that is "FCS2.0" followed by four spaces. 1.1 There must be at least six 8-character integers following the IDENTIFIER. Integers less than 8-characters must be right-aligned and padded with spaces ' '. They are INTERNALPOINTER1-6 1.2 There may be any number of numbers (of arbitrary) length following the first six. 1.3 INTERNALPOINTERS 1.3.0 INTERNALPOINTER1 points to the character offset where the TEXT section begins. INTERNALPOINTER2 points to the character offset where the TEXT section ends. The length of the TEXT section is therefore INTERNALPOINTER2-INTERNALPOINTER1+1. 1.3.1 INTERNALPOINTER3 points to the character offset where the DATA section begins. INTERNALPOINTER3 > INTERNALPOINTER2. INTERNALPOINTER4 points to the end of the DATA section. The length of the DATA section is INTERNALPOINTER4-INTERNALPOINTER3+1. 1.3.1 INTERNALPOINTER5 and INTERNALPOINTER6 point to the ANALYSIS section; they are normally zero. It is not know for certain how to compute the length of the ANALYSIS section. 2. TEXT 2.0 The first character in the TEXT section, pointed at by INTERNALPOINTER1, is the escape character. All characters in the ASCII chart are valid characters in the TEXT section, except for the escape character. The escape character is either a delimiter when it appears `alone' or, to insert it into the TEXT section, is repeated. 2.1 The text section consists of a number of keyword/information pairs delimited by the escape character. All standard keywords begin with the character '$'. The '$' character is reserved for use exlusively when immediately preceded by the escape character. Standard keywords may not have left-padding. Standard key-information may not have left-padding. It is possible for escaped-sequences to appear throughout the TEXT section so it is not safe to assume that even-escape-sequences are keywords and odd are information. Standard keywords must use ALL CAPITALS. 2.2 REQUIRED KEYWORDS (assume escape character is '\') 2.2.0 PAR Usage "\$PAR\4\" This keyword specifies the number of parameters in the file. It will be represented by the variable, 'n'. Whenever the letter 'n' appears it means some keyword, with a number from 1 to PAR in value. Each appearance of such variable-keywords must be unique. In most cases that keyword must also be extant. 2.2.1 PnR Usage "\$P2R\1024\" This keyword specifies the domain of the data over the second parameter. There must be one PnR keyword for each parameter. The value of this keyword must be an integer. In many cases, if the value of this keyword is not a power-of-2, file-handlers will be unable to open the file. 2.2.2 PnB Usage "\$P3B\16\" This keyword specifies either (A) the number of bits in the binary representation of the data for the third parameter (B) the number of bytes for the text representation of the data for the third parameter. When the value of this keyword is the character '*', the data is represented as white-space-delimited text-numbers. 2.2.3 MODE Usage "\$MODE\L\" This keyword specifies the mode. (L) the data is in LIST mode. It is represented as a list of arbitrary length of vectors, where the first scalar in each vector corresponds to the value of the first paramater, the second the second and so on. (U) the data is in UNCORRELATED mode. It is represented as PAR histograms, where each histogram's length is defined by it's parameter's PnR. The value at each point is the number of data points in the histogram. The order of the histogram is the first parameter, the second parameter and so on. (C) the data is in CORRELATED mode. This is a matrix of values of PAR dimensions, with each side having PnR values. The data is in increasing incrementation, i.e. X1Y1...Z1, X2Y1...Z1, ... , XnY1...Z1, X1Y2...Z1 ... 2.2.4 DATATYPE Usage "\$DATATYPE\A\" This keyword specifies the datatype.(A) The data is in text-format. The text is either whitespace delimited if any PnB keyword's value is '*', or has bytes equal to the PnB. (F) Binary IEEE 32-bit floating-point number. (D) Binary IEEE 64-bit double-floating-point number. These 8-byte structures are assumed to be two contiguous 4-byte `words'. (I) An integer. Integers do not have to have to be byte-aligned, but may be bit-aligned and packed. Packing is discussed under BYTEORD. Integers should be less than 4-bytes. 2.2.5 BYTEORD Usage "\$BYTEORD\3,4,1,2\" This keyword specifies the ordering of bytes in a `word'(?). When a bit-aligned integer is written to disk, it is assumed that it is written as a stream of plain-old-datatype of the type whose length is the minimal power-of-two greater than the bits. For example, given the above BYTEORD and a PnB of 12, we would have the following packing (N.B. the parameter's are 'a','b' and 'c'): 0 1 2 3 123456789012345678901234567890123456 <- position aaaaaaaaaaaabbbbbbbbbbbbcccccccccccc 012345670123456701234567012345670123 <- bit-number 0 1 2 3 4 If the BYTEORD was, instead, 4,3,2,1 then: 0 1 2 3 123456789012345678901234567890123456 <- position aaaabbbbaaaaaaaaccccccccbbbbbbbbcccc 012345670123456701234567012345670123 <- bit-number 1 0 3 2 4 Bit-deconvolution is nontrivial and is usually ignored. 2.2.6 NEXTDATA Usage "\$NEXTDATA\0\" This keyword represents the offset from the beginning of this file in the stream to the beginning of the next file in the stream. Typically it is 0 (no following file), but on occassion it is used. 2.3 OPTIONAL KEYWORDS (non-required keywords required for general conformance) 2.3.0 PnN Usage "\$P5N\FITC\" This keyword represents the name of the fifth parameter, `FITC'. Although it is not a required keyword, many programs will not allow an FCS2.0 file to be opened without it. 2.3.1 PnE Usage "\$P2E\4,4\" Many FCS2.0 files are in `log-space' and this represents the offset followed by the number of decades. The actual computation of the linear values is not defined well-enough in the standard to construct a definate function, but logically we would construct it as follows. If we consider the original (linear) value to be X, then since X could be 0, we add an offset, T and take it's base-10 logarithm: log10(X+T) = Y. We thus solve for X in Y: X = 10^Y - T. Since we are only given the number of decades, D, we compute (along each axis) the width of the decade as being PnR/D. Thus to fully transform a given value X={x1,x2,x3,...,xn} to a linear form, we take each xi such that yi = 10^(xi*D/PiR) - T. 2.3.2 TOT Usage "\$TOT\10000\" The total number of events within the file; for L-mode this is the number of vectors; for U-mode this is the sum of the PnRs; for C-mode this is the product of the PnRs. 2.4 EXTENSION KEYWORDS - any file-handler may generate any given number of non-standard extension keywords. These may be placed anywhere within the TEXT portion, so long as they do not split a given standard keyword-key-information pair up. 3. DATA - should be decoded as per the TEXT section. 4. ANALYSIS - ??? 5. CONFORMANCE - the typical file is a List-mode, Integer-datatype, 16-bit-per-parameter file in either 1,2 or 2,1 ordering. It includes both conformance-enhancing optional-keywords PnE/N. It is not uncommon to see a Uncorrelated; Float-datatype are becoming more common. In general it is a good idea to pad the end of the DATA section with at least 2-characters as many file-handlers will attempt to read one-beyond-the-end in order to capture all the binary data as many times the DATA section is calculated by the file-writer to be length INTERNALPOINTER4-INTERNALPOINTER3 (forgetting the `+1). In addition, most file-handlers will attempt to precalculate the length of the file and open that much data -- whether this is correct or not.