GWOLLUM's friend: DQperf

The DQperf package was created to measure the performance of DQ flags or any veto segment list. As explained in What is a data quality (DQ) flag? several figures of merit (FOM) can be computed. In addition, a set of plots are produced to visualize the DQ performance. The performance are measured using a set of triggers. By default the DQperf tool will use Omicron triggers but any trigger sample can be used.

The DQperf package offers an all-in-one script which will:

  • Apply the DQ flag on a given set of triggers
  • Measure the DQ flag FOM
  • Produce performance plots
  • Organize all the results on a nice web report

    • This documentation page aims at describing the procedure to use this script.

    Index:

  • The GetDQperfReport tool
  • The GetDQperfReport options
    		•
    The GetDQperfReport tool

    To use the GetDQperfReport, you first need to source the DQperf environment:

    source ${DQPERFROOT}/${DQperf_tag}/cmt/setup.(c)sh

    There is only one ingredient you need to use this tool: one or several DQ flags to test. Each DQ flag is represented by an ASCII file containing the list of segments. Several formats are supported:

    	  2 columns: GPS start - GPS end
	  3 columns: GPS start - GPS end - segment duration
	  4 columns: segment number - GPS start - GPS end - segment duration
	  5 columns: segment number - GPS start - GPS end - segment duration - segment value (-1/0/+1)

    For this tutorial, let's say we have 3 DQ flag files:

    	  /path/to/my/DQ_files/dq1.txt
	  /path/to/my/DQ_files/dq2.txt
	  /path/to/my/DQ_files/dq3.txt

    Then, the tool is very easy to use, just type:

    	  GetDQperfReport -q "/path/to/my/DQ_files/dq*.txt" -s 934530000 -e 934550000

    The DQ flags performance is measured between 934530000 and 934550000 with Omicron triggers and the html report is dumped in the current directory
    The GetDQperfReport options

    The GetDQperfReport comes with many options detailed below.

    -q "[DQ_FILES]"
    		 This option is mandatory. The user must give the path to the DQ flag files to consider. It can be a list of files, or a file pattern (with the '*' or '?' characters). The DQ files MUST have a '.txt' extension. 
    -d [OUTDIR]
    		 By default, all the report elements are dumped in the current directory. With this option, the user can choose the output directory. The output directory MUST exist. 
    -S [SEGMENT_FILE]
    		 An additional segment file can be given with this option. In this case, the performance will only be measured within this segment list. Triggers and DQ segments outside these segments will be ignored. 
    -s [GPS_START]
    		 Instead of a reference segment file, a single segment can be specified with -s and -e options. If a reference segment file is also given, the intersection is considered. 
    -e [GPS_END]
    		 Instead of a reference segment file, a single segment can be specified with -s and -e options. If a reference segment file is also given, the intersection is considered. 
    -c [MAIN_CHANNEL]
    		 When the performance are measured with Omicron triggers, the channel named 'V1:h_4096Hz' is used by default. However, Omicron triggers are often produced with multiple channels. The user might want to use a different channel to measure the performance. Of course the triggers for this channel must be available otherwise the script will failed with an error message. To get the list of available channel triggers, type 'GetOmicronTriggers -l'. This option is ignored if the user provides his own trigger list (-t or -T option). 
    -T [TRIGGER_FILE]
    		 By default Omicron triggers are used to measure the performance. Obviously, this implies that Omicron triggers are available in the standard Omicron architecture. This is not always the case. Moreover, the user might want to measure the DQ performance over his own set of triggers. With this option, a trigger file can be used as a reference. The user must give the full path to an ASCII file listing the triggers. This file must have the following format: 3 columns: GPS time - frequency - SNR. 
    -t "[ROOT_TRIGGER_FILE_PATTERN]"
    		 By default Omicron triggers are used to measure the performance. Obviously, this implies that Omicron triggers are available in the standard Omicron architecture. This is not always the case. With this option, a ROOT trigger file pattern can be used as a reference. 
    -N "[SNR_THR]"
    		 By default, the performance are measured for 4 SNR thresholds: 5, 8, 10 and 20. The user can change this setting with this option. A maximum of 4 threshold values is allowed. 
    -r
    		 Only the web report is generated. 
    -h
    		 Prints the GetDQperfReport usage procedure

    Florent Robinet
    Contact: robinet@lal.in2p3.fr