---
myst:
    substitutions:
        bloc:
            python: 6-16
            cpp: 6-16
---
# The copula classes

Instead of using samplers with correlation matrix in the case of intricate variables, one can use 
classes relying on *Copula*, in order to describe the dependencies. These classes inherit from the 
`TCopula` class successively through the `TSamplerStochastic` and the {{tsam}} classes. The idea of 
a copula is to define the interaction of variables using a parametric-function that can allow a 
broader range of entanglement than only using a correlation matrix (various shapes can be done). 
There are two kinds of copulas provided in the {{uranie}} platform:

- **TArchimedian** with 4 pre-defined parametrisation: Ali-Mikhail-Haq (`TAMHCopula`), Clayton 
(`TClaytonCopula`), Frank (`TFrankCopula`) and Plackett (`TPlackettCopula`). These copulas, which 
depend only on the input variables and a parameter $\theta$, are shown from 
{numref}`sampler_tcopula_amh_plots` to {numref}`sampler_tcopula_plackett_plots` for different $\theta$ 
values along with the formula of the corresponding parametric function.

- **TElliptical:** it is a class to interface the `TGaussian` copula method.

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/sampler/bloc_codes_chapter/python/TAMHCopula.png\n"
    ":align: center\n"
    ":name: sampler_tcopula_amh_plots\n"
    + figure_scale + "\n"
    "\n"
    "Example of sampling done with half million points and two uniform attributes (from 0 to 1), 
    using AMH copula and varying the parameter value.\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/sampler/bloc_codes_chapter/python/TClaytonCopula.png\n"
    ":align: center\n"
    ":name: sampler_tcopula_clayton_plots\n"
    + figure_scale + "\n"
    "\n"
    "Example of sampling done with half million points and two uniform attributes (from 0 to 1), 
    using Clayton copula and varying the parameter value.\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/sampler/bloc_codes_chapter/python/TFrankCopula.png\n"
    ":align: center\n"
    ":name: sampler_tcopula_frank_plots\n"
    + figure_scale + "\n"
    "\n"
    "Example of sampling done with half million points and two uniform attributes (from 0 to 1), 
    using Frank copula and varying the parameter value.\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/sampler/bloc_codes_chapter/python/TPlackettCopula.png\n"
    ":align: center\n"
    ":name: sampler_tcopula_plackett_plots\n"
    + figure_scale + "\n"
    "\n"
    "Example of sampling done with half million points and two uniform attributes (from 0 to 1), 
    using Plackett copula and varying the parameter value.\n"
    "```"
}}

The following example shows how to create a copula and to use it in order to get a correlated sample.

{{
    "```{literalinclude} " + parent_dir
    + "/roottest/uranie/doc/sampler/bloc_codes_chapter/" + language + "/copula_classes."
    + extension
    + "\n"
    + ":language: " + language + "\n"
    + ":lines: " + bloc[language] + "\n"
    + "```"
}}