Accessing local frame data from MATLAB

Individual frame files can be read with the FrameL functions.
A new MATLAB class with related structure and functions
can be used to retrieve a time-series of arbitrary length.

Getting a sample of frame files

Using frgetvect and frextract for single frames

Using Channel for arbitrary-length time-series from multiple frames

Getting some local frame files

On the LHO GC computers the frame files are stored in a directory structure.
In the examples below, we will be looking at Level 3 RDS files from
an S3 playground segment (Lock 207 from GPS 754562513 to 754563113).
These files are stored in directory /samrds/S3/L3/LHO/H-RDS_R_L3-7545.

The frame files covering the 600-second playground is also available from
the PSU site as an 80-Mb tar-ball. A shorter 100-second tar-ball is also here.
These can be used to get frame files to your laptop for use in the examples
below. These files will be put in the same directory structure as above.

Using frgetvect and frextract

Before trying to use these FrameL MATLAB functions, you may need
to install FrameL for MATLAB from Ligotools.

The basic frextract usage (from the help file) is
This Matlab mex file extract from a frame file the data for
    one ADC channel (this is for Matlab version 5 and later)

The input arguments are:
    1) file name
    2) ADC or PROC name
    3) (optional) first frame (default= first frame in the file)
    4) (optional) number of frame (default = 1 Frames)

Returned matlab data:
    1) ADC or PROC 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#, bias, slope,
                sampleRate, timeOffset(S.N), fShift, overRange
       All this values are stored as double

It is used retrieve data from one or more frames in a frame file. At present,
most LIGO frame files only have one frame per file. Thus from
each call to frextract, you will only get one frame (16 seconds usually) of data.

Here is a example of its use. The path below is for LHO GC computers.
You will need to change 'frameDir' to the location of frame files on your laptop.
Here we build up the frame file path to use in the frextract call.

>> frameDir = '/samrds/S3/L3/LHO/H-RDS_R_L3-7545';
>> frameFile = strcat(frameDir,'/H-RDS_R_L3-754562528-16.gwf');
>> adcData = frextract(frameFile,'H1:LSC-AS_Q');

The similar 'frgetvect' only retrieves ADC data , but is typically faster.

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

Examples of this usage are below.
>> h2Data = frgetvect(frameFile,'H2:LSC-AS_Q');
>> h1Data = frgetvect(frameFile,'H1:LSC-AS_Q');

Note that historically a severe error occurred if 'frgetvect' was called for a non-existent
frame file or non-existent channel.

Using Channel structure (chanstruct, chanvector)

To simplify retrieving data by GPS range instead of by frame, the Channel
class and structure were created at Penn State. Below are examples
for accessing local frame data.

Before doing the following examples, you may need to setup the Channel software.

Create a list of frame files

Although designed to find frame files with a database (LDR), the Channel
structure and functions can be used with an external list of frame files and
GPS times. A convenient function 'dir2framelist' will make a list from
all files in a directory. This can be used with the target frame files as follows on
the LHO GC machines;

>> frameDir = '/samrds/S3/L3/LHO/H-RDS_R_L3-7545';
>> [gpsList,frameList,durList]=dir2framelist(frameDir);

The gpsList is a vector of all the GPS start times, the frameList is a cell array of frame file
paths and durList is a vector of the frame durations. These will be used below.

Defining Channel structures

For each adc channel being used, create a Channel structure using 'chanstruct'.

>> h1Asq = chanstruct('H1-LSC-AS_Q');
>> h2Asq = chanstruct('H2-LSC-AS_Q');

Each Channel structure has fields similar to the elements in a Channel class.
The default values can be shown in this way
>> h1Asq

h1Asq =

          name: 'H1:LSC-AS_Q'
    statusCode: 0
          site: 'LDR'
    instrument: 'H'
          type: 'RDS_R_L1'
      gpsStart: 0
          rate: 0

The name is what we input, the instrument is derived from the name, and the
site 'LDR' is not used at present.

In our case, we are using Level 3 RDS files, so we need to change the type
from the default 'RDS_R_L3'. This is done as expected for structures
>> h1Asq.type = 'RDS_R_L3';
>> h2Asq.type = 'RDS_R_L3';

Get a time-series by start time, duration

The Channel functions use a simple syntax to get data for n seconds after a GPS start time.
To get 30 seconds of time-series data within the time range of a frame list, use the
following example with chanvector.

>> h1Series = chanvector(h1Asq,754562530,30,gpsList,frameList,durList);
>> length(h1Series)

Get a time-series by start and end time

The time-series can also be retrieved by start and end GPS with a slightly different syntax
>> h2Series = chanvector(h2Asq,754562530:754562560,gpsList,frameList,durList);

Optional parameters can be used to get the sample rate of the channel and
any errors which could occur.

>> [h2Series,sampRate,errCode] = chanvector(h2Asq,754562530,30,gpsList,frameList,durList);
>> sampRate

These errors can describe several failures to retrieve all the
time-series data needed. If an error code is retrieved, the
function will always return a time-series of the correct length,
with 0's indicating missing data.

vectorError [OPTIONAL] error code from vector creation
       = 0 if no problems
         1-10 error from FRAMELIST
         11-30 error from MLFRAMEQUERY (via FRAMELIST)
         31-40 error from FETCHSERIES
         41-50 error within CHANVECTOR
       41 Channel input is not a structure
       42 non-numeric GPS range
       43 input structure is not a Channel structure
       44 Bad GPS range
       45 External frame list is empty

Keith Thorne

Last modified: Fri Aug 20 2004 9:15AM PDT