| Title: | Functional Connectivity Tools |
| Version: | 2.3.1 |
| Date: | 2026-09-08 |
| Maintainer: | Charly Billaud <charly.billaud@ntu.edu.sg> |
| Description: | Analyzing and visualizing brain connectivity data, including network-based statistics (NBS) for linear and linear mixed models, both at edge level and functional network level (Yeo's 7-networks (Schaefer et al. (2017) <doi:10.1093/cercor/bhx179>)). Plots include edge-wise connectograms, chord diagrams, network connectograms, heatmaps, and 3D glass brain connectivity plots. 'FCtools' works with vectors of edges (derived from connectivity/adjacency matrices) from the 'Brainnetome' (Fan et al. (2016) <doi:10.1093/cercor/bhw157>), 'Schaefer' (100 or 200, each with 19 'ASeg' subcortices) (Schaefer et al. (2017) <doi:10.1093/cercor/bhx179>, Fischl et al. (2002) <doi:10.1016/S0896-6273(02)00569-X>), and 'Automated Anatomical Labeling' (AAL) atlases (Tzourio-Mazoyer et al. (2002) <doi:10.1006/nimg.2001.0978>). |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| LazyData: | true |
| URL: | https://cogbrainhealthlab.github.io/FCtools/ |
| RoxygenNote: | 7.3.3 |
| Depends: | R (≥ 4.1.0) |
| Imports: | Rfast, circlize, cowplot, doParallel, doSNOW, foreach, ggplot2, ggplotify, ggraph, grid, gridExtra, igraph, parallel, plotly, png, reshape2 |
| NeedsCompilation: | no |
| Packaged: | 2026-09-08 00:58:08 UTC; charly.billaud |
| Author: | Junhong Yu |
| Repository: | CRAN |
| Date/Publication: | 2026-09-15 13:10:08 UTC |
NBS
Description
Network-based statistics analysis
Usage
NBS(model, contrast, FC_data, nperm = 100, nthread = 1, p = 0.001)
Arguments
model |
A data.frame or matrix containing all the predictors in the model |
contrast |
The predictor of interest. The edge- and network-wise statistics will only be estimated for this predictor |
FC_data |
An N x E matrix containing the vectorized edges; where N = number of subjects, E=number of edges |
nperm |
The number of permutations to generate the null distribution of network strengths. Set to 100 by default |
nthread |
The number of CPU threads to use. Set to 1 by default |
p |
the edge-wise threshold. Set to 0.001 by default |
Details
This function implements the NBS analysis described in Zalesky et al. (2010) doi:10.1016/j.neuroimage.2010.06.041
Value
A list object containing
-
resultsEdge- and network-wise results in a data.frame object -
t.origEdge-wise t-stats -
tcritThe critical t-value -
max.netstrA vector containing the null distribution of the permuted network strengths
Examples
demomat=get('demomat')[,1:7021]
contrast=c(1,1,2,2)
random=c('sub1','sub2','sub3','sub4')
model1=NBS(model=contrast,
contrast=contrast,
FC_data=demomat,
nperm=2,
nthread=2,
p=0.001)
NBS
Description
Network-based statistics analysis
Usage
NBS_lme(
model,
contrast,
random,
FC_data,
nperm = 100,
nthread = 1,
p = 0.001,
perm_type = "row"
)
Arguments
model |
A data.frame or matrix containing all the predictors in the model |
contrast |
The predictor of interest. The edge- and network-wise statistics will only be estimated for this predictor |
random |
A N x 1 numeric vector or object containing the values of the random variable (optional). Its length should be equal to the number of subjects in model (it should NOT be inside the model data.frame). |
FC_data |
An N x E matrix containing the vectorized edges; where N = number of subjects, E=number of edges |
nperm |
The number of permutations to generate the null distribution of network strengths. Set to 100 by default |
nthread |
The number of CPU threads to use. Set to 1 by default |
p |
the edge-wise threshold. Set to 0.001 by default |
perm_type |
A string object specifying whether to permute the rows ("row"), between subjects ("between"), within subjects ("within") or between and within subjects ("within_between") for random subject effects. Default is "row". |
Details
This function implements the NBS analysis described in Zalesky et al. (2010) doi:10.1016/j.neuroimage.2010.06.041
Value
A list object containing
-
resultsEdge- and network-wise results in a data.frame object -
t.origEdge-wise t-stats -
tcritThe critical t-value -
max.netstrA vector containing the null distribution of the permuted network strengths
Examples
demomat=get('demomat')[,1:4005]
contrast=c(1,1,2,2)
random=c('sub1','sub2','sub3','sub4')
model1=NBS_lme(model=contrast,
contrast=contrast,
random=random,
FC_data=demomat,
nperm=1,
nthread=1,
p=0.001)
Demo data
Description
A small sample of 4 connectivity vector derived from 219x219 FC matrices generated using the Schaefer-200 atlas + 19 subcortical regions from the freesurfer subcortical segmentations.
Usage
demomat
Format
demomat
matrix with 4 rows (number of individuals), 23871 columns (edge weights)
edgelist
Description
Listing the edges in a connectogram.
Usage
edgelist(data)
Arguments
data |
a vector of edge values with a length of 4005, 7021, 23871 or 30135. |
Details
This function takes a vector of edge-to-edge connections, and returns a data.frame object containing the edges (defined by their pair of connecting nodes) and their edge values
Value
a data.frame() object with the columns of node_1, node_2 and weight columns
Examples
results=sample(c(1,0, -1), 7021, replace = TRUE, prob = c(0.01, 0.98,0.01))
edgelist(data=results)
edges_to_networks
Description
convert an edge level FC matrix into a network level FC matrix
Usage
edges_to_networks(FCmat)
Arguments
FCmat |
an FC matrix or vector |
Details
This function first identifies the unique network pairs in the appropriate FC atlas and then averages the edges within each of the network pairs
Value
A network level FC matrix
Examples
edges_to_networks(runif(23871))
extract.edges
Description
Generates edge-wise masks for calculating subject-level network strengths
Usage
extract.edges(NBS.obj, network = 1)
Arguments
NBS.obj |
A list object generated from an earlier |
network |
the network number (reported in the earlier NBS results) of the network to be masked. Set to 1 by default |
Details
This function generates positive and negative masks (vectors of 1s and 0s), where 1s indicate a significant network-thresholded edge. These masks can then be used to perform a matrix multiplication with the vectorized FC matrices to object subject-level network strengths
Value
Returns a list object containing
-
clust.tstatthresholded edge-wise t-statistics.Edges not belonging to this cluster will be zeroed. -
pos.edgesA vector of 1s and 0s indicating the significant network-thresholded positive edges. -
neg.edgesA vector of -1s and 0s indicating the significant network-thresholded negative edges. -
pos.maskA vector of 1s and 0s indicating the significant network-thresholded positive edges. -
neg.maskA vector of 1s and 0s indicating the significant network-thresholded negative edges.
Examples
demomat=get('demomat')
contrast=c(1,1,2,2)
random=c('sub1','sub2','sub3','sub4')
model1=NBS(model=contrast, contrast=contrast, FC_data=demomat, nperm=2, nthread=1, p=0.001)
edges=extract.edges(model1,network=1)
Fsaverage5
Description
A surface template in fsaverage5 space for the glass brain plot
Usage
fs5brain
Format
fs5brain
A list of two matrices: ()
- vertices
matrix with 3 rows (XYZ coordinates), 20484 columns (number of vertices)
- edges
matrix with 3 rows (triangle neighbours), 40960 columns (unique triangles)
intersubject_similarity
Description
This function runs an intersubject similarity analysis to determine if there is a relationship between similarity in FC and similarity in one or multiple outcomes.
Usage
intersubject_similarity(FC_data, outcome, mode = "diff", nperm = 1000)
Arguments
FC_data |
An N x E matrix containing the vectorized edges; where N = number of subjects, E=number of edges |
outcome |
A numerical vector (single outcome) or matrix (multiple outcomes) containing the values of the outcome(s) of interest |
mode |
When set to |
nperm |
number of permutations for the correlation test between FC similarity and outcome similarity |
Details
This function runs an intersubject similarity analysis to determine if there is a relationship between similarity in FC and similarity in one or multiple outcomes. The outcome(s) will be z-standardized prior to calculating the intersubject similarity in the outcome(s).
Value
A list object containing
-
FC_difference_matrixThe FC difference matrix -
Outcome_difference_matrixThe outcome difference matrix -
permutation_dataThe permuted correlation values
Examples
demomat=get('demomat')
results=intersubject_similarity(FC_data = demomat, outcome=c(1,1,2,2),mode="diff")
Labels data
Description
A list containing four data frames, listing atlas labels, index numbers, hemispheres and lobes they correspond to, for each available atlas (1=AAL-90 atlas, 2=Schaefer-100 atlas + 19 subcortical regions, 3=Schaefer-200 atlas + 19 subcortical regions, 4=Brainnetome atlas).
Usage
labels_dat
Format
labels_dat
A list of four data.frames: ()
- vertices
data frame with 90 rows (atlas parcellations), 6 columns (atlas label, region number, index order (old), index order (new), hemisphere (1=L,2=R), region label (anatomical area name) )
- vertices
data frame with 119 rows (atlas parcellations), 6 columns (atlas label, region number, index order (old), index order (new), hemisphere (1=L,2=R), region label (anatomical area name) )
- vertices
data frame with 219 rows (atlas parcellations), 6 columns (atlas label, region number, index order (old), index order (new), hemisphere (1=L,2=R), region label (anatomical area name) )
- vertices
data frame with 246 rows (atlas parcellations), 6 columns (atlas label, region number, index order (old), index order (new), hemisphere (1=L,2=R), region label (anatomical area name) )
network_lm
Description
mass univariate linear regression at the network level
Usage
network_lm(
model,
contrast,
FC_data,
threshold.method = "fdr",
perm = TRUE,
nperm = 1000
)
Arguments
model |
A data.frame or matrix containing all the predictors in the model |
contrast |
The predictor of interest. The edge- and network-wise statistics will only be estimated for this predictor |
FC_data |
An N x E matrix containing the vectorized edges; where N = number of subjects, E=number of edges |
threshold.method |
method for correcting for multiple tests. set to |
perm |
If set to |
nperm |
number of permutations to use if |
Details
This function first summarizes the FC edges into their respective networks and then carry out mass univariate linear regression analyses on each of the network to network connection
Value
A data.frame object with coef and corrected p values
Examples
demomat=get('demomat')
contrast=c(1,1,2,2)
random=c('sub1','sub2','sub3','sub4')
model1=network_lm(model=contrast,
contrast=contrast,
FC_data=demomat,
nperm=1)
network_lme
Description
mass univariate linear mixed effects analysis at the network level
Usage
network_lme(
model,
contrast,
random,
FC_data,
threshold.method = "fdr",
perm = TRUE,
nperm = 1000,
perm_type = "within_between",
nthread = 4
)
Arguments
model |
A data.frame or matrix containing all the predictors in the model |
contrast |
The predictor of interest. The edge- and network-wise statistics will only be estimated for this predictor |
random |
A N x 1 numeric vector or object containing the values of the random variable (optional). Its length should be equal to the number of subjects in model (it should NOT be inside the model data.frame). |
FC_data |
An N x E matrix containing the vectorized edges; where N = number of subjects, E=number of edges |
threshold.method |
method for correcting for multiple tests. set to |
perm |
If set to |
nperm |
number of permutations to use if |
perm_type |
A string object specifying whether to permute the rows ("row"), between subjects ("between"), within subjects ("within") or between and within subjects ("within_between") for random subject effects. Default is "row". |
nthread |
The number of CPU threads to use. Default is 4. |
Details
This function first summarizes the FC edges into their respective networks and then carry out mass univariate linear mixed effect analyses on each of the network to network connection
Value
A data.frame object with coef and corrected p values
Examples
demomat=get('demomat')[,1:7021]
contrast=c(1,1,2,2)
random=c('sub1','sub2','sub3','sub4')
model1=network_lme(model=contrast,
contrast=contrast,
random=random,
FC_data=demomat,
nperm=1,
nthread=2)
vizChord
Description
Visualizing brain connectivity profiles with a chord diagram
Usage
vizChord(
data,
hot = "#F8766D",
cold = "#00BFC4",
width = 1200,
height = 1200,
filename = paste0(tempdir(), "/conn.png"),
colorscheme,
title,
leg.height = 100,
ncol = 1,
nrow = 1,
colorbar_title = "Connectivity Strength"
)
Arguments
data |
a vector of edge values with a length of 78, 4005, 7021, 23871 or 30135. |
hot |
color for the positive connections.Set to |
cold |
color for the negative connections.Set to |
width |
width (in pixels) of each connectogram. Set to 1200 by default. |
height |
height (in pixels) of each connectogram . Set to 1200 by default. |
filename |
output path and file name with a *.png file extension. Set to |
colorscheme |
an optional vector of color names or color codes to color code the networks. |
title |
a vector of strings to be used as title |
leg.height |
height (in pixels) of legend, in pixels. Set to 100 by default. Not used for single row data |
ncol |
number of columns in the plot. Not used for single row data |
nrow |
number of rows in the plot. Not used for single row data |
colorbar_title |
title for the colorbar legend |
Details
This function takes a matrix (NROW=number of edges in the connectome; NCOL=number of edges in the connectome) of edge values and visualizes the average network-to-network connectivity in a chord diagram.
Value
A .png image
Examples
results=runif(7021, min = -1, max = 1)
vizChord(data=results, filename=paste0(tempdir(),"/FC_chord119.png"))
vizConnectogram
Description
Visualizing brain connectivity profiles with multiple connectogram
Usage
vizConnectogram(
data,
hot = "#F8766D",
cold = "#00BFC4",
ncol = 1,
nrow = 1,
edgethickness = 0.8,
filename = paste0(tempdir(), "/conn.png"),
colorscheme,
title,
width = 1000,
height = 1050,
leg.height = 200,
margins = c(1.2, 1.2, 1, 1.5),
node.size,
node.text.size = 1,
legend.text.size = 7,
legend.title.size = 8,
limits,
title.size = 11,
title.alignment = "center",
colorbar_title = "Edge Strength",
edge_labels = c("Positive", "Negative"),
row_title
)
Arguments
data |
a matrix of edge values with 4005, 7021, 23871 or 30135 columns |
hot |
color for the positive connections. Set to |
cold |
color for the negative connections. Set to |
ncol |
number of columns in the plot. Not used for single row data |
nrow |
number of rows in the plot. Not used for single row data |
edgethickness |
a value to adjust the thickness of the edges. Set to 0.8 by default. |
filename |
output path and file name with a *.png file extension. Set to |
colorscheme |
an optional vector of color names or color codes to color code the networks. |
title |
a vector of strings to be used as title |
width |
width (in pixels) of each connectogram. Set to 1000 by default. Not used for single row data |
height |
height (in pixels) of each connectogram . Set to 1050 by default. Not used for single row data |
leg.height |
height (in pixels) of legend, in pixels. Set to 100 by default. Not used for single row data |
margins |
vector of 4 values specifying the amount of empty space on the left, right, top and bottom for each connectogram. Set to |
node.size |
size parameter for the dots representing the nodes. If not specified, an appropriate size will be set. |
node.text.size |
size parameter for the text labels on the nodes. Set to 1 by default. |
legend.text.size |
size parameter for the legend text. Set to 6 by default. |
legend.title.size |
size parameter for the legend title. Set to 8 by default. |
limits |
a pair of values that governs the limits of the edge strengths displayed. If missing |
title.size |
size parameter for the title. Set to 11 by default. |
title.alignment |
string object specifying title's alignment relatively to its plot options are 'left', 'center' (default), 'right'. |
colorbar_title |
title for the colorbar legend |
edge_labels |
Vector of two strings defining the labels for the edge legends. Default is c("Positive","Negative"). |
row_title |
a vector of strings to be used as left vertical titles for each row of plots when there are many |
Details
This function takes a matrix (NROW=number of edges in the connectome; NCOL=number of edges in the connectome) of edge values and visualizes the edge-to-edge connectivity with multiple connectograms
Value
A .png image
Examples
data=matrix(sample(c(1,0, -1), 23871*1, replace = TRUE, prob = c(0.001, 0.998,0.001)),nrow=1)
vizConnectogram(data=data)
vizGlassbrain
Description
Visualizing brain connectivity with a glass brain plot
Usage
vizGlassbrain(
data,
surf_color = "grey",
node_color = "#00BA38",
surf_alpha = 0.2,
cmap,
node_size = 8,
node_label = TRUE,
node_label_size = 10,
node_label_color = "black",
edgethickness = 8,
limits,
colorbar_title = "Connectivity strength",
orientation_labels = TRUE,
remove_brain = FALSE
)
Arguments
data |
a vector of edge values with a length of 4005, 7021, 23871 or 30135 |
surf_color |
color of the cortical surface. Set to |
node_color |
color of the nodes. Set to |
surf_alpha |
alpha value of the cortical surface, where 0 will cause the cortical surface to disappear and 1 will cause the cortical surface to be completely opaque. Set to |
cmap |
A string vector containing 2 to 3 color names/codes specifying the colors to be used for the color scale. See |
node_size |
size parameter for the dots representing the nodes. Set to |
node_label |
option to show node labels. Set to |
node_label_size |
font size of the node labels. Set to |
node_label_color |
font color of the node labels. Set to |
edgethickness |
a value to adjust the thickness of the edges. Set to |
limits |
Numeric vector of length 2, composed of the lower and upper color scale limits of the plot. When left unspecified, the symmetrical limits |
colorbar_title |
title for the colorbar legend. Set to |
orientation_labels |
A boolean object specifying if orientation labels are to be displayed. Set to |
remove_brain |
A boolean object specifying cortical surface should be removed. Set to |
Details
This function takes a vector of edge values and visualizes the edge-to-edge connectivity with a glass brain plot
Value
A plot_ly object
Examples
mask=sample(c(1,0), 7021, replace = TRUE, prob = c(0.001, 0.999))
data=runif(7021,min = -1,max=1)*mask
vizGlassbrain(data,orientation_labels = TRUE)
vizHeatmap
Description
Visualizing brain connectivity matrices with heatmaps
Usage
vizHeatmap(
data,
hot = "#F8766D",
cold = "#00BFC4",
mid = "white",
ncol,
nrow,
filename = paste0(tempdir(), "/heatmap.png"),
colorscheme,
line.color = "black",
title,
limits,
title.size = 12,
legend.title.size = 8,
legend.text.size = 7,
line.width = 0.3,
width = 1000,
height = 1000,
leg.size = 200,
colorbar_title = "Edge Strengt"
)
Arguments
data |
a matrix of edge values with 4005, 7021, 23871 or 30135 columns |
hot |
color for the positive connections. Set to |
cold |
color for the negative connections. Set to |
mid |
color for the mid point of the color scale. Set to |
ncol |
number of columns in the plot. Not used for single row data |
nrow |
number of rows in the plot. Not used for single row data |
filename |
output filename with a *.png file extension. Set to |
colorscheme |
an optional vector of color names or color codes to color code the networks. |
line.color |
color parameter for grid lines dividing the connectome in to networks. Set to |
title |
a vector of strings to be used as title |
limits |
Numeric vector of length 2, composed of the lower and upper scale limits of the plot. When left unspecified, the symmetrical limits |
title.size |
size parameter for the title. Set to 12 by default. |
legend.title.size |
size parameter for the legend title. Set to 8 by default. |
legend.text.size |
size parameter for the legend text. Set to 8 by default. |
line.width |
line thickness parameter for grid lines dividing the connectome in to networks. Set to 0.3 by default. |
width |
width (in pixels) of each heatmap. Set to 1000 by default. Not used for single row data |
height |
height (in pixels) of each heatmap . Set to 1000 by default. Not used for single row data |
leg.size |
height/width (in pixels) of legend, in pixels. Set to 200 by default. |
colorbar_title |
title for the colorbar legend |
Details
This function takes a matrix (NROW=number of edges in the connectome; NCOL=number of edges in the connectome) of edge values and visualizes the edge-to-edge connectivity with multiple connectograms
Value
A .png image
Examples
data=data=runif(7021,min = -1,max=1)
vizHeatmap(data=data)
vizNetConnectogram
Description
Generate a Network Connectogram from a Vector of FC network or edge data
Usage
vizNetConnectogram(
FC_dat,
show.sig = TRUE,
title = NULL,
title.size = 10,
hot = "#F8766D",
cold = "#00BFC4",
node.text.size = 2,
node.size = 2,
node.color = "black",
edge.thickness = 1.5,
sig.color = "darkgrey",
legend = TRUE,
legend.title = "Standardized Coefficient",
legend.title.size = 6,
legend.text.size = 5,
expand = 1.1,
limits,
filename,
width = 1000,
height = 700
)
Arguments
FC_dat |
a matrix of edge values with 4005, 7021, 23871 or 30135 columns |
show.sig |
Logical. If |
title |
Character string for the plot title. Default is |
title.size |
Numeric. Font size of the plot title. Default is |
hot |
Character. Color used for positive edges and node highlights.
Default is |
cold |
Character. Color used for negative edges and node highlights.
Default is |
node.text.size |
Numeric. Size of the node label text. Default is |
node.size |
Numeric. Size of the node points. Default is |
node.color |
Character. Fill color of the node points. Default is
|
edge.thickness |
Numeric. Width of the edges (and node border stroke).
Default is |
sig.color |
Character. Color for the significant edges. Default is |
legend |
Logical. If |
legend.title |
Character string for the legend title. Default is
|
legend.title.size |
Numeric. Font size of the legend title. Default is
|
legend.text.size |
Numeric. Font size of the legend tick labels. Default
is |
expand |
Numeric. Multiplicative expansion factor applied to the x and y
axis limits to prevent node labels from being clipped. Default is |
limits |
Numeric vector of length 2. Color scale limits for the edge alpha
and node alpha mappings. If not supplied, limits are set automatically to
|
filename |
Character. Path/filename for the output PNG. If the argument is omitted entirely, no file is written. |
width |
Integer. Width of the saved PNG in pixels. Default is |
height |
Integer. Height of the saved PNG in pixels. Default is |
Details
Creates a circular network connectogram (chord diagram) from a data frame of connectivity results, visualizing edge weights and their signs using color and transparency. Node self-connections (diagonal elements) are highlighted on the node border. Optionally saves the plot to a PNG file.
Row names of results must follow the pattern "nodeA to nodeB".
Self-connections (from == to) are extracted to colour and shade node
borders: if all diagonal values are > 1 the border is drawn in
hot; if all are < 1 it is drawn in cold. The diagonal
entries are removed before the igraph graph object is constructed.
Edge colour encodes sign (hot = positive, cold = negative) and
edge transparency encodes absolute magnitude.
The function relies on igraph, ggraph, and ggplot2.
Value
A ggraph/ggplot2 plot object (invisibly returned via
print and return). As a side effect the plot is printed to the
active graphics device, and — if filename is provided — written to a
300 dpi PNG file.
Examples
demomat=get('demomat')
vizNetConnectogram(colMeans(demomat))