francopestilli / life

Please use the new version of LiFE: www.github.com/brain-life/encode

Linear Fascicle Evaluation (LiFE)

Statistical evaluation for brain connections and tracts.

This code is deprecated and unsupported.

The current version of the LiFE algorithm can be found at GitHub.com/Brain-Life.

This is the article describing the most recent approach: Caiafa, C. and Pestilli, F. Multidimensional encoding of brain connectome. Nature Scientific Reports 7, Article number: 11491 (2017)

About

Standard tractography can use diffusion measurements from a living brain to generate a large collection of candidate white-matter fascicles; the connectome. Linear Fascicle Evaluation (LiFE) takes any connectome and uses a forward modelling approach to predict diffusion measurements in the same brain. LiFE predicts the measured diffusion signal using the orientation of the fascicles present in a connectome. LiFE uses the difference between the measured and predicted diffusion signals to measure prediction error. The connectome model prediction error is used to compute two metrics to evaluate the evidence supporting properties of the connectome. One metric -the strength of evidence - compares the mean prediction error between alternative hypotheses. The second metric - the earth movers distance - compares full distributions of prediction error. These metrics can be used for: 1. Comparing tractography algorithms 2. Evaluating the quality of tractography solutions for individual brains or group of brains and 3. Testing hypotheses about white-matter tracts and connections.

Application.

• Evaluate the evidence supporting white-matter connectomes generated using magnetic resonance diffusion imaging and computational tractography .

• Perform statistical inference on white-matter connectomes: Compare white-matter connectomes, show the evidence for white-matter tracts and connections between brain areas.

License.

Copyright (2013-2017), Franco Pestilli, [email protected]

Documentation.

Stable code release.

How to cite LiFE.

Pestilli, Franco, Jason D. Yeatman, Ariel Rokem, Kendrick N. Kay, and Brian A. Wandell. Evaluation and statistical inference for human connectomes. Nature methods 11, no. 10 (2014): 1058-1063.

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

Funding.

This work was supported by grants by US National Science Fundation (NSF BCS-1228397; NSF IIS-1636893; NSF BCS-1734853) and National Institute for Health (NEI EY015000).

Installation.

1. Download LiFE.
2. Start MatLab.
3. Add LiFE to the matlab search path.

Dependencies.

• MatLab.
• vistasoft.
• Matlab Brain Anatomy (MBA).

Getting started.

Learn about LiFE by using life_demo.m in MatLab.

1. Download LiFE.

• Download the LiFE repository from the TAR/ZIP files linked here.
• UNZIP/UNTAR the file.
• Add the life folder to your matlab search path. To do so in the MatLab prompt type:

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

2. Download vistasoft.

• Download the VISTASOFT repository from the TAR/ZIP files linked here.
• UNZIP/UNTAR the file.
• Add the VISTASOFT folder to your matlab search path. To do so in the MatLab prompt type:

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

3. Download LiFE Data Demo.

• Download the LiFE demo data set from the repository here.
• UNZIP/UNTAR the file.
• Add the unzipped/untarred Data folder to your matlab search path. To do so in the MatLab prompt type:

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

4. Read the life_demo documentation.

Read the description of the calculations in the documentation inside the file, life_demo.m by typing the following in the matlab prompt:

  >>  edit life_demo

5. Run the life_demo code.

This final step will run the life_demo code. The code will perform the operations described here.

  >>  life_demo

life_demo.m runs in about 30 minutes on a modern Intel processor with 8GB of RAM. This code has been tested with MatLab 2012b on Ubuntu 12.10 and Mac OSX 10.9.

LiFE in Python : Dipy

The LiFE algorithm has been recently implemented in Python by Ariel Rokem and is now available as part of the Dipy software: LiFE @ Dipy.

life's Issues

NaN values in out.trueError, in the bbnnls_GLNXA64 function

Running life_BD_demo, feSet calls bbnnls_GLNXA64. In this last there seems to be a problem (at least for my data), where out.trueError is NaN for all iterations (and the process finished after all 500 default iterations ended).

Issue in making fe.fg in feSet/feConnectomeInit.

In the newest version of LiFE code, I have a problem in feConnectomeInit.

The problem is at line 49 in feConnectomeInit
fe = feSet(fe,'fg from acpc',fg);

In the newest version, we can define fg as a variable already loaded by fgWrite (in line 43).

However, the newest version of feSet is (from lines 46-60);
case 'fgfromacpc'
% Fiber group candidate fascicles, Connectome.
% Everything isin img coordinates in LiFE

% If it is a file name load.
if ischar(val) && exist(val,'file') 
    [p,n] = fileparts(val);
    val     = fgRead(val); 
    fe.fg  = feSet(fe,'fg',fullfile(feGet(fe,'folder'),n,'_img.mat'));
end

fgWrite(dtiXformFiberCoords(val, fe.xform.acpc2img,'img'));

% Must clear when we change the fg
fe = feSet(fe,'voxel 2 fiber node pairs',[]);

This means, if the var were file name (char), feSet specify fe.fg but if the variable was fg structure, feSet skips the process for assigning fe.fg.

This is a problem because if fe.fg is not determined properly, the code breaks at some point. This code produce empty fe.fg.

Are there any ideas on how to assign fe.fg when we loaded fg structure in advance and put those into feSet?

fefgGet - do we need it, really?

We should have a discussion about why we absolutely need to have fgGet and fefgGet. I know this seemed important to FP. It makes the code organization much harder to follow - why is there an fg and also an fg that is specialized to the fe context. If we can reorganize to eliminate the two types of fg gets, many good things will follow (IMO).

Coordinate management - fiber groups and ROIs

We are trying to use the feGet related to voxel coordinates and indices and so forth. The array of options is very large and somewhat confusing. Perhaps we can simplify.

Further, the creation of the ROI coordinates adds a +1 to the fiber group coordinates. So, there is an inconsistency in the numerical values. I don't see this documented adequately, and I am not sure why it should be this way.

Change feConnectomeInit.m

feConnectoemIniti can be changed to save out some of the information we currently store in the fe structure and only store the fullpath to the file instead. This will likely reduce memory consumption and help parallelization of some of the operations.

Do we need back-ward compatibility?

trk file converted from fe or fg is not readable in trackvis

Hi,

Thanks for the awesome program!

I was able to run demo_life using my tractography results (mrtrix), but a trackvis trk file converted from a fg matlab structure using fe2trk is not recognizable in trackvis (the file caused a run time error). Is there any easy solution to this? I would like to save the life optimized tracks into tck (mrtrix) format eventually to be able to use mrtrix functions.

Thanks so much for your help.

Best,

Jiook

feComputeEvidenceFromTracts.m

write a function that takes:

• fg of a set of tracts
• fg of whole brain tractography
• DWI nifti, bvecs, bvals
• coregistered anatomical t1 (for plotting)
• a whole brain white matter segmentation

The function should:

1. compute the minmax(X,Y,Z) of the coordinates of all tracts passed it.
2. restrict the white matter mask to the cube contained by those coordinates.
3. build endpoints roi from the tracts
4. clip the whole brain fiber group to this new white-matter volume.
5. find tracts similar to the ones passed in present inside the whole brain fiber group by looking at fibers that share both endpoints with the tracts fibers.
6. add the found tracts in 5. to the tracts passed in.
   1. combine the whole brain fiber group and the tracts keeping track of the indices of each individual tract inside the new fiber group.
   2. build a life model from the new fiber group.
   3. fit the model.
   4. test the evidence for each tract.

This can be thought as a general mechanisms for any test when building a whole brian connectome is not possible due to computational limits.

feVirtualLesion

Line 85
se = feComputeEvidence((feGetRep(feNoLesion,'vox rmse')),(feGetRep(feLesion, 'vox rmse')));

Are there any particular reasons for using feGetRep here?
We do not always have data for cross-validation, and the code does not work if fe misss .rep structure.

fe.life

I found that the structure fe.life is removed from the newest version of feSet.m
fe.life will not be used for anymore?

I found that there are several codes which are still using fe.life, which will make bugs.

feGet.m
feConnectomeReduceFibers.m
feConnectomeReduceVoxels.m
feGetConnectomeInfo.m
feConnectomeBuildModel.m

fefgGet

In fefgGet,

line 223,
val = ceil(horzcat(fg.fibers{:})')+1;

should be
val = floor(horzcat(fg.fibers{:})');

because the previous one may make some displacement between fiber coordinates and roi coordinates to test in virtual lesion. If you agree, I'd be happy to make a pull request about this.

Adding images

feGet is very long.

It should be possible to organize the gets in feGet into a few clusters and sort them so that we don't have quite such a long file. And perhaps some of the gets should be eliminated.

Make a routine for reading tck files directly into LiFE

This currently requires a bit of a loop. First you need to convert the tck file into a pdb file using mrtrix_tck2pdb, then you need to use mtrImportFibers to read that one, and finally you need to save that into a mat file, which LiFE can read (e.g. here: https://github.com/francopestilli/life/blob/master/scripts/life_demo.m#L73). It would be nice to have one routine do all of that automatically.

Coordinates - when are they cell arrays, and when are they matrices and do they have to be integers?

We sent in doubles and were rejected because ints are required. Maybe that's OK to force us to think about image space.

But maybe not. Maybe we just need to check that round(X) == X.

Check out Blaze

https://code.google.com/p/blaze-lib/wiki/Benchmarks

V2FNP mapping using has tables: http://en.wikipedia.org/wiki/Hash_table

These are comments to speed up the code, look over these options:

http://stackoverflow.com/questions/12625629/is-there-any-way-to-use-hashtables-hashmaps-in-matlab
http://www.mathworks.com/matlabcentral/fileexchange/15831-hashtable-class

Containers:

m = containers.Map(1:1000000,ones(1,1000000));
tic; for i=1:100000, m(i); end; toc
Elapsed time is 2.715635 seconds

ismemberc.m

Or look at last example here:
http://www-h.eng.cam.ac.uk/help/tpl/programs/Matlab/tricks.html