Offline search

Ligo-raven also now has tools to run searches in an offline mode. The inputs can either be any combination of a GraceDB server and/or local files. This allow us to perform the following example searches:

1. Compare GWs and external events in the same GraceDB server to check the results of online RAVEN after an operating run.

2. Compare a list of new triggers not used in online search to those in a server, such as providing a list of fast radio bursts to see if there are any coincidences with GW candidates.

3. Compare two lists of offline triggers to perform a simulation of a search or test that the methods in RAVEN give sensible results, such as random coincidences giving an expected joint FAR distribution.

Running the script

Similar to other functions in ligo-raven, the offline search can be run in a python script or via the terminal, where a latter example for the CBC-GRB search for O4a is:

$ raven_offline_search -i https://gracedb.ligo.org/api/ https://gracedb.ligo.org/api/ -o results_O4a_CBC -t 1368994979.84 1389072434.67 -w -1 5 -g CBC -s GRB -n 4

For a full list of options see bin.raven_offline_search. Also note the use GraceDB API urls here, see examples for more options. We can also use local files as well.

Example local file inputs

We use Astropy Tables to load local files into a mock version of GraceDB, which support various file formats. Please see the following as examples of .csv inputs for GW candidates and external candidates respectively

Example GW injection file

superevent_id	preferred_event	t_0	pipeline	search	group	far	skymap
S170817a	G1	100	gstlal	AllSky	CBC	1E-07	GW170817.multiorder.fits
S170817b	G2	150	MBTA	AllSky	CBC	1E-06	GW170817.multiorder.fits
S170817c	G2	102	pycbc	AllSky	CBC	1E-03
S170817c	G2	5	pycbc	AllSky	CBC	1E-04
S170817d	G3	120	CWB	BBH	Burst	1E-05	bayestar.fits.gz
S170817e	G4	1000	pycbc	AllSky	CBC	1E-04
S170817f	G3	120	CWB	AllSky	Burst	1E-07	GW170817.multiorder.fits

Example GRB injection file

graceid	gpstime	pipeline	search	far	ra	dec	error_radius	skymap
E170817	102	Fermi	GRB		0	0	15	glg_healpix_all_bn_v00.fit
E170818	101.5	Swift	GRB		10	-45	.05	glg_healpix_all_bn_v00.fit
E2345	104	Swift	SubGRBTargeted	1E-06	0	30	0
E3456	160	Fermi	SubGRB		45	-30	5	glg_healpix_all_bn_v00.multiorder.fits
E4567	75	Fermi	GRB		45	-30	5	glg_healpix_all_bn_v00.multiorder.fits
E5678	6.0	AGILE	GRB		-90	0	10
E6789	99.5	Fermi	SubGRBTargeted	1E-06	45	-30	5	glg_healpix_all_bn_v00.multiorder.fits

Analyzing an operating run

A common use of the offine search will be to analyze an operating run to verify that the online results are reasonable or to use a catalogue of events to check if there would have been coincidences. A tool bin.raven_analyze_run was made to accomplish this, using pre-define variables both within the script and settings in GraceDB to accomplish this.

Verify online results

Here’s an example command to analyze all GRBs in O4:

$ raven_analyze_run -i https://gracedb.ligo.org/api/ https://gracedb.ligo.org/api/ -o O4_GRB_results -s GRB SubGRB SubGRBTargeted -R O4

GRB catalogue search

Here’s an example command to perform an O4a GRB catalogue search given a .csv file:

$ raven_analyze_run -i https://gracedb.ligo.org/api/ O4a_grb_catalogue.csv -o O4a_GRB_results -s GRB -R O4a

Interpreting results

Since examining outputs of this search can be tricky, let’s learn how to do this while looking an example.

Example of background

Here, we constructed an injection set of random coincidences, setting random times and sky maps (so no shared injection parameters), as well as GW FARs consistent with background. We see this in the following plot:

This altogether should give the result of a joint FAR consistent with the expected background, which we see in the following temporal joint FAR plot:

Zooming out and also including the joint FAR with spatial information we get:

where we see the skew that can exist for this type of joint FAR. This is a known issue and is mostly relevant for low-significance joint candidates.

Example including foreground

Crucially important to point out is that real searches with foreground candidates will have an excess in the high-significance regime compared to the expected background. Please see the following for an example with GW candidates:

If a similar curve is observed for joint candidates, this excess could be evidence of a population of real coincidences, even sub-threshold, and could be of interest along with highly-significant events.

Alert thresholds

Of particular interest when running offline searches is finding highly significant events that could be of interest to the astronomical community. An alert threshold is a variable set when launching the offline search and a check is done whether the joint FAR with sky map info passes this, recorded in the column passes_threshold shown in this truncated results file:

Example results file

superevent_id	external_id	gw_far	grb_far	grb_not_real	temporal_coinc_far	spatiotemporal_coinc_far	overlap_integral	previously_found	passes_threshold
S31283	E499	0.0001965434460064377	nan	False	1.2751391759550087e-06	0.07256343902446825	1.7572750039107632e-05	False	False
S33175	E509	3.862926140825821e-06	nan	False	2.506198276296813e-08	7.638660255526659e-10	32.8093957901001	False	True
S4781	E518	0.00019192512515663125	nan	False	1.245176325692756e-06	0.1401808833043857	8.88264003151562e-06	False	False
S19	E530	0.00011532261515218642	nan	False	7.481927657324119e-07	1.5699913574129598e-05	0.047655852511525154	False	False
S4665	E665	0.0001603824866211196	nan	False	1.0405332560464572e-06	8.539809719846769e-09	121.84501647949219	False	True
S12365	E666	0.0002177861875941192	nan	False	1.412958332754845e-06	10.080628923539214	1.401656923860628e-07	False	False

Note that if you are using a GraceDB instance and you find a new significant joint candidate(s), please check the appropriate event in that GraceDB instance to check if there was a good reason why the joint candidate was rejected by the online RAVEN search. The previously_found and grb_not_real columns can help with this as well.

If a joint candidate(s) passes reasonable thresholds and does not have obvious reasons to veto or was previously known, it may be worth sharing with the astronomical community.