Program to evaluate the performance of time-domain vetoes against a list of triggers. More...

#include "VVetoPerf.h"
#include <OmicronUtils.h>

Include dependency graph for vp-makeperf.cc:

Functions
int	main (int argc, char *argv[])
	Main program.

int	printhelp (void)
	Usage funcion.

Detailed Description

Program to evaluate the performance of time-domain vetoes against a list of triggers.

The program takes as a basic input a set of triggers and a set of vetoes. It generates a html report to present the result of the analysis. vp-makeperf uses methods of the VetoPerf class.

Input

The triggers must be provided as ROOT files following the GWOLLUM convention. The triggers are clustered: clusters are used to evaluate the veto performance. The vp-makeperf program is able to discover centralized Omicron triggers using the channel= option.

The performance is evaluated for sub-categories of clusters defined by a SNR threshold: snr-thresholds=.

A veto is defined by a list of time segments. This list can be provided with a text file listing the GPS time segments (veto-files=). It is also possible to provide a veto channel and a threshold: the veto time segments are extracted when the channel value is above the threshold (veto-channels=). For veto channels, a FFL file must be provided with ffl=.

Basic principle

A cluster is vetoed if the cluster peak time stands inside a veto time segment. The veto performance is characterized by a few absolute numbers:

dead-time: total amount of time rejected by a veto
number of vetoed clusters as function of the SNR
number of veto segments actually used to veto clusters

It is also convenient to use relative numbers:

dead-time over the total livetime
number of vetoed clusters over the total number of clusters in the input data set. This is also called "veto efficiency". This is also given as a function of the SNR.
number of veto segments actually used to veto clusters over the total number of veto segments. This is also called "used percentage".

Warning: These relative numbers only make sense if they are computed over the same reference livetime. In other words, it is important that both the veto segments and the clusters are produced over the same time segments (no more, no less). If this is not the case, the intersection must be considered (vp-makeperf will do it for you).

vp-makeperf measures all the numbers presented above. It also generates plots with cluster distributions, before and after applying the vetoes.

Running `vp-makeperf`

If you work with veto segments in text files, use the following command line to run vp-makeperf:

vp-makeperf gps-start=[GPS start] gps-end=[GPS stop] channel=[trigger channel name] veto-files=[list of veto files]

where [GPS start] and [GPS stop] are the GPS times where to start and stop the analysis. [trigger channel name] is the name of the channel (e.g. V1:Hrec_hoft_16384Hz) you want to consider for your trigger data set (Omicron centralized triggers). Finally, you must provide a list of vetoes as a list of text files separated by a ;: "/path/to/my/DQ/flags/veto1.txt;/path/to/my/DQ/flags/veto2.txt;/path/to/my/DQ/flags/veto3.txt". The input veto file is a text file with 2 columns: [gps start] [gps end].

If you work with veto channels, use the following command line:

vp-makeperf gps-start=[GPS start] gps-end=[GPS stop] channel=[trigger channel name] veto-channels=[list of channels] ffl=[path to the ffl]

where [list of channels] is the list of channels and thresholds: "V1:DQ1&0.5;V1:DQ2&1.0e-21". The veto is active when the the channel (here: V1:DQ1 and V1:DQ2) take values above the threshold (here: 0.5 and 1.0e-21). The path to the ffl file must be given with the ffl= option.

Of course, the vp-makeperf tool can be used with both veto files and veto channels.

As explained below in the Options section, it is also possible to choose a set of segments to run the analysis.

vp-makeperf segment-file=[segment file] (...)

In this way, one can really control the input of the code, for instance by running on selected 'SCIENCE after CAT1' segments whereas Omicron triggers are produced more loosely – usually when the detector is in LOW_NOISE configuration.

Options

vp-makeperf comes with many extra options which can be used at the command line. Just type vp-makeperf to get the list of options:

channel=X: Specify the name of the channel processed with Omicron. This defines your trigger data set to evaluate the veto performance. This option only works if Omicron triggers are centrally managed.
file=X: Another way to provide triggers is to give a list of ROOT files (GWOLLUM convention). This list can be given as a list of files separated by a space or by a file pattern like /path/to/my/files/\*.root. You can even give a list of file patterns.
gps-start=X and gps-end=Y: This option defines the time range of your analysis: use GPS seconds.
segment-file=X: Alternatively, you can give a list of time segments to perform the vetoperf analysis. This is provided as a text file with 2 columns: [gps start] and [gps end].
veto-files="X;Y;Z": Specify a list of veto files of which you want to evaluate the performance. A veto file is a text file defining when the veto is active, with 2 columns: [gps start] and [gps end].
veto-channels="X\&tx;Y\&ty</tt>: A veto can also be defined from an ADC channel in frame files. Here, you define your veto as a channel name (<tt>X</tt>) and a threshold (<tt>tx</tt>). The veto is active when channel <tt>X</tt> takes vales above <tt>tx</tt>. This option only works if a FFL file is given with <tt>ffl=X</tt>. - <tt>ffl=X</tt>: Path to the FFL file where to find the veto channels. - <tt>outdir=X</tt>: Path to the output directory where the html report and plots are dumped (must exist!). - <tt>snr-thresholds="X;Y;Z"</tt>: List of SNR thresholds to define categories of triggers. Veto performance numbers are computed for each categories. - <tt>freq-min=X</tt> and <tt>freq-max=Y</tt>: This option defines a frequency range [Hz] to select the triggers. - <tt>print-veto-summary=X</tt>: Use this option to print a veto summary plot in the html report. You must specify the index of the SNR category you want to use. For example, if <tt>snr-thresholds="X;Y;Z"</tt> and <tt>print-veto-summary=1</tt>, then only triggers with <tt>SNR \> Y</tt> are used in the veto summary plot. - <tt>print-veto=1/0</tt>: Use 1 to link the list of veto segments in the html report. Use 0 otherwise. - <tt>print-veto-clusters=1/0</tt>: Use 1 to link the list of vetoed triggers in the html report. Use 0 otherwise. - <tt>cluster-dt=X</tt>: Input triggers are clustered before evaluating the veto performance. Here you can adjust the clustering time window [s]. @snippet this vp-makeperf-usage @author Florent Robinet - <a href="flore.nosp@m.nt.r.nosp@m.obine.nosp@m.t@ij.nosp@m.clab..nosp@m.in2p.nosp@m.3.fr">flore.nosp@m.nt.r.nosp@m.obine.nosp@m.t@ij.nosp@m.clab..nosp@m.in2p.nosp@m.3.fr

Function Documentation

◆ main()

int main	(	int	argc,
		char *	argv[]
	)

Main program.

◆ printhelp()

int printhelp ( void )

Usage funcion.

[vp-makeperf-usage]

Functions