| Title: | Region-Level Connectivity Network Construction via Kernel Canonical Correlation Analysis |
|---|---|
| Description: | It is designed to calculate connection between (among) brain regions and plot connection lines. Also, the summary function is included to summarize group-level connectivity network. Kang, Jian (2016) <doi:10.1016/j.neuroimage.2016.06.042>. |
| Authors: | Xubo Yue [aut], Jian Kang [cre] |
| Maintainer: | Jian Kang <[email protected]> |
| License: | LGPL |
| Version: | 0.1.0 |
| Built: | 2025-03-05 04:03:23 UTC |
| Source: | https://github.com/kangjian2016/brainkcca |
This is data to be included as example
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
This function can create a list of significant (threshold is defined by user) region pairs.
meanConnection(path = getwd(), threshold = 0.2)meanConnection(path = getwd(), threshold = 0.2)
path |
the path where csv files located |
threshold |
the threshold for significance of percentage of connection (if percentage exceeds threhold, then the region pair is significant). Typically, it can be 15-30%. |
you need to specify the path where csv files (containing KCCA information)locoated. This function will read all csv files listed in the path.
the object containing significant regions.
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
#It will take more than 3 min to run filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10)) summary_result1 <- summary_kcca(kcca_object=result1, saveFormat = "excel") write.csv(summary_result1, paste(filePath, "/", "temp.csv", sep="")) summary_data <- meanConnection(path = filePath, threshold=0.25) multipleRegion_plot(summary_data, significance=NA)#It will take more than 3 min to run filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10)) summary_result1 <- summary_kcca(kcca_object=result1, saveFormat = "excel") write.csv(summary_result1, paste(filePath, "/", "temp.csv", sep="")) summary_data <- meanConnection(path = filePath, threshold=0.25) multipleRegion_plot(summary_data, significance=NA)
This function can draw connection line(s) among multiple brain regions, based on the result from funciton permkCCA_multipleRegion(...).
multipleRegion_plot(input, significance = 0.05, regionCodeProvided = FALSE, view = "coronal", color = "blue", screenShot = "None")multipleRegion_plot(input, significance = 0.05, regionCodeProvided = FALSE, view = "coronal", color = "blue", screenShot = "None")
input |
it can accept two types of argument: (1) output generated by "permkCCA_multipleRegion(...)" (with p value). (2) output generated by summary_kcca() or meanConnection() (without p value). |
significance |
significance level of hypothesis testing. If there is no p value in your data (i.e. only region name and region index, then set significance as NA) |
regionCodeProvided |
use TRUE if region code was provided in nii2RData() funciton and FALSE if not. |
view |
view of brain to see. One can choose coronal, axial, SL, or SR. |
color |
color of dots and lines. User can specify multiple colors in this argument and the function will use these colors periodically. |
screenShot |
whether to save figure as png. If it is "None", then the figure will not be saved; If it is a name, for example, "plot.png", then it will be saved as "plot.png". |
If you provide an input with multiple patients, the function will ask you to specify which patients data you would like to use.
1-4 view(s) (depends on the number of views user would like to see) of brain graphic network. All significant regions are connected by colored lines.
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
#It will take more than 3 min to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10)) multipleRegion_plot(result1, view="axial")#It will take more than 3 min to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10)) multipleRegion_plot(result1, view="axial")
This function can take NIfTI data file(s) (the file extension is "nii.gz" or "nii") as input (you only need to specify the name of file before extension) and transform them into RData file(s) (in the form of .RData).
nii2RData(niiFile1, resolution = "2mm", saveName = "None", regionCode = "", niiFile2 = "", imgPath = getwd(), datPath = getwd())nii2RData(niiFile1, resolution = "2mm", saveName = "None", regionCode = "", niiFile2 = "", imgPath = getwd(), datPath = getwd())
niiFile1 |
the NIfTI data file(s) (containing information of fMRI of patient(s)) you would like to use. If you want to read more than one file, you can either type in the name in the form of vector string, or call this function for several times. |
resolution |
the resolution of your region data. It can take "2mm" as default. If user would like to use 3mm resolution, type in "3mm". |
saveName |
whether to save processed imaging data. If you do not have enough space or do not want to use space to store processed data, just type in "None" (default); otherwise you need to specify name in this argument. For example, saveName="myName.RData". |
regionCode |
the region code provided by user or default. It should have 3 columns with index, region code and region name. |
niiFile2 |
the NIfTI region file you would like to use. It has default NIfTI file and can be left as blank if no region file provided. |
imgPath |
the directory where your NIfTI file(s) is (are) located. It chooses your current working directory as default. |
datPath |
the directory where you would like to store .RData file(s). It chooses your current working directory as default. |
This function must accept the NIfTI imaging data as argument to manipulate
the raw data to processed R data. The file extension is "nii.gz" or "nii".
You only need to specify the name of file without extension in the function argument.
For example, your interested imaging file is called "brain.nii.gz" or "brain.nii".
You only need to write niiFile1="brain" in the first argument rather than "brain.nii.gz"
or something else. The package can either use its default region code and region data
or use user-defined region information.
Here are some notes which may be useful:
(1) When reading multiple imaging files, make sure they have the same resolution,
region code and region data.
(2) If you would like to read multiple imaging files, and if you did not use
saveName="None" argument, it can sometimes take a large storage. For example,
if you read 100 files, then 100 "RData" files will be generated and thus take
a large storage space. Thus, saveName="None" is highly recommended in this case.
the processed imaging data.
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
#It will take more than 10 s to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath)#It will take more than 10 s to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath)
This function is the core part for kernel canonical correlation analysis. Generally you do not need to use this function unless you are famaliar with kcca algorithm.
perm_kCCA(x, y, sig = 0.1, gama = 0.1, ncomps = 1, permNum = 50, kernel = "rbfdot") perm_kCCA_par(x, y, sig = 0.1, gama = 0.1, ncomps = 1, permNum = 500, kernel = "rbfdot")perm_kCCA(x, y, sig = 0.1, gama = 0.1, ncomps = 1, permNum = 50, kernel = "rbfdot") perm_kCCA_par(x, y, sig = 0.1, gama = 0.1, ncomps = 1, permNum = 500, kernel = "rbfdot")
x |
region 1, a matrix containing data index by row. |
y |
region 2, a matrix containing data index by row. |
sig |
inverse kernel width for the Radial Basis kernel function "rbfdot" and the Laplacian kernel "laplacedot". |
gama |
regularization parameter (default: 0.1). |
ncomps |
number of canonical components (default: 1). |
permNum |
number of permutation (default 50). |
kernel |
type of kernel. |
Kernel canonical correlation analysis (KCCA) can explore the nonlinear relationship between two variables. It transformed sample vectors into the Hilbert space and maximize correlation coefficient by solving quadratically regularized Lagrangean function. Refer to Kang's paper for more details: Kang J, Bowman FD, Mayberg H, Liu H (2016). "A depression network of functionallyconnected regions discovered via multi-attribute canonical correlation graphs."NeuroImage,141, 431-441.
(lists of) list of region index, p-value, region type ("two" or "multiple"), and region name.
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
https://www.ncbi.nlm.nih.gov/pubmed/27474522
This function can calculate strength of the connectivity among multiple brain regions via kernel canonical correlation analysis. Permutaiton test is employed to assess the statistical significance. The p-values are adjusted for multiple testing.
permkCCA_multipleRegion(imageDat, region, resolution = "2mm", saveName = "None", kernel = "rbfdot", regionCode = "", niiFile2 = "", imgPath = getwd(), datPath = getwd(), parallel = FALSE, loc = "local", perm = 50, saveData = "None")permkCCA_multipleRegion(imageDat, region, resolution = "2mm", saveName = "None", kernel = "rbfdot", regionCode = "", niiFile2 = "", imgPath = getwd(), datPath = getwd(), parallel = FALSE, loc = "local", perm = 50, saveData = "None")
imageDat |
there are two options for this argument: (1)(vectors of) imaging data (with extension .nii or .nii.gz). You do not need to add extension in your argument, simply type in the name of file is enough. (2) the processed image data produced by "nii2RData" function. No matter which option you choose, the result will be the same (as long as you use the same dataset). When you would like to read and save nii data first and run kcca test later, you can first save output of "nii2RData" and, in the future, choose option (2) to run kcca in order to save time (avoid reading same dataset multiple times). |
region |
user-specified multiple brain regions (as vector, for example, c(1,2,30)). |
resolution |
the resolution of your region data. It can take "2mm" as default. If user would like to use 3mm resolution, type in "3mm". |
saveName |
whether to save processed imaging data. If you do not have enough space or do not want to use space to store processed data, just type in "None" (default); otherwise you need to specify name in this argument. For example, saveName="myName.RData". |
kernel |
the kernel function used in training and predicting. The default kernel is the radial basis kernel function "Gaussian" (rbfdot). Use "?kernlab::kcca" to find more available kernels. |
regionCode |
the region code provided by user or default. It should have 3 columns with index, region code and region name. |
niiFile2 |
the nii region file you would like to use. It has default nii file and can be left as blank. |
imgPath |
the directory where your nii file(s) is (are) located. It chooses your current working directory as default. |
datPath |
the directory where you would like to store .RData file(s). It chooses your current working directory as default. |
parallel |
whether to use parallel computing. Type FALSE as not using parallel and TRUE as using parallel. Parallel is not recommended in local computer as it may slow down your system. Use parallel in cluster is preferred |
loc |
this argument can accept argument "local" or "cluster". if you choose to use parallel computing, please specify whether you run your code in your local computer or cluster. If you did not choose parallel computing, then "local" or "clutser" makes no difference. |
perm |
number of permutation. Default time is 50. |
saveData |
whether to save output as R data. Type "None" as not save output. Type name of file if you would like to save. For example, "output_two.RData". |
(1) Kernel canonical correlation analysis (KCCA) can explore the nonlinear relationship between two variables. It transformed sample vectors into the Hilbert space and maximize correlation coefficient by solving quadratically regularized Lagrangean function. Refer to Kang's paper for more details: Kang J, Bowman FD, Mayberg H, Liu H (2016). "A depression network of functionallyconnected regions discovered via multi-attribute canonical correlation graphs."NeuroImage,141, 431-441. (2) Use rgl.snapshot() function if you would like to save plot but forgot to use TRUE in screenShot argument.
(lists of) list of brain regions, p-value, region type ("two" or "multiple"), and sregion name.
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
https://www.ncbi.nlm.nih.gov/pubmed/27474522
#It will take more than 10 s to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10))#It will take more than 10 s to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10))
This function can print information of kcca object for single object.
summary_kcca(kcca_object, significance = 0.05, patientID = 1, saveFormat = "markdown", threshold = 0.2)summary_kcca(kcca_object, significance = 0.05, patientID = 1, saveFormat = "markdown", threshold = 0.2)
kcca_object |
the result generated by permkCCA_multipleRegion function. This argument can also accept an adjacent matrix containing information of connectinity network. This matrix must have row names or column names, which define the region index. For example, column names with 1, 5, 10 means region 1, 5 and 10. |
significance |
significance level of hypothesis testing |
patientID |
if you have more than one patient in the kcca_object, you need to specify which patient you would like to summarize. If you have only one patient, then the default patientID is 1. |
saveFormat |
a character string; possible values are excel, latex, html, markdown, etc.; it can also be set in the global option knitr.table.format; if format is a function, it must return a character string. If you specify saveFormat="group", then this function can help you summarize group level information for all patients. |
threshold |
the threshold for significance of percentage of connection (if percentage exceeds threhold, then the region pair is significant). Typically, it can be 15-30%. |
After you obtained results from permkCCA_multipleRegion() function,
there are two ways to summarize and save information of
kcca objects at group level (i.e. construct region-level conenctivity network):
(1) for each patient i, you can spcify patientID = i and saveFormat="excel",
and then store the output in csv files. The generated csv files have 7 columns:
row number, index1, index2, region1, region2, pvalue, indicator of significance,
and count flag (always 1). See example 1 for more information.
(2) if you do not want save information in csv files, you can specify
saveFormat="group" abd then this function can help you summarize group
level information for all patients. The output variables have 7 columns: row number, index1,
index2, region1, region2, pvalue, indicator of significance, and count flag (always 1).
If you want to save data as other format such as latex, you can directly copy
the generated latex code to your tex file. See example 3 for more information.
Note that if returned object has length 0 (i.e. no connection), then warning message will be generated.
Xubo Yue, Chia-Wei Hsu (tester), Jian Kang (maintainer)
#It will take more than 10 s to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10)) summary_kcca(result1)#It will take more than 10 s to run #write data into temp file filePath <- tempdir() #the nii.gz fMRI imaging file is created (toy example) oro.nifti::writeNIfTI(brainKCCA::input_img, paste(filePath, "/", "temp", sep="")) #read fMRI data testcase1 <- nii2RData(niiFile1 = "temp", resolution = "3mm", imgPath = filePath) result1<-permkCCA_multipleRegion(imageDat = testcase1, region = c(1,5,10)) summary_kcca(result1)