DensParcorr: Conduct the Dens-Based approach for partial correlation...

Description Usage Arguments Details Value Author(s) References Examples

View source: R/DensParcorr.R

Description

This function is to conduct the Dens-based approach for partial correlation estimation in large scale brain network study.
DensParcorr is the main function in this package. prec2dens and prec2part are sub-functions called by DensParcorr.

Usage

1
2
DensParcorr(data,select=FALSE,dens.level="plateau",plateau.thresh=0.01,
            Parcorr.est=NULL,directory=NULL,lambda=NULL)

Arguments

data

Input data matrix with dimension of TxM where T is the number of observations and M is the number of nodes. For example, in fMRI data the T is the number of scans.

select

Whether to conduct the Dens-based selection. If FALSE, output will only contain the estimated partial correlation list and precision matrix list corresponding to the default tuning parameter series ranging from 1e-8 to 0.6. If TRUE, the ouput will include the previous results and the selected partial correlation matrix and percision matrix corresponding to the specified density level. Default is FALSE.

dens.level

Specify the density level in Dens-based tuning parameter selection method, including the plateau based density selection (dens.level = "plateau") and p percentage density selection (dens.level = p, 0<p<1). This option is valid only when select=TRUE. See Details. Default is "plateau".

plateau.thresh

The criterion to select the plateau. This option is valid only when select=TRUE. See Details. Default value is 0.01.

Parcorr.est

Previous output from DensParcorr function.

directory

The directory to output the figures and precision matrices and the partial correlation matrices. The default (directory=NULL) is to output in the current working directory.

lambda

The lambda value for estimating the precision matrix ranging from 0 to 1. The default is NULL. If specified, no extra Dens-based step will be conducted.

Details

This function implements the statistical method proposed in Wang et al. (2016) to estimate partial correlation matrix for studying direct connectivity in large-scale brain network. The method derives partial correlation based on the precision matrix estimated via Constrained L1-minimization Approach (CLIME) (Cai et al., 2011). This function applies the Dens-based tuning parameter selection method in Wang et al. (2016) to help select an appropriate tuning parameter for sparsity control in the network estimation. Below is the breif step of Dens-based approach.

First, we specify a series of tuning parameters {λ_n}. Then, based on {λ_n} we esimate a list of precision matices Ω(λ_n) and and evaluate the density level of each precision matrix based on the Dens criterion function in equation (5) of Wang et al. (2016). This will provide the users the profile of the density level corresponding to the series of tuning parameters in {λ_n}. Users can use the dens.level option to specify the desired density level in the precision matrix estimation. If dens.level="plateau", the function will select the plateau point λ_{platu} in the density profile based on the plateau.thresh and output the precision matrix Ω(λ_{platu}). If dens.level=p and 0<p<1, the function will select the tuning parameter λ_p to achieve p percentage density and output the precision matrix Ω(λ_p). Then, the partial correlation matrix will be derived from the precision matrix. Further details can be found in the Reference.

The density profile and the heatmaps of precision matrices and partial correlation matrices will be saved in directory, and the esimated list of precision matrices and partial correlation matrices will also be saved in directory.

When users would like to run the function multiple times on the same input data for different dens.level, it is computationally more efficient to read in the previous output from DensParcorr to Parcorr.est so that the function won't need to re-estimate the partial correlations based on the previous tuning parameters.

Value

An R list from DensParcorr containing the following terms:

selected.partial.corr

Selected Partial Correlation matrix corresponding to dens.level. Only when select=TRUE.

selected.precision

Selected Precision matrix corresponding to dens.level. Only when select=TRUE.

selected.lambda

Selected tuning parameter corresponding to dens.level. Only when select=TRUE.

lambda.list

The series of tuning parameters used for esimation and density profile.

partial.corr.list

Estimated Partial Correlation matrix list corresponding to lambda.list.

precision.list

Estimated Precision matrix list corresponding to lambda.list.

Dens

Actual density levels for estimated precision matrix list.

Dens.Percentage

Actual percentage density levels for estimated precision matrix list.

selection.method

The method used for tuning parameter selection. For percentage Dens selection, this value will include the actual Dens precentage and the nominal Dens percentage. Only when select=TRUE.

Author(s)

Yikai Wang, Jian Kang, Phebe Brenne Kemmer and Ying Guo
Maintainer: Yikai Wang yikai.wang@emory.edu

References

Wang, Y., Kang, J., Kemmer P. and Guo, Y. (2016). An efficient and reliable statistical method for estimating functional connectivity in large scale brain networks using partial correlation. Front. Neurosci. 10:123. doi: 10.3389/fnins.2016.00123

Cai, T.T., Liu, W., and Luo, X. (2011). A constrained \ell_1 minimization approach for sparse precision matrix estimation. Journal of the American Statistical Association 106(494): 594-607.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# require(gplots)
# require(clime)

## Simulated the data to use. 
# data = matrix(rnorm(200),ncol=20)

##### Example 1: Estimate the partial correlation matrices for the 
##### default series of tuning parameters. 
# t0 = proc.time()[3]
# dens.est = DensParcorr(data,select=FALSE)
# proc.time()[3]-t0

##### Example 2: Estimate the network that reaches 40% density level. 
# partial.dens.est = DensParcorr(data,dens.level  =.4,select=TRUE)

###### Example 3: Now, estimate the 60% density level network based 
###### on the same data. To speed up computation, we read in the 
###### previous output from Example 2 into Parcorr.est
# t0 = proc.time()[3]
# partial.dens.est2 = DensParcorr(data, Parcorr.est = partial.dens.est,
#                                 dens.level=.6,select=TRUE)
# proc.time()[3]-t0

DensParcorr documentation built on May 2, 2019, 3:33 p.m.