Overview

The class TUnfold can be used to unfold measured data spectra and obtain the underlying "true" distribution. The input to the unfolding procedure is:

The measured data histogram. This histogram is one-dimensional. For the case of multi-dimensional problems, the bins are reordered to fit in one dimension (use of the classes TUnfoldDensity and TUnfoldBinning is recommended)
A 2-dimensional histogram which describes for each bin of the truth distribution how it migrates in the measured variable. This histogram does not have to be normalized. The normalisation is handled inside the program.

There may also be histograms with background to the measured distribution and systematic uncertainties connected to the 2-dimensional histogram of migrations. These two cases are handled by the class TUnfoldSys, which provides methods to do systematic error propagation and to do unfolding with background subtraction. Together with complex binning schemes or multi-dimensional distributions all this is best handled by TUnfoldDensity and TUnfoldBinning.

It is strongly recommended to download and use the latest version of TUnfold from this web-page. The version distributed with the root package often is outdated and does not contain the latest bug fixes. First try the latest version, then report problems and new requests to .

Documentation

the mathematics and the basic ideas are explained here: arXiv:1205.6201, published as technical report in JINST 7 (2012) T10003 (this is the citation you could include in your paper). The latest version of the report, including corrections of typos, is available here.
a comparative study of unfolding methods is published with the proceedings of the 12th Conference on Quark Confinement and the Hadron Spectrum (Confinement XII), arXiv:1611.01927
the (slightly outdated) online documentation of the TUnfold classes and methods (version 17.6) as generated by doxygen is available here
some (outdated) html documentation for version 16 and below can be found here.
a brief user manual is distributed with version 17.1 and higher. The latest version is available here [manual V17.9].

TUnfold version history and download

Version 17.9 [Nov 20, 2019] Implement effective number of degrees of freedom and a scan of the SURE variable for choosing the regularisation strength. Also implement iterative unfolding for comparisons. Update the manual to describe the new unfolding example 2a, 2b, 2c.
Version 17.8 [May 24, 2019] Small bug fixes and new method to get matrix DXDY as a histogram for user-dependent error propagation.
Version 17.7 [Jun 27, 2018] Various small bug fixes
Version 17.6 [Nov 17, 2016] Various small bug fixes, doxygen style documentation
Version 17.5 [Aug 26, 2015] Bug fixes (bad systematic error from uncorrelated response matrix uncertainties and other small issues)
Version 17.4 [Feb 10, 2015] Bug fix (crash in TUnfoldBinning when calculating error matrix)
Version 17.3 [Apr 7, 2014] support for repeated bins having the same width (equistant binning) in TUnfoldBinningXML
Version 17.3 beta1 release [Feb 5, 2014] Bug fixes with uncorrelated error of size zero in TUnfoldSys and with underflow/overflow bins in TUnfoldBinning
Version 17.2 [Sep 26, 2013] The TUnfoldBinning XML interface moved to a new class TUnfoldBinning.XML. It is planned to include this version in root 6.00
Version 17.2 beta1 release [Jan 4, 2013] TUnfoldBinning XML interface, bug fix with method GetProbabilityMatrix.
Version 17.1 [Nov 15, 2012] Small bug fixes with GetFoldedOutput and GetOutput, new scan type RhoSquare, bug fix with background subtraction uncertainty.
Version 17.0 [May 29, 2012] New classes TUnfoldDensity and TUnfoldBinning for handling complex binning schemes
Version 16.3 [Feb 21, 2012] Another bug fix with the calculation of errors from background subtraction
Version 16.2 [Aug 17, 2011] Bug fix with the calculation of errors from background subtraction
Version 16.1 Bug fix with calculation of the error matrix/correlations (affects option kConstraintArea only)
Version 16.0 New version numbering, improved error messages, better compatibility to ROOT's CINT
Version 15bugfix Includes a small bugfix
Version 15 Use new tau definition, automated tau scan, unfolding with area constraint, bug fixes with systematic error evaluation, background subtraction, improved examples
Version 14 Improved error handling, less print-out
Version 13 Support for systematic error propagation
Version 12 Matrix inversion error handling
Version 11 Improved error handling
Version 10 Bug fix
Version 9 Faster matrix inversion for special problems
Version 8 Bug fix
Version 7 Bug fix
Version 6 First stable version

TUnfold versions and root versions

Note: as of root version 5.22, TUnfold is included in the root package. However, the version implemented in root may not be up-to date. Check the version table below and use a local copy of TUnfold when necessary.

Relation of distributed Root version, TUnfold version and functionality:

Root Version	TUnfold version	TUnfoldSys	TUnfoldDensity TUnfoldBinning	TUnfoldBinningXML	TUnfoldIterativeEM
5.22	6	no	no	no	no
5.23 to 5.26	13	yes	no	no	no
5.27	15	yes	no	no	no
5.28 to 5.34	16.0	yes	no	no	no
6.00 to 6.08	17.1	yes	yes	no	no
6.10	17.6	yes	yes	yes	no
	17.7	yes	yes	yes	no
	17.8	yes	yes	yes	no
	17.9	yes	yes	yes	yes

TUnfold bugs

The method TUnfoldIterativeEM::GetOutput() returns bad errors if bins are joined after the unfolding (e.g. projections of multi-dim histograms) [reported by D.Britzger Juj 2022].
TUnfoldIterativeEM does not work if there are bins with non-positive prediction [S.Schmitt, July 2022].
The class TUnfoldIterativeEM lacks an include statement for TMath.h [reported by R.Nisius, Feb 2020].
The method TUnfold::GetSqrtEvEmatrix() does not work properly for negative Eigenvalues [reported by P.Verschuuren, Feb 2020].
(fixed in version TUnfold 17.8) the class TUnfoldBinning does not construct histograms properly if the tree (of TUnfoldBinning objects) is too deep. The bug is in the method TUnfoldBinning::GetNonemptyNode(), which internally is used by many methods of the class TUnfoldBining and TUnfoldDensity. Work-around: avoid having binning schemes with too many nested instances of TUnfoldBinning [Nov 2018].
The root library libXMLParser is required when linking code which is using the class TUnfoldBinningXML. This can be deduced from the Makefile, but is not documented elsewhere. It should probably be added to the README file, which is quite outdated anyway [reported by D.Arcaro, July 2018].
(fixed in version TUnfold 17.7) There is a bug in the example testUnfold7a.C, possibly leading to a segmentation fault or similar [May 2018].
(fixed in version TUnfold 17.7) Regularisation in TUnfoldDensity, with mode=kRegModeCurvature is not implemented properly [reported by J.Linacre, August 2017].
(fixed in version TUnfold 17.7) The methods TUnfoldSys::GetBackground() and TUnfoldDensity::GetBackground() are buggy and return background distributions shifted by one bin [reported by A.Bolz, April 2017]
(fixed in version TUnfold 17.7) The method TUnfoldBinning::ExtractHistogram() which was added in V17.6 is buggy [reported by A.Bolz, May 2017].
(fixed in version TUnfold 17.6) the program may crash in TUnfoldDensityV17::GetProbabilityMatrix() if the third argument is set to true (Nov 3, 2015)
(fixed in version TUnfold 17.5) the calculation of uncorrelated uncertainties from the matrix-of-migrations to the result is wrong. This is the error matrix returned in GetEmatrixSysUncorr(). The corresponding (wrong) contribution is also summed up in GetEmatrixTotal(). In the cases where the bug shows up, the resulting error matrix likely will be too small, possibly even having negative entries on the diagonal. The error is related to a bug in the method MultiplyMSparseMSparseTranspVector(), which is part of the TUnfold package (class TUnfold) since version V15. The method gives wrong results in those cases where the third argument is a sparse matrix. The TUnfold version 15, 16.0, 16.1, 16.2, 16.3, 17.0, 17.1, 17.2, 17.3, 17.4 are all affected by this problem.
(fixed in version TUnfold 17.5) the histogram returned by GetInput() is shifted by one bin. The method GetInputInverseEmatrix() does not return the correct matrix (Apr 4, 2015)
(fixed in version TUnfold 17.5) a memory leak has been reported in TUnfold (Mar 27, 2015)
(fixed in version TUnfold 17.4) A problem may occur when calculating the error matrix, the error message is "FillBinMapSingleNode: inconsistent dimensions 1 2". As a temporary solution, force ROOT to ignore this error (e.g. gErrorAbortLevel=kError+1).
(fixed in version TUnfold 17.3) A problem may occur in TUnfoldDensity and TUnfoldSys if a matrix of migration is given with all its errors set to zero. Methods like GetEmatrixTotal() will fail.
Solution: Set a small error on the migration matrix.
Note: typically the matrix of migrations is filled from Monte Carlo, hence the errors are sqrt(N), i.e. non-zero, such that the problem does not show up.
(fixed in version TUnfold 17.3) There is a typo in TUnfoldBinning.h, such that underflow and overflow bins are not handled correctly. For a given axis, cases where there is an underflow bin but no overflow bin, or vice versa, are not handled correctly. However, if there is neither an underflow nor an overflow bin or if there is both an underflow and an overflow bin, then the code should perform as expected.

TUnfold improvements wish-list

The examples should write their output to dedicated directories.
Some methods in TUnfoldIterativeEMV17 have unused arguments.
Add support for handling migrations from outside the phase-space
Add support for splines and event-reweighting (similar to RUN and TRUEE)
Add suport for Eigenvalue-analysis based choices of the regularisation strength.

Updates and plans for the future

Please contact in case you wish to contribute to the project or if you have requests to implement additional features.