Omega scans

The gwdetchar.omega module provides a python implementation of the Omega gravitational-wave burst detection pipeline, used extensively for characterisation of transient noise in LIGO. This pipeline is designed around the Q-transform and is used to analyze hundreds of channels.

The omega pipeline provides a ‘scan’ utility to make high-resolution Q-transform spectrograms of a configurable group of channels, to study the morphology and source of specific transient events (glitches).

The gwdetchar.omega module provides the following functions:

highpass(series, f_low[, order, analog, ftype]) High-pass a TimeSeries with a Butterworth filter
whiten(series, fftlength[, overlap, method, …]) Whiten a TimeSeries against its own ASD
conditioner(xoft, fftlength[, overlap, …]) Condition some input data for an omega scan
primary(gps, length, hoft, fftlength[, …]) Condition the primary channel for use as a matched-filter
cross_correlate(xoft, hoft) Cross-correlate two TimeSeries by matched-filter
scan(gps, channel, xoft, fftlength[, …]) Scan a channel for evidence of transients

The gwdetchar.omega.plot module also provides functions for plotting omega scan data products:

plot.timeseries_plot(data, gps, span, …[, …]) Custom plot for a GWPy TimeSeries object
plot.spectral_plot(data, gps, span, channel, …) Custom plot for a GWPy spectrogram or Q-gram
plot.write_qscan_plots(gps, channel, series) Custom plot utility for a full omega scan

Command-line utilities

GWDetChar provides two command-line utilities for running omega scans, taking care of data discovery and (optionally) configuration discovery for you.

Note

For users working on any of the LIGO Data Grid (LDG) computer clusters, a standard set of configuration files are maintained and discoverable by default with gwdetchar-omega. For information about how to write custom configuration files, see the gwdetchar.omega.config module.

gwdetchar-omega

The gwdetchar-omega tool is a Q-transform utility for generating omega scans. The simplest usage is as follows:

gwdetchar-omega -i <interferometer> <gps-time>

For example,

gwdetchar-omega -i L1 1126259461.5

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

$ gwdetchar-omega --help
usage: gwdetchar-omega [-h] [-V] [-i IFO] [-o OUTPUT_DIRECTORY]
                       [-f CONFIG_FILE] [-d] [-D] [-s] [-t FAR_THRESHOLD]
                       [-c COLORMAP] [-j NPROC]
                       gpstime

Compute an omega scan for a list of channels around a given GPS time This
utility can be used to process an arbitrary list of detector channels with
minimal effort in finding data. The input should be an INI-formatted
configuration file that lists processing options and channels in contextual
blocks. For more information, see gwdetchar.omega.config.

positional arguments:
  gpstime               GPS time or datestring to scan

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
  -o OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY
                        output directory for the omega scan, default:
                        ~/public_html/wdq/{IFO}_{gpstime}
  -f CONFIG_FILE, --config-file CONFIG_FILE
                        path to configuration file to use, can be given
                        multiple times (files read in order), default: choose
                        a standard one based on IFO and GPS time
  -d, --disable-correlation
                        disable cross-correlation of aux channels, default:
                        False
  -D, --disable-checkpoint
                        disable checkpointing from previous runs, default:
                        False
  -s, --ignore-state-flags
                        ignore state flag definitions in the configuration,
                        default: False
  -t FAR_THRESHOLD, --far-threshold FAR_THRESHOLD
                        white noise false alarm rate threshold (Hz) for
                        processing channels, default: 3.171e-08
  -c COLORMAP, --colormap COLORMAP
                        name of colormap to use, default: viridis
  -j NPROC, --nproc NPROC
                        the number of processes to use when reading data,
                        default: 8

gwdetchar-omega-batch

gwdetchar-omega-batch is a wrapper around gwdetchar-omega to build a workflow for executing multiple omega scans easily. This tool will generate a Condor workflow (a Directed Acyclic Graph, or DAG) to process multiple times either in parallel or in series. The simplest usage is much the same as for gwdetchar-omega, but with multiple times:

gwdetchar-omega-batch -i <interferometer> <gps-time-1> <gps-time-2> <gps-time-3> ...

Alternatively, you can pass all of the times in a single file:

gwdetchar-omega-batch -i L1 mytimes.txt

where mytimes.txt should contain a single column of GPS times.

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

$ gwdetchar-omega-batch --help
usage: gwdetchar-omega-batch [-h] [-V] -i IFO [-o OUTPUT_DIR] [-f CONFIG_FILE]
                             [--colormap COLORMAP] [-d] [-D]
                             [-t FAR_THRESHOLD] [-s] [-j NPROC] [-u UNIVERSE]
                             [--submit] [--monitor]
                             [--condor-accounting-group CONDOR_ACCOUNTING_GROUP]
                             [--condor-accounting-group-user CONDOR_ACCOUNTING_GROUP_USER]
                             [--condor-timeout T]
                             [--condor-command CONDOR_COMMAND]
                             gps-time [gps-time ...]

Batch-generate a series of Omega-pipeline scans. GPS times can be given
individually on the command-line, one after the other, or can be bundled into
one file formatted where the first column contains the GPS times (other
columns are ignored). The output of this script is a condor workflow in the
form of a DAG file, with associated condor submit (`.sub`) file in the output
directory. Submitting the workflow to Condor will result in the scans being
processed in parallel.

positional arguments:
  gps-time              GPS time(s) to scan, or path to a file containing a
                        single column of such times

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
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        output directory for all scans
  -f CONFIG_FILE, --config-file CONFIG_FILE
                        path to configuration file to use, default: choose
                        based on observatory, epoch, and pipeline
  --colormap COLORMAP   name of colormap to use, default: viridis
  -d, --disable-correlation
                        disable cross-correlation of aux channels, default:
                        False
  -D, --disable-checkpoint
                        disable checkpointing from previous runs, default:
                        False
  -t FAR_THRESHOLD, --far-threshold FAR_THRESHOLD
                        white noise false alarm rate threshold (Hz) for
                        processing channels, default: 3.171e-08
  -s, --ignore-state-flags
                        ignore state flag definitions in the configuration,
                        default: False
  -j NPROC, --nproc NPROC
                        the number of processes to use when reading data,
                        default: 8

Condor options:
  -u UNIVERSE, --universe UNIVERSE
                        universe for condor processing
  --submit              submit DAG directly to condor queue
  --monitor             monitor the DAG progress after submission; only used
                        with --submit
  --condor-accounting-group CONDOR_ACCOUNTING_GROUP
                        accounting_group for condor submission on the LIGO
                        Data Grid, include '{epoch}' (with curly brackets) to
                        auto-substitute the appropriate epoch based on the GPS
                        times
  --condor-accounting-group-user CONDOR_ACCOUNTING_GROUP_USER
                        accounting_group_user for condor submission on the
                        LIGO Data Grid
  --condor-timeout T    configure condor to terminate jobs after T hours to
                        prevent idling, default: None
  --condor-command CONDOR_COMMAND
                        Extra condor submit commands to add to gw_summary
                        submit file. Can be given multiple times in the form
                        "key=value"