Omegascan Power Overlap task
Requirements
This task requires the following packages that may not be included in the requirements list for dqrtasks:
gwpy
gwdetchar
pycbc
Description
This task attempts to answer the following question:
Does this auxiliary channel has excess power that coincides with the candidate event? If yes, does this happen rarely enough (i.e. the auxiliary channel is relatively quiet)?
If the auxiliary channel has excess power coinciding with the candidate event and the channel is usually quiet, this could indicate that the auxiliary channel recorded the noise which maybe caused the excess power in h(t).
The task performs the following steps:
Find the time-frequency parameters for a given candidate event
Select X% of the most energetic pixels in the time-frequency spectrogram of the auxiliary channel, where X is 1 by default
Estimate how many of those 1% pixels are within the time-frequency track of the given candidate event
Estimate what is the total energy of these 1% pixels within the time-frequency track of the given candidate event
Measure how often this auxiliary channel has this amount of energy at this time-frequency volume
Scaled P-value
The Omegasca_overlap task provides a scaled p-value which takes into account the number of channels that are analysed. The scaled p-value is calculated as follows
\(p_{scaled} = 1 - (1-p)^N,\)
where \(N\) is the number of channels analysed and \(p\) is the lowest p-value from all analysed channels.
If the scaled p-value is below the p-value threshold (default threshold is 0.05), then the task will raise a DQ issue.
Binomial test P-value
Binomial test P-value is estimated using Binomial test. This test estimates the probability of X number of channels from the total of Y number of channels being below the p-value threshold.
For example: 20 out of 400 channels being below the p-value threshold of 0.05 has the binomial test p-value of 1, i.e. this is very likely to happen. However, when there are 29 channels below the p-value threshold instead of 20, the binomial test p-value becomes 0.049 indicating that this is quite unlikely to happen.
What to do if omega_overlap raised a DQ issue
This is a statistical task, so there is a chance that the task reports a low p-value just by chance, i.e. it is a false alarm. Firstly, check what is the binomial test p-value. If it is below 0.05, this means that more channels are below the p-value threshold than expected.
If a channel is flagged by the omega_overlap task, it is helpful to check the HVeto, idq, and pemcheck tasks to see if the same channel is flagged, as these tasks provides complementary information to omega overlap. Event validators should note if multiple tasks flag the same channel as related to a data quality issue.
Omegascan overlap for a single channel example
While the task is designed to run on multiple channels, it is possible to run the task for a single channel. This will not provide a webpage but will provide plots, p-value and a results .json file.
This is the help message:
$ dqr-omegascan-overlap --help
usage: dqr-omegascan-overlap [-h] [-v] [-V] [-q] [-o OUTDIR]
[--graceid GRACEID] [--json JSON]
[--t_start T_START] [--t_end T_END]
[--f_start F_START] [--f_end F_END] [--m1 M1]
[--m2 M2] [--s1z S1Z] [--s2z S2Z] [--ifo IFO]
[--aux-channel AUX_CHANNEL]
[--omegascan-width OMEGASCAN_WIDTH]
[--f-low F_LOW] [--f-high F_HIGH]
[--track-error-dt TRACK_ERROR_DT]
[--track-error-df TRACK_ERROR_DF]
[--pixel-threshold PIXEL_THRESHOLD]
[--far-threshold FAR_THRESHOLD]
[--pval-threshold PVAL_THRESHOLD]
Omegascan power overlap Based on presentation
https://dcc.ligo.org/LIGO-G2100068.
optional arguments:
-h, --help show this help message and exit
-v, --verbose increase verbose output
-V, --version show program's version number and exit
-q, --quiet show only fatal errors
-o OUTDIR, --outdir OUTDIR
directory to output results
--graceid GRACEID event GraceDB ID
--json JSON event GraceDB json file
--t_start T_START GW event start time
--t_end T_END GW event end time
--f_start F_START GW event start freq
--f_end F_END GW event end freq
--m1 M1 mass 1 in Msun
--m2 M2 mass 2 in Msun
--s1z S1Z spin 1 in z-plane
--s2z S2Z spin 2 in z-plane
--ifo IFO detector analysed
--aux-channel AUX_CHANNEL
aux channel name used for the analysis
--omegascan-width OMEGASCAN_WIDTH
omegascan analysis window width (s),default: 32
--f-low F_LOW lowest omegascan frequency (Hz), default: 10
--f-high F_HIGH highest omegascan frequency (Hz), default: 2048
--track-error-dt TRACK_ERROR_DT
padding for the time-frequency track in time (s),
default: 0.1
--track-error-df TRACK_ERROR_DF
padding for the time-frequency track in frequency
(Hz), default: 1
--pixel-threshold PIXEL_THRESHOLD
fraction of the most energetic pixels of an omegascan
to be defined as excess noise (percent), default: 1
--far-threshold FAR_THRESHOLD
white noise false alarm rate threshold (Hz) for
processing channels, default: 3.171e-08
--pval-threshold PVAL_THRESHOLD
pvalue threshold when the aux channel is considered to
significantly overlap, default: 0.05
Example config:
[omegascanoverlap]
description = omegascan power overlap
librarian = detchar@ligo.org
include_in_dag = True
tier = 1
question = Does the excess noise at the auxiliary channel significantly coincide with the GW candidate?
executable = dqr-omegascan-overlap
request_memory = 1000MB
arguments = " --outdir ${outdir} --graceid {graceid} --ifo {ifo} --aux-channel {aux_channel}"
Omegascan overlap for a batch of channels
The task will run on a batch of channels and will provide p-values, plots, as well as .json files for each channel separately.
This is the help message:
$ dqr-omegascan-overlap-batch --help
usage: batch-dqr-omegascan-overlap [-h] [-v] [-V] [-q] [-o OUTDIR] [--ini INI]
[--section SECTION] [--strain STRAIN]
[--pixel-threshold PIXEL_THRESHOLD]
[--far-threshold FAR_THRESHOLD]
[--pval-threshold PVAL_THRESHOLD]
[--omegascan-width OMEGASCAN_WIDTH]
[--track-error-dt TRACK_ERROR_DT]
[--track-error-df TRACK_ERROR_DF]
[--graceid GRACEID] [--json JSON]
[--ifo IFO] [--t_start T_START]
[--t_end T_END] [--f_start F_START]
[--f_end F_END] [--m1 M1] [--m2 M2]
[--s1z S1Z] [--s2z S2Z]
Batch script for omegascan power overlap Based on presentation
https://dcc.ligo.org/LIGO-G2100068.
optional arguments:
-h, --help show this help message and exit
-v, --verbose increase verbose output
-V, --version show program's version number and exit
-q, --quiet show only fatal errors
-o OUTDIR, --outdir OUTDIR
directory to output results
--ini INI config file
--section SECTION section of the config file
--strain STRAIN strain channel
--pixel-threshold PIXEL_THRESHOLD
fraction of the most energetic pixels of an omegascan
to be defined as excess noise (percent), default: 1
--far-threshold FAR_THRESHOLD
white noise false alarm rate threshold (Hz) for
processing channels, default: 3.171e-08
--pval-threshold PVAL_THRESHOLD
pvalue threshold when the aux channel is considered to
significantly overlap, default: 0.05
--omegascan-width OMEGASCAN_WIDTH
omegascan analysis window width (s),default: 32
--track-error-dt TRACK_ERROR_DT
padding for the time-frequency track in time (s),
default: 0.1
--track-error-df TRACK_ERROR_DF
padding for the time-frequency track in frequency
(Hz), default: 1
--graceid GRACEID event GraceDB ID
--json JSON event GraceDB json file
--ifo IFO detector analysed
--t_start T_START GW event start time
--t_end T_END GW event end time
--f_start F_START GW event start freq
--f_end F_END GW event end freq
--m1 M1 mass 1 in Msun
--m2 M2 mass 2 in Msun
--s1z S1Z spin 1 in z-plane
--s2z S2Z spin 2 in z-plane
Example config:
[omegascanoverlap]
description = batch omegascan power overlap
librarian = detchar@ligo.org
include_in_dag = True
tier = 1
question = Does the excess noise at auxiliary channels significantly coincide with the GW candidate?
executable = dqr-omegascan-overlap-batch
request_memory = 1000MB
arguments = " --outdir ${outdir} --graceid {graceid} --ifo {ifo} --ini {config_ini} --section {config_section}"
To produce a webpage, use dqr-omegascan-overlap-webpage.
This is the help message:
$ dqr-omegascan-overlap-webpage --help
usage: webpage-batch-dqr-omegascan-overlap [-h] [-v] [-V] [-q] -o OUTDIR
Generate a results webpage for batch omega scan overlap. Based on presentation
https://dcc.ligo.org/LIGO-G2100068.
optional arguments:
-h, --help show this help message and exit
-v, --verbose increase verbose output
-V, --version show program's version number and exit
-q, --quiet show only fatal errors
-o OUTDIR, --outdir OUTDIR
directory of omegascan results; webpage will be
created in the same folder
Example config:
[omegascanoverlap]
description = batch omegascan power overlap webpage
librarian = detchar@ligo.org
include_in_dag = True
tier = 1
executable = dqr-omegascan-overlap-webpage
request_memory = 1000MB
arguments = " --outdir ${outdir}"
Example results page for a candidate event with no data quality issues recognized by the task
Full webpage can be accessed here.
Example results page for a candidate event with data quality issues
Full webpage can be accessed here.