Creating a client instance¶
ligo.gracedb.rest.GraceDb is the client class and is used for all API interactions.
To instantiate a client object, do:
from ligo.gracedb.rest import GraceDb client = GraceDb()
By default, the client uses the API of the production GraceDB server, https://gracedb.ligo.org/api/.
To specify another server, use the
service_url keyword argument:
client = GraceDb(service_url='https://gracedb-playground.ligo.org/api/')
If you are working behind a proxy, use the
proxy_port arguments to specify the parameter of the proxy server:
client = GraceDb(proxy_host='myproxy.com', proxy_port=8443)
More information about the client class and the options which can be provided to the constructor is covered in detail on the API page.
Credentials are not required, but users who possess them will likely want to authenticate in order to gain full access to the GraceDB server.
LIGO/Virgo users can provide an X.509 certificate to the client for authenticating to the GraceDB server.
This can be a proxy certificate which is generated by
ligo-proxy-init, another certificate which has been registered with the LIGO auth system, or a robot certificate.
There are multiple methods for making these credentials available to the client class, detailed in the documentation for
These certificates may expire after some period of time and need to be renewed.
If you have long-running jobs where the lifetime of a client may exceed that of your certificate,
reload_certificate argument (and optionally, the
reload_buffer argument) when instantiating a client object.
On each request, the client will check whether your certificate has expired; if it has, the client will attempt to reload the certificate before sending the request to the server.
NOTES: the client requires that your renewed certificate is in the same location as the old one. Users may want to set up a cron job to facilitate auto-renewal of their certificate.
Password-based authentication to limited portions of the GraceDB API has historically been available to partner astronomers who have an MOU with LIGO/Virgo.
The documentation for
ligo.gracedb.rest.GraceDb details how to provide these credentials to the client.
This authentication mechanism may be phased out in the future.
Most of the client methods return a
The server API provides a JSON response which is loaded into a Python
dict by using the
response = client.event('G1234') data = response.json()
The exact structure of the resulting dictionary varies depending on which resource type you are retrieving (event, superevent, log entry, etc.). A variety of examples are available in the server code documentation.
Note that most client methods will raise a
ligo.gracedb.exceptions.HTTPError if the response code indicates an error (>= 400).
Basic usage for events¶
Create an event¶
Create an event on the server with the
response = client.createEvent('CBC', 'gstlal', '/path/to/event/data/file.xml', search='LowMass')
Any LVC user can create “test” events by specifying the first argument (analysis group) as
Special permissions are required to upload non-test events.
You can get a list of available analysis groups with
ligo.gracedb.rest.GraceDb.groups, available analysis pipelines with
ligo.gracedb.rest.GraceDb.pipelines, or a list of searches with
The type of data file depends on which pipeline is submitting the event. If you are not a pipeline expert, you may want to download a file from an existing event and use that for creating test events.
Update an event¶
Update an event’s parameters by uploading a new event data file with the
response = client.replaceEvent('G123456', '/path/to/new/event/data/file.xml')
Only the user who originally submitted the event is allowed to update it.
Search for events¶
ligo.gracedb.rest.GraceDb.events() method to search for events and get an iterator:
event_iterator = client.events('far < 1e-10') graceids = [event['graceid'] for event in event_iterator]
See the server documentation for help with constructing search queries. Note that test and MDC events are not included in the search results by default.
Basic usage for superevents¶
Create a superevent¶
ligo.gracedb.rest.GraceDb.createSuperevent() method to create a superevent:
response = client.createSuperevent(1238350677, 1238350680, 1238350682, 'G1234')
G1234 must already exist on the server, and the
category (production, test, or MDC) of the superevent must match that of the event.
Special permissions are required to create non-test superevents.
Update a superevent¶
ligo.gracedb.rest.GraceDb.updateSuperevent() method to update a superevent:
response = client.updateSuperevent('S190202p', t_0=1238350700, preferred_event='G2345')
Note that this method is used to update the
preferred_event parameters of the superevent only.
To add events to or remove events from a superevent, use
Search for superevents¶
ligo.gracedb.rest.GraceDb.superevents() method to search for superevents and get an iterator:
superevent_iterator = client.superevents('public is_gw: True') superevent_ids = [superevent['superevent_id'] for superevent in superevent_iterator]
See the server documentation for help with constructing search queries. Note that test and MDC superevents are not included in the search results by default.
Both events and superevents can be annotated with log entries, file uploads, labels, and more. There are several methods attached to the client class for creating these annotations and for getting information about existing annotations. Most of these methods work for both events and superevents and automatically determine which one you are interested in based on the format of the ID provided.
To create a log entry, use the
response = client.writeLog('G1234', 'comment on event')
You can also upload a file with a log entry:
response = client.writeLog('S190202b', 'comment on event', filename='/path/to/file/')
To get a log or list of logs attached to an event or superevent, use the
response = client.logs('G1234', 12)
Here the second argument is the index number of the log, which represents its chronological order in the entire set of logs for the event or superevent. If this argument is not provided, the entire set of logs for the event or superevent will be retrieved.
The procedure for uploading files is covered in the previous section on log entries.
To retrieve a list of files attached to an event or superevent, use
response = client.files('G1234')
If a specific filename is provided, the server will provide the contents of the file with that name that is associated with the given event or superevent:
response = client.files('G1234', 'skymap.fits.gz') file_contents = response.read()
Note that files are the server are versioned; i.e., uploading a file with the same name as another file attached to the same event or superevent will generate a new version.
Different versions are specified by appending
,N to the filename, where
N is the version number.
Filenames without a version always point to the latest version of the file.
Labels can be applied to or removed from events or superevents. They are generally used to indicate some sort of state. Examples:
ADVREQ: advocate signoff is requested
PE_READY: parameter estimation results are available
DQV: the event or superevent is vetoed due to poor data quality
To add a label, use
response = client.writeLabel('G1234', 'ADVREQ')
To remove a label, use
response = client.removeLabel('S190214g', 'INJ')