FastResponseAnalysis

Note

Shared base class, and classes for both skymap and point-source type followups, with shared functions for each.

Base FastResponseAnalysis class

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

Object to do realtime followup analyses of astrophysical transients with arbitrary event localization

calc_pvalue(ntrials=1000, run_anyway=False)

Given an unblinded TS value, calculate the p value

Parameters:

• ntrials (int) – Number of trials to run (default 1000)

• run_anyway (bool) – Choose to override and run background trials, even if TS=0 (default False)

Returns:

p – P value for this analysis

Return type:

float

property dataset

Returns the dataset used

generate_report()

Generates report using class attributes and the ReportGenerator Class Makes full report and outputs as pdf

get_data(livestream_start=None, livestream_stop=None)

Gets the skylab data and MC from querying the i3live livestream

Parameters:

• livestream_start (float) – (optional) start time for getting data (MJD) from i3Live. Default is start time of the analysis - 5 days

• livestream_stop (float) – (optional) stop time for getting data (MJD). Default is stop time of the analysis

property index

Returns the spectral index

initialize_llh(skipped=None, scramble=False)

Grab data and format it all into a skylab llh object

Parameters:

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

• scramble (bool) – (optional) run on scrambled data (default=False)

Returns:

llh – Likelihood for the analysis

Return type:

skylab llh object

property llh_seed

Returns the seed used in the LLH

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

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)

plot_skymap(with_contour=False, contour_files=None, label_events=False)

Make skymap with event localization and all neutrino events on the sky within the given time window Outputs a plot in png format to the analysis path

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)

plot_skymap_zoom(with_contour=False, contour_files=None)

Make a zoomed in portion of a skymap with all ontime neutrino events within a certain range Outputs a plot (in png and pdf formats) to the analysis path

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)

plot_tsd(allow_neg=False)

Outputs a plot of the background TS distributions as well as the observed TS

Parameters:

allow_neg (bool) – Choose to allow negative TS values (all negative values are then TS=0). Default False

remove_event(exp, dset, skipped)

Remove a given event from the analysis, eg. for an alert event

Parameters:

• exp (skylab data object) – Data events loaded from livestream

• dset (skylab Dataset object) – Dataset used in the analysis

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

Returns:

exp – Data events, minus the removed event (if successful)

Return type:

skylab data object

save_results(alt_path=None)

Once analysis has been performed, save all relevant info to a new directory. Saves to a file called [analysisid]_results.pickle

Parameters:

alt_path (string) – optional specified directory to save results to

Returns:

save_items – dictionary of saved analysis parameters

Return type:

dict

significance(p)

Given p value, report significance

Parameters:

p (float) – P value

Returns:

sigma – Significance

Return type:

float

Base PriorFollowup class

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

Class for skymap-based analyses

dec_skymap_range()

Compute minimum and maximum declinations within of the 90% contour of a given skymap

Returns:

• low (float) – lowest declination in 90%

• high (float) – highest declination in 90%

find_coincident_events(print_events=False)

Find coincident events for a skymap based analysis. These are ontime events that are also in the 90% contour of the skymap

format_skymap(skymap)

Method to up or downgrade nside of a skymap to the nside used in the analysis

Parameters:

skymap (array) – Healpix skymap from a file

Returns:

skymap – Healpix skymap, with correct nside for use in FRA

Return type:

array

initialize_injector(e_range=(0.0, inf))

Method to make relevant injector in Skylab, done for analysis checks as well as for calculating sensitivities

Parameters:

e_range (tuple) – optional energy range allowed for injector. default (0., np.inf)

Returns:

inj – Spatial prior injector using skylab

Return type:

Skylab injector object

ipixs_in_percentage(percentage)

Finding ipix indices confined in a given percentage.

Parameters:

• skymap (ndarray) – array of probabilities for a skymap

• percentage (float) – fractional percentage from 0 to 1

Returns:

ipix – indices of pixels within percentage containment

Return type:

numpy int array

make_dNdE()

Make an E^-2 or E^-2.5 dNdE with the central 90% for the minimum and maximum declinations on the skymap

ns_scan()

NS SCAN WITH SPATIAL PRIOR NOT AN OPTION

run_background_trials(ntrials=1000)

helper method to run background trials for the spatial prior analyses Note: this method is not used in running the analysis in realtime

Returns:

ntrials – number of trials to run (default 1000)

Return type:

int

unblind_TS(custom_events=None)

Unblind TS, either sky scan for spatial prior, or just at one location for a point source

Parameters:

custom_events (array) – specific events for use in scan (UNUSED)

Returns:

• ts (float) – unblinded test statistic

• ns (float) – unblinded fitted number of signal events at the best-fit location

• gamma (float) – unblinded fitted spectral index at the best-fit location returned only if spectral index is floated

upper_limit()

UPPER LIMIT WITH SPATIAL PRIOR NOT YET IMPLEMENTED

Base PointSourceFollowup class

class fast_response.FastResponseAnalysis.PointSourceFollowup(name, ra, dec, tstart, tstop, extension=None, skipped=None, outdir=None, save=True, seed=None)

Class for point-source or extended source followup i.e. there is a fixed location on the sky, not a healpy skymap

find_coincident_events()

Find “coincident events” for the analysis. These are ontime events that satisfy:

Spatial weight * energy weight [* temporal weight] > 10

(Note that for this box time window, all events in the ontime window have the same temporal weight.)

initialize_injector(e_range=(0.0, inf))

Method to make relevant injector in Skylab. Used in calculating upper limit

Parameters:

e_range (tuple) – optional energy range allowed for injector. default (0., np.inf)

Returns:

inj – Point source injector using skylab

Return type:

Skylab injector object

make_dNdE()

Make an E^-2 or E^-2.5 dNdE with the central 90% for the most relevant declination band (+/- 5 deg around source dec)

ns_scan(params={'spectrum': 'dN/dE = 1.00e+00 * (E / 1.00e+03 GeV)^-2.00 [GeV^-1cm^-2s^-1]'})

Calculate the llh as a function of ns, to see how shallow the likelihood space is.

Parameters:

params (mappable) – params dictionary for skylab.ps_llh object. Default is that of this analysis

Returns:

xs, delta_llh – Values of ns scanned and corresponding -2*delta_llh values

Return type:

array-like

run_background_trials(ntrials=1000)

Method to run background trials for point source analysis

Parameters:

ntrials (int) – number of background trials to run (default 1000)

unblind_TS()

Unblind TS at one location for a point source

Returns:

• ts (float) – unblinded test statistic

• ns (float) – best fit ns

upper_limit(n_per_sig=100, p0=None)

After calculating TS, find upper limit Assuming an E^-2 spectrum

Parameters:

• n_per_sig (int) – number of trials per injected signal events to run

• p0 (None, scalar, or n-length sequence) – Initial guess for the parameters passed to curve_fit (optional, default None)

Returns:

upperlimit – Flux upper limit in [TeV cm^2 s]^-1

Return type:

float