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 command-line interface is a Q-transform utility for generating omega scans. The simplest usage is as follows:

python -m gwdetchar.omega -i <interferometer> <gps-time>

For example,

python -m gwdetchar.omega -i L1 1126259461.5

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

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

Produce 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
  -y FREQUENCY_SCALING, --frequency-scaling FREQUENCY_SCALING
                        scaling of all frequency axes, default: log
  -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

To enable batch processing, gwdetchar.omega.batch is a wrapper around gwdetchar.omega that builds a workflow for executing multiple omega scans at once. This tool will generate a Condor workflow (a Directed Acyclic Graph, or DAG) to process multiple event times either in parallel or in series. The simplest usage is much the same as for gwdetchar.omega, but with multiple times:

python -m 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:

python -m 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 interface and options, you can run

$ python -m gwdetchar.omega.batch --help
usage: python -m gwdetchar.omega.batch [-h] [-V] -i IFO [-o OUTPUT_DIR]
                                       [-f CONFIG_FILE] [-d] [-D] [-s]
                                       [-t FAR_THRESHOLD]
                                       [-y FREQUENCY_SCALING] [-c COLORMAP]
                                       [-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]
                                       gpstime [gpstime ...]

Batch-generate a series of Omega 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:
  gpstime               GPS time(s) to scan, or path to a filecontaining 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, default: /home/docs/ch
                        eckouts/readthedocs.org/user_builds/gwdetchar/checkout
                        s/stable/docs

Omega scan options:
  -f CONFIG_FILE, --config-file CONFIG_FILE
                        path to configuration file to use, default: choose
                        based on observatory, epoch, and pipeline
  -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
  -y FREQUENCY_SCALING, --frequency-scaling FREQUENCY_SCALING
                        scaling of all frequency axes, default: log
  -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

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"