root_poisson_stats
==================

Introduction
------------

This is a standalone version of ROOT TRolke and TFeldmanCousins.

It is simply C++, independent of ROOT.

It will be useful for gammalib and maybe also astropy.

Implementation
--------------

TFeldmanCousins and TRolke don't use a lot other ROOT functions.
The ones that are needed are in TMath, see the notes there for details.
I made a lot of trivial code changes like not deriving from TObject, not using TString or TOption,
and replacing Double_t -> double, Int_t -> int, TMath::Sqrt -> sqrt from cmath, ...

Re-writing this in Cython would be quite an effort, it's 3000 lines of complicated math code:
$ wc -l *.h *.cxx
     115 SpecFuncCephes.h
     114 TFeldmanCousins.h
      12 TMath.h
     193 TRolke.h
     982 SpecFuncCephes.cxx
     231 TFeldmanCousins.cxx
     331 TMath.cxx
    1448 TRolke.cxx
    3426 total

There's one special function which is not in the C / C++ math library: the incomplete gamma function.
Here I bundle the version from ROOT, which is the one from the Cephes library.
Note that this is not available in numpy, but scipy does include it, also the Cephes library version:
http://docs.scipy.org/doc/scipy/reference/generated/scipy.special.gammainc.html
scipy/scipy/special/generate_ufuncs.py:gammainc -- igam: dd->d -- cephes.h


Tests
-----

- The binaries Rolke and FeldmanCousins run the examples from the ROOT tutorial and print the same output.
Running diff on this output wrt. the ROOT tutorial is the first test that it basically works.

source /opt/local/bin/thisroot.sh

./Rolke > Rolke.txt
root -b -q /opt/local/share/root/tutorials/math/Rolke.C > Rolke_ROOT.txt
diff Rolke_ROOT.txt Rolke.txt

./FeldmanCousins > FeldmanCousins.txt
root -b -q /opt/local/share/root/tutorials/math/FeldmanCousins.C > FeldmanCousins_ROOT.txt
diff FeldmanCousins_ROOT.txt FeldmanCousins.txt

- Test against ROOT like this from Python
import ROOT
# You need to enter this once to make ROOT load it, otherwise it won't tab-complete!
ROOT.TFeldmanCousins
ROOT.TRolke
ROOT.Math
ROOT.TMath

TODO
----

- ROOT is GPL, astropy needs BSD.
  I'm not sure what license TFeldmanCousins and TRolke are, the TRolke 2.0 paper (http://inspirehep.net/record/826147) mentions MIT license, which would be OK.
  Ask if re-licensing possible?
  If this doesn't pan out, rewrite in Cython using description
  in the original papers and only cross-check against ROOT implementations.

- Change cout / cerr error messages to C++ / Python exceptions?

- create a Python wrapper using SWIG and / or Cython.

- Add unit tests

- Add benchmark

- Pull request for gammalib and astropy