The TUnfold package: user manual Stefan Schmitt, DESY
Contents
1. For the condition kRegModeCurvature the matrix L approximates second derivatives k j xj xi Similar to the case of kRegModeDerivative the corresponding matrix structure may get rather complicated in case of multi dimensional distributions and is most conveniently handled through the use of the classes TUnfoldDensity and TUnfoldBinning 3 2 Non standard regularisation schemes Sometimes it is useful to set up non standard regularisation schemes When using the class TUnfoldDensity with user defined binning schemes there is additional control over the regularisation scheme One may select modifications of the calculation of L such that the components of z are normalized to the corresponding bin widths prior to calculating the regularisation conditions Furthermore it is possible to take into account the bin widths for the calculation of the first or second derivatives One may also set specific normalisation factors or normalisation functions with the binning scheme and use those to modify the normalisation of z in the calculation of the regularisation For binning schemes based on trees with several branches it is possible to restrict the regularisation to one of the branches or to set up dedicated regularisation schemes for each of the branches method RegularizeDistribution For multi dimensional distributions it is possible to exclude underflow or overflow bins or to exclude derivatives calculated along specific axes fro2. In order to achieve this in the distributed TUnfold 17 1 package the classes ROOT TUnfold Supported TUnfold classes 5 21 and earlier Z 5 22 V6 TUnfold 5 23 5 25 V13 TUnfold TUnfoldSys 5 27 V15 TUnfold TUnfoldSys 5 28 5 36 V16 0 TUnfold TUnfoldSys not distributed V17 1 TUnfold TUnfoldSys TUnfoldDensity TUnfoldBinning Table 1 correspondence of distributed ROOT versions and TUnfold versions have been renamed the class TUnfold is named TUnfoldV17 the class TUnfoldSys is named TUnfoldSysV17 etc In the header files statements like define TUnfold TUnfoldV17 have been added such that the renamed classes are accessible under their usual name 1 2 TUnfold distribution The TUnfold package is available for download here 3 The package comes as a gzipped tar archive The archive should contain the files given in table 2 README COPYING tunfold_manual tex tunfold manual _figl eps tunfold_manual_fig2 eps Makefile altercodeversion sh TUnfold h TUnfoldSys h TUnfoldDensity h TUnfoldBinning h TUnfoldV17 cxx TUnfoldSysV17 cxx TUnfoldDensityV17 cxx TUnfoldBinningV17 cxx testUnfoldxXx C docu C notes on compiling licence file LaTex source of this manual Figure 1 of this manual Figure 2 of this manual default makefile for linux systems auxillary script header file providing the class TUnfoldV17 header file providing the class TUnfoldSysV17 header file providing the class TUnfoldDensi
3. is determined in a similar manner for example by deciding on the reconstructed channel and then using the appropriate recon structed quantities to calculate the bin number from the tree of reconstructed bins If the event was not reconstructed the special bin number trec 0 is used Finally the event weight wegen is filled in the corresponding bin of the two dimensional histogram of migrations Sometimes there is a secondary event weight Wree to account for detector efficiency corrections In order to account for this the event must be filled twice into the histogram of migrations First the histogram of migration is filled at the position igen trec using the weight Wgen X Wrec Next the histogram of migration is filled again this time at the position igen 0 using the event weight ween X 1 Wrec For data the procedure to determine the bin number is applied for the reconstructed quantities only and a one dimensional histogram is filled Setting up binning schemes with TUnfoldBinning is illustrated in the example macro testUnfold5b C How to use the binning scheme to fill histograms is illustrated in testUnfold5c C Unfolding and extracting distributions using the binning scheme is il lustrated in testUnfold5d C 3 Regularisation For unfolding regularisation conditions are imposed The regularisation is given by the scalar product 7Lz 7Lz where z is the difference of the unfolding result to a bias vector and L is a matri
4. AvgSys Z pisys average of squares of global correlation coefficients including sys tematic errors Table 4 Choices of the function Z for implemented with the method ScanTau parameters have to be set the number of points n the minimum and maximum value of T to scan and the mode table 4 If the minimum and maximum value of T agree the scan range is determined automatically In addition one may change the way the 8 correlation coefficients p are calculated The calculation may be restricted to one branch in the binning tree or may use all branches Within the distributions it is possible to exclude underflow and overflow bins or to integrate over bins The scan returns four curves the curve Z 7 and in addition the three curves also returned by ScanLcurve For a given interval in T n 1 points are inserted such that large 7 intervals are split into two Finally using the set of n 1 points the position of the minimum is determined and the unfolding is repeated at the position of the minimum The scan of correlation coefficients has the desired property that correlations in the result are minimized Ideally the correlation coefficients are small and can be neglected However this has to be checked carefully A drawback of the method is that it often fails In particular this method can not be used with the kRegModeSize regularisation condition For the regularisation methods kRegModeDerivative and
5. Here it is not possible to use the underflow and overflow bins for measurements Instead these bins are used to count events which originate from a specific truth bin but where the reconstructed quantity is not available An example is given in figure 2 2 4 Complex binning schemes The class TUnfoldBinning provides means to map bins originating from multi dimensional distributions on a single histogram axis and back The multi dimensional distributions are arranged in a tree structure For the truth parameters the branches of the tree structure could correspond to different decay channels signal and background etc Similarly for the reconstructed parameters the branches of the tree structure could correspond to different reconstructed channels and various control distributions So in general there are two binning trees a tree of truth bins and a tree of reconstructed bins When filling the histogram of migrations the proper bin numbers both in the tree of truth bins and in the tree of reconstructed bins have to be determined The bin number igen ON truth level is determined as follows first the appropriate branch is determined for example by deciding on the event type signal or background The method FindNode may be used to locate a branch in the tree using its name Next using the truth param eters the bin number igen is calculated using the method GetGlobalBinNumber The bin number trec in the tree of reconstructed bins
6. November 15 2012 The TUnfold package user manual Stefan Schmitt DESY NotkestraBe 85 22607 Hamburg Email Stefan Schmitt desy de Abstract TUnfold is a package with provides functionality for correcting migration and back ground effects for multi dimensional distributions This document gives a user oriented technical description of the package valid for the version number 17 1 1 Package overview The TUnfold package provides algorithms to correct measured distributions for migration effects The algorithm is based on least square fitting and Tikhonov regularisation it is described in 1 In this document details of the technical implementation and of the user interface are described It is assumed that the reader is familiar with the algorithm 1 The package is written in the C programming language It consists of the four classes TUnfold TUnfoldSys TUnfoldDensity and TUnfoldBinning The package is tied to the ROOT analysis framework 2 1 1 Root versions and TUnfold versions As of root version 5 22 some version of the TUnfold package is distributed together with the root software Table 1 summarizes the connection between TUnfold version and distributed root versions The most recent Root version 5 36 does not include the full functionality of TUnfold However it is possible to download the latest TUnfold version 17 1 and use it together with any ROOT relase even if it comes along with an older version of TUnfold
7. background source GetEmatrixInput error matrix from input errors Retreive unfolding error matrix only when using class TUnfold Method Description GetEmatrix deprecated get error matrix GetRhol deprecated get global corelations Table 3 basic methods required to use the unfolding package The table lists the name of the method and a short description ion binmap 0 binmap 1 1 g overflow not used Output histogram 5 oe overflow E bing gt 2 x bing a ee bin 5 w E i es Te E bine gt na E bind gt ieee bin 3 c 5 nr bin 2 bing gt 3 i bin 1 bine gt B a underflow c gt underflow not used Figure 1 For the classes TUnfold and TunfoldSys the bin map defines which bins of the unfolding result are stored in which histogram bin In the example 10 bins are mapped to 5 bins 2 Histograms and binning schemes ROOT histograns are used to exchange information between the TUnfold package and the user Internally the algorithm works with vectors to store the bins of the input and output distributions 2 1 Use of bin maps with class TUnfold and TUnfoldSys When importing data into the classes TUnfold or TunfoldSys only the bin contents and bin errors of the histograms are relevant The bin edges are not used When extracting data into an existing histogram the bin
8. kRegModeCurvature the method is expected to work more reliably References 1 S Schmitt JINST 7 2012 T10003 arXiv 1205 6201 physics data an 2 R Brun and F Rademakers Nucl Instrum Meth A 389 1997 81 3 S Schmitt TUnfold version 17 1 http www desy de sschmitt tunfold html
9. m the regularisation Ultimatelty it is also possible to define arbitrary regularisation conditions by adding single rows to the matrix L method AddRegularisationCondition 4 Determination of T One of the frequent questions related to the regularized unfolding method implemented in the TUnfold package is the choice of the regularisation parameter 7 If 7 is too small there is no regularisation If 7 is too large the unfolding result is biased strongly by the regularisation condition In the TUnfold package two basic methods to determine the regularisation have been implemented the L curve scan and the minimisation of correlations 4 1 L curve scan The L Curve scan is available with the classes TUnfold TUnfoldSys and TUnfoldDensity The method is named ScanLcurve It works as follows the unfolding is repeated for a number of points with different 7 for example n 30 A parametric curve of two variables X 7 and Y r is calculated The exact definition of these variables is given in 1 The optimal chioce of 7 is determined as the position having the largest curvature kink in the X Y plane For scanning the L curve the following parameters may be set number of points np minimum Tmin and maximum Tmax value of 7 to scan If Tmin Tmax the interval is chosen automatically When runnung the scan the following three curves are produced X 7 Y T and Y X The scan proceeds as follows Given a 7 interval to scan fir
10. ning of that histogram is not checked It is up to the user to book a histogram with the proper binning It is then possible to change the mapping of the vector components to histogram bins The mapping function is stored as an array of integer numbers and is denoted bin map Each element of the bin map corresponds to one of the bins in the unfolding result The value stored in the bin map indicates the destination histogram bin in which the result shall be stored It is possible to add up several bins of the unfolding result simply by using the same destination bin number for different elements of the bin map The concept of the bin map is illustrated in figure 1 2 2 Binning schemes and TUnfoldDensity For the class TUnfoldDensity the bins are structured in a binning scheme using the class TUnfoldBinning For one dimensional unfolding problems the binning schemes are 4 underflow overflow region of 2D histogram overflow visible part 0 5 lt X gex0 7 of 2D histogram 0 4 lt x gers 0 5 0 3 lt x ger 0 4 0 2 lt x gers 0 3 0 1 lt x gent 0 2 underflow 0 5 lt x rec lt 0 6 0 6 lt x rec lt 0 7 0 7 lt x rec lt 0 8 not reconstructed O5 lt X jec lt 0 1 not reconstructed Figure 2 The matrix of migrations in the case of one dimensional unfolding is illustrated The truth parameter Zgen has five non equidistant bins ranging from 0 1 to 0 7 plus underflow and overflow bins seven bi
11. ns in total The reconstructed parameter Zyec has twelve bins ranging from 0 05 to 0 8 The underflow and overflow bins in e are used to count the non reconstructed events constructed directly from the matrix of migrations The user does not have to deal with the class TUnfoldBinning For more complex problems involving multi dimensional dis tributions multiple channels or unfolding of background normalisation factors the corre sponding binning schemes have to be defined by the user The binning scheme information is used when setting up the regularisation scheme In addition it is used to create his tograms having proper bin widths when extracting data from the class TUnfoldDensity Furthermore the binning scheme provides functionality to find the proper bin numbers when filling the histogram of migrations or the histogram of measurements 2 3 Unfolding one dimensional distributions in TUnfoldDensity When unfolding one dimensional distributions it is most convenient to book and fill the histogram of migrations using the bins as required for the analysis There is no need to define binning schemes The matrix of migrations is stored as a two dimensional histogram where on one axis the truth bins are arranged It is possible to have underflow and overflow bins for the truth parameters If these are present their content is also unfolded from the data On the other axis there is the reconstructed quantity again with the appropoiate bins
12. st the unfolding is per formed for T Tmin and T Tmax Intermediate points are then inserted such that a most uniform population along the curve X T Y r is achieved Given two or more points X Y ordered in the corresponding 7 a new point is inserted into the interval which has the largest size S Xi Xi Yiri Yi until np 1 points have been calculated The last point of the scan is inserted at the best choice of tau determined from the set of n 1 points 4 2 Minimisation of correlation coefficients or other quantities With the class TUnfoldDensity another method of determining 7 is implemented The method ScanTau repeats the unfolding np times for different choices of r During that scan the minimum of a function Z 7T is determined The possible choices of the function Z are summarized in table 4 They all depend on the calculation of global correlation coefficients p which is described in 1 When using the method ScanTau the following Mode definition of Z kEScanTauRhoAvg ZL ae gt pi average global correlation kEScanTauRhoMax Z max pi maximum global correlation kEScanTauRhoAvgSys A gt Pisys average global correlation including systematic errors kEScanTauRhoMaxSys Z Max Pi sys maximum global correlation including systematic errors kEScanTauRhoSquareAvg Z a S2 pi average of squares of global correlation coefficients kEScanTauRhoSquare
13. tyV17 header file providing the class TUnfoldBinningV17 implementation of the class TUnfoldV17 implementation of the class TUnfoldSysV17 implementation of the class TUnfoldDensityV17 implementation of the class TUnfoldBinningV17 example macros where XX 1 2 3 4 5a 5b 5c 5d small program to test the documentation generated by ROOT Table 2 files distributed with the TUnfold package version 17 1 1 3 Makefile For many unix systems the Makefile provided with this distribution is suitable for com piling the examples and the library Note however compilation only has been tested on selected systems In general modifications to the Makefile may be needed in order to compile the TUnfold package The main commands from the Makefile are make lib creates a shared library libtunfold so make bin creates wrapper code to call the example macros and compiles them as stand alone executables For example the file testunfold1 C is created and compiled as executable testunfoldt For using the TUnfold package it is probably best to work through the example given by the four macros testUnfold5a C testUnfold5b C testUnfold5c C and testUnfold5d C 1 4 Class overview The four classes distributed with TUnfold are described briefly in the following For most applications the proper class to use is TUnfoldDensity and possibly also the class TUnfoldBinning to set up the analysis bins class TUnfold provides the core unfolding algorithm matri
14. x describing the regularisation scheme The parameter T gives the strength of the regularisation The number of columns of L is identical to the number of unfolded bins The number of rows reflects the number of regularisation conditions it may be different from the number of columns 3 1 Basic regularisation types Three basic types of regularisation are supported kRegModeSize kRegModeDerivative kRegModeCurvature The type of regularisation may be specified with the constructor of 6 either of the classes TUnfold TUnfoldSys TUnfoldDensity as the third argument In that case the given basic regularisation is applied to all bins The simplest regularisation condition is given by kRegModeSize corresponding to the case where L is the unity matrix The matrix L is diagonal and does not mix different bins The regularisation is given by 7 gt 22 For the condition kRegModeDerivative the matrix L calculates differences x 2 thus approximating first derivatives In that case the structure of the input bins matters because differences should be calculated between adjacent bins only For one dimensional distributions this done by simply setting 7 i 1 For two dimensional distributions derivatives may be defined along both dimensions and the relation is getting more com plicated When using the classes TUnfoldDensity and TUnfoldBinning the relation of the bins is known and appropriate regularisation schemes are defined automatically
15. x operations and methods to import from histograms or to export to histograms class TUnfoldSys adds functionality to the class TUnfold to treat background and systematic uncertainties class TUnfoldDensity adds functionality to the class TUnfoldSys to properly take into account bin widths and multi dimensional distributions class TUnfoldBinning is used to tell the class TUnfoldDensity how the bins in complex binning schemes are arranged Table 3 gives a summary of the most important methods available with the TUnfold package Run the unfolding Method Description constructor define matrix of migrations and basic regu larisation scheme SetInput define measurement AddSysError set a systematic uncertianty SubtractBackground set a background source DoUnfold unfold once with fixed tau ScanLcurve scan L curve unfold multiple times and de termine tau ScanTau scan correlations unfold multiple times and determine tau Retreive unfolding results Method Description GetOutput unfolding result GetEmatrixTotal total error matrix GetRhoItotal total global corelations GetDeltaSysSource systematic shifts from one systematic error GetDeltaSysBackgroundScale systematic shifts from one background scale error GetEmatrixSysUncorr error matrix from uncorrelated uncertainty on migration matrix GetEmatrixSysBackgroundUncorr error matrix from uncorrelated uncertainty on one
Download Pdf Manuals
Related Search