LIGOtools includes two Matlab functions, frextract() and frgetvect(), which allow you to read time series data from a frame file into a Matlab array. Both are implemented as MEX-files linked to the C-language Frame library (the core of the Fr package) and thus are rather fast. In addition to these functions, there is a higher-level interface called readframedata() which is built on top of frgetvect(); see the documentation in the web page for the FrContrib package.
There is some subtlety about when to use frextract() and when to use frgetvect(). When reading raw ADC data from a frame file which contains a single frame, the two functions take the same two arguments and produce the same results, though frgetvect() will be faster if the file includes the optional table-of-contents structure (which is normally the case for LIGO data) and contains many channels. On the other hand, when reading from a frame file which contains multiple frames, I find frextract() to be more reliable; also, you must use frextract to read "version 5" frames which are currently (summer 2002) being written by LDAS. The frextract() in version v4r53mod of the 'Fr' package can read "processed" (e.g. resampled) data (stored under the FrProcData structure) as well as raw data; for all other versions of the 'Fr' package, you must use frgetvect() to read processed data. frgetvect() is currently the only option for reading "simulated" data (stored under the FrSimData structure).
Besides the time series, each function can optionally return a vector of time values corresponding to the time-series samples (relative to the beginning of the file) and the GPS time at the beginning of the file. There are also other optional pieces of information that can be returned (slightly different sets for the two functions). You can get the following information about the function arguments and return values by typing "help frextract" or "help frgetvect" within Matlab:
>> help frextract
FREXTRACT - Read time-series data from a frame file
by B. Mours LAPP Dec 20, 2000
This Matlab mex file extract from a frame file the data for
one ADC channel (this is for Matlab version 5)
The input arguments are:
1) file name
2) ADC name
3) (optional) first frame (default= first frame in the file)
4) (optional) number of frame (default = 1 Frames)
Returned matlab data:
1) ADC data (time serie)
2) (optional) time values relative to the first data point
3) (optional) frequency values (for FFT's)
4) (optional) GPS starting time (in second.nanosec)
5) (optional) starting time as a string
6) (optional) ADC comment as a string
7) (optional) ADC unit as a string
8) (optional) additional info: it is a 9 words vector which
content:crate #, channel#, nBits#, biais, slope,
sampleRate, timeOffset(S.N), fShift, overRange
All this values are stored as double
>> help frgetvect
FRGETVECT - Read a data vector from a frame file
by B. Mours Caltech&LAPP Dec 20, 2000
This Matlab mex file extract from a frame file the data for one
vector (ADC ot Proc or Sim data) (this is for Matlab version 5)
The input arguments are:
1) file name
2) vector name
3) (optional) starting GPS time(default= first frame in the file)
4) (optional) number of frame (default = 1 Frames)
Returned matlab data:
1) ADC data (time serie stored as double)
2) (optional) time values relative to the first data point(double)
3) (optional) frequency values (for FFT's) (double)
4) (optional) GPS starting time (in second, stored in double)
5) (optional) starting time as a string
6) (optional) vector unitX as a string
7) (optional) vector unitY as a string
All this values are stored as double
The meaning of the optional third argument to frextract(),
which is described in the help as "first frame (default= first frame
in the file)", is a bit counterintuitive. It is not the
ordinal number of the frame in the file (1 for the first frame in the
file, 2 for the second frame, etc.), nor is it the GPS time of the
frame. Rather, it is the "frame number" written into the frame by the
data acquisition system when the frame was originally created, which
resets to 0 every time the DAQ is restarted. Since you generally
don't know this information about the frame(s) in your file, you
should omit this argument or else set it to 0.
< M A T L A B >
Copyright 1984-2000 The MathWorks, Inc.
Version 6.0.0.88 Release 12
Sep 21 2000
>> %-- Read in data for a 16384-Hz channel
>> adcdata = frgetvect('LLO73189_L-R-694310400-16.gwf','L1:LSC-AS_Q');
Open file:LLO73189_L-R-694310400-16.gwf for channel:L1:LSC-AS_Q t0=0.00 length=1.0
>> size(adcdata)
ans =
262144 1
>> plot(adcdata)
>> %-- Re-read the same data, but return extra information
>> [adcdata,deltat,ignore,gps] = frgetvect('LLO73189_L-R-694310400-16.gwf','L1:LSC-AS_Q');
Open file:LLO73189_L-R-694310400-16.gwf for channel:L1:LSC-AS_Q t0=0.00 length=1.0
>> gps
gps =
694310400
>> %-- Now plot vs. actual time (though axis labels don't cooperate)
>> plot(gps+deltat,adcdata)
>> adcdata = frextract('H-F_l9x2-657968400-10.gwf','H2:LSC-AS_Q',0,10);
Open file:H-F_l9x2-657968400-10.gwf for channel:H2:LSC-AS_Q
first frame:0 nFrames=10
Frame 34222 run 245 GPS : 657968400
>> size(adcdata)
ans =
163840 1
>> %-- Print out minimum, maximum, mean, and rms
>> min(adcdata), max(adcdata), mean(adcdata), sqrt(mean((adcdata-mean(adcdata)).^2))
ans =
-221.8399
ans =
217.6507
ans =
0.0110
ans =
63.0662