Commit a737109e authored by Tanner Prestegard's avatar Tanner Prestegard Committed by GraceDB

docs: update user documentation

parent a6bacaf7
......@@ -50,8 +50,8 @@ master_doc = 'index'
# General information about the project.
project = u'GraceDB'
copyright = u'2015, Brian Moe, Branson Stephens, Patrick Brady'
author = u'Brian Moe, Branson Stephens, Patrick Brady'
copyright = u'2019, Tanner Prestegard, Alexander Pace, Brian Moe, Branson Stephens, Patrick Brady'
author = u'Tanner Prestegard, Alexander Pace, Brian Moe, Branson Stephens, Patrick Brady'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......
......@@ -35,7 +35,6 @@ purposes. The diagram above depicts a typical sequence of events:
Overview of components
======================
GraceDB consists of the server (`gracedb.ligo.org <https://gracedb.ligo.org>`__)
and a set of client tools. Two user interfaces are available: the web interface
for browser access (i.e., the one you are using now), and the
......@@ -44,20 +43,18 @@ These interfaces represent the information in GraceDB in different ways:
the web interface naturally represents information as HTML pages, whereas
the REST interface delivers JSON-serialized data.
The client tools (available via ``pip``, SL6 or Debian packages, and source
build, see :ref:`installing_the_client`) provide a way to interact via the REST API.
These tools include a Python client class
with methods for all common GraceDB operations.
There is also a ``gracedb`` executable for the command line with much of
the same functionality.
The `ligo-gracedb client package <https://gw.readthedocs.io/ligo-gracedb>`__ provides a convenient way to interact with the REST API.
This package includes a Python client class with methods for all common GraceDB operations.
There is also a ``gracedb`` executable for the command line with much of the same functionality.
The GraceDB API conforms to the RESTful principles of "uniform interface" and
"resource-oriented architecture".
Where can I go for help?
==================================
This documentation is not as great as it could be, but we are working on it.
This documentation is not as great as it could be, but
we are working on it. For help with issues not addressed here, please
send mail to uwm-help@ligo.org.
LIGO/Virgo users can join the GraceDB channel in the collaboration's Mattermost instance or email the DASWG mailing list for help.
To report a problem, either `post an issue <https://git.ligo.org/lscsoft/gracedb/issues>`__ or send mail to uwm-help@ligo.org.
......@@ -11,8 +11,9 @@ Contents:
.. toctree::
:maxdepth: 2
ref_manual
ref_manual
tutorials
Documentation for the ligo-gracedb client package <https://gw.readthedocs.io/ligo-gracedb>
LIGO/Virgo Public Alert Guide <https://emfollow.docs.ligo.org/userguide/>
Report a bug (LIGO/Virgo users) <https://git.ligo.org/lscsoft/gracedb/issues>
......
=====================================
Integration with LVAlert
=====================================
======================================
LVAlert notifications (LVC users only)
======================================
Introduction
===============================================
============
LVAlert (LIGO-Virgo Alert system) is an XMPP-based messaging platform used within the LVC.
This document will describe how GraceDB uses LVAlert, which nodes it manages and publishes to, and the content of LVAlert messages sent by GraceDB.
.. GraceDB uses `LVAlert <https://wiki.ligo.org/Computing/DASWG/LVAlert>`__ to send alerts to listeners within the LVC when.
GraceDB uses `LVAlert <https://wiki.ligo.org/Computing/DASWG/LVAlert>`__ to send alerts to listeners within the LVC.
The content of the LVAlert message is designed to convey actionable information about a state change in GraceDB, whether it involves the creation of a new event, or the updating or labeling of an existing one.
Some helpful resources for installing and configuring LVAlert are:
- Main ligo-lvalert `documentation <https://lscsoft.docs.ligo.org/lvalert/index.html>`__
- ligo-lvalert `user guide <https://lscsoft.docs.ligo.org/lvalert/guide.html>`__
- :ref:`Tutorial<responding_to_lvalert>` on setting up LVAlert and configuring your listener.
LVAlert and GraceDB
===================
Generally speaking, GraceDB uses LVAlert to send "push" notifications about different actions that may be taken on the service.
Users can subscribe to different nodes (more below) to receive these notifications, filter their content, and optionally trigger follow-up processes, like data quality checks, parameter estimation, and more.
The content of an LVAlert message is designed to convey actionable information about a state change in GraceDB, including event creation, annotation, and other actions.
.. NOTE::
An LVAlert message is sent out for *any* new event or annotation that arrives in the GraceDB database.
This means that message volumes may be very high under certain circumstances, and appropriate filtering is required in order for LVAlert to be useful.
This means that message volumes may be very high under certain circumstances, and listeners should be constructed to appropriately filter the messages.
Listening to specific event streams
==============================================
LVAlert nodes managed by GraceDB
================================
By running ``lvalert_listen``, you will receive messages over all **nodes** to which you are subscribed.
There are two types of nodes to which GraceDB broadcasts alerts: event nodes and superevent nodes.
Event nodes
-----------
Event node names consist of at least two elements::
<group_name>_<pipeline_name>
......@@ -30,46 +46,45 @@ One can also specify the search name::
which has the effect of narrowing down the messages to only those related to a specific search.
For example, the node ``burst_cwb_allsky`` will contain messages relating to the AllSky search, but not the MDC search.
Note that GraceDB tries to send a message to all applicable nodes.
Thus, a message sent to the node ``burst_cwb_allsky`` will *also* be sent to the more generic node ``burst_cwb``.
This property allows the user to filter according to search by specifying different LVAlert processing scripts for different nodes.
It is important to note that GraceDB will send an LVAlert to all nodes which match the parameters of the event in question.
For example, the creation of a Burst-cWB-AllSky event will result in messages being sent to the ``burst_cwb_allsky`` node, as well as the more generic ``burst_cwb`` node.
This feature allows the user to filter according to search by specifying different LVAlert processing scripts for different nodes.
Superevent nodes
----------------
There are only three superevent nodes; one for each category of superevent:
- ``superevent``
- ``test_superevent``
- ``mdc_superevent``
To see the names of all available nodes, simply execute::
lvalert_admin -a username -i
For more information on how to receive and react to LVAlert messages, see :ref:`responding_to_lvalert`.
Most users will be interested in the ``superevent`` node in order to receive LVAlerts about real GW candidates.
LVAlert message contents
================================================
GraceDB sends messages as a JSON-encoded dictionary.
Contents of LVAlerts sent by GraceDB
====================================
GraceDB sends LVAlert messages as a JSON-encoded dictionary.
This dictionary contains the following keys:
- ``alert_type``: short string representing the. Examples: ``new``, ``update``, ``label_added``, etc. All alert types are shown in the tables below.
- ``alert_type``: short string representing the action which triggered the alert. Examples: ``new``, ``update``, ``label_added``, etc. All alert types are shown in the tables below.
- ``data``: a dictionary representing the relevant object (label, log message, etc.)
- ``object``: a dictionary representing the corresponding "parent" object
- ``object``: a dictionary representing the corresponding "parent" object (i.e., the event or superevent which a log, label, etc. is attached to).
- ``uid``: the unique ID of the relevant event or superevent
Below, we describe the alert contents in more detail.
Examples of the various ``data``/``object`` dictionaries are available in :ref:`models`.
See :ref:`below<example_permissions_list>` for one additional example (list of permissions).
Event alerts
------------
For alerts related to events, the following things are always true:
- ``uid`` is always the event's ``graceid`` (example: G123456).
- ``object`` is always a dictionary corresponding to the event which is affected by the label, log, VOEvent, etc.
The following table shows the ``alert_type`` and ``data`` for different actions:
+-------------------------+---------------------------------+---------------------------------------------------------+
......@@ -113,7 +128,6 @@ The following table shows the ``alert_type`` and ``data`` for different actions:
Superevent alerts
-----------------
For alerts related to superevents, the following things are always true:
- ``uid`` is always the superevent's ``superevent_id`` (example: S800106D).
......@@ -162,14 +176,5 @@ The following table shows the ``alert_type`` and ``data`` for different actions:
Example: list of permission dictionaries
----------------------------------------
.. literalinclude:: dicts/permissions.list
:language: JSON
Further reading on LVAlert
=====================================================
Further information on using LVAlert can be found on the
`LVAlert Project Page <https://wiki.ligo.org/Computing/DASWG/LVAlert>`__
and the `LVAlert Howto <https://wiki.ligo.org/Computing/DASWG/LVAlertHowto>`__.
......@@ -2,6 +2,15 @@
Features for EM Collaboration
=============================
.. NOTE::
This document describes access and features provided to members of
collaborations which the LSC had an MOU with in O1 and O2. This access
is maintained at present (August 2019), but may not be going forward.
The information contained on this page will not be updated or
maintained, and will eventually be removed.
On logging in
=============
......@@ -22,6 +31,7 @@ according to the identity you used for registering for LV-EM membership at
there is no way (at present) to map these different identities to the same
underlying user.
.. _basic_auth_for_lvem:
Scripted access for LV-EM members
......@@ -65,14 +75,12 @@ to make sure that only you can read it). The ``.netrc`` file could look like thi
Place the resulting ``.netrc`` file in your home directory.
Once that's done, you should be able to access the GraceDB REST API
using any tool that supports basic auth.
For example, you can use the GraceDB Python client in much the same
way as described in :ref:`rest_client_basic_usage`, except that the
client class is specially formulated for basic auth::
For example, you can use the GraceDB Python client::
from ligo.gracedb.rest import GraceDbBasic, HTTPError
from ligo.gracedb.rest import GraceDb, HTTPError
service_url = 'https://gracedb.ligo.org/api/'
client = GraceDbBasic(service_url)
client = GraceDb(service_url, username='user', password='pass')
try:
r = client.ping()
......@@ -82,16 +90,14 @@ client class is specially formulated for basic auth::
print "Response code: %d" % r.status
print "Response content: %s" % r.json()
The only real difference is that the ``GraceDbBasic`` client class is used instead
of the ``GraceDb`` class (which assumes that X509 credentials are available).
If you're not comfortable using Python for scripted access to GraceDB, it is
also possible to use ``curl`` to directly make requests to the server with the
same basic auth credentials. Some examples of using curl are available
`here <https://gw-astronomy.org/wiki/LV_EM/TechInfo>`__.
Downloading a skymap
======================
The GraceDB Python client can be used to download
files from Gracedb or add comments, plots, or observation records (see
the next section). Here, we'll
......@@ -117,11 +123,11 @@ This file can be retrieved in the following way::
out_file.write(r.read())
out_file.close()
.. _create_emobservation:
Reporting coordinates of followup observations
===============================================
In the following example, the GraceDB Python client is used to create an
observation record consisting of three separate footprints::
......@@ -169,7 +175,5 @@ something like "delete GraceDB EMObservation" in the subject line. Tell us
which entry you'd like deleted, and we'll take care of it. In the future, we
are hoping to make these observation records editable by the submitter.
For more on the GraceDB 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>`__.
.. For more on the GraceDB 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>`__.
......@@ -12,10 +12,10 @@ Contents:
models
web
rest
auth
queries
labels
lvalert
notifications
lvem
auth
......@@ -6,6 +6,14 @@ Responding to LVAlert Messages
.. sectionauthor:: Reed Essick
.. NOTE::
This tutorial may not be fully up-to-date. The preferred resource for
installing ligo-lvalert and configuring a listener is the
ligo-lvalert `user guide <https://lscsoft.docs.ligo.org/lvalert/guide.html>`__.
However, at present (August 2019), it is not fully completed, and the tutorial
on this page may still provide some useful information.
This tutorial will show you how to
* register to receive LVAlerts
* subscribe and unsubscribe from pubsub nodes
......
This diff is collapsed.
......@@ -44,26 +44,11 @@ The existing tags are also shown in the same column as the message itself, as is
Users are free to create new tags for their own purposes (e.g., searching through annotations at some
later date), but only a pre-determined list of tags is used to create title pane sections.
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 also is a `companion video <https://www.youtube.com/watch?v=ydXUD9KIN98>`__ on the SkymapViewer.
.. 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 also is a `companion video <https://www.youtube.com/watch?v=ydXUD9KIN98>`__ on the SkymapViewer.
Understanding the superevent detail page
========================================
The detail page for a superevent can be accessed similarly to an event page.
The content is analogous to that shown on the event page, although it contains information about the superevent in general, as well as a table summarizing the information about the superevent's preferred event.
Signing up for email or phone alerts (LVC only)
=======================================================
LVC users may set up email or phone notifications for events that come from specific pipelines and have specific labels.
This feature is available to LVC users only because the events are not vetted before the alert is sent out.
For non-LVC users, GCN will provide the equivalent functionality.
See the LV-EM `techinfo page <https://gw-astronomy.org/wiki/LV_EM/TechInfo>`__.)
In order to sign up for an alert, you must first create a contact by clicking on "OPTIONS" in the navigation menu, and then "Create New Contact."
Follow the instructions on that page to add your contact information.
Next, return to the options page and click "Create New Notification".
This page allows you to set the criteria for alerts to be sent to the contact that you created in the previous step.
These are currently only available for events, but may be extended to superevents in the future.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment