llama.safeimports package

A place to safely import modules/objects or else replace them with nonfunctional placeholders or partially functional stubs. Allows the pipeline to be imported even without all dependencies being met with potentially reduced functionality. The placeholders and stubs defined here are recorded in llama.placeholder; see that module’s documentation for details on what this means.

class llama.safeimports.GraceDb(service_url='https://gracedb.ligo.org/api/', proxy_host=None, proxy_port=3128, api_version=None, *args, **kwargs)

Bases: ligo.gracedb.rest.GsiRest

Example GraceDb REST client

The GraceDB service URL may be passed to the constructor if an alternate GraceDb instance is desired:

>>> g = GraceDb("https://alternate.gracedb.edu/api/")
>>> r = g.ping()

The proxy_host and proxy_port may also be passed in if accessing GraceDB behind a proxy. For other kwargs accepted by the constructor, consult the source code.

addEventToSuperevent(superevent_id, graceid)

Add an event to a superevent. Events can only be part of one superevent so the server will throw an error if the event is part of another superevent already.

Signature:
addEventToSuperevent(superevent_id, graceid)
Parameters:
  • superevent_id – id of superevent to which the event will be added
  • graceid – graceid of event to add to superevent

Example

>>> g = GraceDb()
>>> r = addEventToSuperevent('S0001', 'G123456')
>>> r.status
201
addTag(object_id, N, tag_name, displayName=None, *args, **kwargs)

Add a new tag to an event or superevent log message.

Signature:
addTag(object_id, N, tag_name, displayName=None)
Parameters:
  • object_id – event graceid or superevent id
  • N – log message number
  • tag_name – name of tag to add; tags which don’t exist already will be created.
  • displayName – tag display name (optional)

If a displayName is provided (and if the tag doesn’t already exist), a new tag will be created with the provided displayName.

Example

>>> g = GraceDb()
>>> r = g.createTag('T101383', 56, 'sky_loc')
>>> r.status
201
allowed_labels
api_versions
confirm_superevent_as_gw(superevent_id)

Upgrade a superevent’s state to ‘confirmed GW’. Requires specific server-side permissions.

Signature:
confirm_superevent_as_gw(superevent_id)
Parameters:superevent_id
createEvent(group, pipeline, filename, search=None, labels=None, offline=False, filecontents=None, **kwargs)

Create a new GraceDB event

Required args: group, pipeline, filename

Optional args: search, labels, offline, filecontents

The filename is the path to a file containing information about the event. The values for ‘group’, ‘pipeline’, and ‘search’ are restricted to those stored in the database. ‘labels’ should be a list of strings corresponding to labels (values restricted to those stored in the database). ‘labels’ can be a string if only a single label is being applied. ‘offline’ is a boolean which indicates whether the analysis is offline (True) or online/low-latency (False).

Example

>>> g = GraceDb()
>>> r = g.createEvent('CBC', 'gstlal', '/path/to/something.xml',
... labels='INJ', 'LowMass')
>>> r.status
201
createSuperevent(t_start, t_0, t_end, preferred_event, category='production', events=[], labels=None)

Create a superevent.

Signature: createSuperevent(t_start, t_0, t_end, preferred_event,

events=[], labels=None)
Parameters:
  • t_start – t_start of superevent
  • t_0 – t_0 of superevent
  • t_end – t_end of superevent
  • preferred_event – graceid corresponding to event which will be set as the preferred event for this superevent
  • category – superevent category (‘production’, ‘test’, ‘mdc’)
  • events – list of graceids corresponding to events which should be attached to this superevent (optional)
  • labels – list of labels which should be attached to this superevent at creation (optional)

Example

>>> g = GraceDb()
>>> r = g.createSuperevent(1, 2, 3, 'G123456',
... category='production', events=['G100', 'G101'],
... labels=['EM_READY', 'DQV'])
>>> r.status
201
createTag(object_id, N, tag_name, displayName=None, *args, **kwargs)
createVOEvent(object_id, voevent_type, skymap_type=None, skymap_filename=None, internal=True, open_alert=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

Signature:
createVOEvent(self, object_id, voevent_type, skymap_type=None,
skymap_filename=None, internal=True, open_alert=False, hardware_inj=False, CoincComment=False, ProbHasNS=None, ProbHasRemnant=None, BNS=None, NSBH=None, BBH=None, Terrestrial=None, MassGap=None)
Parameters:
  • object_id – event graceid or superevent id
  • voevent_type – VOEvent type (options: ‘preliminary’, ‘initial’, ‘update’, ‘retraction’)
  • skymap_type – skymap type (required for voevents which include a skymap)
  • skymap_filename – name of skymap file in GraceDB (required for ‘initial’ and ‘update’ alerts, optional for ‘preliminary’ alerts.
  • internal – whether the VOEvent should be distributed to LVC members only (True/False)
  • hardware_inj – whether the candidate is a hardware injection (True/False)
  • open_alert – whether the candidate is an open alert or not (True/False)
  • CoincComment – whether the candidate has a possible counterpart GRB (True/False)
The following arguments are optional and only apply to CBC events:
ProbHasNS: probability that at least one object in the binary is
less than 3 M_sun (optional)
ProbHasRemnant: probability that there is matter in the
surroundings of the central object (optional)

BNS: probability that the source is a binary neutron star merger NSBH: probability that the source is a neutron star-black hole

merger

BBH: probability that the source is a binary black hole merger Terrestrial: probability that the source is terrestrial (i.e.,

a background noise fluctuation or a glitch)
MassGap: probability that at least one object in the binary
has a mass between 3 and 5 M_sun.
create_signoff(object_id, signoff_type, status, comment, instrument='', *args, **kwargs)
deleteTag(object_id, N, tag_name, *args, **kwargs)
delete_signoff(object_id, signoff_type, instrument='', *args, **kwargs)
eel_statuses
eels(graceid)

Given a GraceID, get a list of EMBB log entries

Example

>>> g = GraceDb()
>>> r = g.eels('T101383')
>>> full_dictionary = r.json()            # Convert the response to a dictionary
>>> eel_list = full_dictionary['embblog'] # Pull out a list of EEL dicts
em_groups
emobservations(object_id, emobservation_num=None, *args, **kwargs)

Given an event graceid or superevent id, get a list of EM observation entries or a specific EM observation.

Signature:
emobservations(object_id, emobservation_num=None)
Parameters:
  • object_id – event graceid or superevent id
  • emobservation_num – number of the EM observation (N) (optional)

Example 1: get a list of EM observations

>>> g = GraceDb()
>>> r = g.emobservations('T101383')
>>> full_dictionary = r.json()
>>> emo_list = full_dictionary['observations']

Example 2: get a single EM observation

>>> g = GraceDb()
>>> r = g.emobservations('T101383', 2)
>>> observation_dict = r.json()
event(graceid)

Get information about a specific event

Args: graceid

Example

>>> g = GraceDb()
>>> event_dict = g.event('T101383').json()
events(query=None, orderby=None, count=None, columns=None, max_results=None)

Get a iterator of events in response to a query

This function returns an iterator which yields event dictionaries. Optional arguments are query, orderby, count, and columns. The columns argument is a comma separated list of attributes that the user would like in each event dictionary. If columns are not specified, all attributes of the events are returned.

Example

>>> g = GraceDb()
>>> for event in g.events('ER5 submitter: "gstlalcbc"', columns='graceid,far,gpstime'):
...     print "%s %e %d" % (event['graceid'], event['far'], event['gpstime'])
files(object_id, filename='', *args, **kwargs)

Files for a particular event or superevent.

Signature:
files(object_id, filename=”“)
Parameters:
  • object_id – event graceid or superevent id
  • filename – name of file (optional)

If a filename is not specified, a list of filenames associated with the event or superevent is returned. If a filename is specified, the file’s content is returned.

Example 1: get a list of files

>>> g = GraceDb()
>>> event_files = g.files('T101383').json()
>>> for filename in event_files.keys():
...     # do something
...     pass

Example 2: get a file’s content

>>> outfile = open('my_skymap.png', 'w')
>>> r = g.files('T101383', 'skymap.png')
>>> outfile.write(r.read())
>>> outfile.close()
groups
instruments
labels(object_id, label='', *args, **kwargs)

Get a list of labels or a single label for an event or superevent.

Signature:
labels(object_id, label=”“)
Parameters:
  • object_id – event graceid or superevent id
  • label – name of label (optional)

Example 1: get list of labels

>>> g = GraceDb()
>>> label_list = g.labels('T101383').json()['labels']
>>> for label in label_list:
...     print label['name']

Example 2: get a single label

>>> g = GraceDb()
>>> dqv_label = g.labels('T101383', 'DQV').json()
logs(object_id, log_number=None, *args, **kwargs)

Get log messages associated with an event or superevent

Signature:
logs(object_id, log_number=None)
Parameters:
  • object_id – event graceid or superevent id
  • log_number – log message number (N) of log message to retrieve (optional)

If a log_number is specified, only a single log message is returned. If a log_number is not specified, a list of all log messages attached to the event or superevent in questions is returned.

Example 1: 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']

Example 2: get a single log message

>>> g = GraceDb()
>>> log_info = g.logs('T101383', 10).json()
modify_permissions(object_id, action, *args, **kwargs)

Expose or hide an event or superevent to/from the public. Requires specific server-side permissions.

Signature:
modify_permissions(object_id, action)
Parameters:
  • object_id – event graceid or superevent id
  • action – ‘expose’ or ‘hide’

NOTE: not currently implemented for events.

numEvents(query=None)

Get the number of events satisfying a query

Example

>>> g = GraceDb()
>>> g.numEvents('ER5 submitter: "gstlalcbc"')
213
obs_statuses
permissions(object_id, *args, **kwargs)

Get a list of permissions for an event or superevent.

Signature:
permissions(object_id)
Parameters:object_id – event graceid or superevent id

NOTE: not currently implemented for events.

ping()

Ping the server

If you get back an HTTPResponse object, it’s alive. The JSON content is the service info, which is normally not of interest. But you can use it to get the known Groups, Searches, Pipelines, etc.

Example

>>> g = GraceDb()
>>> groups = g.ping().json()['groups']
pipelines
removeEventFromSuperevent(superevent_id, graceid)

Remove an event from a superevent.

Signature:
removeEventFromSuperevent(superevent_id, graceid)
Parameters:graceid (superevent_id,) –

Example

>>> g = GraceDb()
>>> r = removeEventFromSuperevent('S0001', 'G123456')
>>> r.status
204
removeLabel(object_id, label, *args, **kwargs)

Remove a label from an event or superevent.

Signature:
removeLabel(object_id, label)
Parameters:
  • object_id – event graceid or superevent id
  • label – name of label to be removed

Example

>>> g = GraceDb()
>>> r = g.removeLabel('T101383', 'DQV')
>>> r.status
204
removeTag(object_id, N, tag_name, *args, **kwargs)

Remove a tag from a given event or superevent log message.

Signature:
removeTag(object_id, N, tag_name)
Parameters:
  • object_id – event graceid or superevent id
  • N – log message number
  • tag_name – name of the tag to be removed

Example

>>> g = GraceDb()
>>> r = g.deleteTag('T101383', 56, 'sky_loc')
>>> r.status
200
replaceEvent(graceid, filename, filecontents=None)

Replace an existing GraceDB event

Required args: graceid, filename

This function uploads a new event file, hence changing the basic details of an existing event.

Example

>>> g = GraceDb()
>>> r = g.replaceEvent('T101383', '/path/to/new/something.xml')
request(method, url, body=None, headers=None, priming_url=None)
searches
service_info

Info from root of API. Should be a dict

service_url
signoff_statuses
signoff_types
signoffs(object_id, signoff_type=None, instrument='', *args, **kwargs)

Get a list of signoffs for an event or superevent, or a particular signoff.

Signature:
signoffs(object_id, signoff_type=None, instrument=’‘)
Parameters:
  • object_id – event graceid or superevent id
  • signoff_type – ‘OP’ or ‘operator’ for operator signoff, ‘ADV’ or ‘advocate’ for advocate signoff
  • instrument – instrument abbreviation (‘H1’, ‘L1’, etc.). Blank string for advocate signoffs

NOTE: not currently implemented for events.

superevent(superevent_id)

Get information about a specific superevent.

Signature:
superevent(superevent_id)
Parameters:superevent_id

Example

>>> g = GraceDb()
>>> superevent = g.superevent('S0001').json()
superevent_categories
superevents(query='', orderby=[], count=None, columns=[], max_results=None)

Get an iterator of superevents in response to a query.

Signature:
superevents(query=’‘, orderby=[], count=None, columns=[])
Parameters:
  • query – query string for filtering superevents (same as on the web interface)
  • orderby – list of strings corresponding to attribute(s) of the superevents used to order the results (optional). Available options: created, t_start, t_0, t_end, is_gw, id, preferred_event. Default is ascending order, but prefix any option with “-” to apply descending order.
  • count – each generator iteration will yield this many objects (optional; default determined by the server)
  • columns – which attributes of the superevents to return (default: all).

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 a list of tags associated with a particular event or superevent log message.

Signature:
tags(object_id, N)
Parameters:
  • object_id – event graceid or superevent id
  • N – log message number

Example

>>> g = GraceDb()
>>> tag_list = g.tags('T101383', 56).json()['tags']
>>> print "Number of tags for message 56: %d" % len(tag_list)
templates
updateSuperevent(superevent_id, t_start=None, t_0=None, t_end=None, preferred_event=None)

Update a superevent’s parameters.

Signature: updateSuperevent(superevent_id, t_start=None, t_0=None,

t_end=None, preferred_event=None)
Parameters:
  • superevent_id – id of superevent to update
  • t_start – t_start of superevent
  • t_0 – t_0 of superevent
  • t_end – t_end of superevent
  • preferred_event – graceid corresponding to event which will be set as the preferred event for this superevent
  • combination of these parameters (Any) –
  • be used; none are required. (may) –

Example

>>> g = GraceDb()
>>> r = g.updateSuperevent('S0001', t_start=12, preferred_event=
... 'G654321')
>>> r.status
200
update_signoff(object_id, signoff_type, status=None, comment=None, instrument='', *args, **kwargs)
voevent_types
voevents(object_id, voevent_num=None, *args, **kwargs)

Get a list of VOEvents or a single VOEvent for an event or superevent.

Signature:
voevents(object_id, voevent_num=None)
Parameters:
  • object_id – event graceid or superevent id
  • voevent_num – number of VOEvent to retrieve (optional)

Example 1: get a list of VOEvents

>>> g = GraceDb()
>>> r = g.voevents('T101383')
>>> voevent_list = r.json()['voevents']

Example 2: get a single VOEvent

>>> g = GraceDb()
>>> r = g.voevents('T101383')
>>> voevent_list = r.json()['voevents']
wavebands
writeEMObservation(object_id, group, raList, raWidthList, decList, decWidthList, startTimeList, durationList, comment='', *args, **kwargs)

Write an EM observation entry.

Signature:
writeEMObservation(object_id, group, raList, raWidthList,
decList, decWidthList, startTimeList, durationList, comment=None)
Parameters:
  • object_id – event graceid or superevent id
  • group – name of EM MOU group making the observation
  • raList – list of right ascensions (deg.)
  • raWidthList – list of right ascension widths OR a single number if all measurements have the same width (deg.)
  • decList – list of declinations (deg.)
  • decWidthList – list of declination widths OR a single number if all measurements have the same width (deg.)
  • startTimeList – list of measurement start times (ISO 8601 UTC) format example: 2018-05-25T16:30:12+00:00
  • durationList – list of exposure times OR a single number if all measurements have the same exposure (seconds)
  • comment – comment on observation (optional)
writeEel(graceid, group, waveband, eel_status, obs_status, **kwargs)

Write an EMBB event log entry

Required args: graceid, group, waveband, eel_status, obs_status

(Note that ‘group’ here is the name of the EM MOU group, not the LVC data analysis group responsible for the original detection.)

Additional keyword arguments may be passed in to be sent in the POST data. Only the following kwargs are recognized:

ra dec raWidth decWidth gpstime duration comment extra_info_dict

Most of these are self-explanatory, but the ‘extra_info_dict’ is meant to be a JSON string containing any additional information the user may wish to convey.

Any other kwargs will be ignored.

writeFile(object_id, filename, filecontents=None)

Upload a file for an event or superevent.

Signature:
writeFile(object_id, filename, filecontents=None)
Required args:
object_id: event graceid or superevent id filename: path to file

This method creates a new log message with your file attached. It is strongly preferred to use writeLog() instead of writeFile() so that you can add a more suitable comment. That will make it easier for other users to know what your file contains.

Example

>>> g = GraceDb()
>>> r = g.writeFile('T101383', '/path/to/my_interesting_plot.png')
>>> print r.status
writeLabel(object_id, label, *args, **kwargs)

Add a new label to an event or superevent.

Signature:
writeLabel(object_id, label)
Parameters:
  • object_id – event graceid or superevent id
  • label – label name

The label name must correspond to one of the existing GraceDB labels (see self.allowed_labels), or an error will result.

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 message.

Signature: writeLog(object_id, message, filename=None, filecontents=None,

tag_name=[], displayName=[])
Parameters:
  • object_id – event graceid or superevent id
  • message – comment to post on the event log
  • filename – path to file to be uploaded (optional)
  • filecontents – handler pointing to a file to be read (optional)
  • tag_name – tag name string or list of tag names to be attached to the log message
  • displayName – tag display name string or list of display names for tags. If provided, there should be one for each tag. (optional)

If only object_id and message are provided, a text comment will be created in the event or superevent log. If a filename is also specified, the file will be attached to the log message and displayed alongside the message text. If a tag_name is provided, the message will be tagged.

Example

>>> g = GraceDb()
>>> r = g.writeLog('T101383', 'Good stuff.', '/path/to/plot.png',
... tag_name='analyst_comments')
>>> print r.status
201
exception llama.safeimports.HTTPError(status, reason, message)

Bases: Exception

llama.safeimports.calc_cr_pull(cr_zen, cr_azi, zenith, muex)

Calculate CR pull corrected value, based on cr_zen,cr_azi, zenith and muex values based on Thomas’s polynomial fit for neutrino16 sample

NOTE: This is modified from the IceCube code to run stand-alone.

llama.safeimports.get_events(topic, starttime, stoptime, timekey=None, retries=10, delay=30)

Query events from the I3Live database.

Parameters:
  • topic (str) – Name of the stream (e.g. ‘neutrino16’).
  • starttime (int or float) – start of timewindow
  • stoptime (int or float) – stop of timewindow
  • timekey (str) – which date/time to compare to, such as insert_time or value.data.eventtime (default: auto-detect)
  • retries (int) – Number of retries in case of HTTP errors
  • delay (int or float) – time delay between retries (default: 10 seconds)
Returns:

  • events (list or None) – Events matching the given criteria or None in case of (repeated) HTTP error.
  • NOTE (This is modified from the IceCube code to run stand-alone.)

Submodules