Home
Where to Start
News and Updates
Tutorials
Data Products
Data Access
Sky Coverage
Instruments
Data Flow
Algorithms
Glossary
Help and Feedback
Search

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 list of plates (with plate number, tile number, ra center, dec center) and the list of stripe segments (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 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 (for the IDL format they are not case sensitive). The data model defines whether the variable with 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:

char[N]character string of length N (N = length of longest char string to appear in table +1, must be explicitly specified)
float4-byte floating-point
double8-byte floating-point
short2-byte integers (signed short assumed)
int4-byte integers (signed int assumed)
enumenumerated types (as in the C language)

The simple data types supported are: int, short, double, float, and char. For char, you also need to specify the length (the length is ignored in the IDL format).

One dimensional fixed length arrays of the above types are supported.

For example here is a complete .par file:
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 charater 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 number 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.

For example, if one wants to keep track of when one is starting or ending a series of runs in a table, you can define an enum such as the following at the top of the table:

# 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
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 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: Thu Jun 3 16:34:14 CDT 2004