Connectome pipeline¶
This tutorial shows how to use the NIAK connectome pipeline to generate seed-based functional connectivity maps on a single subject from the COBRE "lightweight" sample.
clear
path_data = [pwd filesep];
[status,msg,data_fmri] = niak_wget('cobre_lightweight20_nii');
When starting from fMRI data preprocessed with NIAK, it is possible to use niak_grab_fmri_preprocess on the output folder to collect the file names, as described in the pipeline documentation. In this case, we explicitely list all the files
file_pheno = [data_fmri.path filesep 'phenotypic_data.tsv.gz'];
tab = niak_read_csv_cell(file_pheno);
list_subject = tab(2:end,1);
files_in = struct;
for ss = 1:length(list_subject)
files_in.fmri.(list_subject{ss}).sess1.rest = [data_fmri.path filesep 'fmri_' list_subject{ss} '.nii.gz'];
end
Brain parcellation¶
The second input of the pipeline is a set of brain parcels. We will just download the so-called Cambridge functional template.
[status,msg,data_template] = niak_wget('cambridge_template_mnc1');
We are going to pick the parcellation into 7 distributed networks.
files_in.network = [data_template.path filesep 'template_cambridge_basc_multiscale_sym_scale007.mnc.gz'];
List of seeds¶
The next step is to generate a list of seeds. This requires creating a text file that looks like:
, index
MOTOR , 3
DMN , 5We are going to use NIAK's tool to write comma-separated values (CSV) in a file:
files_in.seeds = [path_data 'list_seeds.csv'];
opt_csv.labels_x = { 'MOTOR' , 'DMN' }; % The labels for the network
opt_csv.labels_y = { 'index' };
tab = [3 ; 5];
niak_write_csv(files_in.seeds,tab,opt_csv);
Set the options of the pipeline¶
Now we set up where to store the results:
opt.folder_out = [path_data 'connectome'];
We set options such that we will not generate graph properties, just the correlation maps:
opt.flag_p2p = false; % No parcel-to-parcel correlation values
opt.flag_global_prop = false; % No global graph properties
opt.flag_local_prop = false; % No local graph properties
opt.flag_rmap = true; % Generate correlation maps
Run the pipeline¶
Now let's run the pipeline:
opt.flag_test = false;
[pipeline,opt] = niak_pipeline_connectome(files_in,opt);
Reviewing outputs¶
The pipeline generates an interatice dashboard to explore brain connectivity maps. Just open the file connectome/report/index.html in your browser.
All the correlation maps have been generated in the subfolder called rmap_seeds, inside the output folder. There are first two average (across all subjects) maps, for each selected seed. We can have a quick look at them. Note that the files have been named using the identification codes in the file files_in.seeds.
file_dmn = [opt.folder_out filesep 'rmap_seeds' filesep 'average_rmap_DMN.nii.gz'];
file_motor = [opt.folder_out filesep 'rmap_seeds' filesep 'average_rmap_MOTOR.nii.gz'];
[hdr,rmap_dmn] = niak_read_vol(file_dmn);
[hdr,rmap_motor] = niak_read_vol(file_motor);
size(rmap_dmn)
size(rmap_motor)
We will now use niak_vol2img to generate a series of axial slices for both maps.
% The default-mode network
opt_v = struct;
opt_v.vol_limits = [0.25 0.7];
opt_v.type_color = 'hot_cold';
niak_montage(rmap_dmn,opt_v)
% The sensorimotor network
opt_v = struct;
opt_v.vol_limits = [0.25 0.7];
opt_v.type_color = 'hot_cold';
niak_montage(rmap_motor,opt_v)
There are also two files which contain the seeds as binary masks. E.g.:
file_mask_dmn = [opt.folder_out filesep 'rmap_seeds' filesep 'mask_DMN.nii.gz'];
[hdr,mask_dmn] = niak_read_vol(file_mask_dmn);
opt_v = struct;
opt_v.vol_limits = [0 1];
opt_v.type_color = 'hot_cold';
niak_montage(mask_dmn,opt_v)
Finally, there are also individual connectivity maps for each subject, named using the IDs we used in files_in.fmri. If multiple runs were specified per subject, the pipeline would average the maps from all runs.
file_dmn_40003 = [opt.folder_out filesep 'rmap_seeds' filesep 'rmap_40003_DMN.nii.gz'];
[hdr,rmap_dmn_40003] = niak_read_vol(file_dmn_40003);
opt_v = struct;
opt_v.vol_limits = [0.4 1];
opt_v.type_color = 'hot_cold';
niak_montage(rmap_dmn_40003,opt_v)
We will now load a connectome, aka an individual matrix of correlation between time series of different parcels.
file_connectome_40003 = [opt.folder_out filesep 'connectomes' filesep 'connectome_rois_40003.mat'];
data = load(file_connectome_40003);
The connectome is stored in a variable called conn. The matrix has been vectorized, keeping only diagonal and lower triangular values. To get back a square matrix we need to run niak_lvec2mat:
size(data.conn)
conn = niak_lvec2mat(data.conn);
size(conn)
We have 7 parcels corresponding to our original brain parcellations. Parcels do not need to be numbered 1, 2, ... etc in the original parcellation volume. The numeric IDs of each parcel are stored in data.ind_roi:
data.ind_roi
So here parcels were actually numbered 1 to 7. We can visualize the connectivity matrix:
niak_visu_matrix(conn)
Here the connectivity values are Fisher transformation of correlation coefficients between average time series (for the inter-parcel connectivity), and Fisher transformation of average correlation between any pair of disctinct voxels inside the parcel (for intra-parcel connectivity).
Finally note that you can get a list of all files generated by the pipeline easily:
files = niak_grab_connectome(opt.folder_out)
Using that tool you can easily move to other toolboxes. Check FSL PALM for non-parametric linear regression tests on the connectivity maps (Matlab/Octave-based), and the brain connectivity toolbox for graph analysis (Matlab/Octave-based).