Reference

rate

class sn_stat.rate(a, *, range=None)

create a Rate object

Parameters

• a (scalar or callable or tuple[floats,floats] or ABCRate) – Object to use to create the rate

• range (None or tuple(float,float)) – if given tuple (x0,x1), the rate outside (x0,x1) will be 0

Returns

a constructed rate object (inherited from ABCRate). Depending on the input type will produce following classes:

• scalar - constant rate sn_stat.rate.Const

• callable - rate defined by the function sn_stat.rate.Func

• tuple(x,y) - sn_stat.rate.Interpolated (x,y)

• ABCRate: use given rate

class sn_stat.log_rate(a)

Create a Rate object with log-log interpolation,

This is the alternative to rate() method for interpolation, using the log-log interpolation instead of a linear one. I.e. assuming that between points (x0,y1) and (x1,y1)

\[y(x) = y_0(x/x_0)^{\alpha}\]

where \(\alpha = \ln(y_1/y_0)/\ln(x_1/x_0)\)

Parameters

a – tuple of 1-D array-like (x,y) x values should be sorted and have the same sign (all x<0 or x>0)

Returns

rate object

Raises

ValueError – if not all x are of the same sign

Concrete rates

class sn_stat.rate.Const(c)

Constant rate in time

Parameters

c (float) – constant rate value

class sn_stat.rate.Func(f)

Rate defined by the function

Parameters

f (callable[float]->float) – the desired rate vs. time function

class sn_stat.rate.Interpolated(x, y, **kwargs)

Rate defined by linear interpolation of the given points

Parameters

• x (1D array-like) – time values

• y (1D array-like) – rate values

• **kwargs (dict) – additional parameters to pass to scipy.interp.UnivariateSpline default = dict(ext=1, k=1, s=1) is for linear interpolation.

sampler

class sn_stat.Sampler(r, time_window=[0, 10], Npoints=1000)

Generates random event samples (timestamps) following the given event rate

Parameters

• r (rate) – event rate

• time_window (tuple[float,float]) – limits in which the events are generated

• Npoints (int) – number of subdivisions for the integration. The initial distribution is approximated by Npoints equidistant points in the time_window range

sample()

Produce the random events

Returns

1-d array with the events timestamps

Return type

ndarray

detector configuration

class sn_stat.DetConfig(B, S=([0.0, 1.0], [1.0, 1.0]), time_window='auto', name=None)

Detector configuration, containing signal S and background B event rates.

Parameters

• B (rate) – background rate vs. time

• S (rate) – expected signal event rate vs. time

• time_window ("auto" or tuple(float, float)) – The limits around t0 in which to take the signal. If “auto”, then try to take the full range from S (via S.range)

• name (str) – optional name for the detector configuration

llr

sn_stat.llr.JointDistr(llrs, hypos='H0', t0=0, R_threshold=100, *, dl=0.001, epsilon=1e-16, Nsamples=10000)

Calculate the joint distribution of llrs under hypotheses hypos

Parameters

• llrs (iterable of LLR) – configurations for each experiment

• hypos (iterable of rate or “H0”) – expected rate for each experiment, or “H0” string - taking background rates from each LLR

• t0 (float) – time of assumed SN start

• R_threshold (int) – if the integrated rate in hypothesis is above this threshold, a Gaussian approximation is used for this distribution, otherwise a precise calculation with FFT is performed.

Keyword Arguments

• dl (float) – LLR bin size for distributions. Ignored, if all distributions are gaussian.

• epsilon (float) – calculation precision for FFT distributions (ignored if all distrs are gaussian)

• Nsamples (int) – number of points to sample the LLR values range (ignored if all distrs are gaussian)

Returns

a distribution for the joint (sum) of individual LLRs under the given hypothesis

Return type

Distr

class sn_stat.llr.Distr(bins, vals)

class sn_stat.LLR(det: sn_stat.det_config.DetConfig)

Log likelihood ratio for H0 (B) and H1 (B+S) hypotheses:

\[\ell(t,t_0) = \log\left(1+\frac{S(t-t_0)}{B(t)}\right)\]

where t is the event time and t_0 is assumed signal start time.

__call__(ts, t0, time_precision=None)

Calculate the LLR value for given set of measurements ts, assuming supernova times t0

Parameters

• ts (iterable) – Measured interactions timestamps

• t0 (iterable) – Assumed supernova start times

• time_precision (float or None) – If not None: group the given ts to the time bins with given precision, speeding up the calculation for large number of events

Returns

llr – Cumulative LLR values for each value of t0

Return type

ndarray

distr(hypothesis='H0', t0=0, *, normal=False, Nsamples=10000, dl='auto')

Calculate the LLR distribution under given assumption of the event rate

Parameters

• hypothesis (rate or “H0”) – the assumed event rate vs. time. If hypothesis==’H0’ - use background rate (self.det.B)

• t0 (float) – assumed supernova start time

• normal (bool) – flag to use normal distribution, otherwise use precise FFT calculation

Keyword Arguments

• normal (bool) – if True, approximate with normal distribution, otherwise calculate numerically with FFT

• dl (float or "auto") – LLR bin size for distribution. if ‘auto’ - set it to 1e-3*max(l) (ignored if normal==True)

• epsilon (float) – calculation precision for FFT distributions (ignored if normal==True)

• Nsamples (int) – number of points to sample the LLR values range (ignored if normal==True)

Returns

distribution of the LLR values. If normal==True returns scipy.stats.norm, otherwise constructs Distr with bins from 0 to maximum LLR value in given time window

l_range(t0, Nsamples=10000)

returns: (min, max) LLR values for given t0

Analyses

class sn_stat.CountingAnalysis(det: sn_stat.det_config.DetConfig)

Calculating significance using the counting analysis method: using number of interactions within the time window (DetConfig.time_window) as the test statistics (TS).

Parameters

det (DetConfig) – configuration for the experiment

__call__(data, t0, **params)

calculate significance for the set of measurements

l2p(l)

convert TestStatistics to p-value

l2z(l)

convert TestStatistics to significance

l_distr(hypos, add_bg=False)

Calculate test statistic distribution

Parameters

• hypos – :class:rate or “H0” Hypothetical event we use to calculate the distribution If “H0” then use the background rate (self.det.B)

• add_bg – bool If set, then add the background rate to the hypos

Returns

frozen poisson distribution

l_val(data, t0, **params)

Calculate test statistics value

Parameters

• data (iterable of array of float) – List with arrays of measured events time stamps for each detector. If there is only one detector, just an array(float) is enough

• t0 (ndarray of float) – assumed time/times of signal start

• params – additional optional parameters for the current method

Returns

test statistic values for each value in t0

Return type

ndarray of float

p2l(p)

convert p-value to TestStatistics

z2l(z)

convert significance to TestStatistics

z_distr(hypos, add_bg=False, zbins=100)

calculate significance distribution based on given hypotheses hypos

z_quant(hypos, add_bg=False, qs=array([0.84134475, 0.5, 0.15865525]))

calculate zs, corresponding to quantiles of given hypotheses

class sn_stat.ShapeAnalysis(detectors, **params)

Calculating significance using the shape analysis method, using Log Likelihood Ratio (LLR)

Parameters

detectors (single DetConfig or iterable of DetConfig) – configurations for each experiment. Passing single DetConfig ShapeAnalysis(det) is equivalent to passing a list with one item ShapeAnalysis([det])

Keyword Arguments

params (dict of kwargs) – configuration arguments to be passed to sn_stat.llr.JointDistr():

__call__(data, t0, **params)

calculate significance for the set of measurements

l2p(l)

convert TestStatistics to p-value

l2z(l)

convert TestStatistics to significance

l_distr(hypos, add_bg=False)

Calculate test statistic distribution

Parameters

• hypos – :class:rate or “H0” Hypothetical event we use to calculate the distribution If “H0” then use the background rate (self.det.B)

• add_bg – bool If set, then add the background rate to the hypos

Returns

frozen poisson distribution

l_val(data, t0, **params)

Calculate test statistics value

Parameters

• data (iterable of array of float) – List with arrays of measured events time stamps for each detector. If there is only one detector, just an array(float) is enough

• t0 (ndarray of float) – assumed time/times of signal start

• params – additional optional parameters for the current method

Returns

test statistic values for each value in t0

Return type

ndarray of float

p2l(p)

convert p-value to TestStatistics

z2l(z)

convert significance to TestStatistics

z_distr(hypos, add_bg=False, zbins=100)

calculate significance distribution based on given hypotheses hypos

z_quant(hypos, add_bg=False, qs=array([0.84134475, 0.5, 0.15865525]))

calculate zs, corresponding to quantiles of given hypotheses