Conventions have been defined for GWOLLUM objects. This set of rules was introduced to make sure that GWOLLUM class functions work properly. This page describes the conventions used for the different GWOLLUM objects.

Index:

A segment is a time interval limited by 2 GPS times: [GPS_START] (included) and [GPS_END] (excluded). A segment list must respect the following rules:

• [GPS_START] must always be larger than or equal to 700000000 (Mar 12 2002 20:26:27 UTC)
• For each segment [GPS_END] is greater than (and not equal to) [GPS_START]
• The list is time-sorted by increasing [GPS_START]

Segments can be individually tagged. This tag must respect conventions:

• [TAG] is an integer
• [TAG]≥0
• [TAG]=-1 is the default value (it basically means 'no tag')

Operations on segments (like merging, intersection...) requires rules for propagating the tags:

• [TAG1] * [TAG2] =
  • -1, if [TAG1] = -1, whatever the [TAG2] value is
  • -1, if [TAG2] = -1, whatever the [TAG1] value is
  • Max([TAG1], [TAG2]), if [TAG1] > -1 and [TAG2] > -1
• [TAG1] + [TAG2] = Max([TAG1], [TAG2]).

A segment list can be described by several containers which have specific conventions:

The segment list is internally managed by a Segments object. Overlapping segments are internally merged (in particular, if a segment ends where the next one starts). The merging of tags obeys to the [TAG1] + [TAG2] law described above.

A segment text file is an ASCII file listing the time segments (one segment per line). Several formats are supported defined by the number of columns:

• 2 columns: [GPS_START] [GPS_END]
• 3 columns: [SEGMENT_INDEX] [GPS_START] [GPS_END]
• 4 columns: [SEGMENT_INDEX] [GPS_START] [GPS_END] [DURATION]
• 5 columns: [SEGMENT_INDEX] [GPS_START] [GPS_END] [DURATION] [TAG]

A segment TTree is a ROOT TTree listing the time segments (one segment per tree entry). The [GPS_START] values are stored in a TBranch (double) named 'start' and [GPS_END] values are stored in a TBranch (double) named 'end'. The tree index is based on [GPS_START]. An optional TBranch can be added to store the tag values. It is named 'tag' and is of type int.

A stream (or data stream) is used to describe a gravitational-wave detector channel. It is characterized by:

1. A full name with the following format: [prefix]:[suffix]
2. A prefix composed of 2 letters before the first column in the full name
3. A suffix composed of, at least, one letter after the first column in the full name

A stream can be associated to a LIGO-Virgo detector. This is done using the prefix of the stream:

• [prefix] = 'V1': Virgo detector
• [prefix] = 'H1': Hanford 1 detector
• [prefix] = 'H2': Hanford 2 detector
• [prefix] = 'L1': Linvingston detector

When this is done, the stream gets new attributes associated to the detector: position, orientation, antenna factors etc.

CONTENT

A Triggers object must be composed of 2 TTree structures named 'triggers' and 'segments'. One optional TTree named 'metadata' can be added. The 2(+1) TTree objects must be saved in the same ROOT TDirectory.

SEGMENTS

The 'segments' tree must contain 2 variables of type double and named:

	  start   [s]
	  end     [s]
	

Each tree entry represents one continuous time segment in which the trigger generator was on and stable. Each time segment must follow the GWOLLUM convention for Segments. It is mandatory that the 'segments' tree is not empty and with a non-zero livetime. Time segments can overlap, if so, they are merged and considered as a single segment.

TRIGGERS

The 'triggers' tree must contain 10 variables of type double and named:

	  time           [s]   peak time (precision: 1e-6s)
	  frequency      [Hz]  peak frequency
	  tstart         [s]   starting time
	  tend           [s]   ending time
	  fstart         [Hz]  starting frequency
	  fend           [Hz]  ending frequency
	  snr            [-]   SNR
	  q              [-]   quality factor
	  amplitude      [Hz^-½] amplitude
	  phase          [rad] phase
	

Each tree entry represents one trigger. The tree entries must verify the following conditions:

• Entries must be sorted by increasing 'tstart'.
• 'tstart' ≤ 'time' ≤ 'tend'.
• 'fstart' ≤ 'frequency' ≤ 'fend'.
• All 'time' and 'tstart' values must be contained in at least one time segment of the 'segments' object.

META-DATA

Meta-data can be saved along with the triggers. A TTree named 'metadata' contains one set of metadata per entry. Each tree branch represents a meta-data field. The name and type of meta-data are free. Only 2 meta-data fields are mandatory and expected to be found:

	  start [double]
	  end   [double]
	

These branches are used to map the meta-data and the triggers. The set of meta-data is applied to every trigger with start ≤ 'time' ≤ end. For the sake of unicity, the segments [start-end] should not overlap (but can be contiguous). Moreover, they should not conflict with the segments structure. This means that the meta-data segments should be entirely contained in the trigger segments.

If the meta-data content is free, a set of pre-defined meta-data containers are reserved to be used by GWOLLUM applications. Filling these fields is not mandatory but very helpful for external applications:

	  'Mprocessname' [string] = process name used to produce the triggers
	  'Mstreamname'  [string] = name of the processed stream
	  'Mdetindex'    [int]    = detector index
	  'Mfmin'        [double] = minimum trigger 'frequency' value
	  'Mfmax'        [double] = maximum trigger 'frequency' value
	  'Mqmin'        [double] = minimum trigger 'q' value
	  'Mqmax'        [double] = maximum trigger 'q' value
	  'Msnrmin'      [double] = minimum trigger 'snr' value
	  'Msnrmax'      [double] = maximum trigger 'snr' value
	

FILE NAMING

A trigger object must be saved in a ROOT format. Any name can be given to a trigger file as long it has a ".root" extension. There is a GWOLLUM convention which is optional but it is suggested to follow it:

[STREAMPREFIX]-[STREAMSUFFIX]_[PROCESSNAME]-[START]-[DURATION].root

[STREAMPREFIX]: stream prefix extracted from the triggers metadata streamname.
[STREAMSUFFIX]: stream suffix extracted from the triggers metadata streamname.
[PROCESSNAME]:  process name extracted from the triggers metadata processname.
[START]:        starting time of the first segment of 'segments' rounded to the integer below.
[DURATION]:     [ending time of the last segment of 'segments' rounded to the integer above] - [START].
	

Many GWOLLUM classes or applications come with the definition of a verbosity level usually set in the constructors. The printing is performed in the standard output stream. The verbosity level is an integer flag defined as follows:

• verbosity = 0 : minimal printing
• verbosity = 1 : basic printing to keep track of the evolution through the code
• verbosity = 2 : high level printing with more information about the process internal parameters
• verbosity > 2 : full printing with debugging information