search

ferella / polepp

Automatically exported from code.google.com/p/polepp
0 stars 0 forks source link

readme

This is a short version of a 'manual'. The intention is to include this in the doxygen documentation with somewhat more fancy layout.

The contents for now is:

I Installation II Tools III Input options, polelim IV Input options, polecov V Example, polelim VI Example, polecov VII Scripts VIII Known issues

I. INSTALLATION

  1. untar file. The files will be created in current directory.

tar -xzvf polelib.tgz

  1. compile

make

  1. to run the code, you need to make the library available. This can be done by copying libPole++.so to /usr/lib or similar (need to be root). Otherwise, you can add the current directory to the library path:

    setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:.

    or in bash:

    export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:.

    Now it should be possible to run polelim or polecov.

  2. To clean up:

make clean

II. TOOLS

  1. polelim: limit calculator
  2. polecov: coverage calculator
  3. poleconst: calculates only the likelihood ratio construction in (s_hyp,N) plane
  4. polebelt: calculates the confidence belt

To create these tools, do

make tools

III. INPUT OPTIONS, POLELIM

The tools polelim, poleconst and polebelt all have the same options. Their options are all defined in the file argsPole.cxx.

Running polelim with option --help yields:

USAGE:

./polelim [-l ] [-f ] [-V ] [--poisnx ] [--poisnm ] [--poismax ] [--poismin ] [--bkgintn ] [--bkgintscale ] [--effintn ] [--effintscale ] [--hstep ] [--hmax ] [--hmin ] [--threshprec ] [--threshbs ] [--nmus ] [--dmus ] [--corr ] [--bkgscale ] [--bkgdist ] [--bkgmeas ] [--bkgsigma ] [--effscale ] [--effdist ] [--effmeas ] [--effsigma ] [--minp ] [-K] [-m ] [--strue ] [--cl ] [--nobs

] [--] [-v] [-h] III.1 Minimum requirements -------------------------- Pole calculates the confidence interval of a given confidence level from the following information: * Number of observed events --nobs : default is 1 * Method -m or --method : 1 - FHC2 (default), 2 - MBT * Confidence level --cl : default is 0.90 * Efficiency --effmeas : measured mean --effdist : assumed distribution --effsigma : measured uncertainty * Background --bkgmeas : measured mean --bkgdist : assumed distribution --bkgsigma : measured uncertainty * Correlation coefficient between eff and bkg: --corr : is in the range of [-1,1] The distributions above are: 0 - none 1 - poisson 2 - gauss 3 - flat 4 - log normal 5 - 2d gauss, that is, use --corr; eff and bkg correlated ------------------------------------------------------------------ An alternative way of inputting data is by file. This is not yet well developed. See the function Pole::exeFromFile(). * Filename -f : data file name - see/modify Pole::exeFromFile() -l : number of lines to read from input file If -f is used --nobs, --eff/bkg{meas,dist,sigma} are ignored III.2 Precision related ----------------------- There are several other parameters to control the precision of integrals, limit scan etc. * Integral over aposteriori efficiency distribution: --effn : integrate between [ mean-scale*sigma, mean+scale*sigma ] where mean == --effmeas and sigma = --effsigma default = 5.0 * Ditto for background integration: --bkgn : see above --bkgscale : see above * Finding s_best - only used when method is FHC2 --dmus : step size in search, usually fine with 0.01 increase or reduce depending on requirements in precision or speed. --nmus : maximum number of steps - using the given step size, the number of steps is not allowed to be greater than nmus. default = 100 * Search threshholds --threshbs : minimum relative change in hypothesis in the binary search for the limit default = 0.0001 --threshalpha : minimum relative diff in alpha to required alpha = 1-cl default = 0.0001 The binary search stops whenever one of the above conditions are met. * Probability threshhold --minp : minimum probability p(n|H) considered when calculating the belt automatically set depending on the selected CL * Poisson table; for speed, the poisson table is tabulated for a range of N and mean values. This only makes sense if many points are to be caclulated. When reading the table, 2nd order derivative corrections are applied. --poisnx : maximum N default = 200 --poisnm : number of mean values default = 100000 --poismin : minimum mean default = 0.0 --poismax : maximum mean default = 100.0 NOTE: if large N or mean values are used, it might fail due to limited memory. -K : do not tabulate poisson - rarely needed but can be good to check that the poisson table is accurate enough III.3 Various options --------------------- -V or --verbose : verbose mode; mainly for debugging. Output may be confusing... -v or --version : print version -h or --help : print help III.4 Extras - NOT USED WHEN CALCULATING LIMITS ----------------------------------------------- * Confidence belt construct. Relevant when calculating the construct or belt (polebelt and poleconst tools). --hstep : hypothesis step size --hmin : minimum --hmax : maximum The following options are now obsolete: --strue IV. INPUT OPTIONS, POLECOV =========================== Running polecov --help gives: USAGE: ./polecov [--poisnx ] [--poisnm ] [--poismax ] [--poismin ] [--bkgn ] [--bscale ] [--effn ] [--effscale ] [--hstep ] [--hmax ] [--hmin ] [--threshalpha ] [--threshbs ] [--nmus ] [--dmus ] [--corr ] [--bkgstep ] [--bkgmax ] [--bkgmin ] [--bkgsigma ] [--bkgdist ] [--effstep ] [--effmax ] [--effmin ] [--effsigma ] [--effdist ] [--sstep ] [--smax ] [--smin ] [-P ] [-V ] [--dump ] [--minp ] [-S] [-C] [-K] [-m ] [--cl ] [--rseedofs ] [--rseed ] [--nloops ] [--] [-v] [-h] polecov calculates the coverage over a given range of parameters. It accepts largely the same arguments as for polelim. The specifics for polecov are described below. *The program can scan over: 1. true signal --smin : min signal --smax : max signal --sstep : step size 2. efficiency: --emin, --emax, --estep --effdist: distribution (not scanable...) 3. background --bmin, --bmax, --bstep, --bkgdist Number of loops --nloops : number of MC experiments (default = 1), usually 1000 is enough, increase the number for increased precision Random number generator --rseed : set the random number seed; if not set, a seed is set based on the time --rseedofs : seed offset (not really used) It is possible to fix the N(obs) in each experiment: -S or --fixsig Control the usage of tabulated poisson: -K or --notab : do not use the table Verbosity: -P or --verbpol : set verbosity level for the pole part -V or --verbcov : ditto for the coverage Statistics: --dump : dump file prefix -C, --stats : collect statistics - will take longer time since it will always calculate the full limits * The output For each point calculated a line is printed as follows: DATA: