MaCh3 Diagnostic & Processing

Tools used for diagnostic MCMC and general MCMC processing. More...

Files
file	CombineMaCh3Chains.cpp
	Combine chains files produced by MCMC, enforcing the condition that all the files to combine were made using the exact same software versions and config files.
file	DiagMCMC.cpp
file	GetPenaltyTerm.cpp
	KS: This file contains the implementation of the function to extract specific penalty terms from systematic chains.
file	PlotLLHMap.cpp
	Processing n-dimensional LLHMap outputs generating 1D and 2D profiled likelihoods as defined in config.
file	PlotMCMCDiag.cpp
	KS: This script is used to analyse output form DiagMCMC.
file	ProcessMCMC.cpp
	Main exectable responsible for different types of MCMC processing like drawing posteriors, triangle plots etc. Actual implantation of methods is in MCMCProcessor.
file	ReweightMCMC.cpp
	This executable allow to reweight MCMC Chain, such technique is used to study impact of different priors without rerunning MCMC.
file	RHat.cpp
	This executable calculates the \( \hat{R} \) estimator for Markov Chain Monte Carlo (MCMC) convergence.
file	RHat.cpp
	This executable calculates the \( \hat{R} \) estimator for Markov Chain Monte Carlo (MCMC) convergence.
file	SmearChain.cpp
	Allows you to smear contour. For example after performing sets of study one finds out that used sets of uncertainty doesn't fully cover analysis need. Then one can smear additionally contour.

Detailed Description

Tools used for diagnostic MCMC and general MCMC processing.

Diagnostic Applications

ProcessMCMC The main application for analysing the ND280 chain. It prints posterior distributions after the burn-in cut and allows comparison of two or three different chains. Several options can be configured directly in the app, such as selection, burn-in cut, and whether to plot xsec+flux or only flux.

Additional functionality includes:

1. Produce a covariance matrix with multithreading (RAM intensive due to caching)
2. Violin plots
3. Credible intervals and regions
4. Calculation of Bayes factors with significance based on the Jeffreys scale
5. Triangle plots
6. Study of covariance matrix stability

More options are described here: https://github.com/mach3-software/MaCh3/wiki/09.-Bayesian-Analysis,-Plotting-and-MCMC-Processor

GetPenaltyTerm Since xsec, flux, and ND spline systematics are treated as the same systematic object, the log term cannot be taken directly. This utility evaluates the correct penalty term:

GetFluxPenaltyTerm MCMCChain.root config

Relevant parameters are loaded via the configuration, allowing arbitrary combinations to be studied. Runtime increases with the number of sets.

DiagMCMC Performs MCMC diagnostics such as autocorrelation and trace plots.

PlotMCMCDiag Plots the output of DiagMCMC and can compare multiple files:

./PlotMCMCDiag DiagMCMC_file_1.root Label_1, DiagMCMC_file_2.root Label_2 ...

Up to four files can be processed simultaneously.

RHat Performs the \(\hat{R}\) diagnostic to verify that all chains converged to the same stationary distribution:

./RHat Ntoys MCMCchain_1.root MCMCchain_2.root MCMCchain_3.root ...

CombineMaCh3Chains Combines chain files produced by MCMC, enforcing that all inputs were generated with identical software versions and configuration:

CombineMaCh3Chains [-h] [-c [0-9]] [-f] [-o <output file>] file1.root [file2.root ...]

Options:

• -c Target compression level (default 1, consistent with hadd)
• -f Force overwrite if the output file already exists
• -h Print usage message and exit

If no output name is specified, the first input file name is reused.

SmearChain Allows smearing of contours. Useful when a study shows that the evaluated uncertainty set does not fully cover the analysis needs:

SmearChain MCMCchain.root Config.yaml

ReweightMCMC Enables chain reweighting to test alternative prior choices without rerunning the MCMC. Commonly used to study the impact of reactor constraints on \(\theta_{13}\):

ReweightMCMC Config.yaml MCMCchain.root