andrewadare / unfolding

UnfoldingUtils class and example macros to solve unfolding problems using ROOT

unfolding.git

C++/ROOT package for unfolding and inference

This package provides many tools for tackling discrete linear inverse problems, including

• Singular value decomposition and Generalized SVD
  • Extension of the method described in SVD approach to data unfolding
  • GSVD provides more regularization flexibility than the classic SVD method, and allows rectangular (m > n) matrices.
  • Error propagation through full covariance matrix
• Preconditioned conjugate gradients for least squares (P-CGLS)
  • Fast iterative method for large problems allowing flexible regularization - see Discrete Inverse Problems by P. C. Hansen
• Richardson-Lucy iterative solver
  • Bayesian-based iterative method of image restoration by W. H. Richardson
  • See also "An iterative technique for the rectification of observed distributions" L. B. Lucy, The Astronomical Journal, vol 79, no 6, 1974.
• $\chi^2$ minimizer using ROOT's TMinuit2 package (requires ROOT to be built with --enable-minuit2)
• "Fully Bayesian" method using MCMC Metropolis random walk sampler.
  • "Fully Bayesian Unfolding" by G. Choudalakis

Significant attention has been devoted to visualization. The examples produce spectral decomposition plots, step-wise animations for the iterative solvers, and surface plots demonstrating evolution the solutions with regularization strength.

Several quantitative methods are included to assist in finding the optimal regularization strength, including generalized cross-validation, L-curve analysis, effective degrees of freedom, and singular value spectra.

Getting started

There is no build system other than ROOT's ACLiC compiler (see examples/rootlogon.C). This package requires MatrixUtils.h and UtilFns.h from andrewadare/utils. Either symlink them to the same directory as README.md, or add their location to the ACLiC and interpreter include paths by editing examples/rootlogon.C. The example scripts should then work without further setup; for example do $ root ConvolutionExample.C+.

This code has been tested on Mac OS X 10.9 against ROOT 5 (5.34/18) and ROOT 6 beta (5.99/06). Unfortunately, I can't say much about any other setup.

unfolding's Issues

Broken MCMC example

BayesUnfoldingExample641.C will not run because the interface to SampleMH() in BayesMCFns.C has been updated. It's on the TODO list.