Tutorial

In this tutorial, we will derive a point source discovery potential. The calculation proceeds in 3 steps:

1. Calculate an effective area for neutrino-induced, incoming muon tracks.
2. Use the effective area to predict the background due to atmospheric and diffuse astrophysical neutrinos in the desired declination band as a function of opening angle from the putative source and reconstructed muon energy.
3. Use the same effective area to predict the signal rate, also as a function of angular distance and reconstructed energy
4. Construct a likelihood and calculate the median test statistic to derive the discovery potential.

Effective area

We use the factory function effective_areas.create_throughgoing_aeff() to construct an effective area. We need to tell it:

1. The efficiency of our event selection as a function of muon energy and zenith angle
2. The fiducial surface that the efficiency was calculated with respect to
3. The geometric coverage of the surface veto (if any)
4. The acceptance of the surface veto (if any)
5. The muon energy resolution after event selection
6. The muon point spread function after event selection

In this example we will use the default efficiencies and resolution tables. You first need to copy these to your metaproject. A make target is provided for this purpose. Invoke it from your metaproject build directory:

make gen2_analysis-data

First, we instantiate the selection efficiency:

selection_efficiency = get_muon_selection_efficiency('Sunflower', 240)

icecube.gen2_analysis.effective_areas.get_muon_selection_efficiency() simply locates a table appropriate for the requested geometry and spacing uses it contructs a icecube.gen2_analysis.effective_areas.ZenithDependentMuonSelectionEfficiency(). If you have your own tables, you can instantiate one yourself. The example script resources/scripts/data prep/muon_selection_efficiency.py demonstrates how to make the appropriate table.

Then, the fiducial surface:

surface = surfaces.get_fiducial_surface('Sunflower', 240)

If you have a fiducial surface that is not yet defined (for example, for a brand-new geometry), you can always instantiate an icecube.gen2_analysis.surfaces.ExtrudedPolygon() yourself.

For the moment we will ignore the surface veto and proceed to energy resolution:

energy_resolution = energy_resolution.get_energy_resolution('Sunflower', 240)

icecube.gen2_analysis.energy_resolution.get_energy_resolution() returns a icecube.gen2_analysis.energy_resolution.MuonEnergyResolution(). The example script resources/scripts/data prep/muon_energy_resolution.py demonstrates how to make an energy resolution table.

Next, we need the point spread function:

psf = angular_resolution.get_angular_resolution('Sunflower', 240)

icecube.gen2_analysis.angular_resolution.get_angular_resolution() returns a icecube.gen2_analysis.angular_resolution.PointSpreadFunction(). The example script resources/scripts/data prep/fit_psf.py demonstrates how to parameterize the muon point spread function.

Optionally we can specify the binning we would like in zenith angle and angular distance from the putative source:

cos_theta = numpy.linspace(-1, 1, 21)
psi_bins = numpy.linspace(0, numpy.sqrt(numpy.radians(5)), 21)**2

Now we have all the inputs we need and can create the effective area:

aeff = effective_areas.create_throughgoing_aeff(
    selection_efficiency=selection_efficiency, surface=surface,
    energy_resolution=energy_resolution, psf=psf,
    cos_theta=cos_theta, psi_bins=psi_bins)

Neutrino fluxes

Now that we have an effective area, we need to construct the neutrino flux sources we will use in the analysis. First

First we need to find an index:

sindec = 0.1
zenith_index = cos_theta.searchsorted(-sindec)-1

API reference

icecube.gen2_analysis.effective_areas.create_throughgoing_aeff(energy_resolution=<icecube.gen2_analysis.energy_resolution.MuonEnergyResolution object>, energy_threshold=<icecube.gen2_analysis.effective_areas.StepFunction object>, veto_coverage=<function <lambda>>, selection_efficiency=<icecube.gen2_analysis.effective_areas.MuonSelectionEfficiency object>, surface=<icecube.gen2_analysis.surfaces.Cylinder object>, psf=<icecube.gen2_analysis.angular_resolution.PointSpreadFunction object>, psi_bins=array([ 0., 0.00558953, 0.00790478, 0.00968134, 0.01117905, 0.01249856, 0.01369149, 0.0147885, 0.01580957, 0.01676858, 0.01767564, 0.01853836, 0.01936269, 0.02015333, 0.0209141, 0.02164815, 0.02235811, 0.02304621, 0.02371435, 0.02436418, 0.02499712, 0.02561443, 0.02621721, 0.02680643, 0.02738298, 0.02794764, 0.02850111, 0.02904403, 0.029577, 0.03010052, 0.0306151, 0.03112117, 0.03161914, 0.03210939, 0.03259226, 0.03306809, 0.03353716, 0.03399977, 0.03445616, 0.03490659]), cos_theta=None)

Create an effective area for neutrino-induced, incoming muons

Parameters:

• selection_efficiency – an energy- and zenith-dependent muon selection efficiency
• surface (surfaces.UprightSurface) – the fiducial surface surrounding the detector
• veto_coverage – a callable f(cos_theta), returning the fraction of the fiducial area that is in the shadow of a surface veto
• energy_threshold (VetoThreshold) – the energy-dependent veto passing fraction
• energy_resolution (energy_resolution.MuonEnergyResolution) – the muon energy resolution for events that pass the selection
• psf (angular_resolution.PointSpreadFunction) – the muon point spread function for events that pass the selection
• cos_theta – sky binning to use. If cos_theta is an integer, bin in a HEALpix map with this NSide, otherwise bin in cosine of zenith angle. If None, use the native binning of the muon production efficiency histogram.
• psi_bins – edges of bins in muon/reconstruction opening angle (radians)

Type:

MuonSelectionEfficiency

Returns:

an effective_area object

icecube.gen2_analysis.effective_areas.get_muon_selection_efficiency(geometry, spacing, energy_threshold=0)

Parameters:energy_threshold – artificial energy threshold in GeV

class icecube.gen2_analysis.effective_areas.ZenithDependentMuonSelectionEfficiency(filename='sunflower_200m_bdt0_efficiency.fits', energy_threshold=0)

icecube.gen2_analysis.surfaces.get_fiducial_surface(geometry='Sunflower', spacing=200, padding=60)

class icecube.gen2_analysis.surfaces.ExtrudedPolygon(xy_points, z_range)

A convex polygon in the x-y plane, extruded in the z direction

classmethod from_I3Geometry(i3geo, padding=0)

Create from an I3Geometry object file

Parameters:

• i3geo – an I3Geometry
• padding – distance, in meters, to expand the surface in all directions

classmethod from_file(fname, padding=0)

Create from a GCD file

Parameters:

• fname – path to an I3 file containing at least a G frame
• padding – distance, in meters, to expand the surface in all directions

icecube.gen2_analysis.energy_resolution.get_energy_resolution(geometry='Sunflower', spacing=200, channel='muon')

class icecube.gen2_analysis.energy_resolution.MuonEnergyResolution(fname='aachen_muon_energy_profile.npz', overdispersion=1.0)

A parameterization of the inherent smearing in muon energy resolution