.. _variables-uncertain_correlation_matrix:

""""""""""""""""""""""""""""
uncertain_correlation_matrix
""""""""""""""""""""""""""""


Correlation among aleatory uncertain variables


.. toctree::
   :hidden:
   :maxdepth: 1



**Specification**

- *Alias:* None

- *Arguments:* REALLIST

- *Default:* identity matrix (uncorrelated)


**Description**



Aleatory uncertain variables may have correlations specified through
use of an ``uncertain_correlation_matrix`` specification. This
specification is generalized in the sense that its specific meaning
depends on the nondeterministic method in use.

When the method is a nondeterministic sampling method (i.e.,
:dakkw:`method-sampling`), then the correlation matrix
specifies *rank correlations* :cite:p:`Iman1982`. When the method is a
reliability (i.e., :dakkw:`method-local_reliability` or :dakkw:`method-global_reliability`) or
stochastic expansion (i.e., :dakkw:`method-polynomial_chaos` or
:dakkw:`method-stoch_collocation`) method, then the correlation matrix specifies
*correlation coefficients* (normalized covariance) :cite:p:`Hal00`.

In either of these cases, specifying the identity matrix results in
uncorrelated uncertain variables (the default). The matrix input
should be symmetric and have all :math:`n^2` entries where *n* is the
total number of aleatory uncertain variables. Ordering of the aleatory
uncertain variables is as shown in the input-specification-ordered
table in :dakkw:`variables` for ``normal``, ``lognormal``, ...,
``histogram_point``.

..
   TODO: What does the following statement mean?

When additional variable types are activated, they assume uniform
distributions, and the ordering is as listed on
:dakkw:`variables`.




**Examples**


Consider the following random variables, distributions and correlations:

- :math:`X_1` , normal, uncorrelated with others
- :math:`X_2` , normal, correlated with :math:`X_3` , :math:`X_4`  and :math:`X_5` 
- :math:`X_3` , weibull , correlated with :math:`X_5` 
- :math:`X_4` , exponential, correlated with :math:`X_3` , :math:`X_4`  and :math:`X_5` 
- :math:`X_5` , normal, correlated with :math:`X_5`  These correlations are captured by the following commands (order of the variables is respected).


.. code-block::

   uncertain_correlation_matrix
     # ordering normal, exponential, weibull
     # X_1   X_2   X_5   X_4   X_3
       1.00  0.00  0.00  0.00  0.00
       0.00  1.00  0.50  0.24  0.78
       0.00  0.50  1.00  0.00  0.20
       0.00  0.24  0.00  1.00  0.49
       0.00  0.78  0.20  0.49  1.00