Triggers Class Reference

Write triggers in a ROOT format. More...

#include <Triggers.h>

Collaboration diagram for Triggers:

Public Member Functions
bool	AddSegment (const double gps_start, const double gps_end, const int tag=-1)
	Adds a segment to the Triggers object.
bool	AddSegments (Segments *aSeg)
	Adds segments to the Triggers object.
bool	AddTrigger (const double atime, const double afrequency, const double asnr, const double aq, const double atstart, const double atend, const double afstart, const double afend, const double aamp)
	Adds a trigger to the Triggers object.
bool	GetMaxFlag (void)
	Returns the max limit flag value.
bool	GetNtrig (void)
	Returns the current number of triggers in memory.
bool	GetNTrig (void)
	Returns the current number of triggers in memory.
Segments *	GetTriggerSegments (TH1D *aThr, const double aPadding=0.0, const double aInfValue=1e20)
	Returns a set of segments built with triggers above a given threshold.
bool	InitUserMetaData (vector< string > aMusername, vector< string > aMusertype)
	Initializes the user-defined meta-data fields.
bool	Reset (void)
	Resets the Triggers objects.
bool	SetClusterDeltaT (const double DeltaT)
	Sets the clustering delta_t parameter.
bool	SetClustering (const string Algo="TIME")
	Activates the clustering.
void	SetMdetindex (const int aMdetindex)
	Set the detector index value for the meta-data field 'Mdetindex'.
void	SetMprocessname (const string aMprocessname)
	Set the process name for the meta-data field 'Mprocessname'.
void	SetMstreamname (const string aMstreamname)
	Set the stream name for the meta-data field 'Mstreamname'.
void	SetNtriggerMax (const int aNmax)
	Sets the maximum number of triggers per file (NtriggerMax).
bool	SetOutputDirectory (const string aoutdir)
	Sets a new output directory to save trigger files.
bool	SetSegments (Segments *aSeg)
	Sets segments to the Triggers object.
bool	SetUserMetaData (const string aMusername, const string aMuservalue)
	Set user-defined meta-data.
bool	SetUserMetaData (const string aMusername, const int aMuservalue)
	Set user-defined meta-data.
bool	SetUserMetaData (const string aMusername, const double aMuservalue)
	Set user-defined meta-data.
void	SetVerbose (const int averbose)
	Sets verbosity level.
string	Write (const string mode="PROC", const string filename="default", const bool sorttriggers=true, const bool writemetadata=true)
	Writes triggers on disk.
Constructors and destructors

	Triggers (const string aoutdir, const string aoutfile, const string afileformat="root", const int averbose=0)
	Constructor of the Triggers class.
virtual	~Triggers (void)
	Destructor of the Triggers class.
Protected Attributes
double	Camp
	cluster amplitude
double	Cdelta_t
	clustering time window in ms
double	Cfend
	cluster frequency end
double	Cfreq
	cluster frequency
double	Cfstart
	cluster frequency start
bool	cluster_OK
	clustering flag
double	Cq
	cluster Q
double	Csnr
	cluster SNR
double	Ctend
	cluster time end
double	Ctime
	cluster time
TTree *	Ctree
	clusters tree
double	Ctstart
	cluster time start
string	fAlgo
	clustering algorithm
vector< string >	ffileformat
	output file formats
string	foutdir
	output directory
string	foutfile
	output file base name
int	fverbose
	verbosity level
bool	Maxflag
	maximum number of triggers flag
int	Mdetindex
	meta detector index
double *	Mdvar
	user metatree var - double
double	Mend
	meta end time
double	Mfmax
	meta maximum frequency
double	Mfmin
	meta minimum frequency
int *	Mivar
	user metatree var - int
string	Mprocessname
	meta process name
double	Mqmax
	meta maximum Q
double	Mqmin
	meta minimum Q
double	Msnrmax
	meta maximum SNR
double	Msnrmin
	meta minimum SNR
double	Mstart
	meta start time
string	Mstreamname
	meta stream name
string *	Msvar
	user metatree var - string
TTree *	Mtree
	metadata tree
vector< string >	Musername
	user metadata name
vector< string >	Musertype
	user metadata type
int	NtriggerMax
	maximum number of triggers per file
Segments *	Seg
	segment structure
bool	status_OK
	class status
double	Tamp
	trigger amplitude
double	Tfend
	trigger ending frequency
double	Tfreq
	trigger peak frequency
double	Tfstart
	trigger starting frequency
double	Tq
	trigger Q
double	Tsnr
	trigger SNR
Streams *	Tstream
	stream structure
double	Ttend
	trigger ending time
double	Ttime
	trigger peak time
TTree *	Ttree
	triggers tree
double	Ttstart
	trigger starting time
int	Ttstart_ms
	trigger starting time (ms)

Detailed Description

Write triggers in a ROOT format.

This class was designed to write triggers in a ROOT tree following the GWOLLUM convention for triggers. When triggers are produced by some external algorithms, the Triggers class can be used to manage output triggers, to save them and to perform some basic operations (like clustering).

Author:: Florent Robinet

Constructor & Destructor Documentation

Triggers::Triggers	(	const string	aoutdir,
		const string	aoutfile,
		const string	afileformat = `"root"`,
		const int	averbose = `0`
	)

Constructor of the Triggers class.

The trigger files are saved in the directory 'aoutdir'. The base name for the file name is 'aoutfile'. No file extension should be given in 'aoutfile'. The file name is completed by the timing of the triggers contained in the file. The output file format is determined by 'afileformat'. The verbosity level, set by 'averbose', follows the GWOLLUM convention for verbosity.

Supported file formats:

root (default): ROOT format
txt: text file with columns
xml: sngl_burst table following the LIGO conventions

To save the triggers in several different formats, enter a string containing all the desired formats.

It should be noted that saving triggers in a format other than ROOT is a dead-end for GWOLLUM. Indeed, GWOLLUM is entirely based on ROOT, therefore, GWOLLUM routines can only read and process triggers if they are saved in a ROOT format. For this reason, the user is strongly encouraged to save triggers in a ROOT format.

Parameters:

	aoutdir	output directory
	aoutfile	base name for output trigger files
	afileformat	output file formats
	averbose	verbosity level

Triggers::~Triggers ( void ) [virtual]

Destructor of the Triggers class.

Member Function Documentation

bool Triggers::AddSegment	(	const double	gps_start,
		const double	gps_end,
		const int	tag = `-1`
	)

Adds a segment to the Triggers object.

No check is performed with respect to the triggers added with AddTrigger(). The user must make sure that the segment is compatible with the triggers as described in the GWOLLUM convention for triggers. true is returned in case of success.

Parameters:

	gps_start	segment start
	gps_end	segment end
	tag	segment tag

bool Triggers::AddSegments ( Segments * aSeg )

Adds segments to the Triggers object.

No check is performed with respect to the triggers added with AddTrigger(). The user must make sure that the segments are compatible with the triggers as described in the GWOLLUM convention for triggers. true is returned in case of success.

Parameters:

aSeg

Segments object to be added

bool Triggers::AddTrigger	(	const double	atime,
		const double	afrequency,
		const double	asnr,
		const double	aq,
		const double	atstart,
		const double	atend,
		const double	afstart,
		const double	afend,
		const double	aamp
	)

Adds a trigger to the Triggers object.

The trigger parameters are defined in the GWOLLUM convention for triggers. The timing parameters (time, tstart and tend) are recorded with a precision of 1 microsecond.

The number of added triggers cannot exceed NtriggerMax fixed by the SetNtriggerMax() function, false is returned if this value is exceeeded.

Parameters:

	atime
	afrequency
	asnr
	aq
	atstart	= Min( atstart, atime )
	atend	= Max( atend, atime )
	afstart	= Min( afstart, afrequency )
	afend	= Max( afend, afrequency )
	aamp

bool Triggers::GetMaxFlag ( void ) [inline]

Returns the max limit flag value.

If true, no trigger can be added anymore. The Write() or Reset() must be called to turn this flag off.

bool Triggers::GetNtrig ( void ) [inline]

Returns the current number of triggers in memory.

bool Triggers::GetNTrig ( void ) [inline]

Returns the current number of triggers in memory.

Segments * Triggers::GetTriggerSegments	(	TH1D *	aThr,
		const double	aPadding = `0.0`,
		const double	aInfValue = `1e20`
	)

Returns a set of segments built with triggers above a given threshold.

The threshold object is an histogram binned in frequency and filled with SNR thresholds. Triggers are selected when applying the SNR threshold at the trigger frequency. For each selected trigger, a segment is defined from tstart to tend. A time pad can be added at both segment ends with 'aPadding'.

If, for some frequency bins, the SNR threshold exceeds 'aInfValue', the threshold is considered as infinite and no triggers can be selected for this frequency bin.

NB: The user is in charge of deleting the output Segments object.

NB: This function should be called while the triggers ar still memory. For example, it should be called before the Write() function is called.

If this function fails, an empty Segments is returned.

Parameters:

	aThr	SNR threshold binned in frequency
	aPadding	extra time padding to be added at both segment ends
	aInfValue	SNR value above which the threshold is considered as infinitely high.

bool Triggers::InitUserMetaData	(	vector< string >	aMusername,
		vector< string >	aMusertype
	)

Initializes the user-defined meta-data fields.

'aMusername' should be a non-empty vector with the list of meta-data names. 'aMuservalue' should be a vector with the list of meta-data types (same size as aMusername). Supported types: "d" for double, "i" for int, "s" for string. Default values are -1 for double and int types and "none" for string type.

Parameters:

	aMusername	vector of metadata names
	aMusertype	vector of metadata types (i/d/s)

bool Triggers::Reset ( void )

Resets the Triggers objects.

Triggers, clusters, segments and metadata are reset.

bool Triggers::SetClusterDeltaT ( const double DeltaT )

Sets the clustering delta_t parameter.

For the "TIME" clustering algorithm, this function sets a new value for the delta_t parameter. This value must be given in seconds and cannot be smaller than 0.001s. See SetClustering().

Parameters:

DeltaT

new delta_t value

bool Triggers::SetClustering ( const string Algo = "TIME" )

Activates the clustering.

A clustering algorithm can be applied on produced triggers. This function initiates the clustering method. It should be called <u>once</u> before writing the first output file with the Write() function. If the ROOT format was chosen, the output tree containing the clusters will be named 'clusters'.

true is returned in case of success.

Several clustering algorithms are available and are set by the 'Algo' option.

Q-clustering (Algo="Q")

   This method was specifically developed for Omicron triggers.
   Triggers are represented by tiles laying on time-frequency maps. 
   A time-frequency map is defined by a Q value. With this clustering
   method when 2 tiles overlap in time or in frequency, only the tile
   with the highest SNR is kept.
   This clustering method can be highly destructive.

Time-clustering (Algo="TIME")

   A trigger is defined by a time value and a duration (tend - tstart).
   This clustering method can be described by the following logic:
                                                       'time'
   A trigger can be represented by a time segment:  |----||--------|
                                                 tstart           tend
   
   2 consecutive triggers are clustered if they verify one of the 2 following scenarios:
   
   Scenario#1: overlapping triggers,
        trigger#1 |---||---------|
        trigger#2            |--------||--|
   
   Scenario#2: if the distance inter-triggers dt < delta_t,
        trigger#1 |---||---------|
        trigger#2                      |--------||--| 
                                 <----->
                                    dt
   
   In Scenario#2, 2 consecutive triggers are clustered if the time distance
   between them is smaller than the delta_t parameter. This parameter is equal
   to 100ms by default. It can be changed with the SetClusterDeltaT() function.

The new cluster takes the characteristics of the loudest trigger of the cluster, i.e. the 'time', 'frequency', 'q', 'amplitude' and 'snr' values. The time and frequency boundaries variables are integrated over the full cluster.

Parameters:

Algo

clustering algorithm

void Triggers::SetMdetindex ( const int aMdetindex ) [inline]

Set the detector index value for the meta-data field 'Mdetindex'.

See GWOLLUM convention. By default Mdetindex = guessed from the file base name given in Triggers().

Parameters:

aMdetindex

detector index

void Triggers::SetMprocessname ( const string aMprocessname ) [inline]

Set the process name for the meta-data field 'Mprocessname'.

See GWOLLUM convention. By default Mprocessname = "unknown".

Parameters:

aMprocessname

process name

void Triggers::SetMstreamname ( const string aMstreamname ) [inline]

Set the stream name for the meta-data field 'Mstreamname'.

See GWOLLUM convention. By default Mstreamname = file base name given in Triggers().

Parameters:

aMstreamname

stream name

void Triggers::SetNtriggerMax ( const int aNmax ) [inline]

Sets the maximum number of triggers per file (NtriggerMax).

No trigger can be added if this limit is reached. By default the number of triggers is limited to 1,000,000 per file.

Parameters:

aNmax

new limit value

bool Triggers::SetOutputDirectory ( const string aoutdir ) [inline]

Sets a new output directory to save trigger files.

The new directory must exist.

Parameters:

aoutdir

new output directory

bool Triggers::SetSegments ( Segments * aSeg )

Sets segments to the Triggers object.

When this function is used any previous Segments object is deleted and replaced by this new set of segments.

No check is performed with respect to the triggers added with AddTrigger(). The user must make sure that the segments are compatible with the triggers as described in the GWOLLUM convention for triggers. true is returned in case of success.

Parameters:

aSeg

Segments object to be used

bool Triggers::SetUserMetaData	(	const string	aMusername,
		const string	aMuservalue
	)

Set user-defined meta-data.

Set the meta-data named 'aMusername' with the value 'aMuservalue'.

Parameters:

	aMusername	metadata name
	aMuservalue	metadata value

bool Triggers::SetUserMetaData	(	const string	aMusername,
		const int	aMuservalue
	)

Set user-defined meta-data.

Set the meta-data named 'aMusername' with the value 'aMuservalue'.

Parameters:

	aMusername	metadata name
	aMuservalue	metadata value

bool Triggers::SetUserMetaData	(	const string	aMusername,
		const double	aMuservalue
	)

Set user-defined meta-data.

Set the meta-data named 'aMusername' with the value 'aMuservalue'.

Parameters:

	aMusername	metadata name
	aMuservalue	metadata value

void Triggers::SetVerbose ( const int averbose ) [inline]

Sets verbosity level.

Parameters:

averbose

new verbosity level

string Triggers::Write	(	const string	mode = `"PROC"`,
		const string	filename = `"default"`,
		const bool	sorttriggers = `true`,
		const bool	writemetadata = `true`
	)

Writes triggers on disk.

This function writes all the triggers added until now in the output file as well as the segment and metadata trees. The Triggers object is then completely resetted and the user can add more triggers with the AddTrigger() function and call the Write() function again and so on... The user should be careful and call this function often enough not to reach the maximum number of triggers per file (1,000,000 by default).

The output file path is returned. "none" is returned if this function fails in some way.

If the clustering has been activated, clustering is then performed here, just before writing the output file.

The optional argument 'mode' is only taken into account if the clustering mode was activated. In that case, the user can choose between 2 writing modes:

mode="PROC" (default), only clusters will be saved in a tree named 'clusters'.
mode="UNPROC", only unclustered triggers will be saved in a tree named 'triggers'.
mode="ALL", 2 trees will be saved, unclustered triggers will be saved in a tree named 'triggers' and clusters will be saved in a tree named 'clusters'. If triggers are saved in a text or xml file, then this option is useless, only the "PROC" mode will be applied.

The optional argument 'filename' allows to bypass the file naming GWOLLUM convention. With this option, the triggers will be saved in: [aoutdir]/[filename].[afileformat], where 'aoutdir' and 'afileformat' are given in the constructor.

If the optional flag 'sorttriggers' is set to true, the collected triggers are first sorted by starting times before being saved on disk. This flag can be set to false if the user knows that the triggers were already added with the correct time order.

Parameters:

	mode	writing mode: "PROC" or "ALL"
	filename	new base name for ouput file
	sorttriggers	flag to sort triggers before saving
	writemetadata	flag to save metadata tree

Member Data Documentation

double Triggers::Camp [protected]

cluster amplitude

double Triggers::Cdelta_t [protected]

clustering time window in ms

double Triggers::Cfend [protected]

cluster frequency end

double Triggers::Cfreq [protected]

cluster frequency

double Triggers::Cfstart [protected]

cluster frequency start

bool Triggers::cluster_OK [protected]

clustering flag

double Triggers::Cq [protected]

cluster Q

double Triggers::Csnr [protected]

cluster SNR

double Triggers::Ctend [protected]

cluster time end

double Triggers::Ctime [protected]

cluster time

TTree* Triggers::Ctree [protected]

clusters tree

double Triggers::Ctstart [protected]

cluster time start

string Triggers::fAlgo [protected]

clustering algorithm

vector<string> Triggers::ffileformat [protected]

output file formats

string Triggers::foutdir [protected]

output directory

string Triggers::foutfile [protected]

output file base name

int Triggers::fverbose [protected]

verbosity level

bool Triggers::Maxflag [protected]

maximum number of triggers flag

int Triggers::Mdetindex [protected]

meta detector index

double* Triggers::Mdvar [protected]

user metatree var - double

double Triggers::Mend [protected]

meta end time

double Triggers::Mfmax [protected]

meta maximum frequency

double Triggers::Mfmin [protected]

meta minimum frequency

int* Triggers::Mivar [protected]

user metatree var - int

string Triggers::Mprocessname [protected]

meta process name

double Triggers::Mqmax [protected]

meta maximum Q

double Triggers::Mqmin [protected]

meta minimum Q

double Triggers::Msnrmax [protected]

meta maximum SNR

double Triggers::Msnrmin [protected]

meta minimum SNR

double Triggers::Mstart [protected]

meta start time

string Triggers::Mstreamname [protected]

meta stream name

string* Triggers::Msvar [protected]

user metatree var - string

TTree* Triggers::Mtree [protected]

metadata tree

vector<string> Triggers::Musername [protected]

user metadata name

vector<string> Triggers::Musertype [protected]

user metadata type

int Triggers::NtriggerMax [protected]

maximum number of triggers per file

Segments* Triggers::Seg [protected]

segment structure

bool Triggers::status_OK [protected]

class status

double Triggers::Tamp [protected]

trigger amplitude

double Triggers::Tfend [protected]

trigger ending frequency

double Triggers::Tfreq [protected]

trigger peak frequency

double Triggers::Tfstart [protected]

trigger starting frequency

double Triggers::Tq [protected]

trigger Q

double Triggers::Tsnr [protected]

trigger SNR

Streams* Triggers::Tstream [protected]

stream structure

double Triggers::Ttend [protected]

trigger ending time

double Triggers::Ttime [protected]

trigger peak time

TTree* Triggers::Ttree [protected]

triggers tree

double Triggers::Ttstart [protected]

trigger starting time

int Triggers::Ttstart_ms [protected]

trigger starting time (ms)

The documentation for this class was generated from the following files:

/afs/in2p3.fr/throng/virgo/virgoDev/GWOLLUM/v1r3/src/Triggers/Triggers.h
/afs/in2p3.fr/throng/virgo/virgoDev/GWOLLUM/v1r3/src/Triggers/Triggers.cc

Triggers Class Reference

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation