Module correlation_matrices

Returns a positive definite matrix, S, corresponding to a block
covariance matrix. Each block has the structure:

          [1, ..., rho_k]
    S_k = [...,  1,  ...],
          [rho_k, ..., 1]

i.e. 1 on the diagonal and rho_k (on average) outside the diagonal. S then
has the structure:

        [S_1, delta, delta]
    S = [delta, S_i, delta],
        [delta, delta, S_N]

i.e. with the groups-correlation matrices on the diagonal and delta (on
average) outside.

Parameters
----------
p    : A scalar or a list of scalars with the numbers of variables for each
       group.

rho  : A scalar or a list of the average correlation between off-diagonal
       elements of S.

delta: Baseline noise between groups. Only used if the number of groups is
       greater than one. The baseline noise is computed as

           delta * rho_min,

       and you must provide a delta such that 0 <= delta < 1.

eps  : Entry-wise random noise. This parameter determines the distribution
       of the noise. The noise is approximately normally distributed with
       mean

           delta * min(rho)

       and variance

           (eps * (1 - max(rho))) ** 2.0 / 10.

       You can thus control the noise by this parameter, but note that you
       must have

           0 <= eps < 1 - max(rho).

Returns
-------
S    : The correlation matrix.

Returns a positive definite matrix, S, corresponding to a block
covariance matrix. Each block has the structure:

          [            1,       rho_k^1, rho_k^2,     ..., rho_k^{p_k-1}]
          [      rho_k^1,             1, rho_k^1,     ..., rho_k^{p_k-2}]
    S_k = [      rho_k^2,       rho_k^1,       1,     ...,           ...]
          [          ...,           ...,     ...,       1,       rho_k^1]
          [rho_k^{p_k-1}, rho_k^{p_k-2},     ..., rho_k^1,             1]

i.e. 1 on the diagonal and exponentially decreasing correlations outside
the diagonal. S then has the structure:

        [S_1,     0,     0]
    S = [  0,   S_i,     0],
        [  0,     0,   S_N]

i.e. with the group-correlation matrices on the diagonal and zero (on
average) outside.

Parameters
----------
p    : A scalar or a list of scalars with the numbers of variables for each
       group.

rho  : A scalar or a list of the average correlation between off-diagonal
       elements of S.

eps  : Maximum entry-wise random noise. This parameter determines the
       distribution of the noise. The noise is approximately normally
       distributed with zero mean and variance

           (eps * (1.0 - max(rho)) / (1.0 + max(rho))) ** 2.0 / 10.

       You can thus control the noise by this parameter, but note that you
       must have

           0 <= eps < 1.

Returns
-------
S    : The correlation matrix.