Bigsimr.CorTypeType
CorType

A type used for specifiying the type of correlation. Supported correlations are:

Bigsimr.cor_boundsMethod
cor_bounds(margins::AbstractVector{<:UnivariateDistribution}, cortype::CorType, samples::Int)

Compute the stochastic pairwise lower and upper correlation bounds between a set of marginal distributions.

The possible correlation types are:

Examples

julia> using Distributions

julia> margins = [Normal(78, 10), Binomial(20, 0.2), LogNormal(3, 1)];

julia> lower, upper = cor_bounds(margins, Pearson);

julia> lower
3×3 Matrix{Float64}:
1.0       -0.983111  -0.768184
-0.983111   1.0       -0.702151
-0.768184  -0.702151   1.0

julia> upper
3×3 Matrix{Float64}:
1.0       0.982471  0.766727
0.982471  1.0       0.798379
0.766727  0.798379  1.0
Bigsimr.cor_boundsMethod
cor_bounds(d1::UnivariateDistribution, d2::UnivariateDistribution, cortype::CorType, samples::Int)

Compute the stochastic lower and upper correlation bounds between two marginal distributions.

This method relies on sampling from each distribution and then estimating the specified correlation between the sorted samples. Because the samples are random, there will be some variation in the answer for each call to cor_bounds. Increasing the number of samples will increase the accuracy of the estimate, but will also take longer to sort. Therefore ≈100,000 samples (the default) are recommended so that it runs fast while still returning a good estimate.

The possible correlation types are:

Examples

julia> using Distributions

julia> A = Normal(78, 10); B = LogNormal(3, 1);

julia> cor_bounds(A, B)
(lower = -0.7646512417819491, upper = 0.7649206069306482)

julia> cor_bounds(A, B, 1e6)
(lower = -0.765850375468031, upper = 0.7655170605697716)

julia> cor_bounds(A, B, Pearson)
(lower = -0.7631871539735006, upper = 0.7624398609255689)

julia> cor_bounds(A, B, Spearman, 250_000)
(lower = -1.0, upper = 1.0)
Bigsimr.cor_constrainMethod
cor_constrain(X::AbstractMatrix{<:Real})

Constrain a matrix so that its diagonal elements are 1, off-diagonal elements are bounded between -1 and 1, and a symmetric view of the upper triangle is made.

See also: cor_constrain!

Examples

julia> a = [ 0.802271   0.149801  -1.1072     1.13451
0.869788  -0.824395   0.38965    0.965936
-1.45353   -1.29282    0.417233  -0.362526
0.638291  -0.682503   1.12092   -1.27018];

julia> cor_constrain(a)
4×4 Matrix{Float64}:
1.0       0.149801  -1.0        1.0
0.149801  1.0        0.38965    0.965936
-1.0       0.38965    1.0       -0.362526
1.0       0.965936  -0.362526   1.0
Bigsimr.cor_convertMethod
cor_convert(X, from, to)

Convert from one type of correlation matrix to another.

The role of conversion in this package is typically used from either Spearman or Kendall to Pearson where the Pearson correlation is used in the generation of random multivariate normal samples. After converting, the correlation matrix may not be positive semidefinite, so it is recommended to check using LinearAlgebra.isposdef, and subsequently calling cor_nearPD.

See also: cor_nearPD, cor_fastPD

The possible correlation types are:

Examples

julia> r = [ 1.0       -0.634114   0.551645   0.548993
-0.634114   1.0       -0.332105  -0.772114
0.551645  -0.332105   1.0        0.143949
0.548993  -0.772114   0.143949   1.0];

julia> cor_convert(r, Pearson, Spearman)
4×4 Matrix{Float64}:
1.0       -0.616168   0.533701   0.531067
-0.616168   1.0       -0.318613  -0.756979
0.533701  -0.318613   1.0        0.13758
0.531067  -0.756979   0.13758    1.0

julia> cor_convert(r, Spearman, Kendall)
4×4 Matrix{Float64}:
1.0       -0.452063   0.385867    0.383807
-0.452063   1.0       -0.224941   -0.576435
0.385867  -0.224941   1.0         0.0962413
0.383807  -0.576435   0.0962413   1.0

julia> r == cor_convert(r, Pearson, Pearson)
true
Bigsimr.cor_fastMethod
cor_fast(X::AbstractMatrix{<:Real}, C::CorType=Pearson)

Calculate the correlation matrix in parallel using available threads.

Bigsimr.cor_fastPDFunction
cor_fastPD(X::AbstractMatrix{<:Real}, tau=1e-6)

Return a positive definite correlation matrix that is close to X. tau is a tuning parameter that controls the minimum eigenvalue of the resulting matrix. τ can be set to zero if only a positive semidefinite matrix is needed.

Bigsimr.cor_nearPDMethod
cor_nearPD(X::AbstractMatrix{<:Real})

Return the nearest positive definite correlation matrix to X.

Bigsimr.cor_randPDMethod
cor_randPD(T::Type{<:Real}, d::Int, k::Int=d-1)

The same as cor_randPSD, but calls cor_fastPD to ensure that the returned matrix is positive definite.

Examples

julia> cor_randPD(Float64, 4, 2)
4×4 Matrix{Float64}:
1.0        0.458549  -0.33164    0.492572
0.458549   1.0       -0.280873   0.62544
-0.33164   -0.280873   1.0       -0.315011
0.492572   0.62544   -0.315011   1.0

julia> cor_randPD(4, 1)
4×4 Matrix{Float64}:
1.0        -0.0406469  -0.127517  -0.133308
-0.0406469   1.0         0.265604   0.277665
-0.127517    0.265604    1.0        0.871089
-0.133308    0.277665    0.871089   1.0

julia> cor_randPD(4)
4×4 Matrix{Float64}:
1.0        0.356488   0.701521  -0.251671
0.356488   1.0        0.382787  -0.117748
0.701521   0.382787   1.0       -0.424952
-0.251671  -0.117748  -0.424952   1.0
Bigsimr.cor_randPSDMethod
cor_randPSD(T::Type{<:Real}, d::Int, k::Int=d-1)

Return a random positive semidefinite correlation matrix where d is the dimension ($d ≥ 1$) and k is the number of factor loadings ($1 ≤ k < d$).

See also: cor_randPD

Examples

julia> cor_randPSD(Float64, 4, 2)
4×4 Matrix{Float64}:
1.0        0.276386   0.572837   0.192875
0.276386   1.0        0.493806  -0.352386
0.572837   0.493806   1.0       -0.450259
0.192875  -0.352386  -0.450259   1.0

julia> cor_randPSD(4, 1)
4×4 Matrix{Float64}:
1.0       -0.800513   0.541379  -0.650587
-0.800513   1.0       -0.656411   0.788824
0.541379  -0.656411   1.0       -0.533473
-0.650587   0.788824  -0.533473   1.0

julia> cor_randPSD(4)
4×4 Matrix{Float64}:
1.0        0.81691   -0.27188    0.289011
0.81691    1.0       -0.44968    0.190938
-0.27188   -0.44968    1.0       -0.102597
0.289011   0.190938  -0.102597   1.0
Bigsimr.cov2corMethod
cov2cor(X::AbstractMatrix{<:Real})

Transform a covariance matrix into a correlation matrix.

Details

If $X \in \mathbb{R}^{n \times n}$ is a covariance matrix, then

$$$\tilde{X} = D^{-1/2} X D^{-1/2}, \quad D = \mathrm{diag(X)}$$$

is the associated correlation matrix.

Bigsimr.is_correlationMethod
is_correlation(X)

Check if the given matrix passes all the checks required to be a valid correlation matrix.

Criteria

A matrix is a valid correlation matrix if:

• Square
• Symmetric
• Diagonal elements are equal to 1
• Off diagonal elements are between -1 and 1
• Is positive definite

Examples

julia> x = rand(3, 3)
3×3 Matrix{Float64}:
0.834446  0.183285  0.837872
0.637295  0.270709  0.458703
0.626566  0.736907  0.61903

julia> is_correlation(x)
false

julia> x = cor_randPD(3)
3×3 Matrix{Float64}:
1.0       0.190911  0.449104
0.190911  1.0       0.636305
0.449104  0.636305  1.0

julia> is_correlation(x)
true

julia> r_negdef = [
1.00 0.82 0.56 0.44
0.82 1.00 0.28 0.85
0.56 0.28 1.00 0.22
0.44 0.85 0.22 1.00
];

julia> is_correlation(r_negdef)
false
Bigsimr.rmvnMethod
rmvn(n::Int[, μ::AbstractVector{<:Real}], Σ::AbstractMatrix{<:Real})

Utilizes available threads for fast generation of multivariate normal samples.

Examples

julia> μ = [-3, 1, 10];

julia> S = cor_randPD(3)
3×3 Matrix{Float64}:
1.0        -0.663633  -0.0909108
-0.663633    1.0        0.151582
-0.0909108   0.151582   1.0

julia> rmvn(10, μ, S)
10×3 Matrix{Float64}:
-1.32616   -1.02602     11.0202
-3.59396    2.84145      8.84367
-0.441537  -1.53279      8.82931
-4.69202    2.84618     10.5977
-2.63359    2.65779      9.8374
-3.75917    2.07208      8.90139
-3.00716    0.00897664  10.1173
-3.00928    0.851214     9.74029
-3.43021    0.402382     9.51274
-1.77849    0.157933     9.15944
Bigsimr.rvecMethod
rvec(n::Int, rho::AbstractMatrix{<:Real}, margins::AbstractVector{<:UnivariateDistribution})

Generate samples for a list of marginal distributions and a correaltion structure.

Examples

julia> using Distributions

julia> margins = [Normal(3, 1), LogNormal(3, 1), Exponential(3)]

julia> R = [
1.00 -0.23  0.12
-0.23  1.00 -0.46
0.12 -0.46  1.00
];

julia> rvec(10, R, margins)
10×3 Matrix{Float64}:
3.89423  38.6339    1.30088
5.87344  11.5582    5.25233
3.62383  20.4001    3.25627
3.65075   3.8316    4.48547
1.62223   9.95032   1.48367
3.42208  35.0998    0.644814
1.82689  58.417     0.580125
4.73678   4.75506  11.2741
1.92511   9.44913   0.651013
3.19883  39.3707    0.581781
Statistics.corMethod
cor(x[, y], ::CorType)

Compute the correlation matrix of a given type.

The possible correlation types are:

Examples

julia> x = [-1.62169     0.0158613   0.500375  -0.794381
2.50689     3.31666    -1.3049     2.16058
0.495674    0.348621   -0.614451  -0.193579
2.32149     2.18847    -1.83165    2.08399
-0.0573697   0.39908     0.270117   0.658458
0.365239   -0.321493   -1.60223   -0.199998
-0.55521    -0.898513    0.690267   0.857519
-0.356979   -1.03724     0.714859  -0.719657
-3.38438    -1.93058     1.77413   -1.23657
1.57527     0.836351   -1.13275   -0.277048];

julia> cor(x, Pearson)
4×4 Matrix{Float64}:
1.0        0.86985   -0.891312   0.767433
0.86985    1.0       -0.767115   0.817407
-0.891312  -0.767115   1.0       -0.596762
0.767433   0.817407  -0.596762   1.0

julia> cor(x, Spearman)
4×4 Matrix{Float64}:
1.0        0.866667  -0.854545   0.709091
0.866667   1.0       -0.781818   0.684848
-0.854545  -0.781818   1.0       -0.612121
0.709091   0.684848  -0.612121   1.0

julia> cor(x, Kendall)
4×4 Matrix{Float64}:
1.0        0.733333  -0.688889   0.555556
0.733333   1.0       -0.688889   0.555556
-0.688889  -0.688889   1.0       -0.422222
0.555556   0.555556  -0.422222   1.0