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 :func:`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:

.. code-block:: sh

	make gen2_analysis-data

First, we instantiate the selection efficiency::
	
	selection_efficiency = get_muon_selection_efficiency('Sunflower', 240)

:func:`icecube.gen2_analysis.effective_areas.get_muon_selection_efficiency` simply locates
a table appropriate for the requested geometry and spacing uses it contructs a
:func:`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
:func:`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)

:func:`icecube.gen2_analysis.energy_resolution.get_energy_resolution` returns
a :func:`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)

:func:`icecube.gen2_analysis.angular_resolution.get_angular_resolution` returns
a :func:`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
-------------

.. autofunction:: icecube.gen2_analysis.effective_areas.create_throughgoing_aeff

.. autofunction:: icecube.gen2_analysis.effective_areas.get_muon_selection_efficiency

.. autoclass:: icecube.gen2_analysis.effective_areas.ZenithDependentMuonSelectionEfficiency

.. autofunction:: icecube.gen2_analysis.surfaces.get_fiducial_surface

.. autoclass:: icecube.gen2_analysis.surfaces.ExtrudedPolygon
	:members: from_I3Geometry, from_file

.. autofunction:: icecube.gen2_analysis.energy_resolution.get_energy_resolution

.. autoclass:: icecube.gen2_analysis.energy_resolution.MuonEnergyResolution