Executables¶

The DQR contains two main high-level executables, although it may also contain ancilliary executables used for separate tasks. Here, we only discuss the purpose and usage of the two main executables.

dqr-create¶

This is the main executable. It is triggered by new lvalert messages and will construct and submit a DAG to manage follow-up tasks along with uploading the required html document, javascript library, and json config file to GraceDb for each event. In it’s most basic usage, it only requires a DQR config file (INI file) and will read the lvalert message from STDIN. Alternatively, users can specify a GraceID via the command line to force dqr-create to run on that event.

Additional control is provided to both change the JSON configuration uploaded to GraceDb and to modify the DAG created.

Example use cases¶

When listening for lvalert messages, dqr-create should be called with something like:

dqr-create /path/to/dqr.ini

with additional options to control the workflow, for which the default values will almost always suffice.

When running dqr-create on a specific GraceID, users should do something like:

dqr-create /path/to/dqr.ini GraceID

Again, specifying additional options as necessary.

Helpstring¶

$ dqr-create -h
usage: dqr-create [-h] [-v] [-V] [-q REQUIRED_QUESTION] [-a ALERT_TYPE]
                  [-t EVENT_TYPE] [-f FAR_THRESHOLD] [--do-not-alert]
                  [--do-not-annotate] [--suppress-notification]
                  [--do-not-upload] [--do-not-submit]
                  config [graceid]

Create a Data-Quality Report for the given GraceID. This script schedules all
data quality report tasks and writes the html documents. If a GraceID is not
provided, this script will read one from the STDIN buffer.

positional arguments:
  config                path to DQR configuration file
  graceid               GraceID of event to follow-up, if not given will be
                        read from stdin (default: None)

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         show verbose output (default: False)
  -V, --version         show program's version number and exit
  -q REQUIRED_QUESTION, --required-question REQUIRED_QUESTION
                        specify questions to be included in dqr.json even if
                        no tasks are assigned to them. Can be repeated to
                        specify multiple required questions. DEFAULT=['Did the
                        candidate occur at a suspicious GPS time?', 'Is there
                        a high probability that a glitch was present based on
                        statistical inference of auxiliary information?', 'Are
                        known sources of noise with auxiliary witnesses
                        active?', 'Are known sources of noise without
                        auxiliary witnesses active?', 'Are environmental
                        monitors active?', 'Was the detector in a nominal
                        state?'] (default: ['Did the candidate occur at a
                        suspicious GPS time?', 'Is there a high probability
                        that a glitch was present based on statistical
                        inference of auxiliary information?', 'Are known
                        sources of noise with auxiliary witnesses active?',
                        'Are known sources of noise without auxiliary
                        witnesses active?', 'Are environmental monitors
                        active?', 'Was the detector in a nominal state?'])

processing options:
  -a ALERT_TYPE, --alert-type ALERT_TYPE
                        alert type to follow-up. Can be repeated to specify
                        multiple alert-types. DEFAULT is to only follow-up
                        alert_type="new" (default: [])
  -t EVENT_TYPE, --event-type EVENT_TYPE
                        event type to follow-up. Can be repeated to specify
                        multiple types. (default: [])
  -f FAR_THRESHOLD, --far-threshold FAR_THRESHOLD
                        the maximum FAR to follow-up (default: inf)
  -s SLEEP, --sleep SLEEP
                        wait this number of seconds and then poll GraceDb to
                        get the most recent FAR for an event. This allows us
                        to only responde to alert_type="new" lvalert packets
                        and still catch updated FARs within reason. If
                        sleep<=0, we do not query GraceDb and proceed with the
                        far available within lvalert or from the original
                        query. (default: 0.0)
  --do-not-post         do not post to logbook (default: False)
  --do-not-alert        do not add the dqr-alert jobs to the DAG (default:
                        False)
  --do-not-annotate     do not add in the dqr-annotate jobs into the DAG
                        (default: False)
  --suppress-notification
                        silence all notifications from Condor. This overrides
                        the default value on the cluster, so be careful with
                        what you set! (default: False)
  --condor-retry CONDOR_RETRY
                        the number of retries encoded in the DAG. DEFAULT=3
                        (default: 3)

output options:
  --do-not-upload       do not upload anything to GraceDb (default: False)
  --do-not-submit       do not submit the workflow to condor (default: False)

configuration file for dqr-create¶

More information can be found in this tutorial: How to Configure the DQR INI file. However, we briefly mention a few required and protected options for each section here.

[general]

output_dir (required)

the directory into which local (intermediary) products will be written before they are uploaded to GraceDb.

this is also where things like the Condor DAG and SUB files will be written.

output_url (required)

the URL corresponding to output_dir.

gracedb_url (required)

the URL for an instance of GraceDb. This can be a local path instead of a server name, in which case the DQR will use an instance of lvalertTest’s FakeDb as a proxy for GraceDb’s Python REST API.

keyname (optional)

If posting to a logbook (–do-not-post was not specified), this is the username used with keytab to authenticate via kerberos.

keytab (optional)

If posting to a logbook (–do-not-post was not specified), this is the keytab used with keyname to authenticate via kerberos.

logbook_url (optional)

If posting to a logbook (–do-not-post was not specified), this is the main URL of that logbook from which the permanent link will be generated.

request_url (optional)

If postint to a logbook (–do-not-post was not specified), this is the url for the PHP request to generate a new post.

[tiers]

tier (optional)

a space-delimited list of email addresses to notify when a tier completes (e.g.: 0 = albert@ligo.org einstein@ligo.org)

tier name (optional)

the name of the tier to be rendered within the DQR html (e.g.: 0 = low latency). If not supplied, will default to “Tier tier” (e.g.: “Tier 0”).

[follow-up task]

include_in_dag (required)

a boolean flag that tells the DQR schedule whether to attempt to write a SUB file for this task within the DAG.

tier (required)

the tier at which this task should first appear.

question (required)

the high-level question this task is associated with. This also determines where the task shows up within the rendered html.

allow (required)

a space-delimited list of which states this task is allowed to return. Note that “missing” and “error” states are automatically included and do not to be specified. If tasks return states that are not included in this list, they will be rendered as “bad_state” which is treated as equivalent to an error.

toggles (optional)

a space-delimited list of toggles to be included in the dqr.html document. These toggles allow users to filter which tasks are shown at a given time. Each toggles can be any string (as long as it does not contain spaces), but are typically IFOs (e.g.: H1)

email_upon_error (optional)

a single email address. If the associated task fails within the DAG (exit code != 0), this email will be notificed automatically by Condor. If no email is specified, no warning email will be sent.

we note that this will overwrite options passed through condor_classads, so the user should be careful!

pre (optional)

the path to an executable run as the Condor pre-script for this job. If not supplied, no pre-script is written in the DAG for this task.

post (optional)

the path to an executable run as the Condor post-script for this job. If not supplied, no post-script is written in the DAG for this task.

and task-specific options, which may or may not be required depending on the individual task. We also note that a [DEFAULT] section can be specified to define common parameters (such as condor_classads), but is not required.

dqr-interact¶

This executable is used to interact with the DQR html document by uploading more information by-hand. A tutorial for how to use this executable can be found here: How to Interact with the DQR. Briefly, this executable allows users to either override/change a tasks state (e.g.: change human_input_needed to pass) or add a comment. It also can automatically apply labels to the event if requested (see –retract-if-fail).

dqr-interact will prompt the user to answer a series of questions by default. These act as a safety-net against errant uploads. The answers to these questions are not logged, but instead it is assumed that the user (identified by the –yourname command-line option) has answered in the affirmative for all of them in order to successfully generate and upload the associated file.

Note that users should run ligo-proxy-init prior to dqr-interact to interact with the production GraceDB server. If interacting with GraceDB playground, users will need to specify the GraceDB url (but running `ligo-proxy-init is not necessary in this case).

Example use cases¶

To override the state of a task called a simple task for a specific GraceID, setting it to pass, users should do something like:

dqr-interact override GraceID "Albert Einstein" pass --taskname "a simple task"

Please note the use of quotation marks to define input arguments that contain spaces! Alternatively, users could specify:

dqr-interact-override GraceID "Albert Einstein" pass --taskname asimpletask

Note that the DQR will automatically collapse the taskname for you, so you can copy-and-paste the taskname directly out of the DQR html page.

To post an overall comment, users should do something like:

dqr-interact comment GraceID "Albert Einstein" "a useful comment"

To post a comment to a specific task, users should do something like:

dqr-interact comment GraceID "Albert Einstein" "a very insightful comment" --taskname "a simple task"

So far, all these examples will require the user to answer a series of questions to sanity-check their upload. If you’re confident that you know exactly what you’re doing and never make mistakes, you can skip this with:

dqr-interact comment GraceID "Albert Einstein" "a very insightful comment" --skip-sanity-check --taskname "a simple task"

Please note, to interact with events hosted in Gracedb-playground, users will need to specify –gracedb-url https://gracedb-playground.ligo.org/api/ for all commands.

Helpstring¶

$ dqr-interact -h
usage: dqr-interact [-h] [--taskname TASKNAME] [-v]
                    [--gracedb-url GRACEDB_URL] [--retract-if-fail]
                    [--skip-sanity-check] [--cleanup]
                    command graceid yourname comment

This executable allows users to submit "human override" JSON packets for
specific tasks for a specific GraceID. It performs some basic sanity checks
and requires the user to confirm they've specified the correct event before
posting.

positional arguments:
  command               either "override" or "comment"
  graceid
  yourname              please supply your full name as a single command line
                        argument (wrapped in quotation marks). For example,
                        "Albert Einstein" instead of just "Albert".
  comment               if command=override, this should be the state to which
                        taskname is set. if command=comment, this should be
                        the comment to be posted.

optional arguments:
  -h, --help            show this help message and exit
  --taskname TASKNAME   interact with a specific task. This must be provided
                        to override a state. If omitted while commenting the
                        comment will be rendered as an "overall comment"
                        unassociated with any individual task (default: None)
  -v, --verbose

GraceDb options:
  --gracedb-url GRACEDB_URL
                        DEFAULT=https://gracedb.ligo.org/api/ (default:
                        https://gracedb.ligo.org/api/)

workflow options:
  --retract-if-fail     if the state is set to "fail", automatically label the
                        GraceDb entry and post a DQR comment about the
                        labeling event (default: False)
  --skip-sanity-check   do not prompt user for sanity checking before posting
                        (default: False)
  --cleanup             delete temporary files created to facilitate
                        annotation to GraceDb (default: False)

dqr-stats¶

This executable is used to gather summary reports on the DQR for several events, although it could be run over a single event. It does this by querying GraceDb for a set of events, and then building local representations of the DQR information that is present for each GraceDb entry. In this way, it can report things like latency quantiles for tiers and individual tasks.

dqr-stats is meant to be primarily a developer tool, and therefore may not be as user-friendly as the rest of the library.

Example use cases¶

To get performance statistics for all DQRs associated with superevents in gracedb-playground between 1 Oct 2018 and 15 Oct 2018, do something like:

dqr-stats -v "$(lalapps_tconvert 1 Oct 2018) .. $(lalapps_tconvert 15 Oct 2018)" --superevents --gracedb-url https://gracedb-playground.ligo.org/api/

Helpstring¶

$ dqr-stats -h
usage: dqr-stats [-h] [-v] [-V] [--superevents] [--gracedb-url GRACEDB_URL]
                 [--toggle TOGGLE] [--latency-quantile LATENCY_QUANTILE]
                 sql_query

Summarize DQR statistics for a set of GraceIDs This is meant to be a developer
tool, and therefore may not be as user-friendly as the rest of the library

positional arguments:
  sql_query             the query used to find GraceIDs

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         show verbose output (default: False)
  -V, --version         show program's version number and exit
  --superevents         query for superevents, otherwise we just query for
                        regular events (default: False)
  --gracedb-url GRACEDB_URL
                        DEFAULT=https://gracedb.ligo.org/api/ (default:
                        https://gracedb.ligo.org/api/)
  --toggle TOGGLE       specify a toggle that is active. Can be repeated to
                        specify multiple toggles.DEFAULT=None (no toggles
                        specified so all tasks are active). (default: [])
  --latency-quantile LATENCY_QUANTILE
                        quantiles reported for latency measurements. Can be
                        repeated to specify multiple quantiles. DEFAULT=[0.9]
                        (default: [0.9])

Executables¶

dqr-create¶

Example use cases¶

Helpstring¶

configuration file for dqr-create¶

dqr-interact¶

Example use cases¶

Helpstring¶

dqr-stats¶

Example use cases¶

Helpstring¶

Table of Contents

Previous topic

Next topic

This Page