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:
Compare GWs and external events in the same GraceDB server to check the results of online RAVEN after an operating run.
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.
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
superevent_id |
preferred_event |
t_0 |
pipeline |
search |
group |
far |
skymap |
---|---|---|---|---|---|---|---|
S170817a |
G1 |
100 |
gstlal |
AllSky |
CBC |
1E-07 |
ligo/raven/tests/data/GW170817/GW170817.multiorder.fits |
S170817b |
G2 |
150 |
MBTA |
AllSky |
CBC |
1E-06 |
ligo/raven/tests/data/GW170817/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 |
ligo/raven/tests/data/GW170817/bayestar.fits.gz |
S170817e |
G4 |
1000 |
pycbc |
AllSky |
CBC |
1E-04 |
|
S170817f |
G3 |
120 |
CWB |
AllSky |
Burst |
1E-07 |
ligo/raven/tests/data/GW170817/GW170817.multiorder.fits |
graceid |
gpstime |
pipeline |
search |
far |
ra |
dec |
error_radius |
skymap |
---|---|---|---|---|---|---|---|---|
E170817 |
102 |
Fermi |
GRB |
0 |
0 |
15 |
ligo/raven/tests/data/GW170817/glg_healpix_all_bn_v00.fit |
|
E170818 |
101.5 |
Swift |
GRB |
10 |
-45 |
.05 |
ligo/raven/tests/data/GW170817/glg_healpix_all_bn_v00.fit |
|
E2345 |
104 |
Swift |
SubGRBTargeted |
1E-06 |
0 |
30 |
0 |
|
E3456 |
160 |
Fermi |
SubGRB |
45 |
-30 |
5 |
ligo/raven/tests/data/GW170817/glg_healpix_all_bn_v00.multiorder.fits |
|
E4567 |
75 |
Fermi |
GRB |
45 |
-30 |
5 |
ligo/raven/tests/data/GW170817/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 |
ligo/raven/tests/data/GW170817/glg_healpix_all_bn_v00.multiorder.fits |
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:
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.