FCnet_overview_of_package
Elvio Blini
December 2020
FCnet_overview_of_package.RmdIntroduction
The analysis of (Functional Connectivity) neuroimaging data can be daunting due to the very high dimensionality of the features involved. In time, several approaches to the problem have been devised. FCnet allows one to easily implement a three steps procedure consisting of:
Feature reduction: the functional connectivity matrices are first summarized through data reduction techniques such as Principal Component Analysis or Independent Components Analysis.
Robust regression: the reduced matrix of Weights is then entered into a robust regression model (with either ridge or LASSO penalty). The model is crossvalidated internally by means of Leave-One-Out (nested) crossvalidation.
Back-projection: models’ coefficients can be back-projected onto the original space, in order to rank the most predictive edges of a matrix.
For useful references, see: Siegel et al., 2016; Salvalaggio et al., 2020; Calesella et al., 2020.
This vignette will provide an overview of FCnet main routines.
Setting up the simulation
We will need the following packages:
library("FCnet") #for the main analysis routines## Loading required package: glmnet## Loading required package: Matrix## Loaded glmnet 4.1-1## Loading required package: glmnetUtils##
## Attaching package: 'glmnetUtils'## The following objects are masked from 'package:glmnet':
##
## cv.glmnet, glmnet
library("ggplot2") #beautiful depictions
library("gridExtra") #arrange plots
library("future.apply") #for speed and parallel computing## Loading required package: futureIn order to use your own set of matrices, you should make sure that these are imported in R as a list of lists. You can use several approaches in order to do that. The easiest way is probably to use loadFC(), which comes with the package FCnet:
my_matrices= FCnet::loadFC()Matrices should be stored as .csv files in a folder, and with specific formatting requirements.
The FCnet package comes with a 324x324 matrix of functional connectivity data obtained from 37 participants. We use it, in this overview, as a starting point to simulate several FC matrices which will help to illustrate the main functions of FCnet.
data("MeanFC") #the object MeanFC is now available
set.seed(1)
N_subs= 50 #number of participants/matrices
subjs_variability= 0.2 #variability (sd) between matrices
#this function creates several matrices by adding gaussian noise
#with sd "variability" to a reference matrix
m_start= simulateMat(mat = MeanFC,
Nmat = N_subs,
mat_variability = subjs_variability)m_start is now a list of lists, the preferred format of FCnet, including several FC matrices putatively obtained from different individuals.
Now we perturb only one subset of these matrices (i.e. a network), in a very crude way, just to illustrate FCnet.
Specifically, we bias one network systematically, as a function of one behavioral score y (to be recovered in a subsequent step). In this scenario, a subset of edges will be injected with signal that is directly related to the behavioral score to be ultimately predicted: these edges will be correlated with the score y. To have a more realistic simulation, this bias will not be constant but rather modulated by a random factor such that different participants may present different degrees of this bias.
y= rnorm(N_subs, mean = 0, sd= 1) #the behavioral score
network1= 50:100 #network to perturb
network2= 200:250 #network to perturb
bias_multiplier= 0.6 #mean signal to inject (i.e. mean correlation with y)
bias_variability= 0.2 #variability - sd - around this mean signal
#this function biases a given network as a function
#of a behavioral score y
m_bias= biasMat(matrices = m_start,
y = y,
network1 = network1,
network2 = network2,
bias_multiplier = bias_multiplier,
bias_variability = bias_variability,
mat_variability = subjs_variability)We now have two sets of matrices: the starting set m_start, in which no signal has been added; the biased set m_bias, in which connections in a given subnetwork have been biased according to y. We will use the latter to test whether we can fit a predictive model and whether the most predictive edges fall within the subnetwork that we have perturbed.
The utility function plotFC gives a graphical depiction of a FC matrix. We can plot a representative participant:
#this adds a grid on the plot corresponding to the
#network which was perturbed
grid_net= list(geom_rect(aes(xmin= min(network1),
xmax= max(network1),
ymin= min(network2),
ymax= max(network2)),
size= 1.05, color= "black",
fill= "transparent"))
ps= plotFC(m_start[[which.max(y)]], #we plot one specific matrix
lim = c(-1, 1)) + ggtitle("Start") + grid_net
pb= plotFC(m_bias[[which.max(y)]],
lim = c(-1, 1)) + ggtitle("Bias") + grid_net
#arrange plots
grid.arrange(ps, pb)
Indeed, we can plot the correlation map:
f_cor= function(lst, y){
n= length(lst)
rc= dim(lst[[1]])
ar1= array(unlist(lst), c(rc, n))
apply(ar1, c(1, 2), function(x)(cor(x, y)))
}
cor_bias= f_cor(m_bias, y) #warnings due to vectors being identical (e.g. diagonal)
plotFC(cor_bias) + ggtitle("Correlation map") + grid_net
We have indeed injected correlation between edges and the behavioral score in the highlighted region of the correlation matrix. The mean correlation is 0.6. We can also plot the variability between FC matrices, just to show that the only signal injected is correlation between edges and the behavioral score, not noise.
f_sd= function(lst){
n= length(lst)
rc= dim(lst[[1]])
ar1= array(unlist(lst), c(rc, n))
apply(ar1, c(1, 2), function(x)(sd(x)))
}
bias_sd= f_sd(m_bias)
plotFC(bias_sd, limit = c(0.15, 0.25)) + ggtitle("Variability") + grid_net
Features reduction
Once we have obtained all the simulated matrices, we can chain all the FCnet main functions in order to see whether models are predictive or not, and whether we can reconstruct the network that we have artificially biased.
We start with performing feature reduction through PCA. By default, reduce_featuresFC() performs Principal Component Analysis (PCA) and returns, in the Weights slot, the components that explain at least 95% of the variance in the matrices. Other available techniques include Independent Component Analysis (ICA). Being this a very crude simulation, with our main bias probably tapping on the first few components, we will only ask the function to retain 10 features. Note that signal is usually more distributed in the matrices, thus this is rather artificial; a better simulation would perturb random edges, but that would be less visually clear within the scope of this overview.
rf_bias= reduce_featuresFC(FCmatrices = m_bias,
Ncomp = 10) Modelling
We can run Leave-One-Out (nested cross-validated by default) robust regressions with one line:
optionsFCnet("nested"= F)
r_bias= FCnetLOO(y = y,
x = rf_bias,
alpha= 0, #ridge regression
parallelLOO = F)
r_bias$R2## [1] 0.4439749It appears that this model is capable to explain about 44% of the variance from LOO observations.
A graphical depiction of the fit or coefficients can be obtained with plotFCnet():
plotFCnet(model = r_bias,
plot_labels = F) #avoid padding, otherwise useful## `geom_smooth()` using formula 'y ~ x'
plotFCnet(model = r_bias,
output = "coefficients") 
As can be seen from the second plot, perhaps the model is still overparametrized, and the first coefficient seems to drive this effect. This is certainly due to the crude assumptions of this simulation.
A far more compelling proof, however, would be back-projection. Ideally, relevant edges will be scattered all around the matrix for non-predictive models, but will be more centered on the network (or interaction between networks) that we perturbed for really informative ones.
Visualization and back-projection
We ensure that back-projected coefficients properly identify the network that we perturbed:
bp_bias= backprojectFCnet(coeffs = r_bias,
reduce_features_object = rf_bias,
normthresh = F,
threshold = length(network1)*length(network2))
plotFC(bp_bias) + grid_net
Indeed, predictive edges appear to highlight the exact same network we perturbed as the most relevant one, on top of a few spurious edges.
Back-projection by default computes the linear contribution to the behavioral score for all edges through the estimated coefficients. We checked before individual coefficients with plotFCnet: the most predictive component was the first one (note that this is a very crude simulation after all!). We can back-project only the edges tapping on this first component:
bp_first= backprojectFCnet(coeffs = 1,
reduce_features_object = rf_bias,
threshold = length(network1)*length(network2))## Warning in backprojectFCnet(coeffs = 1, reduce_features_object = rf_bias, : Parameter threshold disregarded because normthresh is TRUE
plotFC(bp_first) + grid_net
Indeed, the first component mainly taps onto the network that we have biased. Edges have a negative loading on this feature, but they have a positive association with the behavioral score.
Testing significance: permutation test
Large R2 values may occur by chance or simply in light of the many predictors in the model - even though this problem is mitigated by using the LOO R2. In order to test whether this R2 is beyond chance, we can run a permutation test. Here, values of y are shuffled and then predicted. Ideally, the distribution of the models created in this way should cover - and inform about - the range of the null model.
Note that, in order to optimize computational resources, we only ask for 50 permutations (generally not enough) and, most importantly, we use parallel computing to optimize the procedure. When parallelLOO is TRUE, the outer cycles are run in parallel on multiple cores (if available) by using the package future.apply, which must be installed. In addition, plan(multisession or similar must be invoked in advance by the user.
plan(multisession) #prepare for parallel computing
set.seed(1)
perm_bias= permutateLOO(y = y,
x= rf_bias,
alpha = 0,
parallelLOO = T,
nperm = 50,
model_R2 = r_bias,
return_coeffs= T)##
|
| | 0%
|
|==================== | 2%
|
|======================================== | 4%
|
|=========================================================== | 6%
|
|=============================================================================== | 8%
|
|=================================================================================================== | 10%
|
|======================================================================================================================= | 12%
|
|========================================================================================================================================== | 14%
|
|============================================================================================================================================================== | 16%
|
|================================================================================================================================================================================== | 18%
|
|====================================================================================================================================================================================================== | 20%
|
|========================================================================================================================================================================================================================== | 22%
|
|============================================================================================================================================================================================================================================= | 24%
|
|================================================================================================================================================================================================================================================================= | 26%
|
|===================================================================================================================================================================================================================================================================================== | 28%
|
|========================================================================================================================================================================================================================================================================================================= | 30%
|
|============================================================================================================================================================================================================================================================================================================================ | 32%
|
|================================================================================================================================================================================================================================================================================================================================================ | 34%
|
|==================================================================================================================================================================================================================================================================================================================================================================== | 36%
|
|======================================================================================================================================================================================================================================================================================================================================================================================== | 38%
|
|============================================================================================================================================================================================================================================================================================================================================================================================================ | 40%
|
|=============================================================================================================================================================================================================================================================================================================================================================================================================================== | 42%
|
|=================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 44%
|
|======================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 46%
|
|=========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 48%
|
|============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 50%
|
|================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 52%
|
|====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 54%
|
|========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 56%
|
|============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 58%
|
|================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 60%
|
|===================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 62%
|
|========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 64%
|
|============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 66%
|
|================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 68%
|
|==================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 70%
|
|======================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 72%
|
|============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ | 74%
|
|================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================ | 76%
|
|=================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 78%
|
|======================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 80%
|
|=========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 82%
|
|=============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 84%
|
|=================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 86%
|
|====================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 88%
|
|========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 90%
|
|============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 92%
|
|================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 94%
|
|===================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================== | 96%
|
|========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================= | 98%
|
|=============================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================| 100%
knitr::kable(perm_bias$Summary)| Model_R2 | Permutations | P_value | Mean | SD | Upper_95 | Quantile_50 | Quantile_70 | Quantile_90 | Quantile_95 |
|---|---|---|---|---|---|---|---|---|---|
| 0.4439749 | 50 | 0 | 0.0167841 | 0.031879 | 0.0792669 | 0 | 0.0043456 | 0.0719234 | 0.0780952 |
The original model’s R2 is reported on the left. On the rightmost part of the row, a few statistics concerning the distribution of R2 from null models is reported. The full distribution is available to the user anyway in the created object through the relative slot. In this fictional scenario, and considering the low number of permutations, it appears that the original model beats most null models. Models can always be improved by crossvalidating the number of features to extract, which is now implemented in both FCnetLOO() and consequently permutateLOO(). In addition, selection of coefficients on the basis of permutated samples is now possible through the select_coefficients() function.
Conclusion
These simulations were based on crude assumptions and parameters. Yet, they were only meant to confirm that, in principle, the procedures in FCnet may help recovering the most predictive connections from very rich and multidimensional datasets. More simulations are needed to check its sensitivity and specificity.
Appendix
Packages’ versions:
## R version 4.0.3 (2020-10-10)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 10 x64 (build 19042)
##
## Matrix products: default
##
## locale:
## [1] LC_COLLATE=Italian_Italy.1252 LC_CTYPE=Italian_Italy.1252 LC_MONETARY=Italian_Italy.1252 LC_NUMERIC=C LC_TIME=Italian_Italy.1252
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] future.apply_1.7.0 future_1.21.0 gridExtra_2.3 ggplot2_3.3.3 FCnet_0.1.8.9000 glmnetUtils_1.1.8 glmnet_4.1-1 Matrix_1.2-18
##
## loaded via a namespace (and not attached):
## [1] Rcpp_1.0.7 lattice_0.20-41 listenv_0.8.0 assertthat_0.2.1 rprojroot_2.0.2 digest_0.6.27 foreach_1.5.1 utf8_1.2.1 parallelly_1.25.0 plyr_1.8.6 R6_2.5.0 evaluate_0.14 highr_0.8 pillar_1.6.0 settings_0.2.7 rlang_0.4.11 jquerylib_0.1.4 rmarkdown_2.7 pkgdown_1.6.1 labeling_0.4.2 textshaping_0.3.1 desc_1.2.0 splines_4.0.3 stringr_1.4.0 munsell_0.5.0 compiler_4.0.3 xfun_0.21 pkgconfig_2.0.3 systemfonts_1.0.1 shape_1.4.5 mgcv_1.8-33 globals_0.14.0 htmltools_0.5.1.1 tidyselect_1.1.0 tibble_3.1.1 codetools_0.2-16 fansi_0.4.2 crayon_1.4.1 dplyr_1.0.5 withr_2.4.2 grid_4.0.3 nlme_3.1-149 jsonlite_1.7.2 gtable_0.3.0 lifecycle_1.0.0 DBI_1.1.1 magrittr_2.0.1 scales_1.1.1 stringi_1.6.1 cachem_1.0.4 farver_2.1.0 reshape2_1.4.4 fs_1.5.0 bslib_0.2.4 ellipsis_0.3.2
## [56] ragg_1.1.1 generics_0.1.0 vctrs_0.3.8 iterators_1.0.13 tools_4.0.3 glue_1.4.2 purrr_0.3.4 parallel_4.0.3 fastmap_1.1.0 survival_3.2-7 yaml_2.2.1 colorspace_2.0-1 memoise_2.0.0 knitr_1.31 sass_0.3.1