Functionnectome as a framework to analyse the contribution of brain circuits to fMRI

In recent years, the field of functional neuroimaging has moved away from a pure localisationist approach of isolated functional brain regions to a more integrated view of these regions within functional networks. However, the methods used to investigate functional networks rely on local signals in grey matter and are limited in identifying anatomical circuitries supporting the interaction between brain regions. Mapping the brain circuits mediating the functional signal between brain regions would propel our understanding of the brain’s functional signatures and dysfunctions. We developed a method to unravel the relationship between brain circuits and functions: The Functionnectome. The Functionnectome combines the functional signal from fMRI with white matter circuits’ anatomy to unlock and chart the first maps of functional white matter. To showcase this method’s versatility, we provide the first functional white matter maps revealing the joint contribution of connected areas to motor, working memory, and language functions. The Functionnectome comes with an open-source companion software and opens new avenues into studying functional networks by applying the method to already existing datasets and beyond task fMRI.


Supplementary discussion 1
The region-wise analysis delivers results comparable to those obtained with the voxel-wise analysis, albeit slightly less sensitive and specific. For instance, compared to the voxel-wise analysis, a few pathways were missing in the regionwise analysis (e.g. the first branch of the superior longitudinal fasciculus -SLF1in the working memory task map -Supplementary figure 3), and other tracts were displaying larger activations (e.g. the left uncinate/IFOF in the semantic system task map -Supplementary figure 4). The choice of brain segmentation used for the simplified region-wise analysis could improve the results. Here, the multimodal parcellation of the HCP has a general-purpose, but using a brain parcellation tailored for the specific analysis of a project could yield better results.
Overall, the region-wise analysis offers a way for any research team to use the Functionnectome and obtain results in a short amount of time, independently from the computational resources available. Even teams considering the application of the voxel-wise analysis could use it as a quick test of their method, before investing the time and computational resources for the complete analysis.

Introduction
The Functionnectome is a Python-based tool to allow projecting functional signals (or more generally grey matter information) onto the white matter. As input, the software accepts NifTI 4D volumes (usually fMRI files), uses predefined (but modifiable if needed) white matter priors for the computation, and outputs functionnectome 4D volumes. The user can choose between navigation through commands or a GUI (Graphical User Interface).
The generated functionnectomes 4D volumes can then be processed with the same statistical tools used to analyze fMRI. For example, the functionnectome generated from a classic task fMRI can be analyzed with the usual tools (e.g. generalized linear model) to reveal the whitematter pathways involved with the task.

Disclaimer
No financial conflicts.
Not licensed for medical use.
The software and its codes are licenced under the GNU General Public License.

Definitions
• "Functionnectome" (with an uppercase "F") refers to the overall method and the program applying the method. "functionnectome" (with a lowercase "f") refers to the 4D volume resulting from the application of the Functionnectome. • "Voxel-wise" analysis refers to the projection of functional signals onto the white matter as this is done at the voxel level. "Region-wise" analysis runs on predefined parcels of brain regions, grouping voxels together and reducing the number of steps to the order of hundreds at most, though at the cost of precision.
Requirements (Read this before starting!) 1. The Functionnectome runs on Python 3.6 (or higher). In addition to the basic Python distributions, four python libraries are needed: Numpy, Pandas, Nibabel and H5py. If you install the Functionnectome toolbox using pip (see the "Installation" section), they will be installed automatically. Otherwise, you will have to install them manually on your python virtual environment. 2. Depending on the size of the input data, RAM usage can vary. An 8-12GB RAM is recommended, but for small input volumes, 4GB might suffice. 3. Expected input files are NifTI (.nii or .nii.gz) 4D volumes in MNI152 space, with 2mm 3 isotropic voxels. 4. Input files should either be: o All in the same folder, e.g. : • "/myHome/dataFMRI/subject01.nii" • "/myHome/dataFMRI/subject02.nii" o Or in different folders but with "similar paths," i.e., with the same number of subfolders and the folder with the data ID at the same depth, e.g. : • "/myHome/subject01/data/mydata.nii" • "/myHome/subject02/data/mydata.nii" 5. For a voxel-wise analysis, a brain (or rather gray-matter) mask in MNI152 space, with 2mm 3 isotropic voxels, selecting the voxels with "interesting" functional signal, is also necessary. The mask should be a NifTI 3D volume, with the same spatial dimensions as the main 4D volume input. 6. The white matter anatomical priors are available online (https://www.dropbox.com/s/22vix4krs2zgtnt/functionnectome_7TpriorsH5.zip?dl= 0), but the toolbox gives you also the option to download them automatically. 7. The provided priors require input data to be in the MNI152 space, with 2mm 3 isotropic voxels. 8. We strongly recommend running the Functionnectome on a machine equipped with multiple CPUs (8 cores or more). At least for the voxel-wise analysis. The region-wise analysis is much less computationally demanding. Note that process parallelisation should not increase the RAM load.

Overview
In the GUI, the analysis parameters can be set and the input and the output can be defined. The Functionnectome analysis can be launched from the GUI once the parameters are set. The settings can be saved and loaded for future analysis.
• Input: 4D volume, NifTI • (opt.) Input mask: 3D volume, NifTI. (required for voxel-wise analysis) • Output1: the functionnectome, 4D volume, NifTI o The user defines the general output folder o A subfolder is generated for voxel-wise or region-wise analysis o A second subfolder is generated with the unique ID* of the input data o The output 4D data is saved there and named "functionnectome.nii.gz" o Example: "/myHome/myOutput/voxelwise_analysis/subject01/functionnectome.nii.gz" • Output2: 3D volume, NifTI. o sum_ probaMaps_voxel.nii.gz or sum_ probaMaps_region.nii.gz o Stored in the same directory as Output1 (for voxel-wise analysis) or in the general output folder (for region-wise analysis) o Sum of all probability maps used for a given subject (depends on the mask) o Used during the processing, might be useful for alternative processing *Unique ID: If all input files are in the same folder, the program uses the filenames (without the extension). If the files are in different folders with similar paths (cf. bullet 4 in Requirements), the ID is the name of the folder (e.g. it will be "subject01" in the example given above with "/myHome/subject01/data/mydata.nii") A quick guide to run an analysis: 1. Select the input 4D files by clicking on either "Choose files" buttons (depending on your data storage organisation).

Select whether you want a region-wise or voxel-wise analysis
o If you chose the voxel-wise approach, select the masks that will filter out unwanted voxels. You can either choose one mask per input file or choose one unique mask applied to all input files. 3. Select the number of parallel processes you want to launch concurrently. The more processors, the faster the analysis. Importantly, the priors should be saved on a storage device with fast reading speed. For an estimation of the time needed to run the Functionnectome on your data, check the FAQ at the end of the manual. 4. Choose the file type of the priors. If the priors of the software are to be used they are made available as HDF5 files. Where users wish to use their own templates we recommend using the same file type. 5. If the priors have not yet been downloaded (or the path leading to the files is not set), you will be offered to automatically download it (or asked to select the file path). This should only happen once, when you first try to run the Functionnectome. 6. Choose the output folder. If the provided path doesn't exist, it will be automatically generated. 7. Choose whether or not you want to mask the output to remove voxels outside of the brain (as defined by a brain template). We recommend it (default behaviour). 8. Launch the analysis. Or save the settings in order to launch it later or with a command line.

Installation
The project can be download through pip using the command line: • pip install git+https://github.com/NotaCS/Functionnectome.git or • python -m pip install git+https://github.com/NotaCS/Functionnectome.git You can also manually download the project from GitHub: The priors will be automatically downloaded during the first launch of the Functionnectome, but you can also download them manually here: If you download the priors manually, you will need to unzip the file. The path to the priors will be asked by the program during the first run.

Loading the input 4D volume
Once you have downloaded the package, launch the GUI. To do so, there are 3 possible ways: • If the toolbox was installed using pip, simply call "FunctionnectomeGUI" (without the quotation marks) in a command window using the virtual environment where you installed the Functionnectome. • If you manually downloaded the codes, run the functionnectome_GUI.py script from a python interpreter, or run "python functionnectome_GUI.py" in a command window.
In the GUI, you can specify the input data (assumed to be BOLD data, but any 4D nifty files are accepted). Two ways of selecting the files are possible depending on how they are stored on your computer: 1. ALL FILES IN 1 FOLDER: If they are all in the same folder, click on the "Choose files" button just under the "Select BOLD files from one folder" label.
A generic interactive window will open to allow you to choose the files from a folder. You can manually select the files you want to keep/discard. Only NifTI files are accepted (extension ".nii" or ".nii.gz"). 2. SEPERATE FOLDERS FOR EACH PARTICIPANT: If the files are in different folders (but properly organised with folders and sub-folders following the same pattern), click on the "Choose files" button under the "Select BOLD files by pasting paths" label.
A new window will open. In the central box, you can paste the paths of each file. An easy way to obtain the paths of all the files requires the use of a command window (i.e. a terminal): • On MacOS/Unix/Linux, use the "ls" command. For example, let's say that all my files are stored in paths as: "/myhome/current_project/subject????/functionalFiles/ fMRI_acquisition.nii.gz" with "????" being a unique ID (e.g a number) that is different for every subject. Use as many "?" as there are digits in the ID numbers. To display all the file-paths, simply enter the command (in the terminal): "ls -1 /myhome/current_project/subject????/funFiles/fMRI_acquisition.nii.gz" Here, "ls" will list all the paths, and the "-1" option will display one path per line.
• On Windows, use the "dir" command, similarly to the above-mentioned "ls".
If for some reason you enter or paste something wrong in the GUI text box, you can easily correct it manually or clear the whole box by clicking on "Clear". When you are done, click on "OK" to accept the file-paths. Or "Cancel" to return to the main window without keeping the paths or the changes made to existing paths.
Advanced tip: Once you have files selected, you can manually edit them (add/remove) by opening the "pasting" window and adding ore removing a line, even if you selected the all from one folder. Note that the added paths should still keep the same naming pattern as the other already there. Likewise, if you "Clear" the window and click on "OK", it will delete every path (not the files, of course, just the paths stored by the GUI). If you accidentally modify or clear the paths, simply click on "Cancel".
To differentiate the input files and to name the output folders, a unique ID is attributed to each of them. When selecting all inputs from the same folder (option 1), the unique ID is the name of the file (without the extension). When selecting from multiple similar folders (option 2), the program will automatically select the first divergence in the paths as the ID. The position of the ID in the path is displayed, and an example of ID (from the first selected path) is given. Subsequently, the GUI gives you the option to manually change the location in the paths where the program finds the IDs, using the little arrows near the position number: List of the paths given: /myHome/workspace/myProject/myAcquisition/MRI/subject01/fMRI/readyData.nii.gz /myHome/workspace/myProject/myAcquisition/MRI/subject02/fMRI/readyData.nii.gz /myHome/workspace/myProject/myAcquisition/MRI/subject03/fMRI/readyData.nii.gz Position of the subject ID in the path (index of the folder in the path, starting at "0"): /myHome/workspace/myProject/myAcquisition/MRI/subject01/fMRI/readyData.nii.gz Here, "subject01" has been automatically selected as it is the first (and only in the example) divergence between the paths.
Sometimes, the first divergence is not the one you want to keep. You can then manually modify the position. For example, if we have the paths: /myHome/myProject/session1/subject01/readyData.nii.gz /myHome/myProject/session1/subject02/readyData.nii.gz /myHome/myProject/session2/subject03/readyData.nii.gz /myHome/myProject/session2/subject04/readyData.nii.gz The number of the session is the first divergence between the paths, so the position will be automatically set at "2", and the example given will be "session1". The user will then have to change the position to "3" (which will change the example to "subject01").

Voxel-wise and region-wise analysis
Select whether you want to run a voxel-wise or a region-wise analysis. If you have enough computational power, we recommend using the voxel-wise analysis.
If you select the voxel-wise analysis (i.e. "voxel-wise functionnectome"), you will need to specify the mask(s) that will filter out unwanted voxels. Click on "Select mask(s)". A new window will pop open: You can either attribute one mask per input file ("One mask per subject"), usually useful if the masks are created depending on the individual data; or select one unique mask that will be similarly applied to all inputs, for example, a mask delimiting the grey matter.
Selecting one mask per input uses the same procedure as the selection of the input 4D volumes (Manual selection in one folder, or pasting the paths).
The paths of the 4D inputs and the masks are automatically and systematically sorted. Consequently, these inputs and the masks must have the same naming convention because the pairing between a mask and an input 4D volume is done using the position of the paths in the corresponding list. Using the "View selected files" and "View selected masks" buttons, check the paths to verify that this is correct.
The region-wise analysis uses priors derived from a brain parcellation. In the provided default priors, we used the HCP multi-modal parcellation (MMP, doi.org/10.1038/nature18933). The functional signal of a region is defined as the median of the voxel values at a given time point.

Number of processors to use
The Functionnectome processing time can be significantly cut down by parallelizing it. You can choose the number of processes (i.e. the number of CPU or core used at the same time). The maximum number of parallel processes is automatically detected and set as a top limit.
The parallelization happens at the subject level, so only one subject is run at a time, which limits the RAM load. The Functionnectome parallel processing system does not support the spread of the computation across multiple machines/nodes. All the CPUs must be mounted on the same machine.
As an example, using 16 processes in parallel, the processing time of a typical fMRI scan with the voxel-wise analysis can be around 4 hours (but it depends a lot on the size of the input and how many voxels are kept with the mask).

White matter anatomical priors
As the Functionectome projects BOLD onto the brain's connections, the priors are necessary. They consist of the white matter probability maps and a brain template. The template is a T1 brain template and is used to define the dimensions of the images and to delimit the brain. The program can access them from two different types of storage: • A collection of NifTI files, with a folder containing all the probability maps (voxel-wise or region-wise), and a brain template (same dimensions as the probability maps). This option might be better if you need to easily change (some of) the priors. • An HDF5 priors file (containing all the required images). This format allows for rapid access to the files, fast transfer of the file from one location to another, and because it is not easy to change, it reduces the risk of accidentally deleting necessarily data. Check the FAQ "How do I specify different paths to alternate priors?" if you want to create your own priors.
Paths to the priors are saved in a file and are purposely not readily available (to encourage traceability practices). Ideally, the paths to the priors should be set once (when downloading them) and left alone. It is possible to specify alternative paths directly in the settings file (see FAQ "How do I specify different paths to alternate priors?"). For ease of use and to reduce the margin for errors, the settings file is always saved with the results. This way you'll always know what priors you used (default or manually changed).

Output options
Choose the output folder by either clicking on the "…" button or by copy-and-pasting the path to the text-box.
If the folder does not exist, it will be automatically created. It will serve as a "root" folder for the analysis, where the settings file (resulting from the parameters you entered in the GUI) and the additional sub-folders will be stored. Multiple analyses can use the same output folder, as long as the IDs of the input data are different. Typically, if you select "/myHome/myProject/myOutputFolder/" as the path to the output folder, the results will be stored in this structure (assuming you are doing a voxel-wise analysis): /myHome/myProject/myOutputFolder/ The last parameter available is the "Mask the output" option. If checked (recommended and set as default), the functionnectome will be masked to remove all voxels outside of the brain (as defined by the brain template, which is part of the priors).

Save, Load, Launch & Exit
The buttons at the bottom of the GUI: • Save: Saves the parameters entered on the GUI in a simple text file (with a ".fcntm" extension). It can be opened with any text editor. This settings file can be used to manually launch the Functionnectome from a terminal. All the parameters must be properly entered in the GUI before saving is possible. • Load: Loads a settings file (".fcntm") to fill the GUI parameters. Useful if you want to run a different analysis using the same input 4D files. • Launch: Saves the parameters in the output folder, closes the GUI, and runs the analysis using the provided settings. • Exit: Closes the GUI without doing anything.

Frequently Asked Questions and advanced functions
How long will the software take to process my data?
It really depends on a lot of factors. The size of the input data, but also the type of processors, the type of storing device on which the priors are written, and the number of processes all play a part. On our machines, we estimated a value of 0.004 sec/voxel/volume. So, to get an estimation of the computation time: Duration (sec.) = 0.004 x VoxelMask x NbVol / NbCore • VoxelMask: Number of voxels in the mask used in voxel-wise analysis. Replace by the number of regions in region-wise analysis.
• NbVol: Number of volumes (i.e. time point) in your input 4D file.
• NbCore: Number of cores (CPU) used to run the computation.
For example, running the Functionnectome in voxel-wise analysis, using a gray-matter mask containing 180,000 voxels, and with an fMRI scan of 1,050 volumes, on a machine with 16 cores, gives: • 0.004 x 180,000 x 1,050 / 16 = 47,250 sec » 13 hours Using the region-wise analysis drastically cuts the time needed, even using a less powerful machine (at the cost of some precision and sensitivity in the final results). Indeed, with the same input fMRI volume, using a segmentation of 438 brain areas (as in the priors), with a 4-core machine, we get: • 0.004 x 438 x 1,050 / 4 = 460 sec » 8 min Note that is approach will give you more of an order of magnitude than a precise result conserning the time needed for your processes. Importantly, some of our test seems to show that using more than 16 parallel processes doesn't not seem to improve the duration. This issue is being investigated.
How do I use the Functionnectome with command lines only?
You first need to create a settings file for your analysis (see below "Can I manually change/create a setting file?"). Let's assume it is called "settings.fcntm" and saved in /myPath/ Then: • If you manually downloaded the scripts and saved it in, e.g. /myPath/, you can run the script by simply calling: python -u /myPath/Functionnectome/functionnectome.py /myPath/settings.fcntm • If you installed the Functionnectome package using pip: o You can directly call "Functionnectome" in a command window (with the correct virtual environment) followed by the path to the settings file, e.g. "Functionnectome /myPath/settings.fcntm". o Or you can find where the functionnectome.py script is stored and use it as is shown above. o You could also create a simple script importing the package, then running the function. For example, something like that: from Functionnectome.functionnectome import run_functionnectome fpath="/myPath/settings.fcntm" run_functionnectome(fpath) Probability maps (region) path: Region masks path:

###
An example file using this option can be found in the project directory: • settings_example2.fcntm How do I make my own anatomical priors?
We do not have a readily available, easy to use code yet.
In essence, you are free to generate any kind of probability maps that reflect the probability of connection from each voxel to the rest of the brain, using the method of you choice. On that subject, we encourage you to build your own priors to better fit the type of analysis you are planning to do, or simply try and improve upon ours priors.
Note that the tractography used to generate the priors provided here used a deterministic approach, with parameters tuned to provide the most accurate results with regard to axonal tracing studies and with post-mortem dissections.
How do I create my own HDF5 file for my priors?
We provide a script to export the priors in NIfTI format into a single HDF5 file. If you installed the package through pip, you can directly call "MakeH5" from a terminal. Otherwise, you can find the script in the project/package under the name makeHDF5prior.py. The command requires 5 arguments, each being the path to one of the input data. • /myProject/myPriors.h5 the output path to the generated HDF5 file.
• /myData/brainT1template.nii.gz the input path to the brain template file (used to mask the brain) • /myData/myVoxelwisePriors the input path to the folder containing the voxel-wise priors • /myData/myRegionwisePriors the input path to the folder containing the region-wise priors • /myData/myParcellation the input path to the folder containing the masks of the brain regions used to generate the region-wise priors Both voxel-wise and region-wise priors must be given, but if you plan to only use one type of analysis, you can provide "fake" folders for the unwanted priors. These fake folders should then contain at least 1 NIfTI image with the proper geometry (for example, a copy of the template image should do), with a proper filename (see below).