Description of ASCII Parameter Files
Most simple ASCII data files used in the SDSS are formatted as
"ASCII parameter files". Examples of this are the endpoints of survey stripes
(with stripe number,
eta,
minimum lambda,
and maximum lambda)
and the list
of stripe segments in SDSS data (listing run, rerun, camcol, field0,
nFields, etc - see this tsChunk.par
example). This file format is described here.
Format ASCII parameter files contain two elements, keyword/value
pairs and tables.
Keyword/value pairs
A line in the file line may contain a keyword/value pair. The first
token is the keyword. The remainder of the line, up to a
comment-delimiting '#' sign, is the value of the keyword. In
the following example, the value '51256' is assigned to the
keyword 'MJD', and the value 'u g r i z' is assigned to the
keyword 'filters':
mjd 51256 # MJD day number of observations
filters u g r i z
Tables
Tables of data are given by first defining a C-like structure
which defines the table format. Then, any lines in the file
whose first token is the name of the structure are considered
to contain the data for a single entry in the table. The
tokens in each line are in the same order as in the
structure. Arrays are contained within '{ }' and array
elements are whitespaced-separated. Lines may be continued
using a backslash (\) as the last character. For example, a
simple weather table containing four different temperatures
stored as an array along with a single pressure, humidity, and
time stamp might look like:
typedef struct {
double mjd;
double humidity;
double pressure;
double temperature[4];
} WEATHER;
WEATHER 52191.300 0.23 75.21 {10.4 10.7 10.6 10.7}
WEATHER 52191.310 0.24 75.26 {10.3 10.6 10.5 10.7}
WEATHER 52191.320 0.23 75.28 {10.2 10.6 10.4 10.5}
WEATHER 52191.330 0.23 75.30 {10.2 10.5 10.3 10.3}
The keyword names (mjd, humidity, etc. in the above example)
are case sensitive (except for the IDL format in which they are not).
The data model defines whether the variable that
describes, for example, the camera column, is camCol, CamCol,
camcol, or CAMCOL.
The name of the structure (WEATHER in the above example) must
be in ALL CAPS in the structure definition, but is
case-insensitive in the table entries.
Standard (allowed) datatypes are:
float | 4-byte floating-point |
double | 8-byte floating-point |
short | 2-byte integers (signed short assumed) |
int | 4-byte integers (signed int assumed) |
enum | enumerated types (as in the C language) |
char[N] | character string (N must be explicitly specified
and must be the sum of '1' plus the length of the longest char string contained in the param file
NOTE: length is ignored in IDL)
|
One dimensional fixed length arrays of the above types are supported.
For example here is a complete param file, mystruct.par:
typedef struct {
float mag[5];
char b[5][20];
double c;
int flags[2];
} MYSTRUCT;
mystruct {17.5 17.546 17.4 16.1 16.0} {the rain in "spain is" wet} 1.24345567 {123123 1231213}
mystruct {17.5 17.446 17.4 16.1 16.0} {the snow in chile "is dry"} 7.24345567 {123123 0}
As mentioned, a backslash (\) may be used as a line continuation
character for long table or header entries.
Note on character string length in tables:
char program[20]; # Identifying name for CCD program.
The length of the string is defined in square brackets after
the variable name. The actual length (20 in this case) is
defined by the data model for the structure or file you are
writing. No 'program' string in the table section of the
corresponding ASCII param file in this example then should
exceed 19 characters (1 extra for the C termination).
Enums
You may also use an enum to define an enumerated data type.
These are similar to C-language enums, in that one lists a
comma-separated list of identifying tags in a multi-line
typedef statement which are internally stored as ints, 0, 1,
2, 3, etc, but which are referenced by the tag for mnemonic
convenience or documentation purposes.
The tags should start
with a letter, and be alphanumeric, like a variable-name in
C. Underscores are permitted in the tag name, i.e. START_RUN,
END_RUN .
By convention enum values (i.e. START,END ) are all-caps and
newlines separate the comma-separated entries in the typedef
definition of the enum.
For example, to track the starting or ending a series of runs in a table,
an enum such as the following can be defined at the top of the param file:
# Entry written at start or end of run
typedef enum {
START,
END
} RUNMARK;
#and a structure and table with the attribute defined using this enum looks like this:
typedef struct {
int run; # Run number
RUNMARK mark; # Entry written at start or end of run.
double mjd; # time of START or END of run
} NEWSTRUCT;
NEWSTRUCT 712 START 51876.1
NEWSTRUCT 712 END 51876.123
NEWSTRUCT 722 START 51878.1
NEWSTRUCT 722 END 51879.123
For this example, each table entry has either START or END for
its RUNMARK field value. The enum definition needs to appear
in the file before a typedef that uses that enumerated type.
Multiple Tables/Structures in a single ASCII file
A given file may contain any number of keyword/value lines and
any number of tables.
Reading and Writing:
Users of param files should find the reading/writing of these files
straightforward and non-ambiguous via a simple script of the users'
design, suited to their own purposes.
Last modified: Tue Jun 20 20:06:25 BST 2006
|