Welcome to MaCh3 Tutorial

After this tutorial you should know how to run MCMC, implement systematic uncertainties, new samples, and how to plot standard Bayesian diagnostics.

There are several standard parts of MaCh3 analysis like sample/systematic implementations, validations and plotting. This tutorial will help you get used to different parts of MaCh3.

MaCh3 is predominantly C++ software, although some functionality is available through python as well. See the table of contents for more.

How to Start?
How to Run MCMC
Posterior Predictive Analysis
1. Plotting Posterior Predictive Distributions
2. Prior Predictive Distributions
How to Develop a Model of Systematic Uncertainties
1. How to Compare Chains
2. Holding Parameters Fixed
How to Develop New Samples
MCMC Diagnostic
1. Running Multiple Chains
Useful Settings
Other Useful Plots
1. LLH scans
2. Sigma Variations

How to Start?

To compile try

git clone https://github.com/mach3-software/MaCh3Tutorial.git
mkdir build;
cd build;
cmake ../ -DPYTHON_ENABLED=ON [DPYTHON_ENABLED not mandatory]
make -jN [set number of threads]
make install

then

source bin/setup.MaCh3.sh
source bin/setup.MaCh3Tutorial.sh

If this does not work, check out the Requirements for MaCh3 in case you are missing something.

One of the suggestions in Requirements is to use a conda/micromamba environment. You can install everything you need and build the tutorial using these commands:

<details> <summary>Click to see commands</summary>

To install micromamba and the environment needed to build MaCh3:

mkdir MaCh3Things && cd MaCh3Things

echo "" | BIN_FOLDER=".micromamba" INIT_YES="n" CONDA_FORGE_YES="y" "${SHELL}" <(curl -L micro.mamba.pm/install.sh)

cat > env.sh <<'EOF'
export MAMBA_ROOT_PREFIX="$(pwd)/.micromamba"
command="$(${MAMBA_ROOT_PREFIX}/micromamba shell hook -s posix)"
eval "$command"
EOF

source env.sh

micromamba env create -n MaCh3 -c conda-forge root cmake -y
micromamba activate MaCh3

and then to build MaCh3:

git clone https://github.com/mach3-software/MaCh3Tutorial.git
cd MaCh3Tutorial

mkdir build && cd build
cmake ../
make -j8
make install

source bin/setup.MaCh3.sh
source bin/setup.MaCh3Tutorial.sh

Note: To run the tutorial from a fresh terminal after this installation you must source and activate the relevant scripts and environments:
cd MaCh3Things
source env.sh # source micromamba
micromamba activate MaCh3

cd MaCh3Tutorial/build
source bin/setup.MaCh3.sh
source bin/setup.MaCh3Tutorial.sh

</details>

Alternatively you can use containers by

docker pull ghcr.io/mach3-software/mach3tutorial:alma9latest

To read more about how to use containers, check our doxygen here.

How to run MCMC

To run MCMC simply

./bin/MCMCTutorial TutorialConfigs/FitterConfig.yaml

Congratulations! 🎉 You have just finished your first MCMC chain. You can view Test.root for example in TBrowser like in plot below.

A single entry in the tree represents a single MCMC step. Other than debug purposes, it is highly recommended to use MaCh3 processing tools for further visualisation.

WARNING Your posterior may look very shaky and slightly different to the one in example. This is because you have run the chain with low number of steps, meaning you don't have enough statistic to build out the posterior distribution. It is good homework to increase the number of steps and see how much smoother the posterior becomes, but at the cost of having to wait more. You can easily test this by modifying TutorialConfigs/FitterConfig.yaml to change the number of MCMC steps:

General:
  MCMC:
    NSteps: 10000

and then re-running MCMCTutorial.

Warning: If you modified files in the main MaCh3Tutorial folder instead of build, you will have to call make install for the changes to propagate! Generally speaking, it is good practice to work from the build directory and make your config changes there so that local changes do not have to be tracked by git.

Config Overrides

Instead of changing the config file TutorialConfigs/FitterConfig.yaml above directly, you can instead dynamically override your configurations at the command line like this:

./bin/MCMCTutorial TutorialConfigs/FitterConfig.yaml General:MCMC:NSteps:100000

In this way, you can add as many configuration overrides here as you like, as long as the format is [executable] [config] ([option1] [option2] ...).

Warning This overriding process is only possible for the "main config" (i.e., configs that respond directly to the Manager class in MaCh3 core). This main config is used with the apps in the Tutorial folder here; for the other apps (mainly plotting apps like PredictivePlotting) that read from bin/TutorialDiagConfig.yaml, this is not possible, as further command line arguments are interpreted as input ROOT files, not override directives.

Processing MCMC Outputs

Being able to visualise and analyse the output of the MCMC is standard procedure after a chain has finished. MaCh3 uses ProcessMCMC to transform the raw output from the MCMC into smaller outputs that are more easily digested by downstream plotting macros. You can run it using

./bin/ProcessMCMC bin/TutorialDiagConfig.yaml Test.root

where Test.root is the output of running MCMCTutorial as described here. You can find some quickly-generated plots in Test_drawCorr.pdf. One of plots you will encounter is:

This is the marginalised posterior of a single parameter. This is the main output of the MCMC.

There are many options in ProcessMCMC that allow you to make many more analysis plots from the MCMC output; we recommend that you see here to get better idea what each plot means. In particular, we recommend comparing 2D posteriors with the correlation matrix, and playing with triangle plots.

Plotting MCMC Posteriors

Once you have the processed MCMC output from ProcessMCMC, which will be called something like <inputName>_Process.root, you can make fancier analysis plots from it using the GetPostfitParamPlots app like:

./bin/GetPostfitParamPlots Test_drawCorr.root

The output should look like plot below. This conveys same information as the individual posteriors from Test_drawCorr.pdf, but is more compact. This is useful especially if you have hundreds of parameters to compare.

<img width="350" alt="Posterior example" src="https://github.com/user-attachments/assets/27e3e4c8-629e-4c05-ac64-f6a7bec85331"> <details> <summary><strong>(Detailed) Additional Plots </strong></summary> `GetPostfitParamPlots` can produce two additional sets of plots:

Ridge Plot - This allow to nicely see non-Gaussian paramters.

Violin Plot - This also allow to see nicely non-Gaussian parameters but also is useful in comparing two chains. ProcessMCMC must be run with option "PlotCorr" to be able to produce violin plot.

Plotting Correlation Matrix

If you have run ProcessMCMC with option "PlotCorr" you will have a correlation matrix in the outputs. This is a handy tool for viewing how correlated different parameters are. However, mature analyses with hundreds of parameters may run into the problem of having too large of plots to be useful. To combat this, you can plot a subset of parameters using MatrixPlotter:

./bin/MatrixPlotter bin/TutorialDiagConfig.yaml Test_drawCorr.root

This macro will give you MatrixPlot.pdf, where you should see a plot like this:

In this particular example, you can see only two parameters. Using Tutori

MaCh3Tutorial

Install / Use

README