BAT - Bayesian Analysis Toolkit

Release notes for version: 1.0.0
Release date: 2018-05-18
Urgency: high

SHA256: 620e8069d85f18f8504137823621cbb578fa5b159e3074f0f2379ac295dd1482

Overview

This release is the result of a major clean up of the code and build
system. This allowed us to implement important new features but
implied that we had to break compatibility with previous releases. We
removed many inconsistencies in the interface and intend to not do any
such changes in future versions 1.X of BAT. To ease the maintenance
burden, we also removed some parts of the code that felt were untested
and not easy to keep up to date.

Documentation

The documentation has been modernized and rewritten. It is now hosted at github (also as a PDF) along with the reference guide

New code features and improvements

proposal function

We now have a multivariate proposal function that learns its
covariance during the prerun. It's the new default. It provides a
massive speed-up compared to the factorized proposal for problems with
more than a few parameters. Both factorized and multivariate proposal
are of the Gaussian or Student's [default] type. For Student's, the
degree of freedom is adjustable and defaults to 1; that is a
Cauchy. The mixing of chains via R values has been synchronized with an
update to the original paper by Gelman and Rubin.

Continuation of marginalization

• Continuation of a main run, for example in interactive sessions, to collect more samples
• Continuation of a main run loaded in from file. This feature has been requested by many users.

Further features

• Laplace integration for evidence calculation
• Refactored BCEngineMCMC: the state of a chain (mean, variances, etc.) is now summarized in a BCChainState
• The number of attempts to find a valid initial point to start the Markov chain can be defined with BCEngineMCMC::SetInitialPositionAttemptLimit.
• The log prefix like Summary: can be turned off with BCLog::SetPrefix(false)
• Drawing styles have been defaulted to those of ROOT
• update CUBA default settings

Build system changes

• INSTALL.md gives explicit advice on how to install BAT in the
  current Ubuntu and Debian releases
• ./configure --with-cuba=download downloads and builds the latest
  version of CUBA 4.2 and sets everything up so BAT can use it without
  any further setup required from the user
• make builds the library and all examples
• unit tests expanded
• make check runs the unit tests and all examples, without requiring
  to install BAT
• out-of-source builds now work; e.g., in a subdirectory of the source
  files, one can build BAT such that the source directory remains
  clean from build artefacts
• make distcheck does the above and more and now passes
• the performance test suite is overhauled
• Update minimum root version to 5.34/19
• we test every pull request to the master branch on travis with ROOT 5 and ROOT 6 to pass the unit tests and successfully run all examples
• we now use rpath on Mac OS X because dynamic loading via LD_LIBRARY_PATH doesn't work with security integrity protection. LD_LIBRARY_PATH still used on Linux.
• BAT is easier to use as a git submodule

Bug fixes

An excerpt from the detailed list

• All examples outputs are checked to look reasonable. This required many fixes because ROOT changed the behavior of several plot commands and options
• The text output was polished to remove several inconsistencies
• Many ROOT plot objects were leaked. This is fixed now by putting them into a BCTrash that is cleaned when the BCModel instance is destroyed. We avoid letting ROOT take over control of named TObject instances.
• User models have default copy constructors and assignment operators that work and don't leak or produce segmentation faults
• BCHistogramFitter had issues with non-unit bin widths
• File opening, tree and histogram writing and reading is now more robust
• The smallest intervals in marginal histograms were off by one in some cases
• GetBestFitParameters does not report observables any more
• Samples in parallel mode could be incorrect due to a race condition. The frequency of occurrence depended strongly on the number of chains and threads and the speed of the posterior evaluation. It could happen not at all or just every 10000 or even every 100 iterations. Stricter unit tests ensure that serial and parallel evaluation give byte-identical results but on travis we do not have many threads available.
• MCMCUserInitialize is now also called in advance of optimization techniques to allow the user to initialize any structures needed for the calling of the likelihood.
• BC*Fitter classes are now thread safe
• the output precision is now adaptively calculated
• GetCurrentChain() now returns robust results with multiple threads
• LogApproxBinomial returns -inf when needed
• return -inf instead inf in BCConstantPrior

Known problems

• BCRooInterface and BATCalculator are not thread safe; both
  classes have been updated to compile and run but we can offer no
  guarantee that they work correctly because the original author is
  not available anymore. In contrast to all other BAT classes,
  BATCalculator can not be used in interactive ROOT 6 sessions.
• BCTH1Prior::swap doesn't work correctly with root older than 5.34/25
• The ROOT macros in example/advanced may not work on the Mac under ROOT6.

Interface changes

• ./configure --enable-parallelization -> ./configure --enable-parallel
• many methods now accept or return std::string references instead
  of const char*
• rename many getters and setters in BCEngineMCMC striving for
  consistency and simplicity; for example, MCMCSetNIterationsRun ->
  SetNIterationsRun
• All members related to p values corrected for their degrees of freedom have been removed. There are too many assumptions going into those calculations that we feel that the result shouldn't be blindly used. The user can easily compute the correction manually with BCMath::CorrectPValue().
• For explicit control, we now return a TMinuitMinimizer instead of TMinuit before
• File output within simulated annealing has been removed completely
• marginalized histograms now stored to disk by name of variables instead of indices
• With the new BCChainState, we dropped BCEngineMCMC::Getx but access to invidual chains via Getx(unsigned c) still works
• BCObservable cannot share data with each other any more. This improves consistency and avoid seg faults and leaks
• several functions that previously returned bool to indicate success of action now return nothing, but throw if an error is encountered.

BAT - Bayesian Analysis Toolkit

Release notes for version: 1.0.0-RC2
Release date: 2018-04-24
Urgency: high

Overview

This release candidate is expected to be very close to the actual release of 1.0.
Since the last release candidate, we fixed 75 issues and merged 52 pull requests. Numerous small problems were fixed so everyone is encouraged to update to this version.

New code features and improvements

• Continue the main run, for example in interactive sessions, to collect more samples
• Laplace integration for evidence calculation
• Refactored BCEngineMCMC: the state of a chain (mean, variances, etc.) is now summarized in a BCChainState
• The number of attempts to find a valid initial point to start the Markov chain can be defined with BCEngineMCMC::SetInitialPositionAttemptLimit.
• The log prefix like Summary: can be turned off with BCLog::SetPrefix(false)

Build system changes

• Update minimum root version to 5.34/19 and at least autoconf 2.69
• we test every pull request to the master branch on travis with ROOT 5 and ROOT 6 to pass the unit tests and successfully run all examples
• we now use rpath on Mac OS X because dynamic loading via LD_LIBRARY_PATH doesn't work with security integrity protection. LD_LIBRARY_PATH still used on Linux.
• BAT is easier to use as a git submodule

Bug fixes

An excerpt from the detailed list

• All examples outputs are checked to look reasonable. This required many fixes because ROOT changed the behavior of several plot commands and options
• The text output was polished to remove several inconsistencies
• Many ROOT plot objects were leaked. This is fixed now by putting them into a BCTrash that is cleaned when the BCModel instance is destroyed. We avoid letting ROOT take over control of named TObject instances.
• User models have default copy constructors and assignment operators that work and don't leak or produce segmentation faults
• BCHistogramFitter had issues with non-unit bin widths
• File opening, tree and histogram writing and reading is now more robust
• The smallest intervals in marginal histograms were off by one in some cases
• GetBestFitParameters does not report observables any more
• Samples in parallel mode could be incorrect due to a race condition. The frequency of occurrence depended strongly on the number of chains and threads and the speed of the posterior evaluation. It could happen not at all or just every 10000 or even every 100 iterations. Stricter unit tests ensure that serial and parallel evaluation give byte-identical results but on travis we do not have many threads available.

Known problems

• the manual is not ready yet but the current version is now hosted on github (also as a PDF) along with the reference guide
• continuing the Markov chain from the results in a file is still work in progress

Interface changes

• All members related to p values corrected for their degrees of freedom have been removed. There are too many assumptions going into those calculations that we feel that the result shouldn't be blindly used. The user can easily compute the correction manually with BCMath::CorrectPValue().
• For explicit control, we now return a TMinuitMinimizer instead of TMinuit before
• File output within simulated annealing has been removed completely
• marginalized histograms now stored to disk by name of variables instead of indices
• With the new BCChainState, we dropped BCEngineMCMC::Getx but access to invidual chains via Getx(unsigned c) still works
• BCObservable cannot share data with each other any more. This improves consistency and avoid seg faults and leaks

BAT - Bayesian Analysis Toolkit

Release notes for version: 1.0
Release date: 2015-12-11
Urgency: high

Overview

This release is the result of a major clean up of the code and build
system. This allowed us to implement important new features but
implied that we had to break compatibility with previous releases. We
removed many inconsistencies in the interface and intend to not do any
such changes in future versions 1.X of BAT. To ease the maintenance
burden, we also removed some parts of the code that felt were untested
and not easy to keep up to date.

New features and improvements

proposal function

We now have a multivariate proposal function that learns its
covariance during the prerun, it's the new default. It provides a
massive speed-up compared to the factorized proposal for problems with
more than a few parameters. Both factorized and multivariate proposal
are of the Gaussian or Student's [default] type. For Student's, the
degree of freedom is adjustable and defaults to 1; that is a
Cauchy. The mixing of chains via R values has been synced with an
update to the original paper by Gelman and Rubin.

Miscellaneous

• update CUBA default settings
• use exceptions instead of an error message when there is no way to
  proceed

testing and building

• INSTALL.md gives explicit advice on how to install BAT in the
  current Ubuntu and Debian releases
• we now run tests for every change to the master branch with root 5
  and 6 on Ubuntu and Mac to ensure compatibility with all supported
  platforms
• ./configure --with-cuba=download downloads and builds the latest
  version of CUBA 4.2 and sets everything up so BAT can use it without
  any further setup required from the user
• make builds the library and all examples
• unit tests expanded
• make check runs the unit tests and all examples, without requiring
  to install BAT
• out-of-source builds now work; e.g., in a subdirectory of the source
  files, one can build BAT such that the source directory remains
  clean from build artefacts
• make distcheck does the above and more and now passes
• the performance test suite is overhauled

Bug fixes

• BC*Fitter classes are now thread safe
• the output precision is now adaptively calculated
• GetCurrentChain() now returns robust results with multiple threads
• MCMCInitialize() called at the appropriate time
• LogApproxBinomial returns -inf when needed
• outputs are polished
• return -inf instead inf in BCConstantPrior

Known problems

• ROOT 6.05/02 has a bug in the TF1 copy constructor slowing down the
  fast fitter and leading to segfaults with multiple threads; see
  issues #74 and #81
• with ROOT 5.34 and CUBA, BCIntegrate.TEST produces errors on the
  shell but the program passes all checks. This does not occur with
  ROOT 6.
• BCRooInterface and BATCalculator are not thread safe; both
  classes have been updated to compile and run but we can offer no
  guarantee that they work correctly because the original author is
  not available anymore. In contrast to all other BAT classes,
  BATCalculator can not be used in interactive ROOT 6 sessions.
• BCTH1Prior::swap doesn't work correctly with root older than 5.34/25

Interface changes

• ./configure --enable-parallelization -> ./configure --enable-parallel
• many methods now accept or return std::string references instead
  of const char*
• rename many getters and setters in BCEngineMCMC striving for
  consistency and simplicity; for example, MCMCSetNIterationsRun ->
  SetNIterationsRun

BAT - Bayesian Analysis Toolkit

Release notes for version: 0.9.4.1
Release date: 2015-01-19
Urgency: low

Bug fixes

• fix installation on Mac OS X with root6 and a version of sed that
  is incompatible with GNU sed to avoid errors when using sed -i.

BAT - Bayesian Analysis Toolkit

Release notes for version: 0.9.4
Release date: 2014-11-20
Urgency: medium

New features

• support ROOT6 (requires compiler that implements C++ 11)
• support cuba 4.0

Improvements

• CreateProject.sh becomes bat-project, loses a lot of clutter, and is installed to the bin directory
• every subclass of BCEngineMCMC provides access to the parameters via GetParameters

Interface changes (for users of previous BAT versions):

• cuba 3.2 had bugs and is not supported anymore
• configure option --with-roostats became --enable-roostats

Bug fixes

• fix off-by-one error in BCH1D::Draw
• include all 1D/2D marginals in pdf if there is more than 1 plot per page
• all examples that use the ROOT interpreter work
• bat libraries have the proper dependency on other bat libraries and external libraries encoded

Improvements of the build system

• important flags from ROOT are now passed on
• fix and update installation instructions, display how-to-setup-bat steps at the end of make install
• support VPATH builds: you can now create a subdirectory, run configure from there, and keep all build products in the subdirectory
• unit tests and the latex sources now part of the distribution
• make distcheck passes
• dependencies properly included in the libraries
• transform INSTALL to markdown format, fix csh instructions
• add a bat-config script that is installed to $PREFIX/bin/. It
  can be queried to return libraries, compiler flags, version etc. The
  variable $BATINSTALLDIR is no longer used in the examples and
  bat-project
• support pkgconfig
• no longer required ROOT's libmathmore to build the bat libraries

BAT - Bayesian Analysis Toolkit

Release notes for version: 0.9.4
Release date: 2014-11-XX
Urgency: medium

New features

• support ROOT6 (requires compiler that implements C++ 11)
• support cuba 4.0

Improvements

• CreateProject.sh becomes bat-project, loses a lot of clutter, and is installed to the bin directory
• every subclass of BCEngineMCMC provides access to the parameters via GetParameters

Interface changes (for users of previous BAT versions):

• cuba 3.2 had bugs and is not supported anymore
• configure option --with-roostats became --enable-roostats

Bug fixes

• fix off-by-one error in BCH1D::Draw
• include all 1D/2D marginals in pdf if there is more than 1 plot per page
• all examples that use the ROOT interpreter work
• bat libraries have the proper dependency on other bat libraries and external libraries encoded

Improvements of the build system

• important flags from ROOT are now passed on
• fix and update installation instructions, display how-to-setup-bat steps at the end of make install
• support VPATH builds: you can now create a subdirectory, run configure from there, and keep all build products in the subdirectory
• unit tests and the latex sources now part of the distribution
• make distcheck passes
• dependencies properly included in the libraries
• transform INSTALL to markdown format, fix csh instructions
• add a bat-config script that is installed to $PREFIX/bin/. It
  can be queried to return libraries, compiler flags, version etc. The
  variable $BATINSTALLDIR is no longer used in the examples and
  bat-project
• support pkgconfig
• no longer required ROOT's libmathmore to build the bat libraries

BAT - Bayesian Analysis Toolkit

Release notes for version: 0.9.4
Release date: 2014-11-XX
Urgency: medium

New features

• support ROOT6 (requires compiler that implements C++ 11)
• support cuba 4.0

Improvements

• CreateProject.sh becomes bat-project, loses a lot of clutter, and is installed to the bin directory
• every subclass of BCEngineMCMC provides access to the parameters via GetParameters

Interface changes (for users of previous BAT versions):

• cuba 3.2 had bugs and is not supported anymore
• configure option --with-roostats became --enable-roostats

Bug fixes

• fix off-by-one error in BCH1D::Draw
• all examples that use the ROOT interpreter work
• bat libraries have the proper dependency on other bat libraries and external libraries encoded

Improvements of the build system

• important flags from ROOT are now passed on
• fix and update installation instructions, display how-to-setup-bat steps at the end of make install
• support VPATH builds: you can now create a subdirectory, run configure from there, and keep all build products in the subdirectory
• unit tests and the latex sources now part of the distribution
• make distcheck passes
• dependencies properly included in the libraries
• transform INSTALL to markdown format, fix csh instructions
• add a bat-config script that is installed to $PREFIX/bin/. It
  can be queried to return libraries, compiler flags, version etc. The
  variable $BATINSTALLDIR is no longer used in the examples and
  bat-project
• support pkgconfig
• no longer required ROOT's libmathmore to build the bat libraries