Metadata-Version: 1.2
Name: lauztat
Version: 1.1.2
Summary: Pure python statistic tools for high energy physics.
Home-page: https://github.com/marinang/lauztat
Author: Matthieu Marinangeli
Author-email: matthieu.marinangeli@epfl.ch
Maintainer: Matthieu Marinangeli
Maintainer-email: matthieu.marinangeli@epfl.ch
License: UNKNOWN
Description: lauztat
        ^^^^^^^
        
        .. image:: https://travis-ci.org/marinang/lauztat.svg?branch=master
            :target: https://travis-ci.org/marinang/lauztat
        
        .. image:: https://dev.azure.com/matthieumarinangeli/matthieumarinangeli/_apis/build/status/marinang.lauztat?branchName=master
            :alt: Build Status
            :target: https://dev.azure.com/matthieumarinangeli/matthieumarinangeli/_build?definitionId=1
        
        .. image:: https://img.shields.io/azure-devops/tests/matthieumarinangeli/matthieumarinangeli/1.svg?compact_message
            :alt: Test Status
            :target: https://dev.azure.com/matthieumarinangeli/matthieumarinangeli/_build?definitionId=1
        
        .. image:: https://img.shields.io/coveralls/github/marinang/lauztat.svg
            :alt: Coveralls github
            :target: https://coveralls.io/github/marinang/lauztat?branch=master
        
        .. image:: https://api.codacy.com/project/badge/Grade/f78242fbdbd34ef8a21a9f9055b6c898
            :alt: Codacy Badge
            :target: https://app.codacy.com/app/marinang/lauztat?utm_source=github.com&utm_medium=referral&utm_content=marinang/lauztat&utm_campaign=Badge_Grade_Dashboard
        
        .. image:: https://mybinder.org/badge_logo.svg
            :target: https://mybinder.org/v2/gh/marinang/lauztat/master?filepath=examples%2Fnotebooks%2F
        
        .. image:: https://img.shields.io/pypi/v/lauztat.svg
            :alt: PyPI
            :target: https://pypi.org/project/lauztat/
        
        .. image:: https://img.shields.io/pypi/pyversions/lauztat.svg
            :alt: PyPI - Python Version
            :target: https://pypi.org/project/lauztat/
        
        .. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.2593789.svg
            :target: https://doi.org/10.5281/zenodo.2593789
        
        
        
        Pure python statistics tools for high energy physics using `zfit <https://github.com/zfit/zfit>`__ as
        a backend for maximum likelihood fits.
        
        Tests for discovery, upper limits and confidence intervals are provided based on likelihood ratios
        in a frequentist approach (using pseudo-experiments) or using asymptotic formulae from
        "Asymptotic formulae for likelihood-based tests of new physics" `[arxiv:1007.1727] <https://arxiv.org/abs/1007.1727>`__.
        
        lauztat has been developed at EPFL, Lausanne Switzerland (laus' or lauz is how the cool kids call Lausanne).
        
        Installation
        ------------
        
        Install ``lauztat`` like any other Python package:
        
        .. code-block:: bash
        
            pip install lauztat                       # maybe with sudo or --user, or in virtualenv
        
        Dependencies
        ------------
        
        - `Numpy <https://scipy.org/install.html>`__
        - `zfit <https://github.com/zfit/zfit>`__
        - `matplotlib <https://matplotlib.org/users/installing.html>`__ (optionnal)
        
        Getting started
        ---------------
        
        Usual HEP results can be recast in terms of hypothesis testing where you have to
        choose a null H\ :sub:`0` and an alternative H\ :sub:`1` hypothesis, H\ :sub:`0`
        being the one you want to disprove.
        To do a test you will need your data (and weights), a model, a loss function builder
        and a minimizer as input to a calculator (*FrequentistCalculator* or *AsymptoticCalculator*).
        
        Discovery:
        ==========
        
        if you do a measurement to find signals S in a dataset and you find an excess, this
        test answers "is the data compatible with the background only ?" with:
        
        - H\ :sub:`0`: background only (S = 0)
        - H\ :sub:`1`: presence of a signal (S ≠ 0)
        
        The test return a p-value or a significance Z. If Z ≥ 3 there is an evidence
        and if Z ≥ 5 a discovery of a signal.
        
        Examples of significance computations for a gaussian peak over an exponential background are
        provided for the `asymptotic calculator <https://github.com/marinang/lauztat/blob/master/examples/notebooks/discovery_zfit_asy.ipynb>`__
        and the `frequentist calculator <https://github.com/marinang/lauztat/blob/master/examples/notebooks/discovery_zfit_freq.ipynb>`__
        and can be ran in `mybinder <https://mybinder.org/v2/gh/marinang/lauztat/master?filepath=examples%2Fnotebooks%2F>`__.
        
        Upper limit:
        ============
        
        if you find a small signal excess in a dataset, but not enough to claim
        an evidence or a discovery, you can exclude large signal yields S:
        
        - H\ :sub:`0`: background + some signal (S = S\ :sub:`0`)
        - H\ :sub:`1`: S < S\ :sub:`0`
        
        S\ :sub:`0` is adjusted to a predefined p-value, typically 5%. S\ :sub:`0` is the upper
        limit on the signal yield S with 95 % confidence level
        (CL = 1 - p ; p = 5 % ⟺ CL = 95%).
        
        Examples of `CLs <https://iopscience.iop.org/article/10.1088/0954-3899/28/10/313/meta>`__ upper limits on the signal yield
        for a gaussian peak over an exponential background are
        provided for the `asymptotic calculator <https://github.com/marinang/lauztat/blob/master/examples/notebooks/upper_limit_zfit_asy.ipynb>`__
        and the `frequentist calculator <https://github.com/marinang/lauztat/blob/master/examples/notebooks/upper_limit_zfit_freq.ipynb>`__
        and can be ran in `mybinder <https://mybinder.org/v2/gh/marinang/lauztat/master?filepath=examples%2Fnotebooks%2F>`__.
        
        Confidence interval:
        ====================
        
        if you do a measurement of a parameter α with an estimator ᾰ, given an observation
        ᾰ\ :sub:`obs` what value of α are not rejected at a certain confidence level (typically 68%)?
        
        - H\ :sub:`0`: α ≤ α \ :sub:`down` or α ≥ α\ :sub:`up`
        - H\ :sub:`1`: α\ :sub:`down` < α < α\ :sub:`up`
        
        α\ :sub:`down` and α\ :sub:`up` are adjusted such the test returns a p-value of 32%.
        
        Examples of confidence intervals on the mean of a gaussian peak are
        provided for the `asymptotic calculator <https://github.com/marinang/lauztat/blob/master/examples/notebooks/confidence_interval_zfit_asy.ipynb>`__
        and the `frequentist calculator <https://github.com/marinang/lauztat/blob/master/examples/notebooks/confidence_interval_zfit_freq.ipynb>`__
        (Feldman and Cousins confidence interval `[arxiv:9711021] <https://arxiv.org/abs/physics/9711021>`__)
        and can be ran in `mybinder <https://mybinder.org/v2/gh/marinang/lauztat/master?filepath=examples%2Fnotebooks%2F>`__.
        
Platform: Any
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Scientific/Engineering :: Physics
