How to create a frame file

Peter Shawhan
Revised April 9, 2002

LIGOtools includes the C-language frame i/o library written by Benoit Mours et al., which forms the core of the Fr package. The web page for the Fr package contains a link to the documentation for the frame library, plus links to several example C programs which demonstrate calling sequences to read and write frame files. You can compile a C program and link it to the frame library using something like:
gcc myprog.c $LIGOTOOLS/lib/libFrame.a -lm -I$LIGOTOOLS/include -o myprog
(The -lm is needed on Solaris to link in the math library, since the frame library uses the sqrt() function.)

LIGOtools also includes two methods for creating frame files without having to write a C program.

The Fbe package

The Fbe ("frame builder emulation") package, written by Andrea Vicere', is a layer on top of the frame library intended to simplify the user interface. There is a summary on the web page for the Fbe package. The package includes a library of routines that may be called by a C program (as in this this example), but it is probably more common to just use one of the "ready-to-use" command-line utilities: Note that there is no way to specify the name of the file produced by ascii2frame; it chooses a name (following an old naming convention) which includes the current GPS time. You may have to rename the file for your purposes.
The table2frame utility offers an -o option to specify the output filename (but I have not checked to see whether it works).

Here is a usage example, courtesy of Duncan Brown:

Here is what I use to build frames for the inspiral code:

ascii2frame -channel "H2:LSC-AS_Q" -type adc -sampling 16384 -compress 0 \
-frames_per_file 1 -seconds_per_frame 1 -detector LIGO_HANFORD_2K \
-GTimeS 600000000 -i cn_1.40_1.40_20.00.dat

where cn_1.40_1.40_20.00.dat is a single column ascii data file.
Here are two more examples using ascii2frame, courtesy of John Whelan:
PIPESTOCHIFOIFO0000_frames.tclsh
PIPESTOCHIFOIFO1000_frames.tclsh

You can also type "ascii2frame -h" or "table2frame" to get detailed usage information for these two utilities.

The Matlab function mkframe

Sam Finn has supplied a Matlab MEX-file called mkframe which writes out a frame file, given a Matlab structure of the proper form. It is included as part of the Fr package. While working in Matlab, you can get help by typing help mkframe.

Here is an example of a Matlab session which creates a frame file called 'mydata.dat' containing one second of data (2048 samples) of a floating-point channel called 'H2:mychan':

>> dat.channel='H2:mychan';
>> dat.data = sin( 0.1 * (0:1:2047) );
>> dat.type='f';
>> dat.mode='a';
>> mkframe('mydata.dat',dat,'n',1)
Note that the GPS time stamp of the frame file is set to the time at which it was created, and the detector name is set to "NoiseSim".