(calibration_classes_functions_observations_calibration_classes)=
# Common methods of the calibration classes

All calibration classes that derive from `TCalibration` share many common methods, and their 
organisation has been streamlined as much as possible. This section describes the shared 
code to avoid repetition in the later sections, which cover each specific calibration 
method (from [](#calibration_minimisation) to [](#calibration_markov_chain)).

The subsections from [](#calibration_classes_functions_observations_calibration_classes_runner) to 
[](#calibration_classes_functions_observations_calibration_classes_function_launcher_archi) 
discuss the different constructors, explaining the various ways the model can be provided and 
their implications while [](#calibration_classes_functions_observations_calibration_classes_running) 
provides a glimpse of the shared possible options that can be defined and their purpose. Finally, 
[](#calibration_classes_functions_observations_calibration_classes_draw_parameter) and 
[](#calibration_classes_functions_observations_calibration_classes_draw_residuals) introduce the drawing 
methods in principle (though illustrations are postponed to dedicated sections of this documentation).

```{warning}
As with some earlier discussions, the following methods are common to all classes inheriting from 
`TCalibration`. For illustration, the examples will use an instance `cal` 
of the fictitious class `TCalClass` (as if it inherited from `TCalibration` class). A 
more realistic syntax can be found in the dedicated sections (from [](#calibration_minimisation) 
to [](#calibration_markov_chain)).
```

Calibration classes can generally be constructed in four different ways, depending on how the model 
has been specified. To estimate how close the new set of parameter values (the **configuration**) 
produces output that are close to the reference, one needs to be able to run the model on the input variables of the reference dataset. The 
input variables of the reference dataset are not the only input variables of the model used within 
the calibration method, as the parameters themselves have to be specified as inputs (as they also 
obviously affect the predictions). This section illustrates, using the **fictitious** class 
`TCalClass`, how calibration objects can be constructed.

```{toctree}
calibration_classes/runner
calibration_classes/tcode
calibration_classes/function_launcher_archi
calibration_classes/running
calibration_classes/estimate_residuals
calibration_classes/draw_parameter
calibration_classes/draw_residuals
```

:::{admonition} Summary: **`TCalibration` and `TDistanceLikelihoodFunction`**
In summary, a calibration analysis should always follow these key steps:

1. Define both the parameter (`tdsPar`) and reference (`tdsRef`) objects, as explained in 
[](#calibration_classes_functions_observations_data_model).

2. Define the model architecture (either **Relauncher** or **Launcher**-based) and the evaluator kind 
(code, C++-function, python-function...). Particular attention is needed when specifying the input and 
output attributes (the former should be an admixture of attributes from `tdsPar` and `tdsRef`, as 
explained in [](#calibration_classes_functions_observations_data_model).

3. Define the `TCalibration`-inheriting object (meaning the underlying method chosen for this 
analysis) and construct it (see from 
[](#calibration_classes_functions_observations_calibration_classes_runner) to 
[](#calibration_classes_functions_observations_calibration_classes_function_launcher_archi)).

4. Define the `TDistanceLikelihoodFunction`-inheriting object by calling `setDistance` or `setLikelihood` (depending 
on the `TCalibration` object), see the recommended distance and likelihood functions in 
[](#calibration_classes_functions_observations_data_and_distance_recommended_distance).

5. Set the method-dependent parameters (discussed in dedicated part, from 
[](#calibration_minimisation) to [](#calibration_markov_chain)).

6. Call the `estimateParameters` method with selected options (see 
[](#calibration_classes_functions_observations_calibration_classes_running)).

7. Perform the post-processing using method-dependent functions discussed in the dedicated sections, from 
[](#calibration_minimisation) to [](#calibration_markov_chain)) and drawing 
methods (see also both [](#calibration_classes_functions_observations_calibration_classes_draw_parameter) 
and [](#calibration_classes_functions_observations_calibration_classes_draw_residuals)).
:::