.. _executables: 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: :ref:`configuring`. 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: :ref:`interact`. 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])