LOSC API Examples

In this tutorial, we will use the sample API and a segment list to read in some LIGO data that we know to be of good quality. This tutorial will emphasize reading in data only for target GPS segments.

The method getstrain() is the main tool in the API for loading LIGO data. Instead of taking the file name as input, getstrain takes a GPS start and stop time, and uses the LIGO file naming convention to find the right file to read in. So, you can download a lot of LIGO data files to a directory or a directory tree. Then, you can tell getstrain only the times and instrument for which you want data, and the API will find the files and load the data for you.

Files you will need for this tutorial:

Download some data files

The LOSC API will work with a directory of LIGO data files. To see how it works, try downloading a few LIGO data files.
  1. Go to the Data Archive Query Form
  2. Choose the S5 data set and the H1 detector
  3. Enter start time 842656000 and end time 842670000
  4. Click Continue to get a list of data files. You should see 4 data files
  5. Click HDF5 to download all 4 data files, and save them in the same directory where you have been working.

Collect the data files and readligo.py in a single directory. Then, start the python interpreter (or Canopy) and make sure your working directory is the same directory where you stored these files.

Load all data from a single file

The command loaddata can be used to load all data from a single LIGO data file.
#----------------------------------------------------------------
# Load all LIGO data from a single file 
#----------------------------------------------------------------
strain, time, dq = rl.loaddata('ligo_data/H-H1_LOSC_4_V1-842653696-4096.hdf5', 'H1')
  • STRAIN is a numpy array of strain data between the input GPS times
  • TIME is a numpy array of GPS times of each sample, corresponding to STRAIN.
  • DQ is a dictionary of data quality flags.
Including the optional argument tvec=False will result in returning a dictionary of gps start, stop, and sample time instead of the TIME vector. So, with tvec set to False, the return value is (STRAIN, META, DQ).

To loop over segments of usable strain data, you can do the following:

slice_list = rl.dq_channel_to_seglist(dq['DATA'])
for slice in slice_list:
    time_seg = time[slice]
    strain_seg = strain[slice]
    # -- Process strain segment here    

Basic use case: Load data using a segment list

The methods getstrain() and getsegs() will not work for releases of individual events. To work with released events, see the above example.
A common task is to read in data associated with each segment, and then perform some analysis on that data. The API is designed to make this easy.
import readligo as rl
import numpy as np
start = 842656000
stop  = 842670000

segs = rl.getsegs(start, stop, 'H1')
for (begin, end) in segs:
    strain, meta, dq = rl.getstrain(begin, end, 'H1')
    #-- Your analysis code goes here
This default configuration assumes that the needed LIGO data files are available in the current working directory or a subdirectory. The variable strain is now a numpy array of strain values, between gps meta['start'] and meta['stop']. The time between samples (in seconds) can be seen in the variable meta['dt']. Currently, LOSC data is sampled at 4096 Hz.

The return values are as follows:

  • STRAIN is a numpy array of strain data between the input GPS times
  • META is a dictionary of gps start, gps stop, and the sample time.
  • DQ is a dictionary of data quality flags.

Segment Lists

The "Basic Use Case" example above loops over segments in a segment list. The segment list is constructed with the getsegs() method. By default, getsegs() returns Science Mode segments. However, the optional argument flag may be used to return segments based on any data quality flag:
segs = rl.getsegs(start, stop, 'H1', flag='BURST_CAT2')
Alternatively, a segment list may be downloaded from the LOSC web site using the Timeline Query Form. A segment list as an ASCII text file may be read in using the SegmentList class.
segs = rl.SegmentList('H1_segs.txt')
It is also possible to construct a segment list by combining 2 or more channels from a DQ dictionary. The data quality channels contained in the DQ dictionary are sampled at 1 Hz, and may be easily combined with logical operators. The method dq2segs will convert a 1 Hz DQ channel to a segment list.
# -- Construct segment list based on multiple DQ channels
strain, time, dq = rl.loaddata('ligo_data/H-H1_LOSC_4_V1-842653696-4096.hdf5', 'H1')
bcat3 = dq['BURST_CAT3']
cbccat3 = dq['CBCLOW_CAT3']
clean = bcat3 & cbccat3
segs = rl.dq2segs(clean, time[0])

File Lists

The LOSC API uses the class FileList to identify LIGO data files that are stored locally. By default, the current working directory and sub-directories are searched for LIGO data files. If the LIGO data files are in another directory tree, first construct a FileList, and then pass it as the parameter filelist to getsegs and getstrain.
filelist = rl.FileList(directory='/home/ligodata')
segList = getsegs(842657792, 842658792, 'H1', filelist=filelist)
for start, stop in segList:
  strain, meta, dq = getstrain(start, stop, 'H1', filelist=filelist)
  # -- Analysis code here
For large data sets, it is also possible to save a file list as a cache file with the method filelist.writecache('cache.txt'). A previously saved cache file may be loaded as a working FileList object by passing the cache file name to the FileList constructor:
filelist = rl.FileList(cache='cache.txt')
An existing FileList may be searched for a file containing a given GPS time using the method FileList.findfile()
gps = 842656000
filename = filelist.findfile(gps, 'H1')
print "The file {0} contains time {1} for IFO H1".format(filename, gps)

That's it! Additional documentation is available in the readligo.py docstrings with help(rl). You can also download the examples shown here as api_examples.py.