---
myst:
    substitutions:
        macro:
            python: 1-5,17-62,69-86,88-94,96-116,118-124,126-132
            cpp: 6-8,14-55,64-81,84-90,93-113,116-122,125-131
        bloc1:
            python: 28-36
            cpp: 23-29
        bloc2:
            python: 51-62,69-79
            cpp: 44-55,64-74
        bloc3:
            python: 81-86,88-94,96-116,118-124,126-132
            cpp: 76-81,84-90,93-113,116-122,125-131
        console:
            python: 2-51,54-66
            cpp: 6-55,58-70
---
(use_cases_macro_calibration_mcmc_linReg)=
# Macro "**calibrationMCMCLinReg.{{extension}}**"

## Objective

The goal here is to calibrate the parameters $t_0$ (constant term) and $t_1$ (multiplicative term) 
within a simple linear model (implemented in `UserFunctions.C`), against the observable 
outputs $y_{Exp}$, associated with given values of $x$ stored in the input file `linReg_Database.dat`. 
The initial lines defining the {{tds}} and the model are similar to those presented in 
[](#calibration_classes_functions_observations_use_case). This macro demonstrates how to apply 
the Markov chain Monte Carlo approach and more precisely the classic Metropolis-Hastings 
algorithm in two dimensions using a **Relauncher**-based architecture.

## Macro {{uranie}}

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCLinReg."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + macro[language] + "\n"
    + "```"
}}

Much of this code has already been covered in the previous section 
[](#use_cases_macro_calibration_minimisation) (up to the sequential run). The main difference here 
is that the input parameter is now defined as a `TStochasticDistribution`, representing the *a priori* 
chosen distribution.

Another difference from the previous example [](#use_cases_macro_calibration_mcmc) 
is that no uncertainty associated with the observables is provided in the input file. To this end, 
a new attribute is defined and added to the reference dataserver, with an assumed standard 
deviation of $y_{Exp}$ equal to 0.2.

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCLinReg."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc1[language] + "\n"
    + "```"
}}

The model is defined (from a `TCIntEval` instance with the three input variables discussed above, 
in the **correct order**) along with the computation distribution method (sequential). 

The calibration object is 
then created by specifying both the number of iterations of the algorithm (set to 4000). The 
likelihood function is defined as Gaussian, with the reference dataserver, the input and output 
variables, and the assumed standard deviation of the experimental data (see previous paragraph) provided as arguments. Several 
additional options are configured: the interval between two console displays is specified, the number of chains to 
initialise is defined, the starting points of each chain are assigned (one by one), and the 
standard deviation of the initial proposal distribution is set (for all chains at once). For 
further details on these options, see [](#calibration_markov_chain_mcmc_properties). Finally, 
the estimation process is performed, using the default MCMC algorithm (classic Metropolis-Hastings).

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCLinReg."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc2[language] + "\n"
    + "```"
}}

The final part demonstrates how to display and analyse the results. The first elements to examine 
are the trace plot ({numref}`usecases_calibrationMCMCLinReg_Tr`) and the acceptance ratio plot 
({numref}`usecases_calibrationMCMCLinReg_Acc`). On these plots, you should check that the number 
of accepted iterations is sufficiently high (at least several hundred if the chains stabilise quickly 
— in our case, around 1500), and that the converged acceptance ratio falls within a reasonable range 
(20–50% — here, it is close to 40%). When inspecting the trace, the chains should have converged 
around the same region (as they do here), and they should evolve rapidly, which indicates efficient 
exploration and low autocorrelation (also observed in our case). Finally, these plots help verify 
whether all chains behave stably and from which iteration they can be considered stable. This provides 
a first indication of a suitable burn-in value. In this example, the chains appear to have converged, 
and a burn-in value of 100 seems appropriate.

The burn-in size can then be defined and its consistency verified using the Gelman–Rubin statistic. In 
our case, values of 1.00092 and 0.99993 (for parameters $t_0$ and $t_1$ respectively) are reported in [](#use_cases_macro_calibration_mcmc_linReg_console) which are 
very close to 1 and confirms excellent convergence of the chains for both parameters. Otherwise, a different burn-in value 
might have been more appropriate, the calculation could have been extended, or the MCMC algorithm 
settings adjusted.

The next step is to check for sample autocorrelation within the chains. The Effective Sample Size 
(ESS) provides a good indication of the lag to be used. In our case, the chains contain a reasonable 
number of independent samples (at least 424 each), and a lag of 3 is sufficient (see 
[](#use_cases_macro_calibration_mcmc_linReg_console)). Otherwise, the calculation could have been extended, 
or the MCMC algorithm settings adjusted (especially the standard deviation of the proposal 
distribution).

It is also possible to represent the chains in two dimensions ({numref}`usecases_calibrationMCMCLinReg_Tr2D`). 
This provides an alternative way to verify whether the chains converge to the same region and highlights 
potential covariance between the posterior distributions of the two parameters.

Two additional pieces of *a posteriori*
information are presented as plots: the residuals 
({numref}`usecases_calibrationMCMCLinReg_Res`), which show the expected normal distribution 
behavior, as discussed in {{metho}} and the posterior distribution 
({numref}`usecases_calibrationMCMCLinReg_Par`).

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/calibration/use_cases/" + language + "/calibrationMCMCLinReg."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc3[language] + "\n"
    + "```"
}}

(use_cases_macro_calibration_mcmc_linReg_console)=
## Console

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/build/uranie/doc/calibration/use_cases/" + language 
    + "/calibrationMCMCLinReg_clean.log"
    + "\n"
    + ":name: usecases_calibrationMCMCLinReg_Console\n"
    + ":language: none\n"
    + ":lines: " + console[language] + "\n"
    + "```"
}}

## Graphs

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc_linReg/calibrationMCMCLinReg_Tr.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCLinReg_Tr\n"
    + figure_scale + "\n"
    "\n"
    "Trace graph of the macro **\"calibrationMCMCLinReg." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc_linReg/calibrationMCMCLinReg_Acc.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCLinReg_Acc\n"
    + figure_scale + "\n"
    "\n"
    "Acceptation ratio graph of the macro **\"calibrationMCMCLinReg." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc_linReg/calibrationMCMCLinReg_Tr2D.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCLinReg_Tr2D\n"
    + figure_scale + "\n"
    "\n"
    "2D Trace graph of the macro **\"calibrationMCMCLinReg." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc_linReg/calibrationMCMCLinReg_Res.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCLinReg_Res\n"
    + figure_scale + "\n"
    "\n"
    "Residuals graph of the macro **\"calibrationMCMCLinReg." + extension + "\"**\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/calibration/use_cases/" + language 
        + "/mcmc_linReg/calibrationMCMCLinReg_Par.png\n"
    ":align: center\n"
    ":name: usecases_calibrationMCMCLinReg_Par\n"
    + figure_scale + "\n"
    "\n"
    "Parameter graph of the macro **\"calibrationMCMCLinReg." + extension + "\"**\n"
    "```"
}}