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) – REST API client for HTTP connection

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

  • pipelines (array) – 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, gracedb_ext=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) – REST API client for HTTP connection

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

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

  • pipelines (array) – 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(gw_skymap, ext_skymap=None, ra=None, dec=None, gw_nested=True, ext_nested=True, use_hpmoc=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:

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

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

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

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

  • gw_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

  • use_hpmoc (bool) – If True, uses the hpmoc method to compare two MOC sky maps. If False, uses a legacy method that utilizes the GW sky map grid.

ligo.raven.search.coinc_far(se_far, tl, th, joint_far_method=None, ext_rate=None, far_ext=None, far_gw_thresh=None, far_ext_thresh=None, ext_search=None, ext_pipeline=None, incl_sky=None, gw_skymap=None, ext_skymap=None, ra=None, dec=None, use_radec=False, gw_nested=False, ext_nested=False, use_hpmoc=True, se_preferred_event=None, ext_graceid=None)[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_far (float) – Superevent false alarm rate

  • tl (float) – Start of coincident time window

  • th (float) – End of coincident time window

  • joint_far_method (str) – Joint FAR method to use, either ‘untargeted’ or ‘targeted’ If None, will try to determine from given search field

  • ext_rate (float) – Detection rate of external events

  • far_ext (float) – External event false alarm rate

  • 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

  • ext_search (str) – “GRB”, “SubGRB”, “SubGRBTargeted”, “MDC”, or “HEN”

  • ext_pipeline (str) – External trigger pipeline name

  • incl_sky (bool) – If True or False, uses or doesn’t sky maps in the joint FAR calculation. If None, checks if the needed sky map info is present to include

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

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

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

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

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

  • gw_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

  • use_hpmoc (bool) – If True, uses the hpmoc method to compare two MOC sky maps. If False, uses a legacy method that utilizes the GW sky map grid.

  • se_preferred_event (str) – GraceDB ID of the preferred GW event

  • ext_graceid (str) – GraceDB ID of the external event

ligo.raven.search.calc_signif_gracedb(se_id, ext_id, tl, th, joint_far_method=None, ext_rate=None, far_gw_thresh=None, far_ext_thresh=None, gracedb=None, gracedb_ext=None, upload_to_gracedb=False, se_dict=None, ext_dict=None, incl_sky=None, gw_fitsfile=None, ext_fitsfile=None, gw_moc=None, ext_moc=None, gw_nested=False, ext_nested=False, use_hpmoc=True, use_radec=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

  • joint_far_method (str) – Joint FAR method to use, either ‘untargeted’ or ‘targeted’ If None, will try to determine from given search field

  • ext_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

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

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

  • se_dict (float) – Dictionary of superevent

  • ext_dict (float) – Dictionary of external event

  • incl_sky (bool) – If True or False, uses or doesn’t sky maps in the joint FAR calculation. If None, checks if the needed sky map info is present to include

  • gw_fitsfile (str) – GW’s sky map file name

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

  • gw_moc (bool) – If True, assumes multi-order coverage (MOC) GW sky map If None, reads the file to determine whether MOC

  • ext_moc (bool) – If True, assumes multi-order coverage (MOC) external event sky map If None, reads the file to determine whether MOC

  • gw_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

  • use_hpmoc (bool) – If True, uses the hpmoc method to compare two MOC sky maps. If False, uses a legacy method that utilizes the GW sky map grid.

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

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