Tutorials#

The tutorials below walk through common SkyLLH analysis tasks using IceCube public data. They progress from a basic steady-state point-source fit to more specialised techniques.

The tutorials support both the 10-year (IceTracks-DR1) and the 14-year (IceTracks-DR2) IceCube public point-source datasets. They are automatically downloaded from dataverse.harvard.edu to a local cache directory (~/.cache/skyllh). To use custom dataset locations, set the cfg['repository']['base_path'] to the desired path.

Note

As of this release, 'IceTracks-DR2' refers to version 2.0 of the 14-year dataset, which fixes two binning issues identified in version 1.0:

The IC86 Monte Carlo simulations extend only up to a true energy of log10(E/GeV) = 8.7, which falls inside the last true-energy bin, log10(E/GeV) = [8.6, 8.8). The resulting lack of simulated events artificially reduced the effective area in that bin at all declinations. Version 2.0 sets the range of this bin to log10(E/GeV) = [8.6, 8.7), matching the simulation boundary.
The sin(declination) binning of the smearing matrices was set to IceCube’s internal IC40 binning for all detector configurations (IC40, IC59, IC79, and IC86), rather than to the per-season internal binning described in the accompanying paper. Version 2.0 uses the corresponding binning for each season.

Version 1.0 remains available under the explicit name 'IceTracks-DR2-v1', while 'IceTracks-DR2-v2' is an explicit alias for the current default.

To load respective datasets:

import skyllh
from skyllh.core.config import Config

cfg = Config()

datasets = skyllh.create_datasets('IceTracks-DR2', cfg=cfg)

datasets = skyllh.create_datasets('IceTracks-DR1', cfg=cfg)

Additional information about the IceCube public datasets can be found in the following references:

We provide an incomplete list of tutorials below. They are meant to illustrate how to perform a time-integrated point-source analysis using SkyLLH, but they are not exhaustive. We encourage users to explore the documentation and contribute additional tutorials covering other analysis types and techniques.

Fitting a steady point-source with the public 14-year IceCube track data: Fit a steady point source (NGC 1068) using IceCube 14-year (IceTracks-DR2) public track data. Covers loading datasets, maximising the log-likelihood ratio, computing the test statistic, and deriving flux normalisations. Also demonstrates converting between mean signal event counts and flux normalisations.
Dataset collections: Introduces the concept of dataset collections, which are used to manage multiple datasets in a unified way. Covers loading datasets, inspecting available datasets, and accessing individual datasets.
Fixing the Spectral Index: Repeat the point-source fit with a fixed (non-free) spectral index.
Setting an energy range for the signal injection: Set a user-defined energy range for the signal injection. Illustrates the distinction between the signal-injection energy range and the likelihood hypothesis energy range.
Sky scan: Produce a 2-D test-statistic map by scanning source positions on a sky grid around a candidate source. Visualises best-fit position and confidence contours using Wilks’ theorem.
Likelihood scan: Scan the log-likelihood ratio over a 2-D grid of flux normalisation and spectral index. Produces confidence contours in the gamma-flux parameter space.
Significance/p-value calculation: Compare two methods for computing a local p-value from a test statistic: generating background-only trials versus fitting a truncated gamma distribution to the TS distribution.
Sensitivity and discovery potential: Estimate sensitivity and discovery potential for a point source. Demonstrates the analysis construction and how to convert signal counts to flux.
Time dependent analysis: Perform a time-dependent point-source analysis. Uses the Expectation-Maximisation (EM) algorithm to fit the timing and duration of a neutrino flare (TXS 0506+056).