Module for reading/writing/manipulating SFTs (Short Fourier Transforms)
This implements the SFT (Short Fourier Transforms) standard defined in [4] . It contains various helper functions to create, handle, combine, and destroy SFTs and related data structures, including SFTtype, SFTVector, SFTCatalog (and their multi-detector generalizations) as well as tools for dealing with SFT timestamps and semicoherent analysis segments.
The basic operation of reading SFTs from files proceeds in two simple steps:
Note 1: currently supported SFT file-formats are (merged or single) SFT 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} \]
Thes function XLALSFTdataFind() 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 [minStartTime, maxStartTime)
MUST be found!]
Note 3: XLALSFTdataFind() will refuse to return any SFTs without their detector-name properly set.
The returned SFTCatalog is a vector of SFTDescriptor describing one SFT, with the fields
locator:
an opaque data-type describing where to read this SFT from.header:
the SFts headercomment:
the comment-string found in the SFT, if anynumBins:
the number of frequency-bins in the SFTversion:
version-number of SFT file-formatcrc64:
the crc64 checksum reported by this SFTOne can use the following catalog-handling API functions:
LIGOTimeGPSVector
)NOTE: The SFTs in the returned catalogue are guaranteed to
The function XLALLoadSFTs() 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 XLALLoadMultiSFTs() 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.
The function XLALLoadMultiSFTs() is similar to the above, except that it accepts an SFTCatalog with different detectors, and returns corresponding multi-IFO vector of SFTVectors.
For writing SFTs:
Prototypes | |
static int | read_SFDB_header_from_fp (FILE *fp, SFDBHeader *header) |
static BOOLEAN | CheckIfSFDBInScienceMode (SFDBHeader *SFDBHeader, LALStringVector *detectors, MultiLIGOTimeGPSVector *startingTS, MultiLIGOTimeGPSVector *endingTS) |
static long | get_file_len (FILE *fp) |
static BOOLEAN | consistent_mSFT_header (SFTtype header1, UINT4 version1, UINT4 nsamples1, UINT2 windowspec1, SFTtype header2, UINT4 version2, UINT4 nsamples2, UINT2 windowspec2) |
static BOOLEAN | timestamp_in_list (LIGOTimeGPS timestamp, LIGOTimeGPSVector *list) |
void | endian_swap (CHAR *pdata, size_t dsize, size_t nelements) |
FILE * | fopen_SFTLocator (const struct tagSFTLocator *locator) |
Open an "SFT" defined by the SFT-locator, return a FILE-pointer to the beginning of this SFT. More... | |
int | read_SFTversion_from_fp (UINT4 *version, BOOLEAN *need_swap, FILE *fp) |
Read valid SFT version-number at position fp, and determine if we need to endian-swap the data. More... | |
int | read_sft_header_from_fp (FILE *fp, SFTtype *header, UINT4 *version, UINT8 *crc64, UINT2 *SFTwindowspec, BOOLEAN *swapEndian, CHAR **SFTcomment, UINT4 *numBins) |
static int | read_header_from_fp (FILE *fp, SFTtype *header, UINT4 *nsamples, UINT8 *header_crc64, UINT8 *ref_crc64, UINT2 *SFTwindowspec, CHAR **SFTcomment, BOOLEAN swapEndian) |
UINT4 | read_sft_bins_from_fp (SFTtype *ret, UINT4 *firstBinRead, UINT4 firstBin2read, UINT4 lastBin2read, FILE *fp) |
BOOLEAN | has_valid_crc64 (FILE *fp) |
Check the SFT-block starting at fp for valid crc64 checksum. More... | |
int | build_sft_windowspec (UINT2 *windowspec, CHAR(*windowspec_str)[9], const char *window_type, REAL8 window_param) |
Build an SFT 2-byte 'windowspec' or filename field 'windowspec_str' for the window given by 'window_type' and 'window_param'. More... | |
int | parse_sft_windowspec (const UINT2 windowspec, const char **window_type, REAL8 *window_param) |
Parse an SFT 2-byte 'windowspec' into a window name 'window_type' and possible parameter 'window_param'. More... | |
int | parse_sft_windowspec_str (const CHAR *windowspec_str, CHAR(*window_type)[32], REAL8 *window_param) |
Parse an SFT filename field 'windowspec_str' into a window name 'window_type' and possible parameter 'window_param'. More... | |
REAL8 | TSFTfromDFreq (REAL8 dFreq) |
int | compareSFTdesc (const void *ptr1, const void *ptr2) |
int | compareSFTloc (const void *ptr1, const void *ptr2) |
int | compareDetNameCatalogs (const void *ptr1, const void *ptr2) |
int | compareSFTepoch (const void *ptr1, const void *ptr2) |
Data Structures | |
struct | MultiSFTVector |
A collection of SFT vectors – one for each IFO in a multi-IFO search. More... | |
struct | LIGOTimeGPSVector |
A vector of 'timestamps' of type LIGOTimeGPS. More... | |
struct | MultiLIGOTimeGPSVector |
A collection of (multi-IFO) LIGOTimeGPSVector time-stamps vectors. More... | |
struct | SFTConstraints |
'Constraints' for SFT-matching: which detector, within which time-stretch and which timestamps exactly should be loaded ? Any of the entries is optional, and they will be combined by logical AND. More... | |
struct | SFTDescriptor |
A 'descriptor' of an SFT: basically containing the header-info plus an opaque description of where exactly to load this SFT from. More... | |
struct | SFTCatalog |
An "SFT-catalogue": a vector of SFTdescriptors, as returned by XLALSFTdataFind() More... | |
struct | MultiSFTCatalogView |
A multi-SFT-catalogue "view": a multi-IFO vector of SFT-catalogs. More... | |
struct | SFTFilenameSpec |
Structure specifying an SFT file name, following the convention in [4] . More... | |
Typedefs | |
typedef COMPLEX8FrequencySeries | SFTtype |
A so-called 'SFT' (short-Fourier-transform) will be stored in a COMPLEX8FrequencySeries. More... | |
typedef COMPLEX8FrequencySeriesVector | SFTVector |
The corresponding vector-type to hold a vector of 'SFTs'. More... | |
Files | |
file | SFTinternal.h |
Internal SFT types and functions. | |
file | SFTfileIOTest.c |
Test-code for SFT-fileIO library. | |
file | SFTnamingTest.c |
Test the SFT file naming routines. | |
file | XLALMultiNoiseWeightsTest.c |
Tests for XLALComputeMultiNoiseWeights() | |
SFT file reading functions | |
MultiSFTVector * | XLALReadSFDB (REAL8 f_min, REAL8 f_max, const CHAR *file_pattern, const CHAR *timeStampsStarting, const CHAR *timeStampsFinishing) |
Return a MultiSFTVector struct from an input set of SFDBs, possibly from more than one detector. More... | |
SFTVector * | XLALLoadSFTs (const SFTCatalog *catalog, REAL8 fMin, REAL8 fMax) |
Load the given frequency-band [fMin, fMax) (half-open) from the SFT-files listed in the SFT-'catalogue' ( returned by XLALSFTdataFind() ). More... | |
MultiSFTVector * | XLALLoadMultiSFTs (const SFTCatalog *inputCatalog, REAL8 fMin, REAL8 fMax) |
Function to load a catalog of SFTs from possibly different detectors. More... | |
MultiSFTVector * | XLALLoadMultiSFTsFromView (const MultiSFTCatalogView *multiCatalogView, REAL8 fMin, REAL8 fMax) |
This function loads a MultiSFTVector from a given input MultiSFTCatalogView, otherwise the documentation of XLALLoadMultiSFTs() applies. More... | |
LALStringVector * | XLALFindFiles (const CHAR *globstring) |
Returns a list of filenames matching the input argument, which may be one of the following: More... | |
SFT catalog create/destroy functions | |
SFTCatalog * | XLALSFTdataFind (const CHAR *file_pattern, const SFTConstraints *constraints) |
Find the list of SFTs matching the file_pattern and satisfying the given constraints, return an SFTCatalog of the matching SFTs. More... | |
void | XLALDestroySFTCatalog (SFTCatalog *catalog) |
Free an 'SFT-catalogue'. More... | |
MultiSFTCatalogView * | XLALGetMultiSFTCatalogView (const SFTCatalog *catalog) |
Return a MultiSFTCatalogView generated from an input SFTCatalog. More... | |
void | XLALDestroyMultiSFTCatalogView (MultiSFTCatalogView *multiView) |
Destroys a MultiSFTCatalogView, without freeing the original catalog that the 'view' was referring to, which must be destroyed separately using XLALDestroySFTCatalog(). More... | |
SFT catalog property functions | |
int | XLALCheckCRCSFTCatalog (BOOLEAN *crc_check, SFTCatalog *catalog) |
This function reads in the SFTs in the catalog and validates their CRC64 checksums. More... | |
LALStringVector * | XLALListIFOsInCatalog (const SFTCatalog *catalog) |
Return a sorted string vector listing the unique IFOs in the given catalog. More... | |
INT4 | XLALCountIFOsInCatalog (const SFTCatalog *catalog) |
Count the number of the unique IFOs in the given catalog. More... | |
const CHAR * | XLALshowSFTLocator (const struct tagSFTLocator *locator) |
Mostly for debugging purposes: provide a user-API to allow inspecting the SFT-locator [which is an OPAQUE entry in the SFTCatalog!]. More... | |
int | XLALSFTCatalogTimeslice (SFTCatalog *slice, const SFTCatalog *catalog, const LIGOTimeGPS *minStartGPS, const LIGOTimeGPS *maxStartGPS) |
Set a SFT catalog 'slice' to a timeslice of a larger SFT catalog 'catalog', with entries restricted to the interval ['minStartGPS','maxStartGPS') according to XLALCWGPSinRange(). More... | |
SFTCatalog * | XLALReturnSFTCatalogTimeslice (const SFTCatalog *catalog, const LIGOTimeGPS *minStartGPS, const LIGOTimeGPS *maxStartGPS) |
SFT catalog generation functions | |
SFTCatalog * | XLALAddToFakeSFTCatalog (SFTCatalog *catalog, const CHAR *detector, const LIGOTimeGPSVector *timestamps) |
Create a 'fake' SFT catalog which contains only detector and timestamp information. More... | |
SFTCatalog * | XLALMultiAddToFakeSFTCatalog (SFTCatalog *catalog, const LALStringVector *detectors, const MultiLIGOTimeGPSVector *timestamps) |
Multi-detector and multi-timestamp wrapper of XLALAddToFakeSFTCatalog(). More... | |
SFT file writing functions | |
int | XLALWriteSFT2FilePointer (const SFTtype *sft, FILE *fp, const CHAR *SFTwindowtype, const REAL8 SFTwindowparam, const CHAR *SFTcomment) |
Write the given SFTtype to a FILE pointer. More... | |
int | XLALWriteSFT2NamedFile (const SFTtype *sft, const CHAR *SFTfilename, const CHAR *SFTwindowtype, const REAL8 SFTwindowparam, const CHAR *SFTcomment) |
Write the given SFTtype to a SFT file with the supplied filename. More... | |
int | XLALWriteSFT2StandardFile (const SFTtype *sft, SFTFilenameSpec *SFTfnspec, const CHAR *SFTcomment) |
Write the given SFTtype to a SFT file with a standard ([4]) filename. More... | |
int | XLALWriteSFTVector2NamedFile (const SFTVector *sftVect, const CHAR *SFTfilename, const CHAR *SFTwindowtype, const REAL8 SFTwindowparam, const CHAR *SFTcomment) |
Write the given SFTVector to a single merged SFT file with the supplied filename. More... | |
int | XLALWriteSFTVector2StandardFile (const SFTVector *sftVect, SFTFilenameSpec *SFTfnspec, const CHAR *SFTcomment, const BOOLEAN merged) |
Write the given SFTVector to SFT file(s) with a standard ([4]) filename(s). More... | |
int | XLALCheckSFTFileIsValid (const char *fname) |
Verify that the contents of a SFT file are valid. More... | |
Time range/frequency bin convention functions | |
int | XLALCWGPSinRange (const LIGOTimeGPS gps, const LIGOTimeGPS *minGPS, const LIGOTimeGPS *maxGPS) |
Defines the official CW convention for whether a GPS time is 'within' a given range, defined as the half-open interval [minGPS, maxGPS) More... | |
UINT4 | XLALRoundFrequencyDownToSFTBin (const REAL8 freq, const REAL8 df) |
Round a REAL8 frequency down to the nearest integer SFT bin number. More... | |
UINT4 | XLALRoundFrequencyUpToSFTBin (const REAL8 freq, const REAL8 df) |
Round a REAL8 frequency up to the nearest integer SFT bin number. More... | |
int | XLALFindCoveringSFTBins (UINT4 *firstBin, UINT4 *numBins, REAL8 fMinIn, REAL8 BandIn, REAL8 Tsft) |
Return the 'effective' frequency-band [fMinEff, fMaxEff] = [firstBin, lastBin] * 1/Tsft, with numBins = lastBin - firstBin + 1 which is the smallest band of SFT-bins that fully covers a given band [fMin, fMin+Band]. More... | |
SFT type create/destroy functions | |
SFTtype * | XLALCreateSFT (UINT4 numBins) |
XLAL function to create one SFT-struct. More... | |
void | XLALDestroySFT (SFTtype *sft) |
Destructor for one SFT. More... | |
int | XLALCopySFT (SFTtype *dest, const SFTtype *src) |
Copy an entire SFT-type into another. More... | |
SFTVector * | XLALCreateSFTVector (UINT4 numSFTs, UINT4 numBins) |
XLAL function to create an SFTVector of numSFT SFTs with SFTlen frequency-bins (which will be allocated too). More... | |
SFTVector * | XLALCreateEmptySFTVector (UINT4 numSFTs) |
XLAL function to create an SFTVector of numSFT SFTs (which are not allocated). More... | |
void | XLALDestroySFTVector (SFTVector *vect) |
XLAL interface to destroy an SFTVector. More... | |
SFTVector * | XLALDuplicateSFTVector (const SFTVector *sftsIn) |
Create a complete copy of an SFT vector. More... | |
MultiSFTVector * | XLALCreateMultiSFTVector (UINT4 length, UINT4Vector *numsft) |
Create a multi-IFO SFT vector with a given number of bins per SFT and number of SFTs per IFO (which will be allocated too). More... | |
MultiSFTVector * | XLALCreateEmptyMultiSFTVector (UINT4Vector *numsft) |
Create an empty multi-IFO SFT vector with a given number of SFTs per IFO (which are not allocated). More... | |
void | XLALDestroyMultiSFTVector (MultiSFTVector *multvect) |
Destroy a multi SFT-vector. More... | |
int | XLALExtractBandFromSFT (SFTtype **outSFT, const SFTtype *inSFT, REAL8 fMin, REAL8 Band) |
Return an SFTs containing only the bins in [fMin, fMin+Band]. More... | |
SFTVector * | XLALExtractBandFromSFTVector (const SFTVector *inSFTs, REAL8 fMin, REAL8 Band) |
Return a vector of SFTs containing only the bins in [fMin, fMin+Band]. More... | |
MultiSFTVector * | XLALExtractBandFromMultiSFTVector (const MultiSFTVector *inSFTs, REAL8 fMin, REAL8 Band) |
Return a MultiSFT vector containing only the bins in [fMin, fMin+Band]. More... | |
int | XLALExtractStrictBandFromSFT (SFTtype **outSFT, const SFTtype *inSFT, REAL8 fMin, REAL8 Band) |
Return a copy of an SFT containing only the bins in [fMin, fMin+Band). More... | |
SFTVector * | XLALExtractStrictBandFromSFTVector (const SFTVector *inSFTs, REAL8 fMin, REAL8 Band) |
Return a copy of a vector of SFTs containing only the bins in [fMin, fMin+Band). More... | |
MultiSFTVector * | XLALExtractStrictBandFromMultiSFTVector (const MultiSFTVector *inSFTs, REAL8 fMin, REAL8 Band) |
Return a copy of a MultiSFT vector containing only the bins in [fMin, fMin+Band). More... | |
SFT type modify functions | |
int | XLALAppendSFT2Vector (SFTVector *vect, const SFTtype *sft) |
Append the given SFTtype to the SFT-vector (no SFT-specific checks are done!) More... | |
int | XLALReorderMultiSFTVector (MultiSFTVector *multiSFTs, const LALStringVector *IFOs) |
Reorder the MultiSFTVector with specified list of IFOs. More... | |
int | XLALSFTAdd (SFTtype *a, const SFTtype *b) |
Adds SFT-data from SFT 'b' to SFT 'a'. More... | |
int | XLALSFTVectorAdd (SFTVector *a, const SFTVector *b) |
Adds SFT-data from SFTvector 'b' to elements of SFTVector 'a'. More... | |
int | XLALMultiSFTVectorAdd (MultiSFTVector *a, const MultiSFTVector *b) |
Adds SFT-data from MultiSFTvector 'b' to elements of MultiSFTVector 'a'. More... | |
int | XLALSFTResizeBand (SFTtype *SFT, REAL8 f0, REAL8 Band) |
Resize the frequency-band of a given SFT to [f0, f0+Band]. More... | |
int | XLALSFTVectorResizeBand (SFTVector *SFTs, REAL8 f0, REAL8 Band) |
Resize the frequency-band of a given SFT vector to [f0, f0+Band]. More... | |
int | XLALMultiSFTVectorResizeBand (MultiSFTVector *multiSFTs, REAL8 f0, REAL8 Band) |
Resize the frequency-band of a given multi-SFT vector to [f0, f0+Band]. More... | |
SFT type property functions | |
int | XLALEarliestMultiSFTsample (LIGOTimeGPS *out, const MultiSFTVector *multisfts) |
Finds the earliest timestamp in a multi-SFT data structure. More... | |
int | XLALLatestMultiSFTsample (LIGOTimeGPS *out, const MultiSFTVector *multisfts) |
Find the time of the end of the latest SFT in a multi-SFT data structure. More... | |
SFTVector * | XLALExtractSFTVectorWithTimestamps (const SFTVector *sfts, const LIGOTimeGPSVector *timestamps) |
Extract an SFTVector from another SFTVector but only those timestamps matching. More... | |
MultiSFTVector * | XLALExtractMultiSFTVectorWithMultiTimestamps (const MultiSFTVector *multiSFTs, const MultiLIGOTimeGPSVector *multiTimestamps) |
Extract a MultiSFTVector from another MultiSFTVector but only those timestamps matching. More... | |
SFT timestamp type create/destroy functions | |
LIGOTimeGPSVector * | XLALCreateTimestampVector (UINT4 length) |
Allocate a LIGOTimeGPSVector. More... | |
void | XLALDestroyTimestampVector (LIGOTimeGPSVector *vect) |
De-allocate a LIGOTimeGPSVector. More... | |
LIGOTimeGPSVector * | XLALResizeTimestampVector (LIGOTimeGPSVector *vector, UINT4 length) |
Resize a LIGOTimeGPSVector. More... | |
MultiLIGOTimeGPSVector * | XLALCreateMultiLIGOTimeGPSVector (UINT4 numDetectors) |
Simple creator function for MultiLIGOTimeGPSVector with numDetectors entries. More... | |
void | XLALDestroyMultiTimestamps (MultiLIGOTimeGPSVector *multiTS) |
Destroy a MultiLIGOTimeGPSVector timestamps vector. More... | |
SFT timestamp type property functions | |
int | XLALFindTimesliceBounds (UINT4 *iStart, UINT4 *iEnd, const LIGOTimeGPSVector *timestamps, const LIGOTimeGPS *minStartGPS, const LIGOTimeGPS *maxStartGPS) |
SFT timestamp generation functions | |
LIGOTimeGPSVector * | XLALMakeTimestamps (LIGOTimeGPS tStart, REAL8 Tspan, REAL8 Tsft, REAL8 Toverlap) |
Given a start-time, Tspan, Tsft and Toverlap, returns a list of timestamps covering this time-stretch (allowing for overlapping SFTs). More... | |
MultiLIGOTimeGPSVector * | XLALMakeMultiTimestamps (LIGOTimeGPS tStart, REAL8 Tspan, REAL8 Tsft, REAL8 Toverlap, UINT4 numDet) |
Same as XLALMakeTimestamps() just for several detectors, additionally specify the number of detectors. More... | |
LIGOTimeGPSVector * | XLALReadTimestampsFile (const CHAR *fname) |
backwards compatible wrapper to XLALReadTimestampsFileConstrained() without GPS-time constraints More... | |
MultiLIGOTimeGPSVector * | XLALReadMultiTimestampsFiles (const LALStringVector *fnames) |
backwards compatible wrapper to XLALReadMultiTimestampsFilesConstrained() without GPS-time constraints More... | |
LIGOTimeGPSVector * | XLALReadTimestampsFileConstrained (const CHAR *fname, const LIGOTimeGPS *minGPS, const LIGOTimeGPS *maxGPS) |
Load timestamps file 'fname' into LIGOTimeGPSVector struct, allocated here. More... | |
MultiLIGOTimeGPSVector * | XLALReadMultiTimestampsFilesConstrained (const LALStringVector *fnames, const LIGOTimeGPS *minGPS, const LIGOTimeGPS *maxGPS) |
Load several timestamps files, return a MultiLIGOTimeGPSVector struct, allocated here. More... | |
LIGOTimeGPSVector * | XLALExtractTimestampsFromSFTs (const SFTVector *sfts) |
Extract timstamps-vector from the given SFTVector. More... | |
MultiLIGOTimeGPSVector * | XLALExtractMultiTimestampsFromSFTs (const MultiSFTVector *multiSFTs) |
Given a multi-SFT vector, return a MultiLIGOTimeGPSVector holding the SFT timestamps. More... | |
LIGOTimeGPSVector * | XLALTimestampsFromSFTCatalog (const SFTCatalog *catalog) |
Extract timestamps-vector of unique timestamps from the given SFTCatalog. More... | |
MultiLIGOTimeGPSVector * | XLALTimestampsFromMultiSFTCatalogView (const MultiSFTCatalogView *multiView) |
Given a multi-SFTCatalogView, return a MultiLIGOTimeGPSVector holding the SFT timestamps. More... | |
LALSegList * | XLALReadSegmentsFromFile (const char *fname) |
Function to read a segment list from given filename, returns a sorted LALSegList. More... | |
LIGOTimeGPSVector * | XLALTimestampsFromSegmentFile (const char *filename, REAL8 Tsft, REAL8 Toverlap, BOOLEAN adjustSegExtraTime, BOOLEAN synchronize) |
Extract timestamps-vector from a segment file, with functionality based on MakeSFTDAG The filename should point to a file containing <GPSstart GPSend> of segments or <GPSstart GPSend segLength numSFTs> where segLength is in hours. More... | |
SFT file naming convention functions | |
int | XLALRegisterSpecialCWDetector (const LALDetector *specialDetector) |
Register a special detector for use with CW codes. More... | |
int | XLALFindCWDetector (CHAR **prefix, INT4 *lalCachedIndex, const CHAR *name, const BOOLEAN exactMatch) |
Parses valid CW detector names and prefixes. More... | |
BOOLEAN | XLALIsValidCWDetector (const CHAR *name) |
Determine if 'name' is a valid detector name or prefix. More... | |
CHAR * | XLALGetChannelPrefix (const CHAR *name) |
Find the valid CW detector prefix. More... | |
const LALDetector * | XLALGetSiteInfo (const CHAR *name) |
Find the site geometry-information 'LALDetector' for given a detector name (or prefix). More... | |
int | XLALFillSFTFilenameSpecStrings (SFTFilenameSpec *spec, const CHAR *path, const CHAR *extn, const CHAR *detector, const CHAR *window_type, const CHAR *privMisc, const CHAR *pubObsKind, const CHAR *pubChannel) |
Convenience function for filling out the string fields in a SFTFilenameSpec. More... | |
char * | XLALBuildSFTFilenameFromSpec (const SFTFilenameSpec *spec) |
Build an SFT file name from the given specification. More... | |
int | XLALParseSFTFilenameIntoSpec (SFTFilenameSpec *spec, const char *SFTpath) |
Parse a SFT file path and return its specification. More... | |
int | XLALCheckValidDescriptionField (const char *desc) |
Check whether given string qualifies as a valid 'description' field of a FRAME filename (per [25]) or SFT filename (per [4]) More... | |
int | XLALCompareSFTWindows (const CHAR *type1, const REAL8 param1, const CHAR *type2, const REAL8 param2) |
Check whether two SFT windows, each defined by a type name and parameter value, match. More... | |
MultiSFTVector * XLALReadSFDB | ( | REAL8 | f_min, |
REAL8 | f_max, | ||
const CHAR * | file_pattern, | ||
const CHAR * | timeStampsStarting, | ||
const CHAR * | timeStampsFinishing | ||
) |
Return a MultiSFTVector struct from an input set of SFDBs, possibly from more than one detector.
An SFDB (Short Fourier DataBase) is the frequency-domain data format created by the Rome group. It has a time-domain cleaning, which is described in [2].
In order to only use SFDBs within science segments, it is possible to input files for each detector which have the science segments. Two files for each detector are needed, one with the starting timestamps and the other with the ending timestamps. The format for these files is one timestamp per line. If not needed, the timestamp inputs can be NULL.
The returned SFTs in the standard LALSuite format are sorted by increasing GPS-epochs!
Definition at line 100 of file SFDBfileIO.c.
|
static |
Definition at line 372 of file SFDBfileIO.c.
|
static |
Definition at line 415 of file SFDBfileIO.c.
SFTCatalog * XLALSFTdataFind | ( | const CHAR * | file_pattern, |
const SFTConstraints * | constraints | ||
) |
Find the list of SFTs matching the file_pattern and satisfying the given constraints, return an SFTCatalog
of the matching SFTs.
The optional constraints that can be specified are (type SFTConstraints)
==> The returned SFTCatalog can be used directly as input to XLALLoadSFTs() to load a single-IFO SFTVector, or XLALLoadMultiSFTs() to load a multi-IFO vector of SFTVectors
Except for the 'file_pattern' input, all the other constraints are optional and can be passed as NULL (either globally constraings==NULL, or individually).
Note that the constraints are combined by 'AND' and the resulting full constraint MUST be satisfied (in particular: if 'timestamps' is given, all timestamps within [minStartTime, maxStartTime) MUST be found!.
The returned SFTs in the catalogue are sorted by increasing GPS-epochs !
file_pattern | which SFT-files |
constraints | additional constraints for SFT-selection |
Definition at line 71 of file SFTcatalog.c.
void XLALDestroySFTCatalog | ( | SFTCatalog * | catalog | ) |
Free an 'SFT-catalogue'.
catalog | the 'catalogue' to free |
Definition at line 329 of file SFTcatalog.c.
MultiSFTCatalogView * XLALGetMultiSFTCatalogView | ( | const SFTCatalog * | catalog | ) |
Return a MultiSFTCatalogView generated from an input SFTCatalog.
The input catalog can describe SFTs from several IFOs in one vector, while the returned multi-Catalog view contains an array of single-IFO SFTCatalogs.
NOTE: remember that this is only a multi-IFO "view" of the existing SFTCatalog, various allocated memory of the original catalog is only pointed to, not duplicated! This means one must not free the original catalog while this multi-view is still in use!
NOTE2: the returned multi-IFO catalog is sorted alphabetically by detector-name
Definition at line 380 of file SFTcatalog.c.
void XLALDestroyMultiSFTCatalogView | ( | MultiSFTCatalogView * | multiView | ) |
Destroys a MultiSFTCatalogView, without freeing the original catalog that the 'view' was referring to, which must be destroyed separately using XLALDestroySFTCatalog().
Definition at line 496 of file SFTcatalog.c.
int XLALCheckCRCSFTCatalog | ( | BOOLEAN * | crc_check, |
SFTCatalog * | catalog | ||
) |
This function reads in the SFTs in the catalog and validates their CRC64 checksums.
The result of the validation is returned in '*crc_check'. The function itself returns XLAL_SUCCESS if the operation suceeds (even if the checksums fail to validate), and XLAL_FAILURE otherwise.
crc_check | set to true if checksum validation passes |
catalog | catalog of SFTs to check |
Definition at line 524 of file SFTcatalog.c.
LALStringVector * XLALListIFOsInCatalog | ( | const SFTCatalog * | catalog | ) |
Return a sorted string vector listing the unique IFOs in the given catalog.
Definition at line 562 of file SFTcatalog.c.
INT4 XLALCountIFOsInCatalog | ( | const SFTCatalog * | catalog | ) |
Count the number of the unique IFOs in the given catalog.
Definition at line 582 of file SFTcatalog.c.
const CHAR * XLALshowSFTLocator | ( | const struct tagSFTLocator * | locator | ) |
Mostly for debugging purposes: provide a user-API to allow inspecting the SFT-locator [which is an OPAQUE entry in the SFTCatalog!].
NOTE: this returns a STATIC string, so don't try to FREE it, and make a copy if you need to keep it beyond one call of this function!
Definition at line 602 of file SFTcatalog.c.
int XLALSFTCatalogTimeslice | ( | SFTCatalog * | slice, |
const SFTCatalog * | catalog, | ||
const LIGOTimeGPS * | minStartGPS, | ||
const LIGOTimeGPS * | maxStartGPS | ||
) |
Set a SFT catalog 'slice' to a timeslice of a larger SFT catalog 'catalog', with entries restricted to the interval ['minStartGPS','maxStartGPS') according to XLALCWGPSinRange().
The catalog 'slice' just points to existing data in 'catalog', and therefore should not be deallocated.
[out] | slice | Timeslice of SFT catalog |
[in] | catalog | SFT catalog |
[in] | minStartGPS | Minimum starting GPS time |
[in] | maxStartGPS | Maximum starting GPS time |
Definition at line 624 of file SFTcatalog.c.
SFTCatalog * XLALReturnSFTCatalogTimeslice | ( | const SFTCatalog * | catalog, |
const LIGOTimeGPS * | minStartGPS, | ||
const LIGOTimeGPS * | maxStartGPS | ||
) |
[in] | catalog | SFT catalog |
[in] | minStartGPS | Minimum starting GPS time |
[in] | maxStartGPS | Maximum starting GPS time |
Definition at line 670 of file SFTcatalog.c.
SFTCatalog * XLALAddToFakeSFTCatalog | ( | SFTCatalog * | catalog, |
const CHAR * | detector, | ||
const LIGOTimeGPSVector * | timestamps | ||
) |
Create a 'fake' SFT catalog which contains only detector and timestamp information.
[in] | catalog | SFT catalog; if NULL, a new catalog is created |
[in] | detector | Name of detector to set fake catalog entries to |
[in] | timestamps | Timestamps of each fake catalog entry |
Definition at line 692 of file SFTcatalog.c.
SFTCatalog * XLALMultiAddToFakeSFTCatalog | ( | SFTCatalog * | catalog, |
const LALStringVector * | detectors, | ||
const MultiLIGOTimeGPSVector * | timestamps | ||
) |
Multi-detector and multi-timestamp wrapper of XLALAddToFakeSFTCatalog().
[in] | catalog | SFT catalog; if NULL, a new catalog is created |
[in] | detectors | Detector names to set fake catalog entries to |
[in] | timestamps | Timestamps for each detector of each fake catalog entry |
Definition at line 749 of file SFTcatalog.c.
|
static |
Definition at line 774 of file SFTcatalog.c.
|
static |
Definition at line 813 of file SFTcatalog.c.
|
static |
Definition at line 863 of file SFTcatalog.c.
SFTVector * XLALLoadSFTs | ( | const SFTCatalog * | catalog, |
REAL8 | fMin, | ||
REAL8 | fMax | ||
) |
Load the given frequency-band [fMin, fMax)
(half-open) from the SFT-files listed in the SFT-'catalogue' ( returned by XLALSFTdataFind() ).
Note: fMin (or fMax) is allowed to be set to -1
, which means to read in all Frequency-bins from the lowest (or up to the highest) found in all SFT-files of the catalog.
Note 2: The returned frequency-interval is guaranteed to contain [fMin, fMax)
, but is allowed to be larger, as it must be an interval of discrete frequency-bins as found in the SFT-file.
Note 3: This function has the capability to read sequences of SFT segments and putting them together to single SFTs while reading.
Note 4: The 'fudge region' allowing for numerical noise is fudge= 10*LAL_REAL8_EPS ~2e-15 relative deviation: ie if the SFT contains a bin at 'fi', then we consider for example "fMin == fi" if fabs(fi - fMin)/fi < fudge.
< current file in catalog
< the first and last bin we want to read
< min and max bin of all SFTs in the catalog
< number of SFTs, i.e. different GPS timestamps
< frequency spacing of SFT
< local copy of the catalog to be sorted by 'locator'
< the vector of SFTs to be returned
< array of segments already read of an SFT
< empty string
< name of currently open file, initially ""
< open file
< SFT to read from file
catalog | The 'catalogue' of SFTs to load |
fMin | minumum requested frequency (-1 = read from lowest) |
fMax | maximum requested frequency (-1 = read up to highest) |
Definition at line 87 of file SFTfileIO.c.
MultiSFTVector * XLALLoadMultiSFTs | ( | const SFTCatalog * | inputCatalog, |
REAL8 | fMin, | ||
REAL8 | fMax | ||
) |
Function to load a catalog of SFTs from possibly different detectors.
This is similar to XLALLoadSFTs except that the input SFT catalog is allowed to contain multiple ifos. The output is the structure MultiSFTVector which is a vector of (pointers to) SFTVectors, one for each ifo found in the catalog. As in XLALLoadSFTs, fMin and fMax can be set to -1 to get the full SFT from the lowest to the highest frequency bin found in the SFT.
output SFTvectors are sorted alphabetically by detector-name
NOTE: this is basically a backwards-compatible API wrapper to XLALLoadMultiSFTsFromView(), which takes a MultiSFTCatalogView as input instead.
inputCatalog | The 'catalogue' of SFTs to load |
fMin | minumum requested frequency (-1 = read from lowest) |
fMax | maximum requested frequency (-1 = read up to highest) |
Definition at line 416 of file SFTfileIO.c.
MultiSFTVector * XLALLoadMultiSFTsFromView | ( | const MultiSFTCatalogView * | multiCatalogView, |
REAL8 | fMin, | ||
REAL8 | fMax | ||
) |
This function loads a MultiSFTVector from a given input MultiSFTCatalogView, otherwise the documentation of XLALLoadMultiSFTs() applies.
Note: this is basically the core-function of XLALLoadMultiSFTs() doing the actual work.
Note2: we keep the IFO sort-order of the input multiCatalogView
multiCatalogView | The multi-SFT catalogue view of SFTs to load |
fMin | minumum requested frequency (-1 = read from lowest) |
fMax | maximum requested frequency (-1 = read up to highest) |
Definition at line 449 of file SFTfileIO.c.
int XLALWriteSFT2FilePointer | ( | const SFTtype * | sft, |
FILE * | fp, | ||
const CHAR * | SFTwindowtype, | ||
const REAL8 | SFTwindowparam, | ||
const CHAR * | SFTcomment | ||
) |
Write the given SFTtype to a FILE pointer.
Add the comment to SFT if SFTcomment != NULL.
NOTE: the comment written into the SFT-file contains the 'sft->name' field concatenated with the user-specified 'SFTcomment'
sft | SFT to write to disk |
fp | pointer to open file |
SFTwindowtype | window applied to SFT, if any |
SFTwindowparam | parameter of window |
SFTcomment | optional comment |
Definition at line 488 of file SFTfileIO.c.
int XLALWriteSFT2NamedFile | ( | const SFTtype * | sft, |
const CHAR * | SFTfilename, | ||
const CHAR * | SFTwindowtype, | ||
const REAL8 | SFTwindowparam, | ||
const CHAR * | SFTcomment | ||
) |
Write the given SFTtype to a SFT file with the supplied filename.
Add the comment to SFT if SFTcomment != NULL.
NOTE: the comment written into the SFT-file contains the 'sft->name' field concatenated with the user-specified 'SFTcomment'
sft | SFT to write to disk |
SFTfilename | SFT filename |
SFTwindowtype | window applied to SFT, if any |
SFTwindowparam | parameter of window |
SFTcomment | optional comment |
Definition at line 598 of file SFTfileIO.c.
int XLALWriteSFT2StandardFile | ( | const SFTtype * | sft, |
SFTFilenameSpec * | SFTfnspec, | ||
const CHAR * | SFTcomment | ||
) |
Write the given SFTtype to a SFT file with a standard ([4]) filename.
Add the comment to SFT if SFTcomment != NULL.
NOTE: the comment written into the SFT-file contains the 'sft->name' field concatenated with the user-specified 'SFTcomment'
NOTE: The SFT filename spec is updated to reflect the filename of the written SFT, by setting the numSFTs
, detector
, SFTtimebase
, gpsStart
, and SFTspan
fields. if needed, the SFT filename can be reconstructed with XLALBuildSFTFilenameFromSpec()
sft | SFT to write to disk |
SFTfnspec | SFT filename specification used to construct filename |
SFTcomment | optional comment |
Definition at line 656 of file SFTfileIO.c.
int XLALWriteSFTVector2NamedFile | ( | const SFTVector * | sftVect, |
const CHAR * | SFTfilename, | ||
const CHAR * | SFTwindowtype, | ||
const REAL8 | SFTwindowparam, | ||
const CHAR * | SFTcomment | ||
) |
Write the given SFTVector to a single merged SFT file with the supplied filename.
Add the comment to SFT if SFTcomment != NULL.
sftVect | SFT vector to write to disk |
SFTfilename | SFT filename |
SFTwindowtype | window applied to SFT, if any |
SFTwindowparam | parameter of window |
SFTcomment | optional comment |
Definition at line 712 of file SFTfileIO.c.
int XLALWriteSFTVector2StandardFile | ( | const SFTVector * | sftVect, |
SFTFilenameSpec * | SFTfnspec, | ||
const CHAR * | SFTcomment, | ||
const BOOLEAN | merged | ||
) |
Write the given SFTVector to SFT file(s) with a standard ([4]) filename(s).
Add the comment to SFT if SFTcomment != NULL.
NOTE: The SFT filename spec is updated to reflect the filename of the written SFT, by setting the numSFTs
, detector
, SFTtimebase
, gpsStart
, and SFTspan
fields. if needed, the SFT filename can be reconstructed with XLALBuildSFTFilenameFromSpec()
sftVect | SFT vector to write to disk |
SFTfnspec | SFT filename specification used to construct filename(s) |
SFTcomment | optional comment |
merged | If true, write a single merged SFT file; otherwise, write individual SFT files |
Definition at line 755 of file SFTfileIO.c.
Verify that the contents of a SFT file are valid.
This is just an XLAL wrapper to the SFTReferenceLibrary function ValidateSFTFile().
Definition at line 834 of file SFTfileIO.c.
void endian_swap | ( | CHAR * | pdata, |
size_t | dsize, | ||
size_t | nelements | ||
) |
Definition at line 844 of file SFTfileIO.c.
FILE * fopen_SFTLocator | ( | const struct tagSFTLocator * | locator | ) |
Open an "SFT" defined by the SFT-locator, return a FILE-pointer to the beginning of this SFT.
NOTE: Ideally this should be the ONLY function using the internal structure of the opaque SFTLocator type
Definition at line 882 of file SFTfileIO.c.
Read valid SFT version-number at position fp, and determine if we need to endian-swap the data.
Restores filepointer to original position before returning.
RETURN: 0 = OK, -1 = ERROR
Definition at line 916 of file SFTfileIO.c.
int read_sft_header_from_fp | ( | FILE * | fp, |
SFTtype * | header, | ||
UINT4 * | version, | ||
UINT8 * | crc64, | ||
UINT2 * | SFTwindowspec, | ||
BOOLEAN * | swapEndian, | ||
CHAR ** | SFTcomment, | ||
UINT4 * | numBins | ||
) |
Definition at line 992 of file SFTfileIO.c.
|
static |
Definition at line 1102 of file SFTfileIO.c.
UINT4 read_sft_bins_from_fp | ( | SFTtype * | ret, |
UINT4 * | firstBinRead, | ||
UINT4 | firstBin2read, | ||
UINT4 | lastBin2read, | ||
FILE * | fp | ||
) |
Definition at line 1282 of file SFTfileIO.c.
BOOLEAN has_valid_crc64 | ( | FILE * | fp | ) |
Check the SFT-block starting at fp for valid crc64 checksum.
Restores filepointer before leaving.
Definition at line 1409 of file SFTfileIO.c.
int XLALCWGPSinRange | ( | const LIGOTimeGPS | gps, |
const LIGOTimeGPS * | minGPS, | ||
const LIGOTimeGPS * | maxGPS | ||
) |
Defines the official CW convention for whether a GPS time is 'within' a given range, defined as the half-open interval [minGPS, maxGPS)
This function should be used when dealing with SFTs, segment lists, etc. It returns:
If either minGPS
or maxGPS
are NULL
, there are treated as \( -\infty \) or \( +\infty \) respectively.
Definition at line 52 of file SFTtypes.c.
Round a REAL8 frequency down to the nearest integer SFT bin number.
This function provides an official rounding convention, including a "fudge" factor.
Definition at line 70 of file SFTtypes.c.
Round a REAL8 frequency up to the nearest integer SFT bin number.
This function provides an official rounding convention, including a "fudge" factor.
Definition at line 82 of file SFTtypes.c.
int XLALFindCoveringSFTBins | ( | UINT4 * | firstBin, |
UINT4 * | numBins, | ||
REAL8 | fMinIn, | ||
REAL8 | BandIn, | ||
REAL8 | Tsft | ||
) |
Return the 'effective' frequency-band [fMinEff, fMaxEff] = [firstBin, lastBin] * 1/Tsft, with numBins = lastBin - firstBin + 1 which is the smallest band of SFT-bins that fully covers a given band [fMin, fMin+Band].
==> calculate "effective" fMinEff by rounding down from fMin to closest (firstBin/Tsft) and rounds up in the same way to fMaxEff = (lastBin/Tsft).
The 'fudge region' allowing for numerical noise is eps= 10*LAL_REAL8_EPS ~2e-15 relative deviation: ie if the SFT contains a bin at 'fi', then we consider for example "fMin == fi" if fabs(fi - fMin)/fi < eps.
Note: this function is most useful for internal operations, e.g. where a generated time series needs to be over-sampled to cover the SFT frequency band of interest. Ultimately SFTs covering a half-open interval [fMinIn,BandIn) should be returned to the user using XLALExtractStrictBandFromSFTVector().
[out] | firstBin | effective lower frequency-bin fMinEff = firstBin/Tsft |
[out] | numBins | effective Band of SFT-bins, such that BandEff = (numBins-1)/Tsft |
[in] | fMinIn | input lower frequency |
[in] | BandIn | input frequency band |
[in] | Tsft | SFT duration 'Tsft' |
Definition at line 106 of file SFTtypes.c.
XLAL function to create one SFT-struct.
Note: Allows for numBins == 0, in which case only the header is allocated, with a NULL data pointer.
Definition at line 152 of file SFTtypes.c.
void XLALDestroySFT | ( | SFTtype * | sft | ) |
Destructor for one SFT.
Definition at line 176 of file SFTtypes.c.
Copy an entire SFT-type into another.
We require the destination-SFT to have a NULL data-entry, as the corresponding data-vector will be allocated here and copied into
Note: the source-SFT is allowed to have a NULL data-entry, in which case only the header is copied.
[out] | dest | copied SFT (needs to be allocated already) |
src | input-SFT to be copied |
Definition at line 202 of file SFTtypes.c.
XLAL function to create an SFTVector of numSFT
SFTs with SFTlen
frequency-bins (which will be allocated too).
numSFTs | number of SFTs |
numBins | number of frequency-bins per SFT |
Definition at line 230 of file SFTtypes.c.
XLAL function to create an SFTVector of numSFT
SFTs (which are not allocated).
numSFTs | number of SFTs |
Definition at line 276 of file SFTtypes.c.
void XLALDestroySFTVector | ( | SFTVector * | vect | ) |
XLAL interface to destroy an SFTVector.
Definition at line 300 of file SFTtypes.c.
Create a complete copy of an SFT vector.
Definition at line 328 of file SFTtypes.c.
MultiSFTVector * XLALCreateMultiSFTVector | ( | UINT4 | length, |
UINT4Vector * | numsft | ||
) |
Create a multi-IFO SFT vector with a given number of bins per SFT and number of SFTs per IFO (which will be allocated too).
Note that the input argument "length" refers to the number of frequency bins in each SFT. The length of the returned MultiSFTVector (i.e. the number of IFOs) is set from the length of the input numsft vector instead.
length | number of SFT data points (frequency bins) |
numsft | number of SFTs in each per-detector SFTVector |
Definition at line 362 of file SFTtypes.c.
MultiSFTVector * XLALCreateEmptyMultiSFTVector | ( | UINT4Vector * | numsft | ) |
Create an empty multi-IFO SFT vector with a given number of SFTs per IFO (which are not allocated).
numsft | number of SFTs in each per-detector SFTVector |
Definition at line 394 of file SFTtypes.c.
void XLALDestroyMultiSFTVector | ( | MultiSFTVector * | multvect | ) |
Destroy a multi SFT-vector.
multvect | the SFT-vector to free |
Definition at line 424 of file SFTtypes.c.
Return an SFTs containing only the bins in [fMin, fMin+Band].
Note: the output SFT is guaranteed to "cover" the input boundaries 'fMin' and 'fMin+Band', ie if necessary the output SFT contains one additional bin on either end of the interval.
This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to extract.
[out] | outSFT | output SFT (alloc'ed or re-alloced as required) |
[in] | inSFT | input SFT |
[in] | fMin | lower end of frequency interval to return |
[in] | Band | band width of frequency interval to return |
Definition at line 456 of file SFTtypes.c.
Return a vector of SFTs containing only the bins in [fMin, fMin+Band].
Note: the output SFT is guaranteed to "cover" the input boundaries 'fMin' and 'fMin+Band', ie if necessary the output SFT contains one additional bin on either end of the interval.
This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to extract.
[in] | inSFTs | input SFTs |
[in] | fMin | lower end of frequency interval to return |
[in] | Band | band width of frequency interval to return |
Definition at line 527 of file SFTtypes.c.
MultiSFTVector * XLALExtractBandFromMultiSFTVector | ( | const MultiSFTVector * | inSFTs, |
REAL8 | fMin, | ||
REAL8 | Band | ||
) |
Return a MultiSFT vector containing only the bins in [fMin, fMin+Band].
Note: the output MultiSFT is guaranteed to "cover" the input boundaries 'fMin' and 'fMin+Band', ie if necessary the output SFT contains one additional bin on either end of the interval.
This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to extract.
[in] | inSFTs | input MultiSFTs |
[in] | fMin | lower end of frequency interval to return |
[in] | Band | band width of frequency interval to return |
Definition at line 572 of file SFTtypes.c.
int XLALExtractStrictBandFromSFT | ( | SFTtype ** | outSFT, |
const SFTtype * | inSFT, | ||
REAL8 | fMin, | ||
REAL8 | Band | ||
) |
Return a copy of an SFT containing only the bins in [fMin, fMin+Band).
[out] | outSFT | output SFT (alloc'ed or re-alloced as required) |
[in] | inSFT | input SFT |
[in] | fMin | lower end of frequency interval to return |
[in] | Band | band width of frequency interval to return |
Definition at line 601 of file SFTtypes.c.
Return a copy of a vector of SFTs containing only the bins in [fMin, fMin+Band).
[in] | inSFTs | input SFTs |
[in] | fMin | lower end of frequency interval to return |
[in] | Band | band width of frequency interval to return |
Definition at line 658 of file SFTtypes.c.
MultiSFTVector * XLALExtractStrictBandFromMultiSFTVector | ( | const MultiSFTVector * | inSFTs, |
REAL8 | fMin, | ||
REAL8 | Band | ||
) |
Return a copy of a MultiSFT vector containing only the bins in [fMin, fMin+Band).
[in] | inSFTs | input MultiSFTs |
[in] | fMin | lower end of frequency interval to return |
[in] | Band | band width of frequency interval to return |
Definition at line 691 of file SFTtypes.c.
Append the given SFTtype to the SFT-vector (no SFT-specific checks are done!)
vect | destinatino SFTVector to append to |
sft | the SFT to append |
Definition at line 716 of file SFTtypes.c.
int XLALReorderMultiSFTVector | ( | MultiSFTVector * | multiSFTs, |
const LALStringVector * | IFOs | ||
) |
Reorder the MultiSFTVector with specified list of IFOs.
Definition at line 738 of file SFTtypes.c.
Adds SFT-data from SFT 'b' to SFT 'a'.
NOTE: the inputs 'a' and 'b' must have consistent start-frequency, frequency-spacing, timestamps, units and number of bins.
The 'name' field of input/output SFTs in 'a' is not modified!
a | [in/out] SFT to be added to | |
[in] | b | SFT data to be added |
Definition at line 775 of file SFTtypes.c.
Adds SFT-data from SFTvector 'b' to elements of SFTVector 'a'.
NOTE: the inputs 'a' and 'b' must have consistent number of SFTs, start-frequency, frequency-spacing, timestamps, units and number of bins.
The 'name' field of input/output SFTs in 'a' is not modified!
a | [in/out] SFTVector to be added to | |
[in] | b | SFTVector data to be added |
Definition at line 811 of file SFTtypes.c.
int XLALMultiSFTVectorAdd | ( | MultiSFTVector * | a, |
const MultiSFTVector * | b | ||
) |
Adds SFT-data from MultiSFTvector 'b' to elements of MultiSFTVector 'a'.
NOTE: the inputs 'a' and 'b' must have consistent number of IFO, number of SFTs, IFO-names, start-frequency, frequency-spacing, timestamps, units and number of bins.
The 'name' field of input/output SFTs in 'a' is not modified!
a | [in/out] MultiSFTVector to be added to | |
[in] | b | MultiSFTVector data to be added |
Definition at line 842 of file SFTtypes.c.
Resize the frequency-band of a given SFT to [f0, f0+Band].
NOTE: If the frequency band is extended in any direction, the corresponding bins will be set to zero
NOTE2: This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to resize to, in order to coincide with SFT frequency bins.
SFT | [in/out] SFT to resize | |
[in] | f0 | new start frequency |
[in] | Band | new frequency Band |
Definition at line 878 of file SFTtypes.c.
Resize the frequency-band of a given SFT vector to [f0, f0+Band].
NOTE: If the frequency band is extended in any direction, the corresponding bins will be set to zero
NOTE2: This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to resize to, in order to coincide with SFT frequency bins.
SFTs | [in/out] SFT vector to resize | |
[in] | f0 | new start frequency |
[in] | Band | new frequency Band |
Definition at line 917 of file SFTtypes.c.
int XLALMultiSFTVectorResizeBand | ( | MultiSFTVector * | multiSFTs, |
REAL8 | f0, | ||
REAL8 | Band | ||
) |
Resize the frequency-band of a given multi-SFT vector to [f0, f0+Band].
NOTE: If the frequency band is extended in any direction, the corresponding bins will be set to zero
NOTE2: This uses the conventions in XLALFindCoveringSFTBins() to determine the 'effective' frequency-band to resize to, in order to coincide with SFT frequency bins.
multiSFTs | [in/out] multi-SFT vector to resize | |
[in] | f0 | new start frequency |
[in] | Band | new frequency Band |
Definition at line 946 of file SFTtypes.c.
int XLALEarliestMultiSFTsample | ( | LIGOTimeGPS * | out, |
const MultiSFTVector * | multisfts | ||
) |
Finds the earliest timestamp in a multi-SFT data structure.
[out] | out | earliest GPS time |
[in] | multisfts | multi SFT vector |
Definition at line 968 of file SFTtypes.c.
int XLALLatestMultiSFTsample | ( | LIGOTimeGPS * | out, |
const MultiSFTVector * | multisfts | ||
) |
Find the time of the end of the latest SFT in a multi-SFT data structure.
[out] | out | latest GPS time |
[in] | multisfts | multi SFT vector |
Definition at line 1016 of file SFTtypes.c.
SFTVector * XLALExtractSFTVectorWithTimestamps | ( | const SFTVector * | sfts, |
const LIGOTimeGPSVector * | timestamps | ||
) |
Extract an SFTVector from another SFTVector but only those timestamps matching.
Timestamps must be a subset of those sfts in the SFTVector or an error occurs
sfts | input SFTs |
timestamps | timestamps |
Definition at line 1076 of file SFTtypes.c.
MultiSFTVector * XLALExtractMultiSFTVectorWithMultiTimestamps | ( | const MultiSFTVector * | multiSFTs, |
const MultiLIGOTimeGPSVector * | multiTimestamps | ||
) |
Extract a MultiSFTVector from another MultiSFTVector but only those timestamps matching.
Timestamps in each LIGOTimeGPSVector must be a subset of those sfts in each SFTVector or an error occurs
multiSFTs | input SFTs |
multiTimestamps | timestamps |
Definition at line 1116 of file SFTtypes.c.
LIGOTimeGPSVector * XLALCreateTimestampVector | ( | UINT4 | len | ) |
Allocate a LIGOTimeGPSVector.
Definition at line 47 of file SFTtimestamps.c.
void XLALDestroyTimestampVector | ( | LIGOTimeGPSVector * | vect | ) |
De-allocate a LIGOTimeGPSVector.
Definition at line 69 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALResizeTimestampVector | ( | LIGOTimeGPSVector * | vector, |
UINT4 | length | ||
) |
Resize a LIGOTimeGPSVector.
Definition at line 85 of file SFTtimestamps.c.
MultiLIGOTimeGPSVector * XLALCreateMultiLIGOTimeGPSVector | ( | UINT4 | numDetectors | ) |
Simple creator function for MultiLIGOTimeGPSVector with numDetectors entries.
Definition at line 110 of file SFTtimestamps.c.
void XLALDestroyMultiTimestamps | ( | MultiLIGOTimeGPSVector * | multiTS | ) |
Destroy a MultiLIGOTimeGPSVector timestamps vector.
Definition at line 135 of file SFTtimestamps.c.
int XLALFindTimesliceBounds | ( | UINT4 * | iStart, |
UINT4 * | iEnd, | ||
const LIGOTimeGPSVector * | timestamps, | ||
const LIGOTimeGPS * | minStartGPS, | ||
const LIGOTimeGPS * | maxStartGPS | ||
) |
Definition at line 158 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALMakeTimestamps | ( | LIGOTimeGPS | tStart, |
REAL8 | Tspan, | ||
REAL8 | Tsft, | ||
REAL8 | Toverlap | ||
) |
Given a start-time, Tspan, Tsft and Toverlap, returns a list of timestamps covering this time-stretch (allowing for overlapping SFTs).
NOTE: boundary-handling: the returned list of timestamps fall within the interval [tStart, tStart+Tspan), consistent with the convention defined in XLALCWGPSinRange(). Assuming each SFT covers a stretch of data of length 'Tsft', the returned timestamps correspond to a set of SFTs that is guaranteed to cover all data between 'tStart' and 'tStart+Tspan'. This implies that, while the last timestamp returned will always be 'ret->data[numSFTs-1] < tStart+Tspan', the actual data coverage can extend up to 'Tsft' beyond 'tStart+duration'.
tStart | GPS start-time |
Tspan | total duration to cover, in seconds |
Tsft | length of the SFT corresponding to each timestamp, in seconds |
Toverlap | time to overlap successive SFTs by, in seconds |
Definition at line 225 of file SFTtimestamps.c.
MultiLIGOTimeGPSVector * XLALMakeMultiTimestamps | ( | LIGOTimeGPS | tStart, |
REAL8 | Tspan, | ||
REAL8 | Tsft, | ||
REAL8 | Toverlap, | ||
UINT4 | numDet | ||
) |
Same as XLALMakeTimestamps() just for several detectors, additionally specify the number of detectors.
tStart | GPS start-time |
Tspan | total duration to cover, in seconds |
Tsft | Tsft: SFT length of each timestamp, in seconds |
Toverlap | time to overlap successive SFTs by, in seconds |
numDet | number of timestamps-vectors to generate |
Definition at line 272 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALReadTimestampsFile | ( | const CHAR * | fname | ) |
backwards compatible wrapper to XLALReadTimestampsFileConstrained() without GPS-time constraints
Definition at line 297 of file SFTtimestamps.c.
MultiLIGOTimeGPSVector * XLALReadMultiTimestampsFiles | ( | const LALStringVector * | fnames | ) |
backwards compatible wrapper to XLALReadMultiTimestampsFilesConstrained() without GPS-time constraints
Definition at line 305 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALReadTimestampsFileConstrained | ( | const CHAR * | fname, |
const LIGOTimeGPS * | minGPS, | ||
const LIGOTimeGPS * | maxGPS | ||
) |
Load timestamps file 'fname' into LIGOTimeGPSVector struct, allocated here.
The timestamps file must contain one GPS time per line, allowing for '%#' as comments, which are ignored. The constraints 'minGPS', 'maxGPS' are applied by returning only timestamps that fall within the range defined by XLALCWGPSinRange(gps, minGPS, maxGPS) == 0.
check input consistency
Definition at line 319 of file SFTtimestamps.c.
MultiLIGOTimeGPSVector * XLALReadMultiTimestampsFilesConstrained | ( | const LALStringVector * | fnames, |
const LIGOTimeGPS * | minGPS, | ||
const LIGOTimeGPS * | maxGPS | ||
) |
Load several timestamps files, return a MultiLIGOTimeGPSVector struct, allocated here.
The timestamps files must contain one GPS time per line, allowing for '%#' as comments, which are ignored. The constraints 'minGPS', 'maxGPS' are applied by returning only timestamps that fall within the range defined by XLALCWGPSinRange(gps, minGPS, maxGPS) == 0.
Definition at line 388 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALExtractTimestampsFromSFTs | ( | const SFTVector * | sfts | ) |
Extract timstamps-vector from the given SFTVector.
[in] | sfts | input SFT-vector |
Definition at line 416 of file SFTtimestamps.c.
MultiLIGOTimeGPSVector * XLALExtractMultiTimestampsFromSFTs | ( | const MultiSFTVector * | multiSFTs | ) |
Given a multi-SFT vector, return a MultiLIGOTimeGPSVector holding the SFT timestamps.
Definition at line 449 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALTimestampsFromSFTCatalog | ( | const SFTCatalog * | catalog | ) |
Extract timestamps-vector of unique timestamps from the given SFTCatalog.
NOTE: when dealing with catalogs of frequency-slided SFTs, each timestamp will appear in the catalog multiple times, depending on how many frequency slices have been read in. In such cases this function will return the list of unique timestamps.
NOTE 2: This function will also enfore the multiplicity of each timestamp to be the same through the whole catalog, corresponding to the case of 'frequency-sliced' SFTs, while non-constant multiplicities would indicate a potential problem somewhere.
[in] | catalog | input SFT-catalog |
Definition at line 500 of file SFTtimestamps.c.
MultiLIGOTimeGPSVector * XLALTimestampsFromMultiSFTCatalogView | ( | const MultiSFTCatalogView * | multiView | ) |
Given a multi-SFTCatalogView, return a MultiLIGOTimeGPSVector holding the SFT timestamps.
Definition at line 560 of file SFTtimestamps.c.
LALSegList * XLALReadSegmentsFromFile | ( | const char * | fname | ) |
Function to read a segment list from given filename, returns a sorted LALSegList.
The segment list file format is repeated lines (excluding comment lines beginning with %
or #
) of one of the following forms:
startGPS endGPS
startGPS endGPS NumSFTs
(NumSFTs must be a positive integer)startGPS endGPS duration NumSFTs
(DEPRECATED, duration is ignored)id
field in LALSeg to carry the total number of SFTs contained in that segment if NumSFTs
was provided in the segment file. This can be used as a consistency check when loading SFTs for these segments. fname | name of file containing segment list |
Definition at line 598 of file SFTtimestamps.c.
LIGOTimeGPSVector * XLALTimestampsFromSegmentFile | ( | const char * | filename, |
REAL8 | Tsft, | ||
REAL8 | Toverlap, | ||
BOOLEAN | adjustSegExtraTime, | ||
BOOLEAN | synchronize | ||
) |
Extract timestamps-vector from a segment file, with functionality based on MakeSFTDAG The filename should point to a file containing <GPSstart GPSend> of segments or <GPSstart GPSend segLength numSFTs> where segLength is in hours.
adjustSegExtraTime is used in MakeSFTDAG to maximize the number of SFTs in each segement by placing the SFTs in the middle of the segment. synchronize is used to force the start times of the SFTs to be integer multiples of Toverlap from the start time of the first SFT. adjustSegExtraTime and synchronize cannot be used concurrently (synchronize will be preferred if both values are non-zero).
filename | filename: Input filename |
Tsft | Tsft: SFT length of each timestamp, in seconds |
Toverlap | Toverlap: time to overlap successive SFTs by, in seconds |
adjustSegExtraTime | adjustSegExtraTime: remove the unused time from beginning and end of the segments (see MakeSFTDAG) |
synchronize | synchronize: synchronize SFT start times according to the start time of the first SFT. Start time of first SFT is shifted to next higher integer value of Tsft |
Definition at line 694 of file SFTtimestamps.c.
int XLALRegisterSpecialCWDetector | ( | const LALDetector * | specialDetector | ) |
Register a special detector for use with CW codes.
The special detector must have a 2-character prefix of the form "[XYZ][0123456789]".
Definition at line 73 of file SFTnaming.c.
int XLALFindCWDetector | ( | CHAR ** | prefix, |
INT4 * | lalCachedIndex, | ||
const CHAR * | name, | ||
const BOOLEAN | exactMatch | ||
) |
Parses valid CW detector names and prefixes.
'name' input can be either a valid detector name or prefix
If passed a non-NULL pointer 'prefix', will be set to the Allocated prefix string (2 characters+0) for valid detectors, NULL otherwise.
If passed a non-NULL pointer 'lalCachedIndex', will set to index >= 0 into the lalCachedDetectors[] array if found there, or -1 if it's one of the "CW special" detectors
Definition at line 118 of file SFTnaming.c.
Determine if 'name' is a valid detector name or prefix.
Definition at line 188 of file SFTnaming.c.
Find the valid CW detector prefix.
'name' input can be either a valid detector name or prefix
Definition at line 203 of file SFTnaming.c.
const LALDetector * XLALGetSiteInfo | ( | const CHAR * | name | ) |
Find the site geometry-information 'LALDetector' for given a detector name (or prefix).
Definition at line 218 of file SFTnaming.c.
int XLALFillSFTFilenameSpecStrings | ( | SFTFilenameSpec * | spec, |
const CHAR * | path, | ||
const CHAR * | extn, | ||
const CHAR * | detector, | ||
const CHAR * | window_type, | ||
const CHAR * | privMisc, | ||
const CHAR * | pubObsKind, | ||
const CHAR * | pubChannel | ||
) |
Convenience function for filling out the string fields in a SFTFilenameSpec.
[out] | spec | SFT filename specification |
[in] | path | Path to the SFT file |
[in] | extn | Extension of the SFT file; defaults to 'sft' |
[in] | detector | 2-character detector prefix (e.g. 'H1', 'L1', 'V1') |
[in] | window_type | window function applied to SFT |
[in] | privMisc | For private SFTs: miscellaneous description field |
[in] | pubObsKind | For public SFTs: kind of data ('RUN', 'AUX', 'SIM', 'DEV') |
[in] | pubChannel | For public SFTs: channel name of data used to make SFTs |
Definition at line 257 of file SFTnaming.c.
char * XLALBuildSFTFilenameFromSpec | ( | const SFTFilenameSpec * | spec | ) |
Build an SFT file name from the given specification.
[in] | spec | SFT filename specification |
Definition at line 302 of file SFTnaming.c.
int XLALParseSFTFilenameIntoSpec | ( | SFTFilenameSpec * | spec, |
const char * | SFTpath | ||
) |
Parse a SFT file path and return its specification.
[out] | spec | SFT filename specification |
[in] | SFTpath | SFT file path |
Definition at line 463 of file SFTnaming.c.
Check whether given string qualifies as a valid 'description' field of a FRAME filename (per [25]) or SFT filename (per [4])
Definition at line 639 of file SFTnaming.c.
int XLALCompareSFTWindows | ( | const CHAR * | type1, |
const REAL8 | param1, | ||
const CHAR * | type2, | ||
const REAL8 | param2 | ||
) |
Check whether two SFT windows, each defined by a type name and parameter value, match.
This builds standardized windowspec numbers out of the inputs and compares those, ensuring consistent rounding before the comparison.
[in] | type1 | type name of the first window |
[in] | param1 | parameter value of the first window |
[in] | type2 | type name of the second window |
[in] | param2 | parameter value of the second window |
Definition at line 667 of file SFTnaming.c.
LALStringVector * XLALFindFiles | ( | const CHAR * | globstring | ) |
Returns a list of filenames matching the input argument, which may be one of the following:
<file>[;<file>;...]
: a list of filenames.<glob>[;<glob>;...]
: a list of glob-like pattern(s) such as *.sft
, ./dir/*.sft
, etc.list:<filelist>
: a file containing a list of filenames. Prefixes of the form file://localhost/
or file:///
are removed.Note: the list of filenames is returned sorted alphabetically.
Definition at line 61 of file FindFiles.c.
int build_sft_windowspec | ( | UINT2 * | windowspec, |
CHAR(*) | windowspec_str[9], | ||
const char * | window_type, | ||
REAL8 | window_param | ||
) |
Build an SFT 2-byte 'windowspec' or filename field 'windowspec_str' for the window given by 'window_type' and 'window_param'.
Definition at line 691 of file SFTnaming.c.
int parse_sft_windowspec | ( | const UINT2 | windowspec, |
const char ** | window_type, | ||
REAL8 * | window_param | ||
) |
Parse an SFT 2-byte 'windowspec' into a window name 'window_type' and possible parameter 'window_param'.
Definition at line 752 of file SFTnaming.c.
int parse_sft_windowspec_str | ( | const CHAR * | windowspec_str, |
CHAR(*) | window_type[32], | ||
REAL8 * | window_param | ||
) |
Parse an SFT filename field 'windowspec_str' into a window name 'window_type' and possible parameter 'window_param'.
Definition at line 802 of file SFTnaming.c.
Definition at line 1144 of file SFTtypes.c.
Definition at line 1161 of file SFTtypes.c.
Definition at line 1182 of file SFTtypes.c.
Definition at line 1208 of file SFTtypes.c.
Definition at line 1231 of file SFTtypes.c.
typedef COMPLEX8FrequencySeries SFTtype |
A so-called 'SFT' (short-Fourier-transform) will be stored in a COMPLEX8FrequencySeries.
Definition at line 173 of file SFTfileIO.h.
The corresponding vector-type to hold a vector of 'SFTs'.
Definition at line 176 of file SFTfileIO.h.