SNEWS fast likelihood calculator

This is a python extension module for fast calculation of a specific likelihood formula, for use in the SNEWS alert system.

For more information about the formula and derivation, see [paper not yet published].

Installing

This package is written mostly in C++, but implements a Cython wrapper for easy use from normal Python code. Use pip install and no additional compilation will be necessary.

If this repo has been cloned to /eg/dir then run:

> pip install /eg/dir

And it should be available to import in python as:

import burstlag

Interface

Functionality is primarily accessed through the DetectorRelation class. It is also necessary to create at least one instance of FactorialCache. Both of these can be imported from the top level of the module:

from burstlag import DetectorRelation, FactorialCache

cache = FactorialCache()

One cache instance may (and should) be reused to improve performance, but multiple can be created to allow multi-threading etc. It takes no parameters, and acts only to store calculated values of log integers and factorials.

The DetectorRelation class

Instances of this class are used to store parameters describing pairs of detectors to be used in the likelihood calculation.

The full class definition for DetectorRelation (and FactorialCache) can be found in interface.pyx. These include docstrings with further documentation. The key methods are:

• DetectorRelation.from_counts - Convenient way to create a DetectorRelation, infers relative sensitivities from total neutrino counts provided. In other situations, it may be more useful to use the class constructor, which takes the sensitivity as a parameter. There is also the from_hist_arrays function which is more convenient for pre-binned data.

• DetectorRelation.log_likelihood - Calculates the log-likelihood for arrays of neutrino counts at the detectors described by DetectorRelation instance. This function also takes an instance of FactorialCache.

Examples can be found in test/known_values.py.

Very simple example

from burstlag import DetectorRelation, FactorialCache

cache = FactorialCache()

rel = DetectorRelation(200, 0.5, 0.01)
# First detector has background 200/bin
# Second detector has background 0.5/bin
# First detector is 100x more sensitive

precision = 0.01 # 1% precision

import numpy as np # Used only to make signal arrays
sig_1 = np.array([1000, 400, 3])
sig_2 = np.array([10, 5, 1])

eg_log_like = rel.log_likelihood(cache, sig_1, sig_2, precision)