FastFC

Welcome to Fast Functional Connectivity Toolbox.

FastFC is the result of an effort to improve efficiency for Functional Connectivity and related Network measures. You can download the executable files (right now only available for Windows x64 systems) here. All functions are developed so that they can be called directly from Matlab's command line.

Please consider citing our work

Installation

1. Download the latest version of the executables precompiled functions from here. Everything you need is in that folder.
2. Include that folder in Matlab's path.
3. Execute testing_fastFC.m from Matlab to check if everything works fine.
4. Read User Manual to understand input and output parameters of each function.
5. Enjoy!

If a software package needs to be installed a “specified module could not be found” error message will appear in Matlab’s command line window. For normal installations, all necessary .dll libraries are included and in general, users do not need any further installation. Check out these links to see if this problem can be solved.

Microsoft Windows library for multi-thread execution can be found here.

FFTW library for Microsoft Windows 64bit systems can be found here.

User Manual

In general terms, Functional Connectivity matrices are computed compactly. Input data is conceived as the whole matrix, column ordered. Each resulting connectivity matrix will be a squared matrix with the same number of rows and columns as the number of columns (number of sensors) of the input data.

This approach can derive in an out-of-memory problem when dealing with big data matrices (this is particularly the case of Generalized Synchronization algorithm which is very memory demanding). However, this problem can easily be circumvented by calling the function once for each pair of sensors, and collecting the Functional Connectivity index from the resulting squared matrix of size two. Equally, all functions computing network indices compute the specified index for every node in the network. This implementation tries to resemble as much as possible Brain Connectivity Toolbox behavior. All functions in FastFC are directly accessible from the command line window of Matlab. During execution, each function polls the number of CPU cores present in the computer and deploys an equal number of parallel threads for computing the desired index.

Both functions using FFTW subroutine library are the zero phase distortion filter and Phase Synchronization. They both have an input parameter called mode, which allows deciding how exhaustive the search for the optimal FFT algorithm should be. This is a FFTW feature which has been maintained through FastFC. Sometimes it is a good idea to spend a few seconds or even minutes searching for a good algorithm for FFT that can significantly improve performance of subsequent executions. Typically an initial search at the beginning of each MATLAB session can take a few minutes, ensuring an efficient execution which last much less time in every subsequent call to the function. However in general terms mode=1 is more convenient.

Development

Zero phase distortion filter

y=fastfc_filt(filter,data,mode)

Input parameters: *filter = row vector with filter denominator coefficients. *data = column matrix with data to be filtered. Each sensor should be each column. *mode = mode for FFT scheduling *mode = 0 , execute fastest but sub-optimal. *mode = 1 , execute fast but in a sub-optimal algorithm. *mode = 2 , execute slower the first time, but consider possible faster algorithms. *mode = 3 , execute slowest the first time, but consider the fastest algorithm. Output parameters: *y = array the same size of data, with each column corresponding to each filtered column of data.

Phase Synchronization

PLV. PLI. wPLI and imCo are all computed (along with the estimated significance of the PLV) within the MEX function fastfc_ps and fastfc_wpli, directly invoked from the MATLAB environment. It is important to understand an additional input parameter of this function: samples_to_discard is the number of data samples to discard, to prevent edge effects during the estimation of the Hilbert Transform. The function uses an FFT-based algorithm to estimate the Hilbert Transform, after mirror padding the data, so that discarding of data should be used only for narrow signals where serious edge effects are suspected.

[plv,pval_plv,pli]=fastfc_ps(data,samples_to_discard,mode)

[wpli,imC]=fastfc_wpli(data)

Input parameters:

• data = data (sensors by columns).
• samples_to_discard = samples to discard at the beginning and samples to discard at the end of the phase signals. i.e. To discard 200 samples at the beginning and 200 samples at the end of each sensor, samples_to_discard should equal 200.
• mode = 0 -> execute fastest but suboptimal.
• mode = 1 -> execute fast but in a suboptimal algorithm.
• mode = 2 -> execute slower the first time, but consider possible faster algorithms.
• mode = 3 -> execute slowest the first time, but consider the fastest algorithm. Output parameters: *plv = Phase Locking Value Functional Connectivity matrix. *pval_plv = pvalue for each index of the PLV matrix. *pli = Phase Locking Index Functional Connectivity matrix. *wPli = Weighted Phase Locking Functional Connectivity matrix. *imC = Imaginary part of the Coherence Functional Connectivity matrix.

Mutual Information

The function implementing the calculation of MI index using k-nearest neighbours, and its corresponding input/output parameters, is defined below.

[mi]=fastfc_mi(data,emb_dim,tau,k);

Input parameters:

• data = eeg data (sensors by columns).
• emb_dim = embedding dimensions to consider
• tau = time lag to consider for embedding
• k = number of neighbours to consider

Output parameters:

*mi = Mutual Information Functional Connectivity matrix

Generalized Synchronization

The function implementing the calculation of GS indices: S, H, M and L, and its corresponding input/output parameters, is defined below.

[S,H,M,L]=fastfc_gs(data,emb_dim,tau,k,w,states_eff_step)

Input parameters:

• data = eeg data (sensors by columns).
• emb_dim = embedding dimension
• tau = time lag for embedding
• k = number of neighbours to consider
• w = window correction for neighbour finding
• states_eff_step = state-space down sampling to consider when calculating distances

Output parameters: *S, H, M and L = Functional Connectivity matrices for each index.

Strength

[S]=fastfc_strength_wu(A)

Input parameters:

• A = adjacency matrix of real values between 0 and 1, with zeroed principal diagonal elements. Output parameters:
• C = a row matrix where every value represents the Strength of each node.

[note: This function can be more or less like BCT's Matlab version]

Clustering Coefficient

[C]=fastfc_cluster_coef_wu(A)

Input parameters: *A = adjacency matrix of nodes by nodes. Values between 0 and 1. Principal diagonal is zero. Output parameters: *C= column matrix where every value represents the Clustering Coefficient of each node.

[note: This function is much slower than BCT's Matlab version]

Shortest Path Length

[D,L]=fastfc_shortest_path_length_w(W)

Input parameters: *W = directed or undirected weighted connection length matrix.Typically W is obtained by inverting each element in the Functional Connectivity matrix, transforming therefore between weights to length. Output parameters: *D = distance matrix between nodes (shortest weighted path). *L = number of edges in each shortest weighted path.

Betweenness Centrality

Node Betweenness Centrality [D,L,BC]=fastfc_betweenness_cent_w(W)

Input parameters: *W = directed or undirected connection-length matrix. Output parameters: D = distance matrix between nodes (shortest weighted path). L = number of edges in each shortest weighted path. BC = node Betweenness Centrality for each node in the network.

Developers

The complete source-code of this project is available at the GitHub page for FastFC. Each family of measures is separated in its own branch. Whenever an improvement is made to a function, the final compilation result is copied into the default branch called “release”.

Contact & Support

If you have any doubt or would like to help with Fast FC, please contact me.

Juan Garcia-Prieto