============================ 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: 1. Find the time-frequency parameters for a given candidate event 2. Select X% of the most energetic pixels in the time-frequency spectrogram of the auxiliary channel, where X is 1 by default 3. Estimate how many of those 1% pixels are within the time-frequency track of the given candidate event 4. Estimate what is the total energy of these 1% pixels within the time-frequency track of the given candidate event 5. 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 :math:`p_{scaled} = 1 - (1-p)^N,` where :math:`N` is the number of channels analysed and :math:`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: .. command-output:: dqr-omegascan-overlap --help Example config: .. code-block:: ini [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: .. command-output:: dqr-omegascan-overlap-batch --help Example config: .. code-block:: ini [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: .. command-output:: dqr-omegascan-overlap-webpage --help Example config: .. code-block:: ini [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 <./_static/task_examples/omegascan-overlap/passed_example/index.html>`_. .. raw:: html ------------------------------------------------------------------- Example results page for a candidate event with data quality issues ------------------------------------------------------------------- Full webpage can be accessed `here <./_static/task_examples/omegascan-overlap/failed_example/index.html>`_. .. raw:: html