gamma_limits_sensitivity package

Module contents

This is the hard working code in order to calculate ULs, sensitivities, and time to detections.

gamma_limits_sensitivity.upper_limit(t_obs, lambda_lim, a_eff, e_0, plot_resolution=30)

This function generates all plots for the command ‘ul’ from input data. It takes:

t_obs in seconds lambda_lim from Rolke, Knoetig, … a_eff A path to the file with effective area over true energy after cuts plot_resolution a parameter for running tests faster

It returns a dictionary with results.

gamma_limits_sensitivity.sensitivity(sigma_bg, alpha, t_obs, a_eff, e_0, plot_resolution=30)

This function generates all plots for the command ‘sens’ from input data. It takes:

sigma_bg in 1/seconds alpha on/off exposure ratio t_obs observation time in seconds a_eff A path to the file with effective area over true energy after cuts

It returns a dictionary with results.

gamma_limits_sensitivity.predict(sigma_bg, alpha, f_0, df_0, gamma, dgamma, e_0, a_eff, plot_resolution=30)

This function generates all plots for the command ‘predict’ from input data. It takes:

sigma_bg in 1/seconds alpha on/off exposure ratio f_0 flux normalization in 1/(cm^2 s TeV) df_0 flux normalization error 1 sigma 1/(cm^2 s TeV) gamma power law index (<0) dgamma power law index error 1 sigma e_0 reference energy in TeV a_eff A path to the file with effective area over true energy after cuts

It returns a dictionary with results.

gamma_limits_sensitivity.get_effective_area_test_relative_paths()

Helper function to get the paths of stored effective areas

gamma_limits_sensitivity.get_effective_area(a_eff_path)

Function to get the interpolated effective area from a file path

gamma_limits_sensitivity.prepare_phasespace_meshes(t_obs, lambda_lim, a_eff_interpol, e_0, pixels_per_line, gamma=- 2.6)

determine parameter plot ranges

gamma_limits_sensitivity.get_ul_phasespace_figure(t_obs, lambda_lim, a_eff_interpol, e_0=1.0, pixels_per_line=30)

Function to generate the plot of average counts lambda_s in the phase space of the power law. It will indicate the limit lambda_lim in the same plot.

gamma_limits_sensitivity.get_ul_spectrum_figure(t_obs, lambda_lim, a_eff_interpol, e_0, n_points_to_plot=21)

Get the integral spectral exclusion zone for the ‘ul’ command

gamma_limits_sensitivity.get_sens_phasespace_figure(sigma_bg, alpha, t_obs, a_eff_interpol, e_0=1.0, pixels_per_line=30)

This command produces a phase space figure and fills it with time to detection for given telescope parameters

gamma_limits_sensitivity.get_sens_spectrum_figure(sigma_bg, alpha, t_obs, a_eff_interpol, e_0, n_points_to_plot=21)

This command produces a spectrum figure and fills it with the integral spectral exclusion zone for a given observation time and telescope parameters

gamma_limits_sensitivity.get_predict_phasespace_figure(sigma_bg, alpha, f_0, df_0, gamma, dgamma, e_0, a_eff_interpol, pixels_per_line=30)

This function creates a figure and fills it with relevant phase space functions, such as 2D confidence intervals representing the source emission and time to detection

gamma_limits_sensitivity.get_predict_spectrum_figure(sigma_bg, alpha, t_obs_est, f_0, df_0, gamma, dgamma, e_0, a_eff_interpol, n_points_to_plot=21)

This function generates a spectral plot from precalculated times of observation until detection for a specific telescope analysis

It shows the integral spectral exclusion zone for the median time until detection, and the integral spectral exclusion zones for half that time and double that time.

gamma_limits_sensitivity.plot_predict_contours_from_phasespace_parameters(f_0, df_0, gamma, dgamma, n_samples=100000)

This function draws contours from phase space parameters

gamma_limits_sensitivity.get_phasespace_samples(f_0, df_0, gamma, dgamma, n_samples)

Function to return a sample from the phase space according to the given parameters and parameter uncertainties assuming there can only be:

f_0 > 0
gamma < 0

gamma_limits_sensitivity.get_t_obs_samples(sigma_bg, alpha, f_0, df_0, gamma, dgamma, e_0, a_eff_interpol, n_samples=100000, thinning=0.0025)

Function to calculate samples of the time to detection

gamma_limits_sensitivity.get_t_obs_est_from_samples(t_obs_samples, lower_percentile=16.0, upper_percentile=84.0)

Function to calculate the asymmetrical 68% CI from a sample of times to detection

gamma_limits_sensitivity.get_sensitive_energy_figure(a_eff_interpol)

Get a plot showing the sensitive energy given the effective area a_eff_interpol

gamma_limits_sensitivity.get_effective_area_figure(a_eff_interpol)

Get a plot showing the effective area referenced by a_eff_interpol

gamma_limits_sensitivity.get_energy_range(a_eff_interpol)

Get the definition energy range of the effective area for integration and plotting purposes.

gamma_limits_sensitivity.get_f_0_gamma_limits(f_0, gamma)

Get a nice box power law phase space box for plotting

gamma_limits_sensitivity.get_f_0_gamma_mesh(f_0_limits, gamma_limits, pixels_per_line)

Generate two numpy.meshgrids for 2D plotting

gamma_limits_sensitivity.get_ul_f_0(t_obs, lambda_lim, a_eff_interpol, e_0, gamma)

Calculate f_0 on the exclusion line from solving the boundary condition lambda_lim = lambda_s

gamma_limits_sensitivity.sensitive_energy(gamma, a_eff_interpol)

Function returning the sensitive energy, given gamma and the effective area

gamma_limits_sensitivity.get_useful_e_0(a_eff_interpol)

This function will try to yield a useful e_0 value for anchoring the power law on. This is calculated from the effective area definition range

gamma_limits_sensitivity.get_gamma_from_sensitive_energy(E_sens, a_eff_interpol)

numerical inverse of the sensitive energy

gamma_limits_sensitivity.effective_area_averaged_flux(gamma, e_0, a_eff_interpol)

I define this in the paper as c(gamma)

gamma_limits_sensitivity.ln_energy_weighted(gamma, a_eff_interpol)

For calculating the sensitive energy. This function gets the unnormalized mean ln(energy) integrated over the power law flux and sensitive area

gamma_limits_sensitivity.mean_log10_energy(a_eff_interpol)

For calculating mean of the log10 of the energy over the effective area, to estimate a useful e_0

gamma_limits_sensitivity.power_law(energy, f_0, gamma, e_0=1.0)

A power law function as defined in the paper

gamma_limits_sensitivity.plot_effective_area(a_eff_interpol, style='k', label='')

fill a plot with the effective energy from the supplied interpolated data

gamma_limits_sensitivity.plot_sensitive_energy(a_eff_interpol)

fill a sensitive energy plot figure

gamma_limits_sensitivity.plot_ul_spectrum_figure(t_obs, lambda_lim, a_eff_interpol, e_0, n_points_to_plot, fmt='k', label='')

fill a ul spectrum figure with the integral spectral exclusion zone plot

gamma_limits_sensitivity.plot_sens_spectrum_figure(sigma_bg, alpha, t_obs, a_eff_interpol, e_0, n_points_to_plot, fmt='k', label='')

fill a spectrum figure with the sensitivity integral spectral exclusion zone plot

gamma_limits_sensitivity.plot_lambda_s_mesh(t_obs, lambda_lim, a_eff_interpol, e_0, f_0_mesh, gamma_mesh, n_levels=9, linestyles='dashed', linewidths=1, colors='k')

Function to get the lambda_s plot in the phase space of the power law

gamma_limits_sensitivity.plot_t_obs_mesh(sigma_bg, alpha, a_eff_interpol, e_0, f_0_mesh, gamma_mesh, n_levels=9, linestyles='dashed', linewidths=1, colors='k', t_obs=None)

This function puts the times until detection into a plot in phase space (f_0, Gamma) for given telescope analysis parameters

gamma_limits_sensitivity.plot_contours_from_sample(samples, levels=None, smooth=False)

This function draws a contour plot into the current figure showing selected highest density 2D confidence intervals The standard is: 1 sigma, 2 sigma, 3 sigma in 2D

gamma_limits_sensitivity.plot_power_law(f_0, gamma, e_0, energy_range, fmt='k:', label='', alpha_plot=0.7)

This function generates a power law plot in the current figure

gamma_limits_sensitivity.plot_source_emission_spectrum_with_uncertainties(phasespace_samples, e_0, energy_range, label='')

This function draws 100 power laws as an illustration for the source emission uncertainty

gamma_limits_sensitivity.integral_spectral_exclusion_zone(energy, lambda_lim, a_eff_interpol, t_obs, e_0)

This function returns the integral spectral exclusion zone value at one point in energy for given lambda_lim, a_eff_interpol, and t_obs

gamma_limits_sensitivity.integral_spectral_exclusion_zone_parameters(energy, lambda_lim, a_eff_interpol, t_obs, e_0=1.0)

This function calculates the integral spectral exclusion zone parameters f_0 and gamma at at a given energy in order to draw it into spectral plots.

It is done by utilizing the Lagrangian results from the paper.

gamma_limits_sensitivity.t_obs_li_ma_criterion(sigma_s, sigma_bg, alpha, threshold=5.0)

This function calculates the limit average time to detection, given a signal rate, background rate, and alpha

gamma_limits_sensitivity.sigma_lim_li_ma_criterion(sigma_bg, alpha, t_obs, threshold=5.0)

This function returns the limit signal count rate using the LiMa criterion

gamma_limits_sensitivity.li_ma_significance(n_on, n_off, alpha)

A function to calculate the significance, according to :

Li, T-P., and Y-Q. Ma. “Analysis methods for results in gamma-ray astronomy.” The Astrophysical Journal 272 (1983): 317-324.