On the command-line¶

The main interface to the Hveto algorithm is the command-line executable hveto.

Basic instructions¶

For a full explanation of the available command-line arguments and options, you can run

$ hveto --help
usage: hveto [-h] [-V] -i IFO [-j NPROC] [-f CONFIG_FILE] [-p PRIMARY_CACHE]
             [-a AUXILIARY_CACHE] [-S ANALYSIS_SEGMENTS] [-w NSCAN]
             [-o OUTPUT_DIRECTORY] [-e EXTRA_TIMES]
             gpsstart gpsend

Run the HierarchichalVeto (hveto) algorithm over some data

positional arguments:
  gpsstart              GPS start time or datetime of analysis
  gpsend                GPS end time or datetime of analysis

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -i IFO, --ifo IFO     IFO prefix for this analysis, default: None
  -j NPROC, --nproc NPROC
                        the number of processes to use when reading data,
                        default: 1
  -f CONFIG_FILE, --config-file CONFIG_FILE
                        path to hveto configuration file, can be given
                        multiple times (files read in order)
  -p PRIMARY_CACHE, --primary-cache PRIMARY_CACHE
                        path for cache containing primary channel files
  -a AUXILIARY_CACHE, --auxiliary-cache AUXILIARY_CACHE
                        path for cache containing auxiliary channel files,
                        files contained must be T050017-compliant with the
                        channel name as the leading name parts, e.g.
                        'L1-GDS_CALIB_STRAIN_<tag>-<start>-<duration>.<ext>'
                        for L1:GDS-CALIB_STRAIN triggers
  -S ANALYSIS_SEGMENTS, --analysis-segments ANALYSIS_SEGMENTS
                        path to file containing segments for the analysis flag
                        (name in data file must match analysis-flag in config
                        file)
  -w NSCAN, --omega-scans NSCAN
                        generate a workflow of omega scans for each round,
                        this will launch automatically to condor, requires the
                        gwdetchar package
  -e EXTRA_TIMES, --extra-times EXTRA_TIMES
                        extra times to add to the list of primary triggers to
                        include specific times that may not meet the
                        thresholds used to find triggers

Output options:
  -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                        path of output directory, default: .

Detailed instructions¶

A few of the command-line options require special formatting, which is detailed in this section.

`gpsstart` and `gpsend`¶

Each of the required GPS start and stop times can be given as GPS integers, or as date strings, e.g.

hveto 1135641617 1135728017 ...

will produce the same analysis as

hveto "Jan 1 2016" "Jan 2 2016" ...

Note

It is important to use quote marks when passing date strings on the command-line. This will ensure that the shell passes these to python as individual arguments.

`-j/--nproc`¶

Wall-clock processing time for hveto is dominated by two things:

Reading event files for the auxiliary channels
Determining the most-significant channel for a given round

Each of these can be sped up by using multiple CPUs on the host machine by supplying --nproc X, where X is any integer.

Warning

Beware that using too many CPUs could overload the machine at runtime, or otherwise cause problems for yourself and other users.

You can check how many processors are available with the following unix command:

cat /proc/cpuinfo | grep processor | wc -l

`-p/--primary-cache`¶

This flag should receive a LAL-format cache file (see glue.lal for details). If needed, you can use hveto-cache-events for this purpose (see below).

`-a/--auxiliary-cache`¶

This flag requires a LAL-format cache file (similar to --primary-cache), but with a specific format:

Each trigger file should contain events for only a single channel
The cached trigger files should map to their channel as follows: if a channel is named X1:SYS-SUBSYS_NAME, each filename should start X1-SYS_SUBSYS_NAME according to the T050017 convention. Additional underscore-delimited components can be given, but will not be used to map to the channel.

If needed, hveto-cache-events can be used to create this cache (see below).

Note

If channels is not given in the [auxiliary] section of the configuration file, it will be populated from the unique list of channels parsed from the --auxiliary-cache.

Caching trigger events¶

The hveto-cache-events utility can be used to save both gravitational-wave and auxiliary channel triggers:

$ hveto-cache-events --help
usage: hveto-cache-events [-h] [-V] -i IFO [-j NPROC] [-f CONFIG_FILE]
                          [-p PRIMARY_CACHE] [-a AUXILIARY_CACHE]
                          [-S ANALYSIS_SEGMENTS] [--append]
                          [-o OUTPUT_DIRECTORY]
                          gpsstart gpsend

Create a (temporary) cache of event triggers for analysis by `hveto`

This method will apply the minimal SNR thresholds and any frequency cuts
as given in the configuration files

positional arguments:
  gpsstart              GPS start time or datetime of analysis
  gpsend                GPS end time or datetime of analysis

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -i IFO, --ifo IFO     IFO prefix for this analysis, default: None
  -j NPROC, --nproc NPROC
                        the number of processes to use when reading data,
                        default: 1
  -f CONFIG_FILE, --config-file CONFIG_FILE
                        path to hveto configuration file, can be given
                        multiple times (files read in order)
  -p PRIMARY_CACHE, --primary-cache PRIMARY_CACHE
                        path for cache containing primary channel files
  -a AUXILIARY_CACHE, --auxiliary-cache AUXILIARY_CACHE
                        path for cache containing auxiliary channel files,
                        files contained must be T050017-compliant with the
                        channel name as the leading name parts, e.g.
                        'L1-GDS_CALIB_STRAIN_<tag>-<start>-<duration>.<ext>'
                        for L1:GDS-CALIB_STRAIN triggers
  -S ANALYSIS_SEGMENTS, --analysis-segments ANALYSIS_SEGMENTS
                        path to LIGO_LW XML file containing segments for the
                        analysis flag (name in segment_definer table must
                        match analysis-flag in config file)
  --append              append to existing cached event files, otherwise,
                        start from scratch (default)

Output options:
  -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                        path of output directory, default: .

Tracing event triggers¶

The hveto-trace utility can be used to determine whether event triggers are vetoed by a given hveto run:

$ hveto-trace --help
usage: hveto-trace [-h] [-V] -t TRIGGER_TIME -d DIRECTORY [-v]

Check whether a specified trigger time was vetoed by an hveto analysis

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -t TRIGGER_TIME, --trigger-time TRIGGER_TIME
                        GPS time of the trigger
  -d DIRECTORY, --directory DIRECTORY
                        path to the hveto output directory containing a
                        summary-stats.json file
  -v, --verbose         Log verbose output

On the command-line¶

Basic instructions¶

Detailed instructions¶

gpsstart and gpsend¶

-j/--nproc¶

-p/--primary-cache¶

-a/--auxiliary-cache¶

Caching trigger events¶

Tracing event triggers¶

`gpsstart` and `gpsend`¶

`-j/--nproc`¶

`-p/--primary-cache`¶

`-a/--auxiliary-cache`¶