Parameter Files

Parameter files are ASCII files with the extension .par. They are extensively used in SDSS data for storing moderate amounts of data in a form that is both human and machine readable. Parameter files are sometimes informally called ‘Yanny’ files, or, more rarely, ‘FTCL’ files.

Originally, they were designed to be written and read by the FTCL package, dervish. More recently however, in SDSS software, they are most commonly read with IDL and Python. We give examples of usage in these two languages further down this page.

Formal Description

mjd 54321 # MJD of the observation.

Keyword-Value Pairs

A line may contain a keyword-value pair. The first word is the key, and the remainder of the line is the value (excluding comments). For example:

mjd 54321 # MJD of the observation.
filters u g r i z # List of filters.

The keys are ‘mjd’ and ‘filters’ and the values are ‘54321’ and ‘u g r i z’. Note that no further processing is done to the values. They are treated as literal strings.

In at least some software packages, the set of keyword-value pairs is called the ‘header’, analogous to a FITS file header.

Enumerations

Enumerations are similar to the enum type in C. They can be used to limit the values a variable in a table may have. Note that in software implementations, enums are not converted to integers, but retain their string values. The definition of an enum is essentially identical to the C definition:

typedef enum {
    FAILURE,
    INCOMPLETE,
    SUCCESS
} STATUS;

Enumeration values (above, FAILURE, INCOMPLETE, SUCCESS) should be all-caps, and newlines should separate the comma-separated entries in the typedef definition of the enum.

Tables

Tables, also called ‘structures’, are the main component of parameter files. They are used to define subsequent data lines (see below). Table definitions are similar to struct definitions in C. For example:

typedef struct {
    float mag[5];
    char b[5][20];
    double c;
    int flags[2];
    STATUS state;
} MYSTRUCT;

The name of the table should be in all capitals. The underscore character and digits (0-9) are also permitted. The values defined in the definition are the columns of the table.
Variables defined in tables may have the following types.

All types can be arrays. Arrays are declared by adding the length of the array in square brackets after the name of the variable. One exception to this is for character arrays. In the example above, the char variable ‘b’ is an array of 5 strings of length 20, not an array of 20 strings of length 5. This may seem counter-intuitive at first, but this is exactly how arrays of strings are declared in C. Multi-dimensional arrays are not supported.
Strings may also be declared with an empty length, for example, char comment[];. This is not considered good practice, but most software packages support this.

A parameter file may have multiple table definitions, as long as they have different names.

Data

Data that is defined by a table is stored on a single line (a row) starting with the name of the table. Continuing the example above, a data line would look like:

There are several things to note here:

• The first word on the line is the name of the table. Since a parameter file may have multiple table definitions, this is absolutely essential. It is good practice to have the name of the table in all capitals to match the table name exactly, though in software implementations, lower-case table names are also interpreted as belonging to the correct table.
• Data is separated by white space. Thus, if a string contains white space, it must enclosed in double quotes. However, if a string does not contain white space, quotes are not necessary. Empty strings are allowed and must be designated with empty double quotes (“”).
• Arrays are delimited by curly braces ({}).
• Long data lines may be continued onto a new line by adding a backlash character (\) to the preceding line. Note, however, that most software packages do not write long lines onto multiple lines, though they can read them.

Deprecated Features

The following features may exist in very old parameter files. Some software packages support them, but they should never be used in practice.

• Arrays may be declared with angle brackets (< >) rather than square brackets
• Empty double braces ({{}}) can stand for empty double quotes, that is, an empty string

Software

IDL

Parameter files may be read and written by routines in the yanny directory of the idlutils package. The function yanny_readone() is most commonly used, but should be used with caution as it is intended for files with only one table definition. Here is a simple example of the use of yanny_readone():

IDL> a= yanny_readone('sdReport-52059.par', hdr=hdr)
IDL> HELP, a, /STRUCTURE

Keywords may be retrieved from the header with yanny_par():

IDL> PRINT, yanny_par(hdr,'equinox')

More complicated parameter files can be read with yanny_read, but this requires some knowledge of IDL pointers:

IDL> yanny_read, 'sdReport-52059.par', a, hdr=hdr
IDL> HELP, *a[0], /STRUCTURE
IDL> HELP, *a[1], /STRUCTURE

The MJDs in the first structure can be printed with

IDL> PRINT, (*a[0]).mjd

Python

Parameter files may be read and written by methods of the yanny class defined in the yanny module of the pydl package. Recent versions of this class can automatically convert between yanny files and NumPy record arrays.

>>> from pydl.pydlutils.yanny import yanny
>>> par = yanny('sdReport-52059.par')
>>> print(par['SEXP']['mjd'])
>>> print(par['equinox'])

If you prefer to read the file as an astropy Table:

>>> from pydl.pydlutils.yanny import read_table_yanny
>>> table = read_table_yanny('plateHolesSorted-090100.par', 'STRUCT1')

where STRUCT1 is the name of the data structure to extract. In this case you can access the header parameters as table.meta.

Historical Note

This description is based on the original parameter file definition.