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/', cred=None, force_noauth=False, fail_if_noauth=False, api_version=None, reload_certificate=False, reload_cred=False, reload_buffer=300, use_auth='all', retries=5, retry_codes=[502, 504, 408, 409], allowed_methods=None, backoff_factor=0.1)

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.

By default, the code will search for available scitokens, and then X.509 certificates. The credentials will then be used in that order of preference unless overridden by the use_auth variable. Lookup of user credentials is done in the following order:

A scitoken, usually located in /tmp/bt_u${UID}, or the location provided by the SCITOKEN_FILE environment variable.
If provided, import X.509 credentials from the certificate-key pair or combined proxy file provided in the cred keyword arg.
If the X509_USER_CERT and X509_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.
Continue with no authentication credentials.

Parameters:

url (str, optional) – URL of server API root.
cred (tuple or str, 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.
force_noauth (bool, optional) – set to True if you want to skip credential lookup and use this client as an unauthenticated user
fail_if_noauth (bool, optional) – set to True if you want the constructor to fail if no authentication credentials are provided or found, or if no valid scitoken credentials were found when using the reload_cred option
reload_certificate (bool, optional) – if True, your certificate will be checked before each request whether it is within reload_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. To be deprecated in favor of reload_cred.
reload_cred (bool, optional) – if True, the user’s token or certificate will be checked before each request if it is within reload_buffer seconds of expiration, and if so, will be reloaded. Used for long-lived processes in conjunction with a user’s own credential reloading mechanism.
reload_buffer (int, optional) – buffer (in seconds) for reloading a certificate in advance of its expiration. Only used if reload_cred is True.
retries (int, optional) – the maximum number of retries to attempt on an error from the server. Default 5.
backoff_factor (float, optional) – The backoff factor for retrying. Default: 0.1. Refer to urllib3 documentation for usage.
retry_codes (list, optional) – List of HTTPError codes to retry on. Default: [502, 504, 408, 409].
allowed_methods (list or None, optional) – whitelist of allowed http verbs to retry. Default: None (all verbs).
use_auth – (str, optional): Specify the authentication method to be used. Choices: all, scitoken, x509. Default: all.

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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = add_event_to_superevent('S181224a', 'G123456')
>>> r.status_code
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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.add_tag('T101383', 56, 'sky_loc')
>>> r.status
201

add_event_to_superevent(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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = add_event_to_superevent('S181224a', 'G123456')
>>> r.status_code
201

add_pipeline_preferred_event(superevent_id, graceid)

Add an event to a superevent’s pipeline-preferred

list. The event must already be part of a superevent, and there can be only one event per pipeline in the list.

Adding a pipeline’s event to the list, when an event from that pipeline is already present will replace that event in the list, except in the case where the existing event is the preferred event.

Parameters:

superevent_id (str) – ID of the superevent to which the pipeline-preferred event will be added.
graceid (str) – graceid of the event to add to this superevent.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = add_pipeline_preferred_event('S181224a', 'G123456')
>>> r.status_code
201

add_tag(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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.add_tag('T101383', 56, 'sky_loc')
>>> r.status
201

property allowed_labels: List of available labels on the server.

property api_versions: List of available API versions on the server.

auth: Default Authentication tuple or object to attach to Request.

cert: SSL client certificate default, if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

close(): Closes all adapters and as such the session

confirm_superevent_as_gw(superevent_id, gw_id=None)

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:: requests.models.Response
Raises:: ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = confirm_superevent_as_gw('S181224a')
>>> r.status_code
204

cookies: A CookieJar containing all currently outstanding cookies set on this session. By default it is a RequestsCookieJar, but may be any other cookielib.CookieJar compatible object.

createEvent(group, pipeline, filename, search=None, labels=None, offline=False, filecontents=None, kafka=None, http_fallback=False, gracedb_upload=True, skip_supervisor=False, **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 or list[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) – if True, 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, the filename argument is only used to set the name of the file once it is saved on the server.
kafka – optional Kafka producer instance. When provided, the event is submitted via Kafka after reserving a graceid.
http_fallback (bool, optional) – if True and the Kafka reservation fails, fall back to the HTTP POST path.
gracedb_upload (bool, optional) – included in the Kafka message to indicate whether the server should upload/process the event. Default True. Only used with the Kafka path.
skip_supervisor (bool, optional) – if True, the supervisor will not process this message (i.e., will not call upload-reserved-event). Default False. Only used with the Kafka path.

Returns:

requests.models.Response

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_code
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) – t_start of the superevent
t_0 (float) – t₀ of the superevent
t_end (float) – t_end 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 or list[str], optional) – graceid or list of graceids corresponding to events which should be included in this superevent. Events must be in the same category as the superevent and not already attached to a superevent.
labels (str or list[str], optional) – label or list of labels which should be attached to this superevent at creation.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.create_superevent(1, 2, 3, 'G123456',
... category='production', events=['G100', 'G101'],
... labels=['EM_READY', 'DQV'])
>>> r.status_code
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, HasMassGap=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 M_sun (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).
HasMassGap (float, optional) – probability that at least one object in the binary has a mass between 3 and 5 M_sun (CBC events only).

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.create_voevent('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_event(group, pipeline, filename, search=None, labels=None, offline=False, filecontents=None, kafka=None, http_fallback=False, gracedb_upload=True, skip_supervisor=False, **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 or list[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) – if True, 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, the filename argument is only used to set the name of the file once it is saved on the server.
kafka – optional Kafka producer instance. When provided, the event is submitted via Kafka after reserving a graceid.
http_fallback (bool, optional) – if True and the Kafka reservation fails, fall back to the HTTP POST path.
gracedb_upload (bool, optional) – included in the Kafka message to indicate whether the server should upload/process the event. Default True. Only used with the Kafka path.
skip_supervisor (bool, optional) – if True, the supervisor will not process this message (i.e., will not call upload-reserved-event). Default False. Only used with the Kafka path.

Returns:

requests.models.Response

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_code
201

create_kafka_producer(bootstrap_servers, topic='test', ca_cert_path=None, skip_hostname_verification=False, token_scope='gracedb.read', reload_cred=True, reload_buffer=300, auto_refresh_token=None, **kafka_config)

Create a Kafka producer with SciToken authentication.

This method creates a Kafka producer configured to use SciToken authentication. The producer will automatically discover and use SciTokens for authentication with the Kafka broker.

Parameters:

bootstrap_servers (str) – Kafka broker address (e.g., “localhost:9092”)
topic (str, optional) – Default topic name. Default: “test”
ca_cert_path (str, optional) – Path to CA certificate for SSL verification. Required if broker uses custom CA certificates.
skip_hostname_verification (bool) – Skip SSL hostname verification. Use for development/testing when cert CN doesn’t match hostname. Default: False
token_scope (str) – Required SciToken scope. Default: “gracedb.read”
reload_cred (bool) – Proactively reload tokens before expiry. Default: True
reload_buffer (int) – Seconds before expiry to trigger reload. Default: 300
auto_refresh_token (bool) – Deprecated alias for reload_cred.
**kafka_config – Additional confluent_kafka.Producer configuration options

Returns:

Configured Kafka producer instance

Return type:

GraceDbKafkaProducer

Raises:

ImportError – If confluent-kafka is not installed
KafkaConnectionError – If connection to broker fails
KafkaTokenError – If no valid SciToken can be found

Example

>>> g = GraceDb()
>>> producer = g.create_kafka_producer(
...     bootstrap_servers="kafka-dev.ligo.org:9092",
...     ca_cert_path="/tmp/shared/tls/cacert.pem"
... )
>>> event = g.event("G12345").json()
>>> producer.produce(event)
>>> producer.flush()
>>> producer.close()

Note

This method requires the confluent-kafka package. Install it with: pip install ligo-gracedb[kafka]

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:

requests.models.Response

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_code
201

create_superevent(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) – t_start of the superevent
t_0 (float) – t₀ of the superevent
t_end (float) – t_end 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 or list[str], optional) – graceid or list of graceids corresponding to events which should be included in this superevent. Events must be in the same category as the superevent and not already attached to a superevent.
labels (str or list[str], optional) – label or list of labels which should be attached to this superevent at creation.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.create_superevent(1, 2, 3, 'G123456',
... category='production', events=['G100', 'G101'],
... labels=['EM_READY', 'DQV'])
>>> r.status_code
201

create_voevent(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, HasMassGap=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 M_sun (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).
HasMassGap (float, optional) – probability that at least one object in the binary has a mass between 3 and 5 M_sun (CBC events only).

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.create_voevent('T101383', 'initial',
... skymap_type='custom', skymap_filename='skymap.fits.gz',
... internal=True, ProbHasNS=0.7, MassGap=0.4, Terrestrial=0.05)
>>> r.status
201

delete(url, **kwargs)

Sends a DELETE request. Returns Response object.

Parameters:

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

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:

requests.models.Response

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_code
204

property 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:

requests.models.Response

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:: requests.models.Response
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'])

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. If filename 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:

requests.models.Response

When filename is not specified, response.json() contains a dict with file basename keys and full file URL values. When filename is specified, use response.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.content)
>>> outfile.close()

get(url, **kwargs)

Sends a GET request. Returns Response object.

Parameters:

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

get_adapter(url)

Returns the appropriate connection adapter for the given URL.

Return type:: requests.adapters.BaseAdapter

get_redirect_target(resp): Receives a Response. Returns a redirect URI or None

get_user_info(): Get information from the server about your user account.

property groups: List of available analysis groups on the server.

gwtc_create(smap, number, comment=None)

Create a new GWTC entry.

User must be a member of the catalog_managers group to create a gwtc entry.

Parameters:

smap (str | dict) –

path to a json-formatted file containing a catalog entry or a dictionary. An example of the format is below:

{
     "S231002i": {
         "pipelines": {
             "MBTA": "G419572",
             "spiir": "G419571",
             "pycbc": "G419570",
             "gstlal": "G419569"
         },
         "far": null,
         "pastro": null
     },
     "S231002h": {
         "pipelines": {
             "MBTA": "G419568",
             "spiir": "G419567",
             "pycbc": "G419566",
             "gstlal": "G419565"
         },
         "far": 1.8432234e-10,
         "pastro": {
             "BBH": 2.5953132292424023e-28,
             "BNS": 0.9922100906247882,
             "NSBH": 4.260287692039069e-29,
             "Terrestrial": 0.007789909375211845
         }
     },
     "S231002g": {
         "pipelines": {
             "MBTA": "G419564",
             "spiir": "G419563",
             "pycbc": "G419562",
             "gstlal": "G419561"
         },
         "far": 3.23421e-23,
         "pastro": null
     }
}

Note that superevent_id’s and graceid’s in the smap file must correspond to superevents and events on the live server.

far values can be a number, or null

pastro values must be a valid dict, or null

number (str) – identifying number of the catalog. Currently a slug. Example: number={‘4’, ‘4a’, ‘4a-1’, etc}.
comment (str, optional) – an analyst comment to accompany the smap upload

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

gwtc_get(number, version)

Retrieve a specific gwtc catalog based on number and version

Parameters:

number (str) – identifying number of the catalog.
version (int or str('latest')) – positive integer version number of the catalog to retrieve. Entering ‘latest’ will pull the most recently uploaded version.

Returns:

requests.models.Response

A HTTPresponse with an individual catalog entry, if a specific version was specified.

Note: version cannot be specified without specifying number.

gwtc_list(number=None)

Retrieve an iterator of gwtc catalog dictionaries

Parameters:

number (str) – identifying number of the catalog.

Returns:

Iterator[dict]

An iterator which yields individual catalog dictionaries

Note: not specifying a catalog number will retrieve an iterator with all available catalogs.

gwtc_numbers()

Return the unique catalog numbers

Returns:: The list of all unique catalog numbers (e.g. 4 for GWTC-4, etc)
Return type:: list

gwtc_versions(number='4')

Return the unique catalog versions

Parameters:: number (int, optional) – The GWTC number to act on, 4 for now
Returns:: The list of unique catalog versions for this catalog number
Return type:: list

head(url, **kwargs)

Sends a HEAD request. Returns Response object.

Parameters:

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

headers: A case-insensitive dictionary of headers to be sent on each Request sent from this Session.

hooks: Event-handling hooks.

property 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:

requests.models.Response

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()

classmethod load_json_from_response(response): Always return a json content response, even when the server provides a 204: no content

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:

requests.models.Response

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()

max_redirects: Maximum number of redirects allowed. If the request exceeds this limit, a TooManyRedirects exception is raised. This defaults to requests.models.DEFAULT_REDIRECT_LIMIT, which is 30.

merge_environment_settings(url, proxies, stream, verify, cert)

Check the environment and merge it with some settings.

Return type:: dict

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:

requests.models.Response

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()
[]

mount(prefix, adapter)

Registers a connection adapter to a prefix.

Adapters are sorted in descending order by prefix length.

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.num_events('ER5 submitter: "gstlalcbc"')
213

num_events(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.num_events('ER5 submitter: "gstlalcbc"')
213

options(url, **kwargs)

Sends a OPTIONS request. Returns Response object.

Parameters:

url – URL for the new Request object.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

params: Dictionary of querystring data to attach to each Request. The dictionary values may be lists for representing multivalued query parameters.

patch(url, data=None, **kwargs)

Sends a PATCH request. Returns Response object.

Parameters:

url – URL for the new Request object.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

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:: requests.models.Response
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:

requests.models.Response

response.json() contains the information from the API root.

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

property pipelines: List of available analysis pipelines on the server.

post(url, data=None, json=None, **kwargs)

Sends a POST request. Returns Response object.

Parameters:

url – URL for the new Request object.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
json – (optional) json to send in the body of the Request.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

prepare_request(request)

Constructs a PreparedRequest for transmission and returns it. The PreparedRequest has settings merged from the Request instance and those of the Session.

Parameters:: request – Request instance to prepare with this session’s settings.
Return type:: requests.PreparedRequest

proxies: Dictionary mapping protocol or protocol and host to the URL of the proxy (e.g. {‘http’: ‘foo.bar:3128’, ‘http://host.name’: ‘foo.bar:4012’}) to be used on each Request.

put(url, data=None, **kwargs)

Sends a PUT request. Returns Response object.

Parameters:

url – URL for the new Request object.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
**kwargs – Optional arguments that request takes.

Return type:

requests.Response

rebuild_auth(prepared_request, response): When being redirected we may want to strip authentication from the request to avoid leaking credentials. This method intelligently removes and reapplies authentication where possible to avoid credential loss.

rebuild_method(prepared_request, response): When being redirected we may want to change the method of the request based on certain specs or browser behavior.

rebuild_proxies(prepared_request, proxies)

This method re-evaluates the proxy configuration by considering the environment variables. If we are redirected to a URL covered by NO_PROXY, we strip the proxy configuration. Otherwise, we set missing proxy keys for this URL (in case they were stripped by a previous redirect).

This method also replaces the Proxy-Authorization header where necessary.

Return type:: dict

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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = remove_event_from_superevent('S181224a', 'G123456')
>>> r.status_code
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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.remove_label('T101383', 'DQV')
>>> r.status_code
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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.remove_tag('T101383', 56, 'sky_loc')
>>> r.status
200

remove_event_from_superevent(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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = remove_event_from_superevent('S181224a', 'G123456')
>>> r.status_code
204

remove_label(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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.remove_label('T101383', 'DQV')
>>> r.status_code
204

remove_pipeline_preferred_event(superevent_id, graceid)

Remove an event from a superevent’s pipeline-preferred list

The event must already be a part of the preferred list. The preferred event cannot be removed from the pipeline preferred list.

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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = remove_pipeline_preferred_event('S181224a', 'G123456')
>>> r.status_code
204

remove_tag(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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.remove_tag('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, the filename argument is only used to set the name of the file once it is saved on the server.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.replace_event('T101383', '/path/to/new/something.xml')

replace_event(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, the filename argument is only used to set the name of the file once it is saved on the server.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.replace_event('T101383', '/path/to/new/something.xml')

request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None)

Constructs a Request, prepares it and sends it. Returns Response object.

Parameters:

method – method for the new Request object.
url – URL for the new Request object.
params – (optional) Dictionary or bytes to be sent in the query string for the Request.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
json – (optional) json to send in the body of the Request.
headers – (optional) Dictionary of HTTP Headers to send with the Request.
cookies – (optional) Dict or CookieJar object to send with the Request.
files – (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.
auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
timeout (float or tuple) – (optional) How many seconds to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
allow_redirects (bool) – (optional) Set to True by default.
proxies – (optional) Dictionary mapping protocol or protocol and hostname to the URL of the proxy.
hooks – (optional) Dictionary mapping hook name to one event or list of events, event must be callable.
stream – (optional) whether to immediately download the response content. Defaults to False.
verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True. When set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Setting verify to False may be useful during local development or testing.
cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

Return type:

requests.Response

resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs): Receives a Response. Returns a generator of Responses or Requests.

property searches: List of available search types on the server.

send(request, **kwargs)

Send a given PreparedRequest.

Return type:: requests.Response

property server_version: Get the code version being run on the GraceDB server.

property service_info: Gets the root API information.

should_strip_auth(old_url, new_url): Decide whether Authorization header should be removed when redirecting

show_credentials(print_output=True): Prints authentication type and credentials info.

property signoff_statuses: List of available signoff statuses on the server.

property 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:

requests.models.Response

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()

stream: Stream response content default.

superevent(superevent_id)

Get information about an individual superevent.

Parameters:: superevent_id (str) – GraceDB ID of the superevent.
Returns:: requests.models.Response
Raises:: ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> superevent = g.superevent('S181224a').json()

property 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'])

tags(object_id, N, *args, **kwargs)

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:

requests.models.Response

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)

property token

The token object that will be used in authorised requests.

If the Session.auth property isn’t an instance of HTTPSciTokenAuth with a token attached, this returns None.

trust_env: Trust environment settings for proxy configuration, default authentication and similar.

updateSuperevent(superevent_id, t_start=None, t_0=None, t_end=None, preferred_event=None, em_type=None, time_coinc_far=None, space_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 t_start value for superevent
t_0 (float, optional) – new t₀ value for superevent
t_end (float, optional) – new t_end 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 same category 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.
time_coinc_far (float, optional) – new value for temporal coincident FAR with preferred EM coincident event. Defined by analyst or pipeline (e.g., RAVEN). Default is null for new superevents.
space_coinc_far (float, optional) – new value for temporal coincident FAR with preferred EM coincident event. Defined by analyst or pipeline (e.g., RAVEN). Default is null for new superevents.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.update_superevent('S181224a', t_start=12,
... preferred_event='G654321')
>>> r.status_code
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:

requests.models.Response

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:

requests.models.Response

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_code
200

update_superevent(superevent_id, t_start=None, t_0=None, t_end=None, preferred_event=None, em_type=None, time_coinc_far=None, space_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 t_start value for superevent
t_0 (float, optional) – new t₀ value for superevent
t_end (float, optional) – new t_end 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 same category 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.
time_coinc_far (float, optional) – new value for temporal coincident FAR with preferred EM coincident event. Defined by analyst or pipeline (e.g., RAVEN). Default is null for new superevents.
space_coinc_far (float, optional) – new value for temporal coincident FAR with preferred EM coincident event. Defined by analyst or pipeline (e.g., RAVEN). Default is null for new superevents.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.update_superevent('S181224a', t_start=12,
... preferred_event='G654321')
>>> r.status_code
200

upload_reserved_event(graceid, filename, filecontents=None, labels=None, kafka_server=None, kafka_topic=None)

Upload event data for a previously reserved graceid.

Completes a reserved event by uploading its event file, optional labels, and the Kafka provenance metadata. This is the server-side counterpart to the Kafka-based event submission path.

Parameters:

graceid (str) – GraceDB ID of the reserved event.
filename (str) – path to the event file, or a filename when filecontents is provided.
filecontents (bytes, optional) – event file contents. If None, the file at filename is read from disk.
labels (str or list, optional) – label or list of labels to apply to the event.
kafka_server (str, optional) – Kafka broker address that delivered the message.
kafka_topic (str, optional) – Kafka topic the message arrived on.

Returns:

requests.models.Response

Raises:

NotImplementedError – if the server does not expose the event-upload-template endpoint.
ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.upload_reserved_event(
...     'T123456', 'coinc.xml',
...     filecontents=open('coinc.xml', 'rb').read(),
...     labels=['DQV', 'INJ'],
...     kafka_server='kafka-broker:9092',
...     kafka_topic='cbc',
... )

verify: SSL Verification default. Defaults to True, requiring requests to verify the TLS certificate at the remote end. If verify is set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Only set this to False for testing. If verify is set to a string, it must be the path to a CA bundle file that will be used to verify the TLS certificate.

property 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 with ligo.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:

requests.models.Response

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] or float) – 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] or float) – 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] or float) – list of exposure times OR a single number if all measurements have the same exposure (seconds).
comment (str, optional) – comment on observation.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.write_emobservation('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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.write_label('T101383', 'DQV')
>>> r.status_code
201

writeLog(object_id, message, filename=None, filecontents=None, tag_name=[], displayName=[], label=None, *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 as filename on the server.
tag_name (str or list[str], optional) – tag name or list of tag names to be applied to the log message.
displayName (str or list[str], optional) – tag display string or list of display strings for the tag(s) in tag_name. If provided, there should be one for each tag. Not applicable for tags which already exist on the server.
label (str, optional) – label to be applied to event or superevent when log entry is created.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.write_log('T101383', 'Good stuff.', '/path/to/plot.png',
... tag_name='analyst_comments', label='PASTRO_READY')
>>> print r.status_code
201

write_emobservation(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] or float) – 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] or float) – 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] or float) – list of exposure times OR a single number if all measurements have the same exposure (seconds).
comment (str, optional) – comment on observation.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.write_emobservation('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

write_label(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:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.write_label('T101383', 'DQV')
>>> r.status_code
201

write_log(object_id, message, filename=None, filecontents=None, tag_name=[], displayName=[], label=None, *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 as filename on the server.
tag_name (str or list[str], optional) – tag name or list of tag names to be applied to the log message.
displayName (str or list[str], optional) – tag display string or list of display strings for the tag(s) in tag_name. If provided, there should be one for each tag. Not applicable for tags which already exist on the server.
label (str, optional) – label to be applied to event or superevent when log entry is created.

Returns:

requests.models.Response

Raises:

ligo.gracedb.exceptions.HTTPError – if the response has a status code >= 400.

Example

>>> g = GraceDb()
>>> r = g.write_log('T101383', 'Good stuff.', '/path/to/plot.png',
... tag_name='analyst_comments', label='PASTRO_READY')
>>> print r.status_code
201

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.