pm_distCov Module Reference

This module contains classes and procedures for generating random matrices distributed on the space of positive definite matrices, such that their determinants is uniformly or power-law distributed. More...

Data Types
type	dvine_type
	This the derived type whose instances imply the use of the Dvine algorithm for generating random covariance matrices as described in algorithm of Lewandowski et al. (2009). More...
interface	getCovRand
	Generate and return a random positive-definite (correlation or covariance) matrix using the Gram method. More...
type	gram_type
	This the derived type whose instances imply the use of the Gram algorithm for generating random covariance matrices. More...
type	onion_type
	This the derived type whose instances imply the use of the Onion algorithm for generating random covariance matrices as described in algorithm of Lewandowski et al. (2009). More...
interface	setCovRand
	Return a random positive-definite power-law-distributed (correlation) matrix. More...

Variables
character(*, SK), parameter	MODULE_NAME = "@pm_distCov"
type(gram_type), parameter	gram = gram_type()
	The scalar constant of type gram_type implying the use of the Gram algorithm for generating random covariance matrices. More...
type(dvine_type), parameter	dvine = dvine_type()
	The scalar constant of type dvine_type implying the use of the Dvine algorithm for generating random covariance matrices as described in algorithm of Lewandowski et al. (2009). More...
type(onion_type)	onion = onion_type()
	The scalar module variable object of type onion_type implying the use of the Onion algorithm for generating random covariance matrices as described in algorithm of Lewandowski et al. (2009). More...

Detailed Description

This module contains classes and procedures for generating random matrices distributed on the space of positive definite matrices, such that their determinants is uniformly or power-law distributed.

The procedures of this module generate random covariance matrices based on the following approaches:

1. The first class of methods is based on the observation that every real positive definite matrix \(M\) has a Cholesky factorization

   \begin{equation} M = LL* \end{equation}

   where \(L\) is a uniquely defined lower triangular matrix with positive diagonal entries.
   Therefore, \(M\) can be constructed from a given random \(L\).
   The Gram method is fast, however, the resulting matrix \(M\) does not possess any particular structure.
   
2. The second class of methods is based on a modified version of the Vine algorithm of Lewandowski, Kurowicka, and Joe (2009), "Generating random correlation matrices based on vines and extended onion method".
   The resulting matrices generated by procedures of this module are randomly distributed over the space of the correlation matrices such that,

   \begin{equation} \pi(\left|\ms{rand}\right| ~\big|~ \eta) \propto \left|\ms{rand}\right|^{\eta} ~, \end{equation}

   where,
   1. \(\left|\ms{rand}\right|\) represents the determinant of the generated matrix \(\ms{rand}\), and
   2. \(\eta\) is an arbitrary scalar non-negative constant.
   Note that the definition of \(\eta\) in this module corresponds to \(\eta - 1\) in the proposed algorithm of Lewandowski et al. (2009).
   Setting \(\eta = 0.\) corresponds to a uniform distribution of the random matrices on the space of the correlation matrices.
   The off-diagonal elements of the random correlation matrix follow the Beta distribution:

   \begin{equation} \ms{rand}_{ij} \sim \mathcal{B}(\eta + \ms{ndim} / 2, \eta + \ms{ndim} / 2) ~,~ i \neq j ~,~ 1 \leq i, j \leq \ms{ndim} ~, \end{equation}

   over the range \((-1, +1)\), where \(\ms{ndim}\) represents the rank of the correlation matrix.
   Larger values of \(\eta\) lead to random correlation matrices with more homogeneous structure.
   Smaller values of \(\eta\) lead to random correlation matrices with more heterogeneous structure with strong correlations along some dimensions.
   The resulting correlation matrix can be arbitrarily scaled along different dimensions to generate power-law randomly-distributed covariance matrix.
   

See also

pm_distBeta

Test:

test_pm_distCov

Todo:

Critical Priority: The output square matrices from the onion method are frequently non-positive-definite, particularly in higher dimensions.
A closer look into the root causes of this instability must be done.

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Monday March 6, 2017, 3:22 pm, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin.

Variable Documentation

dvine

type(dvine_type), parameter pm_distCov::dvine = dvine_type()

The scalar constant of type dvine_type implying the use of the Dvine algorithm for generating random covariance matrices as described in algorithm of Lewandowski et al. (2009).

See the documentation of pm_distCov for details.

Possible calling interfaces ⛓

use pm_distCov, only: dvine

Note

See the documentation of getCovRand for example usage.

See also

gram
dvine
onion
gram_type
dvine_type
onion_type
getCovRand
setCovRand

Test:

test_pm_distCov

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Monday March 6, 2017, 3:22 pm, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin.

Definition at line 238 of file pm_distCov.F90.

gram

type(gram_type), parameter pm_distCov::gram = gram_type()

The scalar constant of type gram_type implying the use of the Gram algorithm for generating random covariance matrices.

See the documentation of pm_distCov for details.

Possible calling interfaces ⛓

use pm_distCov, only: gram

Note

See the documentation of getCovRand for example usage.

See also

gram
dvine
onion
gram_type
dvine_type
onion_type
getCovRand
setCovRand

Test:

test_pm_distCov

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Monday March 6, 2017, 3:22 pm, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin.

Definition at line 157 of file pm_distCov.F90.

MODULE_NAME

character(*, SK), parameter pm_distCov::MODULE_NAME = "@pm_distCov"

Definition at line 79 of file pm_distCov.F90.

onion

type(onion_type) pm_distCov::onion = onion_type()

The scalar module variable object of type onion_type implying the use of the Onion algorithm for generating random covariance matrices as described in algorithm of Lewandowski et al. (2009).

Unlike dvine which is a scalar parameter, onion is a module variable, whose presence is merely for convenience.
As such, this variable's usage must be restricted to only experimental or serial applications, because this object is not thread-safe.

See the documentation of pm_distCov for details.

Possible calling interfaces ⛓

use pm_distCov, only: onion
print *, onion%info

Warning

The use of module variable can become a thread safety problem in parallel shared memory applications.
All it takes to resolve this thread safety is to not use this variable and declare a local object of type onion_type instead.

Note

See the documentation of getCovRand for example usage.

See also

gram
dvine
onion
gram_type
dvine_type
onion_type
getCovRand
setCovRand

Test:

test_pm_distCov

Final Remarks ⛓

---

If you believe this algorithm or its documentation can be improved, we appreciate your contribution and help to edit this page's documentation and source file on GitHub.
For details on the naming abbreviations, see this page.
For details on the naming conventions, see this page.
This software is distributed under the MIT license with additional terms outlined below.

1. If you use any parts or concepts from this library to any extent, please acknowledge the usage by citing the relevant publications of the ParaMonte library.
   
2. If you regenerate any parts/ideas from this library in a programming environment other than those currently supported by this ParaMonte library (i.e., other than C, C++, Fortran, MATLAB, Python, R), please also ask the end users to cite this original ParaMonte library.
   

This software is available to the public under a highly permissive license.
Help us justify its continued development and maintenance by acknowledging its benefit to society, distributing it, and contributing to it.

Copyright

Computational Data Science Lab

Author:

Amir Shahmoradi, Monday March 6, 2017, 3:22 pm, Institute for Computational Engineering and Sciences (ICES), The University of Texas at Austin.

Definition at line 331 of file pm_distCov.F90.