SFTfileIO
[LAL Support Interface]

Collaboration diagram for SFTfileIO:

Author:
R.Module for reading/writing/manipulating SFTs (Short Fourier transforms)
More...


Files

file  SFTutils.h
 
Author:
Reinhard Prix, Badri Krishnan Utility functions for handling of SFTtype and SFTVectors

file  SFTutils.c
 
Author:
Reinhard Prix, Badri Krishnan, John T.Utility functions for handling of SFTtype and SFTVector's.

file  SFTfileIO.h
 
Date:
Date
2008/08/01 12:17:00
Header file defining the API for the SFTfileIO modules.

file  SFTfileIO.c
 
Author:
R.IO library for reading/writing "Short Fourier transform" (SFT) data files.

file  SFTfileIOTest.c
 
Author:
R.Test-code for SFT-fileIO library

Detailed Description

Author:
R.Module for reading/writing/manipulating SFTs (Short Fourier transforms)

Prix, B. Machenschalk, A.M. Sintes, B. Krishnan

Date
2008/08/01 12:17:00

Overview:

Usage: Reading of SFT-files

The basic operation of reading SFTs from files proceeds in two simple steps:

  1. LALSFTdataFind(): get an 'SFTCatalog' of SFTs matching certain requirements (free with LALDestroySFTCatalog())
  2. LALLoadSFTs(): load a frequency-band into a single-IFO SFTVector defined by the catalogue, OR
    LALLoadMultiSFTs(): load a frequency-band into a multi-IFO vector of SFTVectors defined by the catalogue

Note 1: currently supported SFT file-formats are (merged or single) SFT-v1 and SFT-v2 files. This might be extended in the future to support further file-formats (frames?). None of the following API depends on the details of the underlying file-format. This will ensure that codes using the following functions will NOT have to be changed irrespective of SFT file-format used.

Note 2: irrespective of the underlying SFT file-format, the returned SFTs (SFTVector) will ALWAYS be normalized according the the LAL-specification for frequency-series (LIGO-T010095-00), that is the pure DFT of the time-series $x_j$ is multiplied by the time-step $\Delta t$:

\[ \mathrm{data}[k] = X^\mathrm{d}_k = \Delta t \,\sum_{j=0}^{N-1} x_j \,e^{-i2\pi \,k \,j / N} \]

Details to 1: find matching SFTs and get the SFTCatalog:

 LALSFTdataFind(LALStatus *, SFTCatalog **catalog, const CHAR *file_pattern, SFTConstraints *constraints);

This function returns an SFTCatalog of matching SFTs for a given file-pattern (e.g. "SFT.*", "SFT.000", "/some/path/some_files_[0-9]?.sft", etc ) and additional, optional SFTConstraints.

The optional constraints are:

Note 1: Any constraint can be specified as NULL, all given constraints will be combined by logical AND.

Note 2: if a timestamps-list is given, *ALL* timestamps within [startTime, endTime] MUST be found!]

Note 3: LALSFTdataFind() will refuse to return any SFTs without their detector-name properly set. This applies only to v1-SFTs, for which you have to use constraints->detector, so that the detector-name gets properly set.

Note 4: One special constraint->detector is "??", which acts as if constraints->detector==NULL, except that it allows v1-SFTs to be returned with detector-name set to "??"'.

The returned SFTCatalog is a vector of 'SFTDescriptor's describing one SFT, with the fields

One can use the following catalog-handling API functions:

NOTE: The SFTs in the returned catalogue are guaranteed to

Details to 2: load frequency-band from SFTs described in an SFTCatalog

 LALLoadSFTs ( LALStatus *, SFTVector **sfts, const SFTCatalog *catalog, REAL8 fMin, REAL8 fMax);

This function takes an SFTCatalog and reads the smallest frequency-band containing [fMin, fMax] from the SFTs, returning the resulting SFTVector. Note that this function will return an error if the SFTCatalog contains SFTs from different detectors, for which LALLoadMultiSFTs() must be used.

The frequency-bounds are optional and -1 can be used to specify an 'open bound', i.e.
[-1, fMax]: read from first frequency-bin in the SFT up to fMax.
[fMin, -1]: read from fMin up to last frequency-bin in the SFTS
[-1, -1]: read ALL frequency-bins from SFT.

 LALLoadMultiSFTs ( LALStatus *, MultiSFTVector **sfts, const SFTCatalog *catalog, REAL8 fMin, REAL8 fMax);

This function is similar to the above, except that it accepts an SFTCatalog with different detectors, and returns corresponding multi-IFO vector of SFTVectors.

Usage: Writing of SFT-files

For writing SFTs there are two functions, depending on the desired output-format (v1 or v2 SFTs):

Note: in addition to these two function which take properly normalized SFTs as input, there is a DEPRECATED legacy-function, LALWriteSFTfile(), which writes an v1-SFT file, but *without* changing the data-normalization, i.e. this will only be correct for v1-normalized data (i.e. data = DFT)

Generated on Tue Oct 7 02:41:42 2008 for LAL by  doxygen 1.5.2