Home

Awesome

Encode: Multidimensional encoding of brain connectomes

alt tag

About

This software implements a framework to encode structural brain connectomes into multidimensional arrays. These arrays are commonly referred to as tensors. Encoding Connectomes provides an agile framework for computing over connectome edges and nodes efficiently. We provide several examples of operations that can be performed using the framework.

One major application of the tensor encoding is the implementation of the Linear Fascicle Evaluation method, in short LiFE. The tensor encoding method allows implementing LiFE with a dramatic reduction in storage requirements, up to 40x compression factors. Furthermore, connectome encoding allows performing multiple computational neuroanatomy operations such as tract-dissections, virtual lesions, and connectivity estimates very efficiently using machine-friendly array operators.

We provide demos to explain how to: (1) Load and encode diffusion-weighted data and tractography models of white matter fascicles, as well as perform multidimensional arrays operations. (2) Build and optimize a Linear Fascicle Evaluation model. (3) Perform neuroanatomical segmentation, computational neuroanatomy operations, and virtual lesions using the connectome encoding framework. (4) Reproduce some of the figures of an article describing the method implemented in this toolbox: Caiafa, C.F., Pestilli, F. Multidimensional encoding of brain connectomes. Sci Rep 7, 11491 (2017). https://doi.org/10.1038/s41598-017-09250-w

Application.

License.

Copyright (2017), Cesar Caiafa, ccaiafa@gmail.com and Franco Pestilli, frakkopesto@gmail.com

Stable code release.

View Linear Fascicle Evaluation (LiFE) on File Exchange

How to cite the software.

Caiafa, C. and Pestilli, F. Multidimensional encoding of brain connectomes. Scientific Reports. volume 7, Article number: 11491 (2017).

Caiafa, C., Sporns, O., Saykin, A., and Pestill, F., Unified representation of tractography and diffusion-weighted MRI data using sparse multidimensional arrays. Advances in Neural Information Processing Systems 30 (NIPS 2017)

Funding.

NIH-5UL1TR-001108_05 NSF-BCS-1636893

Installation.

  1. Download (https://github.com/brain-life/encode).
  2. Start MatLab.
  3. Add repository to the matlab search path.

Dependencies.

Getting started.

1. Download the repository.

   >> addpath(genpath('/my/path/to/the/encode/folder/'))

2. Download the vistasoft repository.

   >> addpath(genpath('/my/path/to/the/VISTASOFT/folder/'))

3. Download the MBA repository.

   >> addpath(genpath('/my/path/to/the/MBA/folder/'))

4. Download the Demo Datasets.

   >> addpath(genpath('/my/path/to/the/Demo_Data_for_Multidimensional_Encoding_of_Brain_Connectomes/'))

5. Run the demo_connectome_encoding code.

Here you will learn about creating the tensor representation of a connectoms and perform basic operations such as identifying fascicles having a particular spatial orientation in a small voxel area.

  >>  demo_connectome_encoding.m

6. Run the demo_connectome_data_comparison code.

This code reproduce Fig. 3 of the paper "Multidimensional encoding of brain connectomes", by C. Caiafa and F. Pestilli.

  >>  demo_connectome_data_comparison.m

7. Run the demo_virtual_lesion code.

This code allows you to compute virtual lesions on a particular brain dataset and visualize particular major tracts together with their path-neighborhood, i.e. fascicles sharing same voxels.

  >>  demo_virtual_lesion.m

8. Run the demo_LiFE code.

This code allows you to compute compute the fascicles weights for two different tractography methods, probabilistic and deterministic tractographies, on a same brain. This is similar to the original LiFE demo in https://github.com/francopestilli/life but here a full brain dataset is used. The optimization (fitting fascicles weights) runs in about 3 hours on a modern Intel processor with 8GB of RAM. This code has been tested with MatLab 2015b on Ubuntu 15+ and Mac OSX 10.11.

  >>  demo_LiFE.m

9. Description of the output data structure (fe.mat)

fe fields

• fe.name: [text], customized name of the structure.
• fe.type: [text], type description.
• fe.life: [1 × 1 struct], results of the LiFE method, see fe.life fields description below.
• fe.fg: [1 × 1 struct], input fiber group (connectome) information, see fe.fg fields description below.
• fe.roi: [1 × 1 struct], input fiber group (connectome) information, see fe.roi fields description below.
• fe.path: [1 × 1 struct], paths to input data (connectome, dMRI data, etc.).
• fe.rep: [1×1 struct], dMRI data for a repeated measurement if available.

fe.life fields

• fe.life.M.Phi: [Na × Nv × Nf sptensor], sparse array Φ encoding the connectome.
• fe.life.M.Nphi: Discretization number in azimuth, default = 360.
• fe.life.M.Ntheta: Discretization number in elevation, default = 360.
• fe.life.M.orient: [3 × Na double], matrix containing in its columns the orientations for each Dictionary element.
• fe.life.M.DictSig: [Nθ × Na double], Dictionary matrix containing in its columns the canonical diffusion kernel (demeaned) at different orienta- tions.
• fe.life.xform.img2acpc: [4 × 4 double], Image to ACPC affine trans- form.
• fe.life.xform.acpc2img: [4 × 4 double], ACPC to image affine trans- form.
• fe.life.fibers: not used.
• fe.life.diffusion_signal_img: [Nv × Nθ double], dMRI data.
• fe.life.diffusion_S0_img: [Nv × 10 double], diffusion signal measured at b = 0 (ten times). Usually, we compute S0(v) by averaging over the ten available values.
• fe.life.bvecs: [Nθ × 3 double], each row indicates the gradient 3D di- rection.
• fe.life.bvals: [Nθ × 1 double], each row indicates the used b-value for each gradient.
• fe.life.bvecsindices: [Nθ × 1 int], indices for measurements with non- zero b-value.
• fe.life.imagedim: [Nx , Ny , Nz , Nm ], size of the input 4D dMRI dataset where (Nx,Ny,Nz) are the the sizes in each coordinate, x, y and z, respec- tivelly; and Nm correspond to the number of measurements with b = 0 and b ̸= 0.
• fe.life.voxel2FNpair: not used.
• fe.life.modelTensor: [λ1 , λ2 , λ3 ], parameters of the Diffusion Tensor (DT) model used to generate the Dictionary of diffusion kernels.
• fe.life.fit: this field contains the results of applying the LiFE method, see description below.

fe.life.fit fields

• fe.life.fit.randState: saved by the optimization algorithm.
• fe.life.fit.results: saved by the optimization algorithm.
• fe.life.fit.weights: [Nf × 1 double], fascicles weights obtained as a result of the optimization.
• fe.life.fit.params.fitMethod: [text], name of used optimization method, default is “bbnls”.

fe.fg fields

• fe.fg.name: [text], name of Fiber Group (connectome).
• fe.fg.colorRgb: [R, G, B], color specification for visualization.
• fe.fg.thickness: [double], thickness specificattion for visualization.
• fe.fg.visible: [binary], parameter for visualization.
• fe.fg.seeds: Seeds used by MRTRIX software to generate the connectome.
• fe.fg.seedRadius: MRTRIX parameter.
• fe.fg.seedVoxelOffsets: MRTRIX parameter.
• fe.fg.params: additional MRTRIX parameters.
• fe.fg.fibers: {Nf ×1 cell}, set of fascicles (streamlines), generated with a tractography algorithm. Each cell contains the x,y,z coordinates a list of 3D points describing the trajectory of a single fascicle.

fe.roi fields

• fe.roi.name: [text], name of ROI.
• fe.roi.color: [R, G, B], color specification for visualization.
• fe.roi.coords: [Nv ×3 double], voxel coordinates, each row specifies the spatial location of a single voxel.
• fe.roi.visible: [binary], parameter for visualization.
• fe.roi.mesh: not used.
• fe.roi.dirty: parameter for visualization
• fe.roi.query_id: not used.

Notes

This software is currently compatible with Matlab 2020b or higher and only with Mac OSX and Linux (Ubuntu/Fedora).