ligo.raven.search

Module containing time- and sky- coincidence search functions.

ligo.raven.search.query(event_type, gpstime, tl, th, gracedb=None, group=None, pipelines=None, ext_searches=None, se_searches=None)[source]
Query for coincident events of type event_type occurring within a

window of [tl, th] seconds around gpstime.

Parameters:

  • event_type (str) – “Superevent” or “External”

  • gpstime (float) – Event’s gps time

  • tl (float) – Start of coincident time window

  • th (float) – End of coincident time window

  • gracedb (class) – SDK or REST API client for HTTP connection

  • group (str) – “CBC”, “Burst”, or “Test”,

  • pipelines (list) – List of external trigger pipeline names

  • ext_searches (array) – List of external trigger searches

  • se_searches (array) – List of superevent searches

ligo.raven.search.search(gracedb_id, tl, th, gracedb=None, group=None, pipelines=None, ext_searches=None, se_searches=None, event_dict=None)[source]
Perform a search for neighbors coincident in time within

a window [tl, th] seconds around an event. Uploads the results to the selected gracedb server.

Parameters:

  • gracedb_id (str) – ID of the trigger used by GraceDB

  • tl (float) – Start of coincident time window

  • th (float) – End of coincident time window

  • gracedb (class) – SDK or REST API client for HTTP connection

  • group (string) – “CBC”, “Burst”, or “Test”,

  • pipelines (list) – List of external trigger pipeline names

  • ext_searches (array) – List of external trigger searches

  • se_searches (array) – List of superevent searches

  • event_dict (dict) – Dictionary of the gracedb event

ligo.raven.search.skymap_overlap_integral(se_skymap, exttrig_skymap=None, se_skymap_uniq=None, ext_skymap_uniq=None, ra=None, dec=None, se_nested=True, ext_nested=True)[source]

Sky map overlap integral between two sky maps.

This method was originally developed in:

doi.org/10.3847/1538-4357/aabfd2

while the flattened sky map version was mentioned in:

https://git.ligo.org/brandon.piotrzkowski/raven-paper

Either a multi-ordered (MOC) GW sky map with UNIQ ordering, or a flattened sky map with Nested or Ring ordering can be used. Either a mutli-ordered (MOC) external sky map with UNIQ ordering, flattened sky map with Nested or Ring ordering, or a position indicated by RA/DEC can be used.

Parameters:

  • se_skymap (array) – Array containing either GW sky localization probabilities if using nested or ring ordering, or probability density if using UNIQ ordering

  • exttrig_skymap (array) – Array containing either external sky localization probabilities if using nested or ring ordering, or probability density if using UNIQ ordering

  • se_skymap_uniq (array) – Array containing GW UNIQ indexing, if non-empty then assumes GW sky map is multi-ordered

  • ext_skymap_uniq (array) – Array containing external UNIQ indexing, if non-empty then assume external sky map is multi-ordered

  • ra (float) – Right ascension of external localization in degrees

  • dec (float) – Declination of external localization in degrees

  • se_nested (bool) – If True, assumes GW sky map uses nested ordering, otherwise assumes ring ordering

  • ext_nested (bool) – If True, assumes external sky map uses nested ordering, otherwise assumes ring ordering

ligo.raven.search.coinc_far(se_id, ext_id, tl, th, ext_search='GRB', se_fitsfile=None, ext_fitsfile=None, incl_sky=False, gracedb=None, gracedb_ext=None, far_ext=None, em_rate=None, far_gw_thresh=None, far_ext_thresh=None, se_dict=None, ext_dict=None, se_moc=False, ext_moc=False, use_radec=False, se_nested=False, ext_nested=False, use_preferred_event_skymap=False)[source]
Calculate the significance of a gravitational wave candidate with the

addition of an external astrophyical counterpart in terms of a coincidence false alarm rate. This includes a temporal and a space-time type.

Parameters:

  • se_id (str) – GraceDB ID of superevent

  • ext_id (str) – GraceDB ID of external event

  • tl (float) – Start of coincident time window

  • th (float) – End of coincident time window

  • ext_search (str) – Determines joint FAR method. “GRB”, “SubGRB”, “SubGRBTargeted”, “MDC”, or “HEN”

  • se_fitsfile (str) – GW’s skymap file name

  • ext_fitsfile (str) – External event’s skymap file name

  • incl_sky (bool) – If True, uses skymaps in the joint FAR calculation

  • gracedb (class) – SDK or REST API client for HTTP connection

  • gracedb_ext (class) – SDK or REST API client for HTTP connection for external candidate, if separate from GW candidate (necessary for offline search)

  • far_ext (float) – External event false alarm rate

  • em_rate (float) – Detection rate of external events

  • far_gw_thresh (float) – Maximum cutoff for GW FAR considered in the search

  • far_ext_thresh (float) – Maximum cutoff for External event FAR considered in the search

  • se_dict (float) – Dictionary of superevent

  • ext_dict (float) – Dictionary of external event

  • se_moc (bool) – If True, assumes multi-order coverage (MOC) GW skymap

  • ext_moc (bool) – If True, assumes multi-order coverage (MOC) external event skymap

  • use_radec (bool) – If True, use ra and dec for single pixel external skymap

  • se_nested (bool) – If True, assumes GW skymap uses nested ordering, otherwise assumes ring ordering

  • ext_nested (bool) – If True, assumes external skymap uses nested ordering, otherwise assumes ring ordering

  • use_preferred_event_skymap (bool) – If True, uses the GW sky map in the preferred event rather than the superevent

ligo.raven.search.calc_signif_gracedb(se_id, ext_id, tl, th, ext_search='GRB', se_fitsfile=None, ext_fitsfile=None, incl_sky=False, gracedb=None, far_ext=None, em_rate=None, far_gw_thresh=None, far_ext_thresh=None, se_dict=None, ext_dict=None, se_moc=False, ext_moc=False, use_radec=False, se_nested=False, ext_nested=False, use_preferred_event_skymap=False)[source]
Calculates and uploads the coincidence false alarm rate

of the given superevent to the selected gracedb server.

Parameters:

  • se_id (str) – GraceDB ID of superevent

  • ext_id (str) – GraceDB ID of external event

  • tl (float) – Start of coincident time window

  • th (float) – End of coincident time window

  • ext_search (str) – Determines joint FAR method. “GRB”, “SubGRB”, “SubGRBTargeted”, “MDC”, or “HEN”

  • se_fitsfile (str) – GW’s skymap file name

  • ext_fitsfile (str) – External event’s skymap file name

  • incl_sky (bool) – If True, uses skymaps in the joint FAR calculation

  • gracedb (class) – SDK or REST API client for HTTP connection

  • far_ext (float) – External event false alarm rate

  • em_rate (float) – Detection rate of external events

  • far_gw_thresh (float) – Maximum cutoff for GW FAR considered in the search

  • far_ext_thresh (float) – Maximum cutoff for External event FAR considered in the search

  • se_dict (float) – Dictionary of superevent

  • ext_dict (float) – Dictionary of external event

  • se_moc (bool) – If True, assumes multi-order coverage (MOC) GW skymap

  • ext_moc (bool) – If True, assumes multi-order coverage (MOC) external event skymap

  • use_radec (bool) – If True, use ra and dec for single pixel external skymap

  • se_nested (bool) – If True, assumes GW skymap uses nested ordering, otherwise assumes ring ordering

  • ext_nested (bool) – If True, assumes external skymap uses nested ordering, otherwise assumes ring ordering

  • use_preferred_event_skymap (bool) – If True, uses the GW sky map in the preferred event rather than the superevent