API¶
This section provides detailed information about the ligo.gracedb.rest.GraceDb
client class which is the primary method for accessing the GraceDB API.
-
class
ligo.gracedb.rest.
GraceDb
(service_url='https://gracedb.ligo.org/api/', proxy_host=None, proxy_port=3128, cred=None, username=None, password=None, force_noauth=False, fail_if_noauth=False, api_version=None, reload_certificate=False, reload_buffer=300)¶ GraceDb REST client class.
Provides a client object for accessing the GraceDB server API. Various methods are provided for retrieving information about different objects and uploading information.
Lookup of user credentials is done in the following order:
- If provided, import X.509 credentials from the certificate-key pair or combined proxy file provided in the
cred
keyword arg. - If provided, use the username and password provided in the keyword arguments.
- If the
X509_USER_CERT
andX509_USER_KEY
environment variables are set, load the corresponding certificate and key. - If the
X509_USER_PROXY
environment variable is set, load the corresponding proxy file. - Look for a X.509 proxy from ligo-proxy-init in the default location (
/tmp/x509up_u${UID}
). - Look for a certificate and key file in
$HOME/.globus/usercert.pem
and$HOME/.globus/userkey.pem
. - Look for a username and password for the server in
$HOME/.netrc
. - Continue with no authentication credentials.
Parameters: - url (
str
, optional) – URL of server API root. - proxy_host (
str
, optional) – proxy hostname. - proxy_port (
str
, optional) – proxy port. - cred (
tuple
orstr
, optional) – a tuple or list of (/path/to/cert/file
,/path/to/key/file
) or a single path to a combined proxy file. Used for X.509 authentication only. - username (
str
, optional) – username for basic auth. - password (
str
, optional) – password for basic auth. - force_noauth (
bool
, optional) – set to True if you want to skip credential lookup and use this client without authenticating to the server. - fail_if_noauth (
bool
, optional) – set toTrue
if you want the client constructor to fail if no authentication credentials are provided or found. - api_version (
str
, optional) – choose the version of the server API to use. At present, there is only one version, but this argument is provided with the expectation that this will change in the future. - reload_certificate (
bool
, optional) – if True, your certificate will be checked before each request whether it is withinreload_buffer
seconds of expiration, and if so, it will be reloaded. Useful for processes which may live longer than the certificate lifetime and have an automated method for certificate renewal. The path to the new/renewed certificate must be the same as for the old certificate. - reload_buffer (
int
, optional) – buffer (in seconds) for reloading a certificate in advance of its expiration. Only used ifreload_certificate
isTrue
.
Examples
Instantiate a client to use the production GraceDB server:
>>> g = GraceDb()
Use another GraceDB server:
>>> g = GraceDb(service_url='https://gracedb-playground.ligo.org/api/')
Use a certificate and key in the non-default location:
>>> g = GraceDb(cred=('/path/to/cert/file', '/path/to/key/file'))
-
addEventToSuperevent
(superevent_id, graceid)¶ Add an event to a superevent.
The event must be in the same category as the superevent and must not already be part of a superevent.
Parameters: - superevent_id (str) – GraceDB ID of the superevent to which the event will be added.
- graceid (str) – graceid of the event to add to this superevent.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = addEventToSuperevent('S181224a', 'G123456') >>> r.status 201
-
addTag
(object_id, N, tag_name, displayName=None, *args, **kwargs)¶ Add a tag to an event or superevent log entry.
Parameters: - object_id (str) – event graceid or superevent ID.
- N (int) – ID number of log entry.
- tag_name (str) – name of tag to add; tags which don’t already exist on the server will be created.
- displayName (
str
, optional) – tag display name; only used to create new tags which don’t already exist.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.createTag('T101383', 56, 'sky_loc') >>> r.status 201
-
allowed_labels
¶ List of available labels on the server.
-
api_versions
¶ List of available API versions on the server.
-
confirm_superevent_as_gw
(superevent_id)¶ Upgrade a superevent’s state to ‘confirmed GW’.
All LIGO-Virgo users can perform this action on test superevents, but special permissions are required for production and MDC superevents. This action cannot be undone!
Parameters: superevent_id (str) – GraceDB ID of the superevent to confirm as as GW. Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = confirm_superevent_as_gw('S181224a') >>> r.status 204
-
createEvent
(group, pipeline, filename, search=None, labels=None, offline=False, filecontents=None, **kwargs)¶ Create a new event on the server.
All LIGO-Virgo users can create events in the ‘Test’ group. Special permissions are required to create non-test events.
Parameters: - group (str) – name of the analysis group which identified the candidate.
- pipeline (str) – name of the analysis pipeline which identified the candidate.
- filename (str) – path to event file to be uploaded. Use
'-'
to read from stdin. - search (
str
, optional) – type of search being run by the analysis pipeline. - labels (
str
orlist[str]
, optional) – label(s) to attach to the event upon creation. Should be a string (single label) or list of strings (multiple labels). - offline (
bool
, optional) – ifTrue
, indicates that the event was found by an offline analysis. - filecontents (
str
, optional) – string to be uploaded to the server and saved into a file. If event data is uploaded via this mechanism, thefilename
argument is only used to set the name of the file once it is saved on the server.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.createEvent('CBC', 'gstlal', '/path/to/something.xml', ... labels='INJ', search='LowMass') >>> r.status 201
-
createSuperevent
(t_start, t_0, t_end, preferred_event, category='production', events=None, labels=None)¶ Create a superevent.
All LIGO-Virgo users can create test superevents, but special permissions are required to create production and MDC superevents.
Parameters: - t_start (float) – tstart of the superevent
- t_0 (float) – t0 of the superevent
- t_end (float) – tend of the superevent
- preferred_event (str) – graceid corresponding to the event which
will be set as the preferred event for this superevent. This
event must be in the same
category
as the superevent and not already attached to a superevent. - category (
str
, optional) – superevent category. Allowed choices are: ‘production’, ‘test’, ‘mdc’. - events (
str
orlist[str]
, optional) – graceid or list of graceids corresponding to events which should be included in this superevent. Events must be in the samecategory
as the superevent and not already attached to a superevent. - labels (
str
orlist[str]
, optional) – label or list of labels which should be attached to this superevent at creation.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.createSuperevent(1, 2, 3, 'G123456', ... category='production', events=['G100', 'G101'], ... labels=['EM_READY', 'DQV']) >>> r.status 201
-
createVOEvent
(object_id, voevent_type, skymap_type=None, skymap_filename=None, combined_skymap_filename=None, internal=True, open_alert=False, raven_coinc=False, hardware_inj=False, CoincComment=False, ProbHasNS=None, ProbHasRemnant=None, BNS=None, NSBH=None, BBH=None, Terrestrial=None, MassGap=None, *args, **kwargs)¶ Create a new VOEvent.
Parameters: - object_id (str) – event graceid or superevent ID.
- voevent_type (str) – VOEvent type (choose from
'preliminary'
,'initial'
,'update'
, and'retraction'
). - skymap_type (
str
, optional) – skymap type. Required for VOEvents which include a skymap. - skymap_filename (
str
, optional) – name of skymap file on the GraceDB server (required for ‘initial’ and ‘update’ alerts, optional for ‘preliminary’ alerts). - combined_skymap_file (
str
, optional) – name of combined skymap file, if present - internal (
bool
, optional) – whether the VOEvent should be distributed to LIGO-Virgo members only. - hardware_inj (
bool
, optional) – whether the candidate is a hardware injection. - open_alert (
bool
, optional) – whether the candidate is an open alert or not. - raven_coinc (
bool
, optional) – is VOEvent result of coincidence from RAVEN pipeline. Tells GraceDB to look for coinc_far and em_type data models. - CoincComment (
bool
, optional) – whether the candidate has a possible counterpart GRB. - ProbHasNS (
float
, optional) – probability that at least one object in the binary is less than 3 Msun (CBC events only). - ProbHasRemnant (
float
) – probability that there is matter in the surroundings of the central object (CBC events only). - BNS (
float
, optional) – probability that the source is a binary neutron star merger (CBC events only). - NSBH (
float
, optional) – probability that the source is a neutron star-black hole merger (CBC events only). - BBH (
float
, optional) – probability that the source is a binary black hole merger (CBC events only). - Terrestrial (
float
, optional) – probability that the source is terrestrial (i.e., a background noise fluctuation or a glitch) (CBC events only). - MassGap (
float
, optional) – probability that at least one object in the binary has a mass between 3 and 5 Msun (CBC events only).
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.createVOEvent('T101383', 'initial', skymap_type='custom', ... skymap_filename='skymap.fits.gz', internal=True, ProbHasNS=0.7, ... MassGap=0.4, Terrestrial=0.05) >>> r.status 201
-
create_signoff
(object_id, signoff_type, status, comment, instrument='', *args, **kwargs)¶ Create a superevent signoff.
This action requires special server-side permissions. You must be in the control room of an IFO to perform operator signoffs or in the ‘em_advocates’ group to perform advocate signoffs. This action is not yet implemented for events.
Parameters: - object_id (str) – superevent ID.
- signoff_type (str) – signoff type. Choices are:
'OP'
or'operator'
(operator signoff), or'ADV'
or'advocate'
(advocate signoff). - status (str) – signoff status (
'OK'
or'NO'
). - comment (str) – comment on the signoff.
- instrument (
str
, optional) – instrument abbreviation ('H1'
,'L1'
, etc.) for operator signoffs. Leave blank for advocate signoffs.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.create_signoff('S190102p', 'OP', 'OK', ... 'LHO looks good.', instrument='H1') >>> r.status 201
-
delete_signoff
(object_id, signoff_type, instrument='', *args, **kwargs)¶ Delete a superevent signoff.
This action requires the same permissions as
create_signoff()
.Parameters: - object_id (str) – superevent ID.
- signoff_type (str) – signoff type. Choices are:
'OP'
or'operator'
(operator signoff), or'ADV'
or'advocate'
(advocate signoff). - instrument (
str
, optional) – instrument abbreviation ('H1'
,'L1'
, etc.) for operator signoffs. Leave blank for advocate signoffs.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.delete_signoff('S190102p', 'OP', instrument='H1') >>> r.status 204
-
em_groups
¶ List of available EM groups on the server.
-
emobservations
(object_id, emobservation_num=None, *args, **kwargs)¶ Get EM observation data associated with an event or superevent.
If
emobservation_num
is provided, get a single EM observation data entry. Otherwise, retrieve all EM observation data associated with the event or superevent in question.Parameters: - object_id (str) – event graceid or superevent ID.
- emobservation_num (
int
, optional) – ID number (N) of the EM observation to retrieve.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Examples
Get a list of EM observations:
>>> g = GraceDb() >>> r = g.emobservations('T101383') >>> full_dictionary = r.json() >>> emo_list = full_dictionary['observations']
Get a single EM observation:
>>> g = GraceDb() >>> r = g.emobservations('T101383', 2) >>> observation_dict = r.json()
-
event
(graceid)¶ Get information about an individual event.
Parameters: graceid (str) – GraceDB ID of the event Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> event_dict = g.event('T101383').json()
-
events
(query=None, orderby=None, max_results=None, **kwargs)¶ Search for events which match a query.
Information on forming queries is available here: https://gracedb.ligo.org/documentation/queries.html
Parameters: - query (
str
, optional) – query string. - orderby (
str
, optional) – field to order the results by. - max_results (
int
, optional) – maximum number of results to return (default: all).
Returns: Iterator[dict]
An iterator which yields individual event dictionaries.
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> for event in g.events('ER5 submitter: "gstlalcbc"'): ... print(event['graceid'], event['far'], event['gpstime'])
- query (
-
files
(object_id, filename='', *args, **kwargs)¶ Get a list of files or download a file associated with an event or superevent.
If
filename
is not provided, get a list of available files associated with the event or superevent. Iffilename
is provided, download the contents of that file.Parameters: - object_id (str) – event graceid or superevent ID.
- filename (
str
, optional) – name of file to download.
Returns: httplib.HTTPResponse
When
filename
is not specified,response.json()
contains a dict with file basename keys and full file URL values. Whenfilename
is specified, useresponse.read()
to get the contents of the file.Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Examples
Get a list of files:
>>> g = GraceDb() >>> event_files = g.files('T101383').json() >>> for filename in list(event_files): ... # do something ... pass
Get a file’s content:
>>> outfile = open('my_skymap.png', 'w') >>> r = g.files('T101383', 'skymap.png') >>> outfile.write(r.read()) >>> outfile.close()
-
get_user_info
()¶ Get information from the server about your user account.
-
groups
¶ List of available analysis groups on the server.
-
instruments
¶ List of available instruments on the server.
-
labels
(object_id, label='', *args, **kwargs)¶ Get a label or labels attached to an event or superevent.
Parameters: - object_id (str) – event graceid or superevent ID.
- label (
str
, optional) – name of label.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Examples
Get a list of labels:
>>> g = GraceDb() >>> label_list = g.labels('T101383').json()['labels'] >>> for label in label_list: ... print label['name']
Get a single label:
>>> g = GraceDb() >>> dqv_label = g.labels('T101383', 'DQV').json()
-
logs
(object_id, log_number=None, *args, **kwargs)¶ Get log entries associated with an event or superevent.
If
log_number
is specified, only a single log message is returned. Otherwise, all log messages attached to the event or superevent in question are returned.Parameters: - object_id (str) – event graceid or superevent ID.
- log_number (
int
, optional) – ID number (N) of the log entry to retrieve.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Examples
Get all log messages:
>>> g = GraceDb() >>> response_dict = g.logs('T101383').json() >>> print "Num logs = %d" % response_dict['numRows'] >>> log_list = response_dict['log'] >>> for log in log_list: ... print log['comment']
Get a single log message:
>>> g = GraceDb() >>> log_info = g.logs('T101383', 10).json()
-
modify_permissions
(object_id, action, *args, **kwargs)¶ Expose or hide a superevent to/from the public.
This action requires special server-side permissions. It is not yet implemented for events.
Parameters: - object_id (str) – superevent ID.
- action (str) –
'expose'
or'hide'
.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
Expose a superevent:
>>> g = GraceDb() >>> g.modify_permissions('S190304bc', 'expose').json() [ {'group': 'group1', 'permission': 'view_superevent'}, {'group': 'group1', 'permission': 'annotate_superevent'}, {'group': 'group2', 'permission': 'view_superevent'}, ]
Hide a superevent:
>>> g.modify_permissions('S190304bc', 'hide').json() []
-
numEvents
(query=None)¶ Get the number of events satisfying a query.
Parameters: query ( str
, optional) – query string.Returns: The number of events which matched the given query. Return type: int Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> g.numEvents('ER5 submitter: "gstlalcbc"') 213
-
permissions
(object_id, *args, **kwargs)¶ Get a list of permissions for a superevent.
Only LIGO-Virgo members are allowed to access this information. This is not currently implemented for events.
Parameters: object_id (str) – superevent ID. Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> g.permissions('S190304bc').json()['permissions'] [ {'group': 'group1', 'permission': 'view_superevent'}, {'group': 'group1', 'permission': 'annotate_superevent'}, {'group': 'group2', 'permission': 'view_superevent'}, ]
-
ping
()¶ Ping the server.
Returns: httplib.HTTPResponse
response.json()
contains the information from the API root.Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.
-
pipelines
¶ List of available analysis pipelines on the server.
-
removeEventFromSuperevent
(superevent_id, graceid)¶ Remove an event from a superevent.
The event must already be a part of the superevent.
Parameters: - superevent_id (str) – GraceDB ID of the superevent from which the event will be removed.
- graceid (str) – graceid of the event to remove from this superevent.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = removeEventFromSuperevent('S181224a', 'G123456') >>> r.status 204
-
removeLabel
(object_id, label, *args, **kwargs)¶ Remove a label from an event or superevent.
Parameters: - object_id (str) – event graceid or superevent ID.
- label (str) – label name. The label must be presently applied to the event or superevent.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.removeLabel('T101383', 'DQV') >>> r.status 204
-
removeTag
(object_id, N, tag_name, *args, **kwargs)¶ Remove a tag from an event or superevent log entry.
Parameters: - object_id (str) – event graceid or superevent ID.
- N (int) – ID number of log entry.
- tag_name (str) – name of tag to add; tags which don’t already exist on the server will be created.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.deleteTag('T101383', 56, 'sky_loc') >>> r.status 200
-
replaceEvent
(graceid, filename, filecontents=None)¶ Replace an existing event by uploading a new event file.
The event’s parameters are updated from the new file. Only the user who originally created the event can update it.
Parameters: - graceid (str) – GraceDB ID of the existing event
- filename (str) – path to new event file
- filecontents (
str
, optional) – string to be uploaded to the server and saved into a file. If event data is uploaded via this mechanism, thefilename
argument is only used to set the name of the file once it is saved on the server.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.replaceEvent('T101383', '/path/to/new/something.xml')
-
searches
¶ List of available search types on the server.
-
server_version
¶ Get the code version being run on the GraceDB server.
-
service_info
¶ Gets the root API information.
-
show_credentials
(print_output=True)¶ Prints authentication type and credentials information.
-
signoff_statuses
¶ List of available signoff statuses on the server.
-
signoff_types
¶ List of available signoff types on the server.
-
signoffs
(object_id, signoff_type=None, instrument='', *args, **kwargs)¶ Get a signoff or list of signoffs for a superevent.
This action is not yet implemented for events.
Parameters: - object_id (str) – superevent ID.
- signoff_type (str) – signoff type. Choices are:
'OP'
or'operator'
(operator signoff), or'ADV'
or'advocate'
(advocate signoff). - instrument (
str
, optional) – instrument abbreviation ('H1'
,'L1'
, etc.) for operator signoffs. Leave blank for advocate signoffs.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
Get a list of signoffs:
>>> g = GraceDb() >>> signoffs = g.signoffs('S190221z').json()['signoffs']
Get a single signoff:
>>> signoff = g.signoffs('S190221z', 'H1').json()
-
superevent
(superevent_id)¶ Get information about an individual superevent.
Parameters: superevent_id (str) – GraceDB ID of the superevent. Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> superevent = g.superevent('S181224a').json()
-
superevent_categories
¶ List of available superevent categories on the server.
-
superevents
(query='', orderby=None, count=None, columns=None, max_results=None)¶ Search for superevents which match a query.
Information on forming queries is available here: https://gracedb.ligo.org/documentation/queries.html
Parameters: - query (
str
, optional) – query string. - orderby (
str
, optional) – field to order the results by. - count (
int
, optional) – each generator iteration will yield this many objects (default determined by the server). - columns (
list[str]
, optional) – list of attributes to return for each superevent (default: all). - max_results (
int
, optional) – maximum number of results to return (default: all).
Returns: Iterator[dict]
An iterator which yields individual superevent dictionaries.
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> for s in g.superevents(query='is_gw: True', orderby= ... ['-preferred_event'], columns=['superevent_id', 'events']): ... print(s['superevent_id'])
- query (
Get tags attached to an event or superevent log entry.
Parameters: - object_id (str) – event graceid or superevent ID.
- N (int) – ID number (N) of the log entry for which to get tags.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> tag_list = g.tags('T101383', 56).json()['tags'] >>> print "Number of tags for message 56: %d" % len(tag_list)
-
updateSuperevent
(superevent_id, t_start=None, t_0=None, t_end=None, preferred_event=None, em_type=None, coinc_far=None)¶ Update a superevent’s parameters.
The same permission restrictions apply as for
ligo.gracedb.rest.GraceDb.createSuperevent()
. You must provide at least one parameter value to update, otherwise the request will be rejected for not providing any new information.Parameters: - superevent_id (str) – GraceDB ID of superevent to update
- t_start (
float
, optional) – new tstart value for superevent - t_0 (
float
, optional) – new t0 value for superevent - t_end (
float
, optional) – new tend value for superevent - preferred_event (
str
, optional) – graceid corresponding to an event which will be set as the new preferred event for this superevent. This event must be in the samecategory
as the superevent ('production'
,'test'
,'mdc'
) and must either already be a part of this superevent, or not be in a superevent at all. - em_type (
str
, optional) – name of coincident EM search for “preferred” EM coincident event. Defined by analyst or pipeline (e.g., RAVEN). Default is null for new superevents. - coinc_far (
float
, optional) – new value for coincident FAR with preferred EM coincident event. Defined by analyst or pipeline (e.g., RAVEN). Default is null for new superevents.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.updateSuperevent('S181224a', t_start=12, preferred_event= ... 'G654321') >>> r.status 200
-
update_grbevent
(graceid, ra=None, dec=None, error_radius=None, t90=None, redshift=None, designation=None)¶ Update a GRB event’s parameters.
This method only works on GRB events; i.e., External or Test events whose search is specified as ‘GRB’.
Only LIGO/Virgo users with permission to update GRB events will be able to utilize this method.
Parameters: - graceid (str) – GraceDB ID of the existing event
- ra (
float
, optional) – right ascension (degrees) - dec (
float
, optional) – declination (degrees) - error_radius (
float
, optional) – uncertainty in position as statistical ~1-sigma error radius from the reported right ascension and declination (degrees) - t90 (
float
, optional) – duration of the event in which 90% of the gamma-ray burst fluence was accumulated (seconds) - redshift (
float
, optional) – redshift - designation (
str
, optional) – name of the event, typically reported in GRByymmddx (where x is null, ‘A’, or ‘B’) or GRByymmddfff format, where fff is the three-digit fraction of the day
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.update_grbevent('E274955', redshift=2.33, ra=135.91) >>> r.status 200
-
update_signoff
(object_id, signoff_type, status=None, comment=None, instrument='', *args, **kwargs)¶ Update a superevent signoff.
This action requires the same permissions as
ligo.gracedb.rest.GraceDb.create_signoff()
.Parameters: - object_id (str) – superevent ID.
- signoff_type (str) – signoff type. Choices are:
'OP'
or'operator'
(operator signoff), or'ADV'
or'advocate'
(advocate signoff). - status (
str
, optional) – signoff status (if changed). - comment (
str
, optional) – comment on the signoff (if changed). - instrument (
str
, optional) – instrument abbreviation ('H1'
,'L1'
, etc.) for operator signoffs. Leave blank for advocate signoffs.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.update_signoff('S190102p', 'OP', status='NO', ... comment='IFO status was actually bad.', instrument='H1') >>> r.status 200
-
voevent_types
¶ List of available VOEvent types on the server.
-
voevents
(object_id, voevent_num=None, *args, **kwargs)¶ Get a VOEvent or list of VOEvents for an event or superevent.
To get the XML file associated with a VOEvent, use the
filename
in the response JSON withligo.gracedb.rest.GraceDb.files()
.Parameters: - object_id (str) – event graceid or superevent ID.
- voevent_num (
int
, optional) – ID number (N) of the VOEvent to retrieve.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Examples
Get a list of VOEvents:
>>> g = GraceDb() >>> r = g.voevents('T101383') >>> voevent_list = r.json()['voevents']
Get a single VOEvent:
>>> g = GraceDb() >>> r = g.voevents('T101383', 2) >>> voevent = r.json()
-
writeEMObservation
(object_id, group, raList, raWidthList, decList, decWidthList, startTimeList, durationList, comment='', *args, **kwargs)¶ Create an EM observation data entry for an event or superevent.
Parameters: - object_id (str) – event graceid or superevent ID.
- group (str) – name of EM MOU group making the observation.
- raList (
list[float]
) – list of right ascension coordinates (degrees). - raWidthList (
list[float]
orfloat
) – list of right ascension measurement widths OR a single number if all measurements have the same width (degrees). - decList (
list[float]
) – list of declination coordinates (degrees). - decWidthList (
list[float]
orfloat
) – list of declination measurement widths OR a single number if all measurements have the same width (degrees). - startTimeList (
list[str]
) – list of measurement start times in ISO 8601 format and UTC time zone. - durationList (
list[float]
orfloat
) – list of exposure times OR a single number if all measurements have the same exposure (seconds). - comment (
str
, optional) – comment on observation.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.writeEMObservation('S190131g', 'ZTF', [1, 2, 3], ... [0.1, 0.1, 0.1], [4, 5, 6], 0.2, [], ... [10, 9, 11], comment="data uploaded") >>> r.status 201
-
writeLabel
(object_id, label, *args, **kwargs)¶ Add a label to an event or superevent.
Parameters: - object_id (str) – event graceid or superevent ID.
- label (str) – label name. Use
ligo.gracedb.rest.GraceDb.allowed_labels
to get a list of available labels on the server.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.writeLabel('T101383', 'DQV') >>> r.status 201
-
writeLog
(object_id, message, filename=None, filecontents=None, tag_name=[], displayName=[], *args, **kwargs)¶ Create a new log entry associated with an event or superevent.
Parameters: - object_id (str) – event graceid or superevent ID.
- message (str) – comment to post.
- filename (
str
, optional) – path to file to be uploaded. Use'-'
to read from stdin. - filecontents (
file
, optional) – handler pointing to a file to be read and uploaded. If this argument is specified, the contents will be saved asfilename
on the server. - tag_name (
str
orlist[str]
, optional) – tag name or list of tag names to be applied to the log message. - displayName (
str
orlist[str]
, optional) – tag display string or list of display strings for the tag(s) intag_name
. If provided, there should be one for each tag. Not applicable for tags which already exist on the server.
Returns: httplib.HTTPResponse
Raises: ligo.gracedb.exceptions.HTTPError
– if the response has a status code >= 400.Example
>>> g = GraceDb() >>> r = g.writeLog('T101383', 'Good stuff.', '/path/to/plot.png', ... tag_name='analyst_comments') >>> print r.status 201
- If provided, import X.509 credentials from the certificate-key pair or combined proxy file provided in the
A separate GraceDbBasic
class had been provided in the past for password-based authentication, but that functionality is now included in the GraceDb
class.
ligo.gracedb.rest.GraceDbBasic
is still provided for legacy compatibility, but it is now an exact duplicate of the ligo.gracedb.rest.GraceDb
class.