The MUR package implements R functions for mass univariate analysis of three-dimensional phenotypes.
Currently this package is only available on GitHub and requires R (>= 3.3.2). For installation, the easiest way is using devtools
. If you don’t have devtools
installed, please start by typing:
install.packages("devtools")
library(devtools)
Then, to install the package just use install_github
function.
install_github("Marjola89/MUR")
The following packages are not available on CRAN so they may need to be installed seperately.
multtest
if (!require("BiocManager", quietly = TRUE)) install.packages("BiocManager") BiocManager::install("multtest")
mutools3D
install.packages("devtools") library(devtools) install_github("UK-Digital-Heart-Project/mutools3D", build_vignettes = TRUE)
First prepare matrices X and Y in .rds files e.g S2S_kidney_left.rds
for the model that will be used in Mass Univariate Analysis code.
model <- loadingdata(fileClinicalDataPath, folderImagingDataPath, indVar, nPoints, organ)
Input parameters:
fileClinicalDataPath
: Set the path of the file containing the clinical data of the subjects for all the models e.g."/home/yourname/clinicaldata-path/data/ClinicalData.csv"
.folderImagingDataPath
: Set the path of the folders storing the image data e.g."/home/yourname/folder-path/"
.phenotype
: Define the imaging phenotype e.g.1
for S2S,2
for Curvature.nPoints
: Set the number of points (vertices) in the mesh, this will change for each organ e.g. for kidney left:4380
.organ
: Set organ segmentation e.g."liver"
,"spleen"
,"kidney_left"
etc.
Output parameters:
model
: a list including the design matrixX
, the imaging matrixY
, the matrix with x-coordinatesX_coordinate
, the matrix with y-coordinatesY_coordinate
and the matrix with z-coordinatesZ_coordinate
.
Notes:
- It is essential to saved the output as:
phenoType <- c(1, 2)
# 1 = S2S, 2 = Curvature
phenotypeNames <- c("S2S","Curvature")
for(iM in 1:length(phenotype)){
model <- loadingdata(fileClinicalDataPath, folderImagingDataPath, phenotype[iM], nPoints, organ)
X <- model[[1]]
Y <- model[[2]]
Xc <- model[[3]]
Yc <- model[[4]]
Zc <- model[[5]]
saveRDS(X, paste(data_dir, phenotypeNames[phenotype[iM]], "_", organ, "_clinicalData.rds", sep = ""))
saveRDS(Y, paste(data_dir, phenotypeNames[phenotype[iM]], "_", organ, ".rds", sep = ""))
saveRDS(Xc, paste(data_dir, phenotypeNames[phenotype[iM]], "_", organ, "_Xcoordinate.rds", sep = ""))
saveRDS(Yc, paste(data_dir, phenotypeNames[phenotype[iM]], "_", organ, "_Ycoordinate.rds", sep = ""))
saveRDS(Zc, paste(data_dir, phenotypeNames[phenotype[iM]], "_", organ, "_Zcoordinate.rds", sep = ""))
}
data_dir
: is the path of the data directory were the matrices X and Y for the model will be saved.
This is needed for the Mass Univariate Analysis. Usage:
NN_Area <- create_nnlist_area(mesh_Coordinates, dpl)
Input parameters:
mesh_Coordinates
: The matrix from the 3D model mesh of the template.dpl
: A list describing the structure of the dummy points to be added to the data being triangulated. e.g.list(ndx = 1.5, ndy = 1.5)
. If the argument isNULL
then no dummy point is added to the data. ndx: The x-dimension of a rectangular grid; if either ndx or ndy is null, no grid is constructed. ndy: The y-dimension of the aforementioned rectangular grid.
Notes:
- Alternative way to create NN matrices and area is using
computeNNmatrix
andcomputeVertAreas
from the R packagemutools3D
.
Computes the associations between the 3D mesh-derived phenotype (e.g. signed distances) and other clinical variables using a linear regression framework.
Run the Mass Univariate Analysis with TFCE using the system's cores.
mur_analysis <- mass_univariate_analysis(inputClinical, Y, A, NNmatrix, mesh_Coordinates, phenotype, organ, scale_range, nPermutations, extract_range, output_dir)
This code is dependent on three functions (~/function/murq.R
, ~/function/permFL_fast.R
and ~/function/TFCE.R
) which are called within the code.
Input parameters:
X
is the design matrix. Number of rows = number of subjects in the study, number of columns = number of vertices in the atlas. Numerical variable must be normalized to 0-mean and unit-standard deviation. Categorical variables must be coded using dummy coding. The first column should contain the intercept (all 1s).Y
is the imaging matrix. Number of rows = N. Number of columns = V.A
a V-dimensional vector containing the area associated with a vertex, usually its Voronoi area.NNmatrix
Nx2 matrix containing the mesh edges.mesh_Coordinates
: The matrix from the 3D model mesh of the template.phenotype
: Define the imaging phenotype e.g."S2S"
,"Curvature"
.organ
: Set organ segmentation e.g."liver"
,"spleen"
,"kidney_left"
etc.nPermutations
: Number of permutation testing e.g.1000
.extract_range
: Range of the independent variables to extract the beta coefficients and p-values after MUR analysis e.g.c(2, 5:8)
.output_dir
: Set the path of the output directory were the output with the coefficients and p-values for each covariate are saved as a.txt
file.
Notes:
- For more information on how to run the
mass_univariate_analysis
code see themutools3D
documentation.
Sub-functions for computing the mass univariate regression analysis
-
murq.R
for the mass univariate regression analysis across the mesh vertices.result <- murq(X, Y, extract)
-
permFL_fast.R
for the permutation the data and applying TFCE.TFCEresults <- permFL_fast(X, Y, extract, A, NNmatrix, nPermutations, E = 0.5, H = 2)
Input parameters:
X
is the design matrix. Number of rows = number of subjects in the study, number of columns = number of vertices in the atlas. Numerical variable must be normalized to 0-mean and unit-standard deviation. Categorical variables must be coded using dummy coding. The first column should contain the intercept (all 1s).Y
is the imaging matrix. Number of rows = N. Number of columns = V.extract
is an array expressing which covariates in X you want to extract.A
a V-dimensional vector containing the area associated with a vertex, usually its Voronoi area.NNmatrix
Nx2 matrix containing the mesh edges.nPermutations
number of permutations in the permutation test, default is 1000.E
is the TFCE parameter, by default fixed to 0.5.H
is the TFCE parameter, by default fixed to 2.
Notes:
TFCE.R
function is used from the R packagemutools3D
.murq.R
andpermFL_fast.R
functions are similar to the functionsmur.R
andpermFL.R
of themutools3D
package however, they are enhanced to allow process of big datasets.