The RooUnfold package is now documented and maintained on GitLab.
Please refer to https://gitlab.cern.ch/RooUnfold/RooUnfold and update your bookmarks.

This web page refers to old versions of the software and is kept for archival interest only.

[RooUnfold introduction] [Download] [Method] [Use] [Regularisation] [Building] [Running] [Examples] [Class docs] [Limitations] [Authors] [Development] [References] [History]

RooUnfold: ROOT Unfolding Framework

RooUnfold is a framework for unfolding (AKA "deconvolution" or "unsmearing"). It currently implements five methods:

iterative ("Bayesian"; as proposed by D'Agostini);
singular value decomposition (SVD; as proposed by Höcker and Kartvelishvili and implemented in TSVDUnfold);
bin-by-bin (simple correction factors);
an interface to the TUnfold method developed by Stefan Schmitt; and
simple inversion of the response matrix without regularisation.

RooUnfold was written by Tim Adye, Richard Claridge, Kerstin Tackmann, and Fergus Wilson. It can be used from the ROOT prompt, or linked against the ROOT libraries. It requires ROOT 4 or later.

Please let me know if you use this software. This will further encourage me to continue working on it, and I will let you know about any future updates.

See this overview of RooUnfold or the references below for more information. To cite the RooUnfold package in a publication, you can refer to this web page and/or the paper:
Tim Adye, in Proceedings of the PHYSTAT 2011 Workshop on Statistical Issues Related to Discovery Claims in Search Experiments and Unfolding, CERN, Geneva, Switzerland, 17–20 January 2011, edited by H.B. Prosper and L. Lyons, CERN–2011–006, pp. 313–318.

Unfolding Method

We use unfolding to remove the known effects of measurement resolutions, systematic biases, and detection efficiency to determine the "true" distribution. We parametrise the measurement effects using a response matrix that maps the (binned) true distribution onto the measured one. For 1-dimensional true and measured distribution bins T_j and M_i, the response matrix element R_ij gives the fraction of events from bin T_j that end up measured in bin M_i. The response matrix is usually determined using Monte Carlo simulation (training), with the true values coming from the generator output.

The unfolding procedure reconstructs the true T_j distribution from the measured M_i distribution, taking into account the measurement uncertainties due to statistical fluctuations in the finite measured sample (without these uncertainties, the problem could be solved uniquely by inverting the response matrix). RooUnfold provides several algorithms for solving this problem.

The iterative and SVD unfolding algorithms require a regularisation parameter to prevent the statistical fluctuations being interpreted as structure in the true distribution. It is therefore necessary to optimise this parameter for the number of bins and sample size, using Monte Carlo samples of the same size as the data. These samples can also be used to measure the effectiveness of the unfolding and hence provide estimates of the systematic errors that result from the procedure (testing).

Note that for this last step (in particular), it is important to use Monte Carlo samples with truth distributions that are statistically and systematically independent of the sample used in training (such samples would anyway be used in a systematics analysis, eg. using a different generator, or reweighting variations within the a-priori uncertainties in the truth distribution). After all, if the Monte Carlo were a perfect model of the data, we could use the Monte Carlo truth information directly and dispense with unfolding altogether!

The bin-by-bin method assumes no migration of events between bins (eg. resolution is much smaller than the bin size and no systematic shifts). This is of course trivial to implement without resorting to the RooUnfold machinery, but is included in the package to allow simple comparison with the other methods.

Using RooUnfold

To use RooUnfold, we must first supply the response matrix object RooUnfoldResponse. It can be constructed like this:

RooUnfoldResponse response (nbins, x_lo, x_hi);

or, if different truth and measured binning is required,

RooUnfoldResponse response (nbins_measured, x_lo_measured, x_hi_measured,
                            nbins_true,     x_lo_true,     x_hi_true);

or, if different binning is required,

RooUnfoldResponse response (hist_measured, hist_truth);

In that last case, hist_measured and hist_truth are used to specify the dimensions of the distributions (the histogram contents are not used here), eg. for 2D or 3D distributions or non-uniform binning.

This RooUnfoldResponse object is often most easily filled by looping over the training sample and calling response.Fill(x_measured,x_true) or, for events that were not measured due to detection inefficiency, response.Miss(x_true)

if (measurement_ok)
  response.Fill (x_measured, x_true);
else
  response.Miss (x_true);

Alternatively, the response matrix can be constructed from a pre-existing TH2D 2-dimensional histogram (with truth and measured distribution TH1D histograms for normalisation).

This response object can be passed directly to the unfolding object, or written to a ROOT file for use at a later stage (search for examples/RooUnfoldTest.cxx's stage parameter for an example of how to do this).

To do the unfolding (either to try different regularisation parameters, for testing, or for real data), create a RooUnfold object and pass it the test / measured distribution (as a histogram) and the response object.

RooUnfoldBayes    unfold (&response, hist_measured, iterations);

RooUnfoldSvd      unfold (&response, hist_measured, kterm);

RooUnfoldBinByBin unfold (&response, hist_measured);

hist_measured is a pointer to a TH1D (or TH2D for the 2D case) histogram of the measured distribution (it should have the same binning as the response matrix). The classes RooUnfoldBayes, RooUnfoldSvd, and RooUnfoldBinByBin all inherit from RooUnfold and implement the different algorithms. The integer iterations (for RooUnfoldBayes) or kterm (RooUnfoldSvd) is the regularisation parameter. (Note that RooUnfoldSvd's kterm parameter is also known as tau in the code. That usage is incompatible with the literature, so we adopt k here.)

The reconstructed truth distribution (with errors) can be obtained with the Hreco() method.

TH1D* hist_reco= (TH1D*) unfold.Hreco();

The result can also be obtained as as a TVectorD with full TMatrixD covariance matrix.

Multi-dimensional distributions can also be unfolded, though this does not work for the SVD method, and the interface is rather clumsy (we hope to improve this).

See the class documentation for details of the RooUnfold and RooUnfoldResponse public methods.

A very simple example of RooUnfold's use is given in examples/RooUnfoldExample.cxx. More complete tests, using different toy MC distributions, are in examples/RooUnfoldTest.cxx and examples/RooUnfoldTest2D.cxx.

Choice of Regularisation Parameter

The regularisation parameter determines the relative weight placed on the data, compared to the training sample truth. Both RooUnfoldBayes and RooUnfoldSvd take integer regularisation parameters, with small values favouring the MC truth and larger values favouring the data.

RooUnfoldBayes Regularisation

For RooUnfoldBayes, the regularisation parameter specifies the number of iterations, starting with the training sample truth (iterations=0). You should choose a small integer greater than 0 (we use 4 in the examples). Since only a few iterations are needed, a reasonable performance can usually be obtained without fine-tuning the parameter.

The optimal regularisation parameter can be selected by finding the largest value up to which the errors remain reasonable (ie. do not become much larger than previous values). This will give the smallest systematic errors (reconstructed distribution least biased by the training truth), without too-large statistical errors. Since the statistical errors grow quite rapidly beyond this point, but the systematic bias changes quite slowly below it, it can be prudent to reduce the regularisation parameter a little below this optimal point.

RooUnfoldSvd Regularisation

For RooUnfoldSvd, the unfolding is something like a Fourier expansion in "result to be obtained" vs "MC truth input". Low frequencies are assumed to be systematic differences between the training MC and the data, which should be retained in the output. High frequencies are assumed to arise from statistical fluctuations in data and unfortunately get numerically enhanced without proper regularization. Choosing the regularization parameter, k (kterm), effectively determines up to which frequencies the terms in the expansion are kept. (Actually, this is not quite true, we don't use a hard cut-off but a smooth one.)

The correct choice of k is of particular importance for the SVD method. A too-small value will bias the unfolding result towards the MC truth input, a too-large value will give a result that is dominated by unphysically enhanced statistical fluctuations. This needs to be tuned for any given distribution, number of bins, and approximate sample size — with k between 2 and the number of bins. (Using k=1 means you get only the training truth input as result without any corrections. You basically regularise away any differences, and only keep the leading term which is, by construction, the MC truth input.)

Höcker and Kartvelishvili's paper (section 7) describes how to choose the optimum value for k.

Building the Library

Make sure that ROOT is set up correctly: the $ROOTSYS environment variable should point to the top-level ROOT directory, $ROOTSYS/bin should be in your $PATH, and $ROOTSYS/lib should be in your library path ($LD_LIBRARY_PATH on most Unix systems). In recent versions of ROOT (from 5.18), this can be most easily achieved using ROOT's thisroot.(c)sh setup script. Eg. to use the CERN AFS version 5.28/00a on Scientific Linux 4/5 (x32) from a Bourne-type shell:

shell> . /afs/cern.ch/sw/lcg/app/releases/ROOT/5.28.00a/slc4_ia32_gcc34/root/bin/thisroot.sh

For further details, consult the ROOT "Getting Started" documentation, or your local system administrator.

Download RooUnfold-1.1.1.tar.gz (or other versions here) and unpack

shell> tar zxf RooUnfold-1.1.1.tar.gz
shell> cd RooUnfold-1.1.1

Use GNU make. Just type

shell> make

to build the RooUnfold shared library.

Loading RooUnfold

The RooUnfold library can be used from the ROOT prompt, from a CINT script run from ROOT, from code compiled in ROOT (ACLiC), or linked into a stand-alone program.

If using ROOT (CINT or ACLiC), the library can be loaded automatically when a RooUnfold class is first used. This only works if your current directory is the RooUnfold top-level directory (containing libRooUnfold.so) or that directory has been added to your dynamic path. Otherwise, you can load the library with gSystem->Load(), eg.

root [0] gSystem->Load("/home/RooUnfold-1.1.1/libRooUnfold");
root [1] RooUnfoldResponse response(10,-1,1);

To use ACLiC, you also need to add the RooUnfold headers to the include path. This can be done with .include src from the ROOT command prompt, eg.

root [0] .include src
root [1] .x MyCode.cxx+

To build stand-alone, you need to specify the RooUnfold headers in the src subdirectory and specify the -lRooUnfold library. Alternatively, you can use make (with RooUnfold's GNUmakefile) to compile and link your own code, eg. make MyProgram will compile MyProgram.cxx and link with RooUnfold.

Running the Examples

examples/RooUnfoldExample.cxx makes a simple test of RooUnfold.

shell> root
root [0] .x examples/RooUnfoldExample.cxx

More involved tests, allowing different toy MC PDFs to be used for training and testing, can be found in examples/RooUnfoldTest.cxx (which uses test class RooUnfoldTestHarness). To run RooUnfoldTest from within ROOT:

root [1] .x examples/RooUnfoldTest.cxx

The example programs can also be run from the shell command line.

shell> make bin
shell> ./RooUnfoldTest

and the output appears in RooUnfoldTest.ps.

You can specify parameters for RooUnfoldTest (either as an argument to the routine, or as parameters to the program), eg.

root [2] RooUnfoldTest("method=2 ftestx=3")

shell> ./RooUnfoldTest method=2 ftestx=3

Use RooUnfoldTest -h or RooUnfoldTest("-h")to list all the parameters and their defaults.

method specifies the unfolding algorithm to use:

0   no unfolding (output copied from measured input)

1   Bayes

2   SVD

3   bin-by-bin

4   TUnfold

5   matrix inversion

ftrainx and ftestx specify training and test PDFs:

0   flat distribution
1   top-hat distribution over mean ± 3 x width

2   Gaussian

3   Double-sided exponential decay

4   Breit-Wigner

5   Double Breit-Wigner, peaking at mean-width and mean+width
6   exponential
7   Gaussian resonance on an exponential background

The centre and width scale of these signal PDFs can be specified with the mtrainx and wtrainx (and mtestx and wtestx) parameters respectively. A flat background of fraction btrainx (and btestx) is added. Detector effects are modelled with a variable shift (xbias in the centre, dropping to 0 near the edges), a smearing of xsmear bins, as well as a variable efficiency (between effxlo at xlo and effxhi at xhi).

For 2D and 3D examples look at RooUnfoldTest2D and RooUnfoldTest3D.

Testing without RooFit

The test programs, examples/RooUnfoldTest.cxx, examples/RooUnfoldTest2D.cxx, and examples/RooUnfoldTest3D.cxx use RooFit to generate the toy distributions. (RooFit is not required to use the RooUnfold classes from another program, eg. examples/RooUnfoldExample.cxx). Hand-coded alternatives are provided if ROOT was not build with RooFit enabled (eg. --enable-roofit not specified). This version generates peaked signal events over their full range, so may have a fewer events within the range than requested.

To disable the use of RooFit, #define NOROOFIT before loading RooUnfoldTest*.cxx

root [0] #define NOROOFIT 1
root [1] .x examples/RooUnfoldTest.cxx

For the stand-alone case, use

shell> make bin NOROOFIT=1

to build (this is the default if RooFit is not available).

Limitations

RooUnfoldSvd does not work correctly for multi-dimensional distributions (gives a warning).
Using the histogram under/overflow bins (UseOverflow() setting) only works for 1D histograms.

Authors

The principal RooUnfold developer and contact is Tim Adye (RAL, T.J.Adye@rl.ac.uk).

The TUnfold interface, matrix inversion, and bin-by-bin algorithms as well as the error and parameter analysis frameworks were written by Richard Claridge (RAL).

The SVD algorithm was written by Kerstin Tackmann (LBNL) for the unfolding of the hadronic mass spectrum in B→X_ulν.

An initial implementation of the iterative Bayesian algorithm was written by Fergus Wilson (RAL).

Further Development

RooUnfold is now (July 2010) being developed as part of the Unfolding Framework Project.

The latest development version of RooUnfold is maintained in the project's Subversion code repository, and can be viewed here (WebSVN, or viewvc). It can be checked out using:

shell> svn co https://svnsrv.desy.de/public/unfolding/RooUnfold/trunk RooUnfold

References

To cite the RooUnfold package in a publication, you can refer to this web page and/or the paper:
Tim Adye, in Proceedings of the PHYSTAT 2011 Workshop on Statistical Issues Related to Discovery Claims in Search Experiments and Unfolding, CERN, Geneva, Switzerland, 17–20 January 2011, edited by H.B. Prosper and L. Lyons, CERN–2011–006, pp. 313–318.

Overview

T. Adye, RooUnfold: unfolding framework and algorithms, presentations to the Oxford and RAL ATLAS Groups, May 2008. This includes a brief introduction to unfolding but the description of RooUnfold is now dated (see below for a more recent description).
G. Cowan, A Survey of Unfolding Methods for Particle Physics, Proc. Advanced Statistical Techniques in Particle Physics, Durham (2002).
G. Cowan, Statistical Data Analysis, Oxford University Press (1998), Chapter 11: Unfolding
R. Barlow, SLUO Lectures on Numerical Methods in HEP (2000), Lecture 9: Unfolding

Techniques

T. Adye, Unfolding algorithms and tests using RooUnfold, write-up of a presentatation at the PHYSTAT 2011 workshop on unfolding and deconvolution, CERN (January 2011).
Previously presented at the Alliance Workshop on Unfolding and Data Correction, DESY (May 2010).
A. Höcker and V. Kartvelishvili, SVD Approach to Data Unfolding, NIM A 372 (1996) 469.
BaBar Collaboration, B. Aubert et al., Study of b→ulν Decays on the Recoil of Fully Reconstructed B Mesons and Determination of |V_ub|, hep-ex/0408068, contribution to the 32nd International Conference on High Energy Physics (ICHEP'04, Beijing 2004).
G. D'Agostini, A multidimensional unfolding method based on Bayes theorem, NIM A 362 (1995) 487.
1. V. Blobel, Unfolding Methods in High Energy Physics Experiments, DESY 84-118 (1984) and Proc. 8th CERN School of Computing (Aiguablava, Spain, 1984), CERN 85-09.
2. V. Blobel, An unfolding method for high energy physics experiments, Proc. Advanced Statistical Techniques in Particle Physics, Durham (2002).
Alliance Workshop on Unfolding and Data Correction, DESY (May 2010).
PHYSTAT 2011 workshop on unfolding and deconvolution, CERN (January 2011).

History

See the History file for details of changes to the code. A summary of changes to the code and this web page are:–

11 October 2012: Add formal citation to PHYSTAT 2011 paper.

17 November 2011: Add Loading RooUnfold section to detail how to load the RooUnfold libraries.

10 October 2011: update to version 1.1.1:

Allow RooUnfoldResponse(measured,truth,response) constructor and Setup method to take 0 or empty histogram for measured and/or truth in the case where there are no fakes and/or inefficiencies. With 0, a 1D histogram is assumed.
Calculated histogram of fakes now includes truth under/overflows from user's response matrix histogram. Errors are also calculated, even though these are not used at present.
Fix uninitialsed pointer in RooUnfoldResponse::Vfakes. This fixes a crash reported by Katharina Bierwagen.
Add warning if the number of measured bins doesn't match the response matrix.

30 September 2011: update to version 1.1.0:

All error calculations, except RooUnfoldTUnfold with error propagation, use the full measurement covariance matrix if specified. RooUnfold::SetMeasured can also be passed vectors for measured distribution and errors, or a matrix for the covariance matrix. SetMeasuredCov just sets the covariance matrix. GetMeasuredCov retrieves it.
RooUnfoldTest can include test measurement bin-bin correlations, eg. bincorr=-0.5 gives an anti-correlation of 0.5 between neighbouring bins, a correlation of 0.25 between next-to-neighbours, etc. This input correlation matrix is also plotted for comparison with the unfolded output correlation matrix.
RooUnfoldResponse can now account for fakes (or background, ie. measured entries with no truth). Use Fake(xmeas) to fill, or else add fakes to measured input histogram.
This can be tested with, eg. RooUnfoldTest fakexlo=0.1 fakexhi=0.2 (and similarly for y and z for 2D/3D) for linearly varying background level between 0.1 at xlo and 0.2 at xhi as a fraction of the number of measured events.
Rewrote RooUnfoldBayes to perform the unfolding itself instead of using old classes RooUnfoldBayesImpl and Array2D, which have now been removed from the package. New RooUnfoldBayes::UnfoldingMatrix accessor.
Improved RooUnfoldBayes error calculation to take account of dependence of the unfolding matrix (M_ij) on the input measurements via previous iterations which update the prior (see this note for details). The new errors now agree with the toy MC — previously they were significantly underestimated. In addition, the input measurement errors are now taken from those specified by the user (eg. with SetMeasuredCov or in the histogram errors) instead of assumed multinomial errors based on the number of measured events in each bin (as given by D'Agostini). If the user didn't specify any errors, then ROOT's default assumption of √N is used for each bin, which is similar to (and perhaps more appropriate than) a multinomial distribution if there are more than a few bins.
Allow RooUnfoldSVD to have different numbers of truth and measured bins. This is done by calling TSVDUnfold with a symmetric matrices with zeroes in the extra bins.
The Makefile creates libRooUnfold.rootmap, which can be used to load RooUnfold in PyROOT. Added examples/RooUnfoldExample.py, equivalent to RooUnfoldExample.cxx. If ROOT was built with PyROOT support and the correct version of Python is used, examples/RooUnfoldExample.py can be executed as-is.
Added "make help" target.
RooUnfold::RunToy() returns new RooUnfold object. RunToy() replaces old Runtoy() method, which returned a histogram. This also fixes a memory leak reported by Seth Zenz.
Add I/O streamers for RooUnfold and its subclasses.
Fix MacOSX shared library creation in GNUMakefile.
Fix problem with different versions of TSVDUnfold that caused a crash in ROOT 5.30.
Correct PDF normalisation due to change in RooFit with ROOT 5.29.02 (bug #83534) for RooUnfoldTest.
Fix RooUnfold::New when name but no title is specified.
Fix RooUnfold::PrintTable for when truth histogram isn't specified.
RooUnfoldTest now writes histograms and unfold object to RooUnfoldTest.root (previously just response object was written there).
RooUnfoldTest ploterrors=1 no longer calculates χ² distribution. This allows the comparison of the errors to be run alone, which can be very much faster. Use ploterrors=2 to include the χ² plot.
RooUnfoldTest plots the unfolded correlation matrix. The full error matrix is printed if verbose=2.
RooUnfoldTest scales the measured histogram to match the truth if the number of bins is different.

6 May 2011: reference RooUnfold write-up from PHYSTAT 2011.

9 February 2011: reference the PHYSTAT 2011 workshop on unfolding and deconvolution.

14 January 2011: update to version 1.0.3:

RooUnfoldSvd now uses TSVDUnfold, which was renamed from RooUnfHistoSvd. TSVDUnfold is included in ROOT 2.28 and later, but RooUnfold has a copy which is used with older versions of ROOT.
New RooUnfoldDagostini class. This is an interface to D'Agostini's bayes.for for comparison with our RooUnfoldBayes (they implement the same algorithm). RooUnfoldDagostini is not normally compiled, but will be if bayes.for and bayes_c.for (download) are copied into the src directory.
New RooUnfoldResponse::Add method, suggested by Seth Zenz.
Fixes for building and running on different platforms: MacOS X, non-standard RooFit installation, and ROOT versions 5.12 and before.
Input histograms can be any TH1, eg. TH1F and TH2F, not just TH1D, TH2D etc.
Make sure we don't continue/crash if the unfolding fails.
Fix RooUnfoldTUnfold under/overflow bin handling.
Reformat inline methods so they appear correctly in the ROOT class documentation. Add some missing method documentation comments.
Improve RooUnfoldTest generator and bias model.

13 September 2010: update to version 1.0.2:

Provide different methods for computing the errors on the unfolded result. These are selected with a new RooUnfold::ErrorTreatment enum: no error treatment (RooUnfold::kNoError), use bin-by-bin errors (RooUnfold::kErrors) or full covariance matrix (RooUnfold::kCovariance) propagated through the unfolding, or covariance matrix from the variation of the results in toy MC tests (RooUnfold::kCovToy). This last method should be more accurate, especially for RooUnfoldBayes.
Added new unfolding algorithm classes: RooUnfoldTUnfold is a simple (though not yet fully-featured) interface to ROOT's TUnfold class (requires ROOT 5.22 and above). RooUnfoldInvert performs a simple inversion of the response matrix.
Simplify RooUnfoldBinByBin code (no longer uses RooUnfoldBayesImpl).
RooUnfold can now include the histogram underflow and overflow bins in the unfolding. This is enabled by calling RooUnfoldResponse::UseOverflow(). This currently only works for 1D histograms.
Named static constructor, RooUnfold::New(), creates unfolding object based on the RooUnfold::Algorithm enum (RooUnfold::kNone, RooUnfold::kBayes, RooUnfold::kSVD, RooUnfold::kBinByBin, RooUnfold::kTUnfold, or RooUnfold::kInvert).
New Clone() method for RooUnfold and its subclasses.
New RooUnfold public methods: Chi2(hTrue) calculates the χ² of the unfolded results with respect to a true distribution, Vmeasured() and Emeasured() return the measured distribution and its errors as vectors, ErecoV() returns unfolding errors as a vector, SetResponse() and SetMeasured() allow the unfolding inputs to be changed separately, SetRegParm() and GetRegParm() provide a common method to access the regularisation parameter, and SetNToys() and NToys() access the number of MC tests used in error calculation with the RooUnfold::kCovToy setting.
Impl() methods return the unfolding implementation object for some algorithms.
Added ROOT documentation comments to RooUnfold, RooUnfoldErrors, and RooUnfoldParms.
RooUnfold::PrintTable() shows also the error, residual, and pull for each bin.
New RooUnfoldTest options: wpaper and hpaper (plot paper width and height), draw=0 (disables histogram drawing), ploterrors=1 (error analysis using RooUnfoldErrors), and plotparms=1 (regularisation parameter analysis using RooUnfoldParms), overflow (1=unfolding uses overflows, 2=show under/overflow bins on test histograms).
RooUnfoldTest bias model changed to reduce to zero at the edges of the histogram.
RooUnfoldTest2D shows projections of 2D pulls.

30 July 2010: use thisroot.sh in ROOT setup example. Update RooUnfoldTest help files.

3 June 2010: reference the Alliance Workshop on Unfolding and Data Correction.

20 May 2010: update to version 0.2.2:

Fix RooUnfoldBayes for when the measured and truth distributions have different numbers of bins. (Problem reported by Lluis Marti.)
Fix RooUnfoldSvd to fill kterm and ntoys correctly (broken in 0.2.1).
New accessor methods for unfolding parameters and implementation object.
Can control the verbosity of messages with RooUnfold::SetVerbose(level): 0=warnings, 1=verbose (default, as before), 2=debug, 3=detailed.

19 May 2010: update to version 0.2.1:

Reorganise RooUnfold classes so as not to have hidden virtual methods (Setup and Clear) and to perform unfolding on demand, rather than on construction.
Various RooUnfoldTest changes to work round problems in different ROOT versions (especially with CINT).
RooUnfoldTest (and 2D, 3D) can now be run from the ROOT prompt with ACLiC (as an alternative to CINT), though this requires a bit more setup:
```
root [0] gSystem->Load("libRooUnfold")
root [1] .include src
root [2] .L examples/RooUnfoldTest.cxx+
root [3] RooUnfoldTest()
```

22nd January 2010: update to version 0.2.0:

RooUnfoldBayesImpl::train should use data input rather than MC input for n(E_j). This is _nEstj[] rather _nEj[]. The upshot of this bug was that only the final iteration of the Bayesian unfolding had any effect on the result (though a single iteration still goes some way!). Problem reported by Jan Kapitan.
That change entailed a small reorganisation of RooUnfoldBayesImpl. Client no longer uses train() or trainBinByBin() directly. This is now done in unfold() or unfoldBinByBin() (which specify the unfolding algorithm parameters, iterations and smoothit), since the training now requires the unfolding input. Of course users of RooUnfoldBayes and RooUnfoldBinByBin won't see any difference, since they wrap RooUnfoldBayesImpl.
Protect against division by zero error in RooUnfoldBayesImpl::train.
RooUnfoldBayesImpl::train should normalise _nCi to 1 for the initial P₀(C) rather than N_obs.
RooUnfoldBayes: fix if there are fewer measured than truth bins.
RooUnfoldBayesImpl::getCovariance option doUnfoldSystematic to enable systematic calculation. It remains disabled by default: I'm not sure it is correct, it is very slow, and the effect should be small with good MC statistics.
RooUnfoldSvd may not work very well for multi-dimensional distributions, so print warning if it's tried.
RooUnfold::PrintTable improvements: Don't show residuals and pulls for "empty" bins (both content=0 and error=0) and don't include them in the χ². Fix bin numbering (no under/overflow, which aren't included in the unfolding) and show 2D/3D bin numbers. Also fixed for different number of measured and truth bins. Print test truth (hTrue), which is now optional.
RooUnfoldBayesImpl::train: remove redundant TStopwatch timer.
Tidy some default object names.
Many changes to the examples/RooUnfoldTest, RooUnfoldTest2D, and new RooUnfoldTest3D. They now use test harness classes, RooUnfoldTestHarness, RooUnfoldTestHarness2D, and RooUnfoldTestHarness3D respectively. Test parameters can be specified on the command-line (or ROOT prompt): use RooUnfoldTest -h or RooUnfoldTest("-h") for details. New PDFs, which now include a constant background by default. Improved plots.
Add make html target.

14th October 2009: update to version 0.1.9:

RooUnfold::PrintTable prints a table of the results and χ²/DF. This is called from RooUnfoldTest.
Fix assignment of RooUnfold derived classes. Don't repeat RooUnfold::Setup when constructing derived classes.
Fix bin-by-bin, which was actually running the full bayes code.
SVD prints error if kterm is negative or greater than the number of bins.
Allow weight to be specified with RooUnfoldResponse::Fill() and Miss(). Defaults to 1.0, so no change if not specified. Support for variable binning in 1D case as suggested by Seth Zenz.
Add RooUnfoldResponse::ApplyToTruth based on idea and code from Seth Zenz.
Don't calculate covariance matrix unless required. This can be a slow operation for the Bayes algorithm. RooUnfoldBayesImpl does not call getCovariance after unfolding — now done automatically in RooUnfoldBayes.
Fix conversion of multi-dimensional distributions to 1D (for use in response matrix and in Bayes algorithm). Under/overflow bins are ignored. Uses new routines RooUnfoldResponse::GetBin and FindBin, which return global bin for multi-dimensional histogram corresponding to vector index or x value. Bug reported by Peter Waller.
(Fergus Wilson) RooUnfoldBayesImpl: added a getChi2 method. Added 1D smoothing. Speeded up covarinace matrix.
Fixes for GCC 4.3.3, suggested by Ioana Maris. Add missing include file to RooUnfoldTest.
RooUnfoldTest can test different numbers of bins in truth and measured distributions.
RooUnfoldTest2D only calculates errors with the Bayes algorithm for 25 or fewer bins. It takes a long time for more bins (goes as the 4th power of the number of bins).
RooUnfoldTest: Added a pulls histogram. Draw a line at y=0 on residual plot. Added simple checking of some command line parameters.
(Fergus Wilson) Changed RooUnfoldTest smear method so it now works for different x-axis ranges. New test distribution of exponential decaying background and a resonance (i.e. Higgs-like).
More robust GNUmakefile. If $ROOTSYS/test/Makefile.arch doesn't exist, it gets settings from root-config as suggested by Peter Waller. Use -lRooFitCore if available (seems to be needed with ROOT 5.18 Cygwin).
Use make ROOTBUILD=debug for debug build. Allow make VERBOSE=1 to display compilation commands.

13th August 2008: add brief instructions for setting up ROOT.

13th May 2008: updated RooUnfold slides for a talk I gave today. Updated SPIRES URL.

23rd January 2008: update to version 0.1.5:

Include missing headers for ROOT 5.16/00 (also verified to work in 5.18/00).
Fix RooUnfoldTest2D.ps file name.
Rename RooUnfoldSvd's tau parameter to kterm to match Hoecker and Kartvelishvili's usage (they use k for the last term used in the expansion).
Rebuild class documentation with ROOT 5.18/00.

2nd August 2007: update to version 0.1.4 with these changes to the SVD algorithm from Kerstin Tackmann:

Replace use of copy constructors by use of Clone. This should get rid of the segfaults that Jochen has been seeing.
Fixed bug in TUnfHisto::GetCov that could lead to small numerical changes in the estimated uncertainties.
Tested on my spectrum that the changes, which were supposed to be only clean-up between the previous two tags (Tim's and mine), do indeed give identical results on the curvature of the weight distributions and the errors.

12th July 2007: mention TH1D and TH2D classes explicitly. RooUnfold only supports histograms of doubles, not eg. TH1F.

17th April 2007: first public version.

http://hepunx.rl.ac.uk/~adye/software/unfold/RooUnfold.html last modified 16th September 2019 by

Tim Adye, <T.J.Adye@rl.ac.uk>

0	no unfolding (output copied from measured input)
1	Bayes
2	SVD
3	bin-by-bin
4	TUnfold
5	matrix inversion

0	flat distribution
1	top-hat distribution over mean ± 3 x width
2	Gaussian
3	Double-sided exponential decay
4	Breit-Wigner
5	Double Breit-Wigner, peaking at mean`-`width and mean`+`width
6	exponential
7	Gaussian resonance on an exponential background