# Correlate Dists

## Correlate_Dists(dists, rankCorrs, I, J)

Used to create several distributions, with arbitrary marginals, that have given pairwise rank correlations.

Reorders the samples in «dists» so as to match the desired rank correlations between distributions as closely as possible. The matrix «dists», indexed by «I», specifies the marginal distributions, one such marginal for each element of «I». «RankCorrs» must be symmetric and positive definite, and the diagonal should contain all ones.

The result will be distributions having the same margins as the original input, but with rank correlations close to those of the rankcorrs matrix.

If you need to define a single univariate distribution with a given rank correlation relative to one other univariate distribution, then the Correlate_With function is a bit easier to use.

## Library

Multivariate Distributions library functions (Multivariate Distributions.ana)

- Use File →
**Add Library...**to add this library

## Notes

Why must «rankCorrs» be positive definite? This requirement arises from the fact that not all combinations of rank correlations are logically consistent. As an extreme example, suppose we wanted the rank correlation of `X1`

and `X2`

to be +1, the rank correlation of `X1`

and `X3`

to be +1, but the rank correlation of `X2`

and `X3`

to be -1% (or anything other than +1). This is clearly not possible to achieve, and the matrix containing these rank correlations would not be positive definite. The positive definite requirement captures this requirement that the specified rank correlations be self-consistent in the general case.

The function returns a re-ordering that comes *as close as possible* to achieving the specified rank correlations. With a finite sample size, it might not be possible to obtain the precise rank correlation, but as your sample size increases, the sample rank correlation approaches the desired rank correlation specified in the «rankCorrs» parameter.

## Example

If you would like to work through an example, you can start up Analytica and work through the following steps:

- Select "Add Library..." from the file menu.
- Select "Multivariate Distributions.ana" and press
**OK**. On the next dialog, select "Link". - Create two index nodes and title them
`I`

and`J`

. Set both their definitions to`[1, 2, 3]`

- Create a variable node, title it
`Desired_Corr`

. Set its definition to a*Table*and select indexes`I`

and`J`

. - Fill in the edit table of
`Desired_Corr`

to:

I ▶ J ▼ 1 2 3 1 1 0.5 -0.2 2 0.5 1 0.6 3 -0.2 0.6 1

- Create a chance node and title it
`Marginals`

. Set its definition to a*Table*and select index`I`

. - Fill in the edit table of
`Marginals`

as:

I ▶ 1 2 3 Gamma(2, 3) LogNormal(3, 5) Uniform(-3, 3)

- Create another chance node and title it
`Final_Dists`

. - Enter the following definition for
`Final_Dists`

:

`Correlate_Dists(Marginals, Desired_Corr, I, J)`

- Press
*Ctrl+U*to access the Uncertainty Settings dialog. Set sample size to 10K.

- Now
`Final_dists`

contains the correlated distributions. If you want to split these out into separate variables, you can follow these steps:

- Create a variable node and title it
`X1`

. Set its definition to:

`Final_dists[I = 1]`

- Repeat set
`X1`

for`X2`

and`X3`

, with definitions`Final_dists[I = 2]`

and`Final_dists[I = 3]`

.

Enable comment auto-refresher