Stefan Schmitt, DESY Hamburg

Notkestr. 85, 22607 Hamburg, GERMANY

Notkestr. 85, 22607 Hamburg, GERMANY

- Spokesperson of the H1 collaboration
- Member of the DESY ATLAS group
- Contributing to the Statistics group of the Helmholtz Alliance at the Terascale

Phone: +49-40-8998-3560

- 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.

*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 .
*

- 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 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].

- Version 17.9 [Nov 20, 2019] Implement effective number of degrees of freedom and a scan of the SURE variable for choosing the regularisation strengt. 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

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 |

- 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.

- 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.