1%feature("docstring") OT::NormalCopula
2"Normal copula.
3
4Available constructor:
5    NormalCopula(*n=1*)
6
7    NormalCopula(*R*)
8
9Parameters
10----------
11n : int, :math:`n \geq 1`
12    Dimension of the copula. Default is :math:`n=2`.
13R : :class:`~openturns.CorrelationMatrix`
14    Shape matrix :math:`\mat{R}` of the copula, ie the correlation matrix of
15    any normal distribution with this copula (it is not the Kendall nor the
16    Spearman rank correlation matrix of the distribution).
17
18Notes
19-----
20The Normal copula is defined by :
21
22.. math::
23
24    C(u_1, \cdots, u_n) = \Phi_{\mat{R}}^n(\Phi^{-1}(u_1), \cdots, \Phi^{-1}(u_n))
25
26where :math:`\Phi_{\mat{R}}^n` is the cumulative distribution function of the
27normal distribution with zero mean, unit marginal variances and correlation :math:`R`:
28
29.. math::
30
31    \Phi_{\mat{R}}^n(\vect{x}) = \int_{-\infty}^{x_1} \ldots
32                                   \int_{-\infty}^{x_n}
33                                   \frac{1}
34                                        {{(2\pi\det{\mat{R}})}^{\frac{n}{2}}}
35                                 \exp \left(-\frac{\Tr{\vect{u}}\mat{R}\vect{u}}{2} \right)\di{\vect{u}}
36
37with :math:`\Phi` given by:
38
39.. math::
40
41      \Phi(x) = \int_{-\infty}^x \frac{1}{\sqrt{2\pi}} e^{-\frac{t^2}{2}}\di{t}
42
43The correlation matrix :math:`\mat{R}` is linked to the Spearman correlation
44and the Kendall concordance through the following relations:
45
46- From the Spearman correlation matrix:
47
48  .. math ::
49
50      \mat{R}_{ij} = 2 \sin \left( \frac{\pi}{6}\rho_{ij}^S \right)
51
52  where :math:`\rho_{ij}^S = \rho^S(X_i,X_j) = \rho^P(F_{X_i}(X_i),F_{X_j}(X_j))`
53
54- From the Kendall concordance matrix:
55
56  .. math::
57
58      \mat{R}_{ij} = \sin \left( \frac{\pi}{2} \tau_{ij} \right)
59
60  with
61
62  .. math::
63
64      \tau_{ij} = \tau(X_i,X_j)
65                = \Prob{(X_{i_1} - X_{i_2})(X_{j_1} - X_{j_2}) > 0} -
66                  \Prob{(X_{i_1} - X_{i_2})(X_{j_1} - X_{j_2}) < 0}
67
68  where :math:`(X_{i_1},X_{j_1}` and :math:`(X_{i_2},X_{j_2})` follow the
69  distribution of :math:`(X_i,X_j)`.
70
71See also
72--------
73Distribution
74
75Examples
76--------
77Create a distribution:
78
79>>> import openturns as ot
80>>> R = ot.CorrelationMatrix(3)
81>>> R[0, 1] = 0.25
82>>> R[1, 2] = 0.25
83>>> copula = ot.NormalCopula(R)
84
85Draw a sample:
86
87>>> sample = copula.getSample(5)"
88
89// ---------------------------------------------------------------------
90
91%feature("docstring") OT::NormalCopula::GetCorrelationFromKendallCorrelation
92"Get the correlation matrix from the Kendall correlation matrix.
93
94Parameters
95----------
96K : :class:`~openturns.CorrelationMatrix`
97    Kendall correlation matrix of the considered random vector.
98
99Returns
100-------
101R : :class:`~openturns.CorrelationMatrix`
102    Correlation matrix :math:`\mat{R}` of the normal copula evaluated from
103    the Kendall correlation matrix :math:`K`."
104
105// ---------------------------------------------------------------------
106
107%feature("docstring") OT::NormalCopula::GetCorrelationFromSpearmanCorrelation
108"Get the correlation matrix from the Spearman correlation matrix.
109
110Parameters
111----------
112S : :class:`~openturns.CorrelationMatrix`
113    Spearman correlation matrix :math:`S` of the considered random vector.
114
115Returns
116-------
117R : :class:`~openturns.CorrelationMatrix`
118    Correlation matrix :math:`\mat{R}` of the normal copula evaluated from
119    the Spearman correlation matrix :math:`S`."
120
121