===============
Lock check task
===============

The Lock Check task is designed to verify if interferometers are marked as observing when an event is reported. This task takes the list of interferometers claimed to have detected an event and compares that to each interferometer's observing status to flag potential conflicts.

------------
Requirements
------------

This task requires the following packages that may not be included in the requirements list for dqrtasks:

* `gwpy`

-----------
Description
-----------

When an analysis generates an alert for a potential event, Lock Check will take the interferometers listed as detecting the event and report if the interferometers are marked as "observing" at that time. This is done by comparing the time and duration of the event to the observing state vector for each interferometer (by default GDS-CALIB_STATE_VECTOR).

Since this is a True or False comparison, the p-value reported by Lock Check is either 0 or 1 depending on four possible cases:

* The interferometer is observing and the alert lists the interferometer as detecting the event: p-value = 1
* The interferometer is observing and the alert does not list the interferometer as detecting the event: p-value = 1
* The interferometer is not observing and the alert does not list the interferometer as detecting the event: p-value = 1
* The interferometer is not observing and the alert lists the interferometer as detecting the event: p-value = 0

The last case is where potential conflicts could arise and gets flagged with a p-value of 0.


--------------------
Example command-line
--------------------

This is the help message:

.. command-output:: dqr-lockcheck --help

--------------
Example config
--------------

.. code-block:: ini

    [lockcheck]
    description =  lock check
    librarian = detchar@ligo.org
    include_in_dag = True
    tier = 1
    question = Are known sources of noise without auxiliary witnesses active?
    # use the iterator construct to run on each ifo
    iterate = l1
    executable = dqr-lockcheck
    request_memory = 400MB
    arguments = "-o ${outdir} --ifo ${ifo} --ifo-list ${ifos} --event-time ${t_0} --duration 10 --state-vector ${state_vector} --frame-type ${frame_type}"

--------------------
Example results page
--------------------

*Work in progress*