From 7da04f776761ee60403bd20a3ecbe911385a0d91 Mon Sep 17 00:00:00 2001
From: Branson Stephens <branson.stephens@ligo.org>
Date: Tue, 23 Jun 2015 15:01:56 -0500
Subject: [PATCH] Fixed some typos in REST docs. Added example of parsing
LVAlert messages.
---
doc/source/lvalert.rst | 186 +++++++++++++++++++++++++++++++++++++++--
doc/source/lvem.rst | 4 +
doc/source/rest.rst | 10 +--
doc/source/web.rst | 8 +-
4 files changed, 193 insertions(+), 15 deletions(-)
diff --git a/doc/source/lvalert.rst b/doc/source/lvalert.rst
index 4ceb5270d..360167c7a 100644
--- a/doc/source/lvalert.rst
+++ b/doc/source/lvalert.rst
@@ -39,7 +39,9 @@ nodes. Thus, a message sent to the node ``burst_cwb_allsky`` will *also* be sent
node ``burst_cwb``. This property allows the user to filter by search at the level of
specifying LVAlert processing scripts for individual nodes.
-.. tell them how to get the names of all of the nodes
+To see the names of all available nodes, simply execute::
+
+ lvalert_admin -a username -b password -i
LVAlert message contents
================================================
@@ -56,17 +58,185 @@ following keys:
For example, when a new event is created, an LVAlert message is created
with alert type ``new``, and the ``object`` is just the JSON representation of
of the event provided by the REST interface (see :ref:`searching_for_events`).
-
-.. examples of the different types
-.. demonstration of how to parse
-
-.. what kind of alert does a replacement trigger?
+Below are examples of the possible types of LVAlert message. These were generated
+by creating a new event, adding a couple of log messages, creating a Preliminary
+VOEvent, and applying the DQV label (in that order).
+
+New event::
+
+ {
+ "alert_type": "new",
+ "description": "",
+ "file": "https://gracedb.ligo.org/events/T129911/files/coinc.xml",
+ "object": {
+ "created": "2015-06-17 22:10:43 UTC",
+ "extra_attributes": {
+ "CoincInspiral": {
+ "combined_far": 3.772326334623149e-14,
+ "end_time": 968929613,
+ "end_time_ns": 817383681,
+ "false_alarm_rate": 3.654963804145501e-08,
+ "ifos": "H1,L1",
+ "mass": 2.621732950210571,
+ "mchirp": 1.139938473701477,
+ "minimum_duration": null,
+ "snr": 19.73621083881572
+ }
+ },
+ "far": 3.772326334623149e-14,
+ "gpstime": 968929613.8173836,
+ "graceid": "T129911",
+ "group": "Test",
+ "instruments": "H1,L1",
+ "labels": {},
+ "likelihood": 8.33784842725385e+44,
+ "links": {
+ "embb": "https://gracedb.ligo.org/api/events/T129911/embb/",
+ "filemeta": "https://gracedb.ligo.org/api/events/T129911/filemeta/",
+ "files": "https://gracedb.ligo.org/api/events/T129911/files/",
+ "labels": "https://gracedb.ligo.org/api/events/T129911/labels/",
+ "log": "https://gracedb.ligo.org/api/events/T129911/log/",
+ "neighbors": "https://gracedb.ligo.org/api/events/T129911/neighbors/",
+ "self": "https://gracedb.ligo.org/api/events/T129911",
+ "tags": "https://gracedb.ligo.org/api/events/T129911/tag/"
+ },
+ "nevents": 2,
+ "pipeline": "gstlal",
+ "search": "MDC",
+ "submitter": "branson.stephens@LIGO.ORG"
+ },
+ "uid": "T129911"
+ }
+
+
+Log message without file::
+
+ {
+ "alert_type": "update",
+ "description": "LOG: This is a test.",
+ "file": "",
+ "object": {
+ "N": 4,
+ "comment": "This is a test.",
+ "created": "2015-06-17T17:10:43.381117",
+ "file": null,
+ "file_version": null,
+ "filename": "",
+ "issuer": {
+ "display_name": "Branson Stephens",
+ "username": "branson.stephens@LIGO.ORG"
+ },
+ "self": "https://gracedb.ligo.org/api/events/T129911/log/4",
+ "tag_names": [
+ "analyst_comments"
+ ],
+ "tags": "https://gracedb.ligo.org/api/events/T129911/log/4/tag/"
+ },
+ "uid": "T129911"
+ }
+
+
+Log message with a file::
+
+ {
+ "alert_type": "update",
+ "description": "UPLOAD: bayestar.fits This is a file.",
+ "file": "bayestar.fits",
+ "object": {
+ "N": 6,
+ "comment": "This is a file.",
+ "created": "2015-06-17T17:10:43.980188",
+ "file": "https://gracedb.ligo.org/api/events/T129911/files/bayestar.fits%2C0",
+ "file_version": 0,
+ "filename": "bayestar.fits",
+ "issuer": {
+ "display_name": "Branson Stephens",
+ "username": "branson.stephens@LIGO.ORG"
+ },
+ "self": "https://gracedb.ligo.org/api/events/T129911/log/6",
+ "tag_names": [
+ "sky_loc"
+ ],
+ "tags": "https://gracedb.ligo.org/api/events/T129911/log/6/tag/"
+ },
+ "uid": "T129911"
+ }
+
+New VOEvent created::
+
+ {
+ "alert_type": "update",
+ "description": "VOEVENT: T129911-1-Preliminary.xml",
+ "file": "T129911-1-Preliminary.xml",
+ "object": {
+ "N": 1,
+ "created": "2015-06-17T17:10:44.172876",
+ "file": "https://gracedb.ligo.org/api/events/T129911/files/T129911-1-Preliminary.xml%2C0",
+ "file_version": 0,
+ "filename": "T129911-1-Preliminary.xml",
+ "issuer": {
+ "display_name": "Branson Stephens",
+ "username": "branson.stephens@LIGO.ORG"
+ },
+ "ivorn": "ivo://gwnet/gcn_sender#T129911-1-Preliminary",
+ "self": "https://gracedb.ligo.org/api/events/T129911/voevent/1",
+ "text": "<voevent text>",
+ "voevent_type": "PR"
+ },
+ "uid": "T129911"
+ }
+
+New DQV label applied::
+
+ {
+ "alert_type": "label",
+ "description": "DQV",
+ "file": "",
+ "uid": "T129911"
+ }
+
+.. XXX what kind of alert does a replacement trigger?
+
+Receiving and Parsing LVAlert messages
+====================================================
+
+The LVAlert client tools include the ``lvalert_listen`` executable, which can be used to
+receive and respond to LVAlert messages::
+
+ lvalert_listen -a username -b password -c /path/to/lvalert_config.ini
+
+The ``-c`` (configuration file) option allows you to specify an executable script to be called
+each time a message arrives over a particular node. Suppose one is only interested in
+events from the burst group, cWB pipeline, and MDC search. Then the
+``lvalert_config.ini`` file could look like this::
+
+ [burst_cwb_mdc]
+ executable = /path/to/mdc_event_handler
+
+And the script ``mdc_event_handler`` could be any script that is prepared to receive the
+LVAlert message contents through standard input. Here is an example in Python::
+
+ #!/usr/bin/env python
+ import json
+ from sys import stdin
+
+ # Load the LVAlert message contents into a dictionary
+ streamdata = json.loads(stdin.read())
+
+ # Do something with new events having FAR below threshold
+ alert_type = streamdata['alert_type']
+
+ if alert_type == 'new':
+ # The object is a serialized event. Get the FAR
+ far = streamdata['object']['far']
+
+ if far < 1.e-6:
+ # Do some interesting processing
+ pass
Further reading on LVAlert
=====================================================
-.. links to LVAlert documentation
-
Further information on using LVAlert can be found on the
`LVAlert Project Page <https://www.lsc-group.phys.uwm.edu/daswg/projects/lvalert.html>`_
and the `LVAlert Howto <https://www.lsc-group.phys.uwm.edu/daswg/docs/howto/lvalert-howto.html>`_.
diff --git a/doc/source/lvem.rst b/doc/source/lvem.rst
index 93e622fb4..51940f1c2 100644
--- a/doc/source/lvem.rst
+++ b/doc/source/lvem.rst
@@ -77,3 +77,7 @@ uploading observation records:
- by email (not yet availabe, but in the works)
+For more on the GraceBD event page and creating EM observation records, see
+`this <https://www.youtube.com/watch?v=oIJE4dTISs4>`_ helpful video
+by Roy Williams. There is a companion video on the SkymapViewer
+`here <https://www.youtube.com/watch?v=ydXUD9KIN98>`_.
diff --git a/doc/source/rest.rst b/doc/source/rest.rst
index a9887a187..a73b4d6bb 100644
--- a/doc/source/rest.rst
+++ b/doc/source/rest.rst
@@ -43,8 +43,8 @@ fully featured.
.. NOTE::
Before using the REST client, credentials for authentication must be available.
- Run ligo-proxy-init or, if using a robot certificate, set the appropriate envronment
- variables (for more infomation, see :ref:`auth`).
+ Run ligo-proxy-init or, if using a robot certificate, set the appropriate environment
+ variables (for more information, see :ref:`auth`).
The REST client is typically used in the Python interpreter or in a script to
accomplish a specific task, such as retrieving information about events matching
@@ -97,7 +97,7 @@ Searching for events
Suppose you are working on a script to search for all events matching a
specific query and retrieve a piece of information about each event in
the search results. For example, the following code retrieves the chirp
-mass for each gstlal event during ER5 with FAR less than 1.0E-4::
+mass for each ``gstlal`` event during ER5 with FAR less than 1.0E-4::
from ligo.gracedb.rest import GraceDb
client = GraceDb()
@@ -116,7 +116,7 @@ mass for each gstlal event during ER5 with FAR less than 1.0E-4::
Note that the ``events`` method on the client returns an iterator on
event dictionaries rather than a list. The chirp mass is an attribute
specific the inspiral event subclass, hence the difference between accessing
-the graceid and the chirp mass.
+the ``graceid`` and the chirp mass.
But how did I know the structure of the event dictionary so that I could
pull out the chirp mass? The best way is to look at the structure of an
@@ -240,7 +240,7 @@ Coding against the GraceDB REST API
Some users may wish to code directly against the GraceDB REST API rather
than use the Python or command-line clients. In order to do this, the user
-will need to know which resources are exposed by which URLS, and which HTTP
+will need to know which resources are exposed by which URLs, and which HTTP
methods those URLs allow. Fortunately, the
`Django REST Framework <http://www.django-rest-framework.org>`_ (on which
the GraceDB API is built) provides
diff --git a/doc/source/web.rst b/doc/source/web.rst
index 26b9b6939..92b64cdf3 100644
--- a/doc/source/web.rst
+++ b/doc/source/web.rst
@@ -10,11 +10,15 @@ Under construction.
Understanding the event page
===============================
-.. links to Roy's videos
+Under construction.
.. include a bit on tagging annotations
-Under construction.
+For more on the GraceDB event page, see
+`this <https://www.youtube.com/watch?v=oIJE4dTISs4>`_ helpful video
+by Roy Williams, which is geared toward LV-EM users. There is a
+companion video on the SkymapViewer
+`here <https://www.youtube.com/watch?v=ydXUD9KIN98>`_.
Signing up for email alerts (LVC only)
=======================================================
--
GitLab