GWFollowup

Note

Class for followups of gravitational wave events detected by LVK. Fits the spectral index of the source in the likelihood.

class fast_response.GWFollowup(name, skymap_path, tstart, tstop, skipped=None, seed=None, outdir=None, save=True, extension=None)

Class for followup of a GW. By default, fits the index in the LLH. Built on the PriorFollowup class for skymap-based analyses

check_events_after()

Check that we have recieved at least one event after the on-time window closes. This is to make sure we have all data from i3Live before running.

Returns:

True if there is at least 1 event after tw (prints how many), or False if there are no events after (should re-load!)

Return type:

bool

find_coincident_events()

Find “coincident events” for a skymap based analysis. These are ALL ontime events, with a bool to indicate if they are in the 90% contour

generate_report()

Generates GW report using class attributes and the ReportGenerator Class, from fast_response.reports.GravitationalWaveReport

get_best_fit_contour(proportions=[0.5, 0.9])

Get a contour for the error around the best-fit point. Makes a zoomed skymap of the ts-space with contours

Parameters:

proportions (list) – confidence levels to calculate (default [0.5,0.9])

initialize_llh(skipped=None, scramble=False)

Grab data and format it all into a skylab llh object - This function is very similar to the one in FastResponseAnalysis.py, with the main difference being that these are low-latency enough that we may have to wait for the last min of data to reach i3live. if so, initialize LLH, load ontime data, then add temporal info and ontime data to llh.

Parameters:

• skipped (array of tuples) – Event(s) to be attempted to be removed in the analysis. Format: [(run_id,event_id),… ]

• scramble (bool) – scramble events in LLH (default False)

Return type:

Skylab LLH object

inject_scan(ra, dec, ns, poisson=True)

Run All sky scan using event localization as spatial prior, while also injecting events according to event localization

Parameters:

• ns (float) – Number of signal events to inject

• poisson (bool) – Will poisson fluctuate number of signal events to be injected

Returns:

tuple – results dict with ts, ns, gamma, ra, dec; events in the time window

Return type:

(results, events)

make_dec_pdf()

Plot PDF of source declination overlaid with IceCube’s point source sensitivity

per_event_pvalue()

Calculate per-event p-values. There are a few cases here:

• overall p < 0.1:

  Redoes the all-sky scan, using per_event_scan, with only that single event. This is the same as asking the question: If that single event is the only one on the sky, with this given skymap, what TS/p-value would we get for that event?

• 1.0 > overall p > 0.1:

  Calculates the p-value at the reconstructed event direction. Takes the TS at that location, and calculates the p-value at that location. Does not re-run the scan, to save time in realtime

• p=1.0:

  Does not get p-values for the events (all are set to None)

per_event_scan(custom_events)

Runs the all-sky scan for only one (or certain) events on the sky

Parameters:

custom_events (masked array) – Ontime event(s) loaded in Skylab to use when running the all sky scan

Returns:

• ts (float) – best-fit TS using only this event

• p (float) – p-value for the given event(s)

plot_ontime(with_contour=True, contour_files=None, label_events=True)

Plots ontime events on the full skymap and a zoomed in version near the scan best-fit

Parameters:

• with_contour (bool) – plots the 90% containment contour of a skymap (default False)

• contour_files (string) – text file containing skymap contours to be plotted (default None)

• label_events (bool) – adds a number label to events on skymap (default False)

ps_sens_range()

Compute minimum and maximum sensitivities within the declination range of the 90% contour of a given skymap

Returns:

• low (float) – lowest sensitivity within dec range

• high (float) – highest sensitivity within dec range

run_background_trials(month=None, ntrials=1000)

For GW followups with specific time windows, just use precomputed background arrays. 2 allowed time windows:

• 1000s: for all (default)

• [-0.1, +14]: BNS, NSBH

Returns:

tsd – test-statistic distribution with weighting from alert event spatial prior

Return type:

array-like

upper_limit()

Get a Sensitivity Range (not truly an UL) for the full range of declinations for GW skymap. Calculated with the ps_sens_range function to get the point source sensitivity range within the 90% contour of the map

write_circular()

Generate a circular from a template. Uses a different template if high significance or low-significance (no longer sent for O4). High-significance are generated for p<0.2, in case LLAMA sees p<0.01 for the same event and a circular is needed. Saves a text file in the output directory as gcn_[eventname].txt