Documentation‎ > ‎

Data exchange between DSI Studio and Matlab



Introduction

    All the data output from DSI Studio can be loaded into Matlab for further calculation. Likewise, the data exported from Matlab can also be loaded into DSI Studio, provided that the matrices are named under certain rules and saved in MAT4 format. This data exchange function enables user to manipulate the images using Matlab and presented it using the powerful 3D engine provided by DSI Studio. 

    The SRC file (*.src, *.src.fib.gz) stores the diffusion weighted images and spatial information, which can be used to do reconstruction. The SRC files are MATLAB matrix file stored in V4 version. The src.gz is the SRC file compressed by gzip. To load an SRC file in MATLAB, uncompress the file and rename it as .mat.

    The FIB file (*.fib, *.fib.gz) stores the vector field (fiber orientations) and anisotropy information (the magnitude), which can be used by DSI Studio to conduct multiple direction fiber tracking. The FIB files are also MATLAB matrix file stored in V4 version. The fib.gz files are the FIB files compressed by gzip. 


SRC file


An SRC file stores the raw image volumes in addition to image dimension, voxel size, and b-table (see how to get .src file). To load an SRC file into Matlab, extract .src.gz file to create an uncompressed .src file. Then rename the .src file to .mat file and load it in Matlab. The meanings of each exported matrix are explained as follows.

dimension
    This 1x3 vector is the dimension of the containing image.

voxel_size
    The voxel size in each dimension. (mm)

image0~imageN
    The images extracted from DICOM or NIFTI files. These matrices can be restored to a 3-dimensional image volume by the command "reshape(image0,dimension);"

b-table
    The b-table of the extracted images. b(1,:) stores b-value, whereas b(2:4,:) stores gradient vector.

After loading the .src file in Matlab, the user can process the data and save it back to an SRC file using "save('filename.src','-v4');" Note that you have to specify '-v4' so that DSI Studio can read the .src file.

Example: Load the DWI as a 4D image from a src.gz file


function [image btable vs]= read_src(file_name)
if ~exist('file_name')
    file_name =  uigetfile('*.src.gz');
end
if file_name == 0
    image = [];
    return
end
gunzip(file_name);
[pathstr, name, ext] = fileparts(file_name);
movefile(name,strcat(name,'.mat'));
load(strcat(name,'.mat'));
bsize = size(b_table);
image = zeros([dimension bsize(2)]);
for i = 1:bsize(2)
    eval(strcat('image(:,:,:,',int2str(i),')=reshape(image',int2str(i-1),',dimension);'));
    eval(strcat('clear image',int2str(i-1)));
end
delete(strcat(name,'.mat'));
btable = b_table;
vs = voxel_size;
end


Example: change the DWI image orientation in the src file. The axial slice is rotated to sagittal direction.


%change permute_dim and num_dwi according to your case 
permute_dim = [3 1 2];

num_dwi = 120;

for i = 0:num_dwi

% reodering the dim to z x y
eval(strcat('image',int2str(i),' = permute(reshape(image',int2str(i),',dimension),permute_dim);'));
% flip the third dimension
eval(strcat('image',int2str(i),' = image',int2str(i),'(:,:,128:-1:1);'));
eval(strcat('image',int2str(i),' = reshape(image',int2str(i),',1,[]);'));

end

dimension = size(permute(reshape(image0,dimension),permute_dim));


% copy the b_value
new_b_table(1,:) = b_table(1,:);

% rotate the b_vector
for i = 1:3
   new_b_table(i+1,:) = b_table(permute_dim(i)+1,:);
end

b_table = new_b_table;

clear new_b_table;
clear i;

save output.src -v4

Example: Save a 4D matrix to the src file



%dbsi_data is a 4D matrix arranged in [x,y,b_vector,z]

dim = size(dbsi_data);

num_dwi = dim(3);
dim(3) = [];

% save image matrix
for i=1:99
eval(strcat('image',int2str(i-1),'=dbsi_data(:,:,',int2str(i),',:);'));
eval(strcat('image',int2str(i-1),'=reshape(squeeze(image',int2str(i-1),'),1,[]);'));
end

% input voxel size in mm
voxel_size = [1,1,1];

% the dimension of each DWI
dimension=dim;

b_table = zeros(4,num_dwi);
% input b_value
b_table(1,:) = b_value; 
b_table(2:4,:) = b_vector; 

save example.src -v4


FIB file

 
    An FIB file contains fiber directions and related anisotropy indices such FA or QA (see how to get .fib file).  To load an FIB file into Matlab, extract the *.fib.gz file into ean uncompressed .fib file. Then rename the .fib file to .mat file and load it using Matlab. The meanings of each exported matrix are explained as follows.
 

   

Spatial information


dimension
    This 1x3 vector is the dimension of the containing image.

voxel_size
    The voxel size in each dimension. (mm)

Quantitative measurements


fa0, fa1, fa2,...

The fa0, fa1,... matrices are image volume recording the anisotropy values of the first fiber (fa0), second fiber (fa1) ...etc. Note that a voxel can have multiple fiber orientations. These FA matrices are originally three-dimensional matrices but stored as one-dimensional vectors. To restore the matrix back to three-dimensional, use the following command.

fa0 = reshape(fa0,dimension);


If there is no fiber resolved in a voxel, the corresponding FA value is assigned by zero. Note that in DSI, QBI, and GQI reconstruction, the fa matrices stores the QA values (The definition of QA is documented in Yet et al., "generalized q-sampling imaging", IEEE TMI, 2010), not the FA value. These fa matrices will be used as the fiber termination threshold to determine the end point of the tracks.

Any matrix stored with a dimension of 1-by-n will be viewed as the quantitative measurements if n matches the total image volume. You can store any mapping such as "gfa", "diffusivity", "t1_map" and DSI Studio can use them in track specific analysis.


Fiber orientation

index0, index1, index2,...
  
    These index matrices store the "directional index" of the fiber orientation instead of the full orientation vector. For example: 

%the 1st fiber orientation at coordinate (10,10,10) stored as dir0
index0 = reshape(index0,dimension);
dir0 = odf_vertices(:,index0(10,10,10)+1);

%the 2nd fiber orientation at coordinate (10,10,10) stored as dir1
index1 = reshape(index1,dimension);
dir1 = odf_vertices(:,index1(10,10,10)+1);

    
    The orientation table is stored in a matrix named odf_vertices. The index is zero based. For instance, if a voxel's index0 value is 5, the voxel's first fiber has an orientation of odf_vertices(:,5+1).

    DSI Studio also supports storing the directional vector instead of directional index. The directional vectors will be stored by "dir0", "dir1" ..etc. Each has a dimension of 3xN.

    dir0 is the directional vector of the most prominent fiber, and dir1 is the vector of the second most prominent fiber. These matrices have to be "reshaped" to restore to its original form:

 dir0 = reshape(dir0,[3 dimension]);

    This will make it a 3-by-x-by-y-by-z matrix. 

    To determine the number of fibers in a voxel, we need to refer to fa0, fa1, fa2...etc. For example, if a voxel has two fibers, its fa0 and fa1 have nonzero values, whereas fa2, fa3,... are zero. 

ODF information (optional)


odf1, odf2, ....
     The ODF values of each voxel can also be exported from DSI Studio. To get the ODF data, check the "output ODF" check box in advance option of the reconstruction window. DSI Studio will store a series of matrices named odf1, odf2,.... For each these odf matrices, the dimension is e.g. 321-by-20000. 321 is the dimension of an ODF vector (the actual value depends on the ODF order), and 20000 is the number of the ODFs stored. Note that only the ODFs from the voxels with QA > 0 or FA > 0 are stored.

     For more detail about how to use the ODF matrix and visualize them, please refer to the ODF visualization document. If you are using the ODFs calculated from QSDR, you may also need to look into this document to handle the discrepancy between ODF counts and a number of voxels with qa > 0.

Example: load a fib.gz file and get the information

function [fa index odf_vertices odf_faces]= read_fib(file_name)
if ~exist('file_name')
    file_name =  uigetfile('*.fib.gz');
end
if file_name == 0
    image = [];
    return
end
gunzip(file_name);
[pathstr, name, ext] = fileparts(file_name);
movefile(name,strcat(name,'.mat'));
fib = load(strcat(name,'.mat'));

max_fib = 0;
for i = 1:10
    if isfield(fib,strcat('fa',int2str(i-1)))
        max_fib = i;
    else
        break;
    end
end

fa = zeros([fib.dimension max_fib]);
index = zeros([fib.dimension max_fib]);

for i = 1:max_fib
    eval(strcat('fa(:,:,:,i) = reshape(fib.fa',int2str(i-1),',fib.dimension);'));
    eval(strcat('index(:,:,:,i) = reshape(fib.index',int2str(i-1),',fib.dimension);'));
end

odf_vertices = fib.odf_vertices;
odf_faces = fib.odf_faces;
delete(strcat(name,'.mat'));
end


The odf_vertices matrix stores the ODF sampling orientations table. This table stores sampling orientations that are equally-distributed (almost) on a sphere with the radius of one. You can use the table generated from DSI Studio or any table you prefer. The odf_face matrix indicates which three orientations forms a triangle on an ODF. YOU may use the one generated from DSI Studio. The exemplary table can be download at the bottom of this page.

Examples:

Get the fiber orientation at coordinate (x,y,z)

% decompress the fib.gz to fib file
% the (x,y,z) coordinates starts from (0,0,0)
load xxx.fib
index0 = reshape(index0,dimension);
fiber_orientation = odf_vertices(:,index0(x+1,y+1,z+1)+1);


Save an FIB file

     Similar to saving .src file, users can save the .fib file using the "save xxx.fib -v4" command. The generated .fib files are readily loadable in DSI Studio. Note that some matricies are required in a .fib file, including the dimension (matrix named "dimension"), voxel size (matrix named "voxel_size"), fiber directions (dir0, dir1, dir2 or index0, index1, index2), and fiber anisotropy (fa0, fa1, fa2). ODF information is in optional and can be left out.

   

Comments