The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

Package {FCtools}


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 ORCID iD [aut], Charly Billaud ORCID iD [aut, cre]
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

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

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 NBS() analysis

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

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 "diff", FC similarity is calculated as absolute difference between the FC vectors of a pair of subjects. When set to "corr",FC similarity is calculated as 1 - (pearson's correlation coefficient between the FC vectors of a pair of subjects). Set to "diff" by default.

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

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 fdr by default

perm

If set to TRUE, p values will be calculated using a permutation approach by shuffling subjects' labels, before correcting for FDR. Set to TRUE by default

nperm

number of permutations to use if perm=TRUE.

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 fdr by default

perm

If set to TRUE, p values will be calculated using a permutation approach by shuffling subjects' labels, before correcting for FDR. Set to TRUE by default

nperm

number of permutations to use if perm=TRUE.

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 ⁠#F8766D⁠ by default.

cold

color for the negative connections.Set to ⁠#00BFC4⁠ by default.

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 conn.png by default in the temporary directory (tempdir()).

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 ⁠#F8766D⁠ by default.

cold

color for the negative connections. Set to ⁠#00BFC4⁠ by default.

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 conn.png by default in the temporary directory (tempdir()).

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 c(1.2,1.2,1,1.5) by default. You might want to adjust these values if the text labels get cut off by a neighbouring connectogram or the legend. Not used for single row data

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 limits=range(abs(data),na.rm=TRUE)

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 'grey' by default

node_color

color of the nodes. Set to '#00BA38' by default

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 0.2 by default

cmap

A string vector containing 2 to 3 color names/codes specifying the colors to be used for the color scale. See RColorBrewer::display.brewer.all() for all possible cmap options. If none are specified, appropriate colors will be automatically selected according to range(data)

node_size

size parameter for the dots representing the nodes. Set to 8 by default.

node_label

option to show node labels. Set to TRUE by default.

node_label_size

font size of the node labels. Set to 10 by default.

node_label_color

font color of the node labels. Set to black by default.

edgethickness

a value to adjust the thickness of the edges. Set to 8 by default.

limits

Numeric vector of length 2, composed of the lower and upper color scale limits of the plot. When left unspecified, the symmetrical limits ⁠c(-max(abs(data),max(abs(data)))⁠ will be used.

colorbar_title

title for the colorbar legend. Set to ⁠'Connectivity strength⁠ by default

orientation_labels

A boolean object specifying if orientation labels are to be displayed. Set to TRUE by default

remove_brain

A boolean object specifying cortical surface should be removed. Set to FALSE by default

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 ⁠#F8766D⁠ by default.

cold

color for the negative connections. Set to ⁠#00BFC4⁠ by default.

mid

color for the mid point of the color scale. Set to white by default.

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 heatmap.png by default in the temporary directory (tempdir()).

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 "black" by default.

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 ⁠c(-max(abs(data),max(abs(data)))⁠ will be used.

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 TRUE, significant edges will be outlined with sig.color. Default is FALSE.

title

Character string for the plot title. Default is NULL (no title).

title.size

Numeric. Font size of the plot title. Default is 10.

hot

Character. Color used for positive edges and node highlights. Default is "#F8766D" (red).

cold

Character. Color used for negative edges and node highlights. Default is "#00BFC4" (teal).

node.text.size

Numeric. Size of the node label text. Default is 2.

node.size

Numeric. Size of the node points. Default is 2.

node.color

Character. Fill color of the node points. Default is "black".

edge.thickness

Numeric. Width of the edges (and node border stroke). Default is 2.

sig.color

Character. Color for the significant edges. Default is "darkgrey"

legend

Logical. If TRUE, a continuous color bar legend is added to the plot. Default is TRUE.

legend.title

Character string for the legend title. Default is "Standardized Coefficient".

legend.title.size

Numeric. Font size of the legend title. Default is 8.

legend.text.size

Numeric. Font size of the legend tick labels. Default is 5.

expand

Numeric. Multiplicative expansion factor applied to the x and y axis limits to prevent node labels from being clipped. Default is 1.1.

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 c(0, max(abs(weight))) inside the function.

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 1000.

height

Integer. Height of the saved PNG in pixels. Default is 1000.

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))

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.