---
myst:
    substitutions:
        bloc:
            python: 6-17
            cpp: 6-17
---
# Imposing the correlation coefficients

It is possible to set the correlation coefficient by hand, using the `setUserCorrelation` method of 
both `TSampling` and `TBasicSampling`.

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

**Specification of a correlation**

1. Generating a uniform random variable in [3., 4.]

2. Generating a gaussian random variable with 0.5 as mean value 1.5 as standard deviation.

3. Specification of correlation of 0.90 between the two attributes `xunif` and `xnorm`.

4. Generate the sample by calling the `generateSample` method in `TSampling` (respectively the 
`generateCorrSample` method in `TBasicSampling`).

The coefficient provided is changing the correlation between the two considered attributes (for a 
more general discussion on this, see {{metho}}). As an example, {numref}`sampler_set_correlation_notrank` 
and {numref}`sampler_set_correlation_rank` show the {{doe}} created with the `TSampling` class, 
using a normal and uniform distribution, using three different correlation coefficient values: 0, 
0.45 and 0.9. The first one is showing the obtained 2D plan and their corresponding projections, 
while the second one is showing the same information but displaying their rank instead of their 
values (this is further discussed in {{metho}}).

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/sampler/bloc_codes_chapter/cpp/producePlotsSampler/SetCorrelationExample_NotRank.png\n"
    ":align: center\n"
    ":name: sampler_set_correlation_notrank\n"
    + figure_scale + "\n"
    "\n"
    "Tufte plot of the " + doe + " created using a normal and uniform distribution, with a LHS method 
    with three correlation coefficient: 0, 0.45 and 0.9\n"
    "```"
}}

{{
    "```{" "figure" "} " + parent_dir +
        "/roottest/build/uranie/doc/sampler/bloc_codes_chapter/cpp/producePlotsSampler/SetCorrelationExample_Rank.png\n"
    ":align: center\n"
    ":name: sampler_set_correlation_rank\n"
    + figure_scale + "\n"
    "\n"
    "Tufte plot of the rank of the " + doe + " created using a normal and uniform distribution, with 
    a LHS method with three correlation coefficient: 0, 0.45 and 0.9\n"
    "```"
}}

Instead of provided one-by-one the correlation factors, one can provide the correlation matrix using 
the `setCorrelationMatrix` method of both `TSampling` and `TBasicSampling`. This method ask for a 
`TMatrixD` input and it will check that:

- the dimension is correct : $(n_{X},n_{X})$.

- the coefficient are all in the range $[-1,1]$

- the diagonal term are exactly at one (if not it sets them to this value).

```{toctree}
imposing_coefficients/correlation_matrix
```