Documentation‎ > ‎

Command line interface of DSI Studio


Introduction

    DSI Studio has command line interface to support batch processing. The graphic user interface (GUI) and command line interface shares the same DSI Studio executive. If DSI Studio is executed with command line parameters, then the command line will be initiated. Otherwise, graphic user interface will bring up the main window.

    In the Windows system, a batch script (examples in this page) can be used to automate processing by calling the DSI Studio program (dsi_studio.exe) directly. In the MacOS system, DSI Studio is distributed as an app package. To run the command line, you may need to run "./dsi_studio.app/Contents/MacOS/dsi_studio", where dsi_studio.app is the app package in the dsi_studio.dmg file. A bash script can be used to automate processing on image data.


Fiber tracking


     The fiber tracking function on DSI Studio can be executed by using command line. After fiber tracking, a log file named tracking_log.txt will be generated. The result can be saved as a .txt file or .trk file. The detail for tracking commands is as follows. For parameters not assigned explicitly, default values will be used instead.

Parameters 



    action: use "trk" to perform fiber tracking

    source: specify the .fib file for tracking. 


    The following are tracking parameters

    method: tracking methods 0:streamline (default), 1:rk4 

    fiber_count : specify the number of fibers to be generated. If seed number is preferred, use seed_count instead. If DSI Studio cannot find a track connecting the ROI, then the program may run forever. To avoid this problem, you may assign fiber_count and seed_count at the same time so that DSI Studio can terminate if the seed count reaches a large number.

    fa_threshold: the threshold for fiber tracking. In QBI, DSI, and GQI, "fa_threshold" will be applied to QA threshold. To use other index as the threshold, add "threshold_index=[name of the index]" (e.g. "--threshold_index=nqa --fa_threshold=0.01" sets a threshold of 0.01 on nqa for tract termination). If fa_threshold  is not assigned, then the default Otsu's threshold will be used.

    otsu_threshold: The default Otsu's threshold can be adjusted to any ratio. The default value is 0.6.

    initial_dir: initial propagation direction 0:primary fiber (default), 1:random, 2:all fiber orientations

    seed_plan: specify the seeding strategy 0:subvoxel random (default) 1:voxelwise center

    interpolation:interpolation methods (0:trilinear, 1:gaussian radial, 2:nearest neighbor)

    thread_count: specify the thread count. 1 for single thread. 2 for two threads...

    random_seed: specify whether a timer is used for generating seed points. Setting it on (--random_seed=1) will make tracking random. The default is off. 

    step_size, turning_angle, interpo_angle, fa_threshold, smoothing, min_length, max_length: refer to tracking manual for detail. The step_size, min_length, and max_length are at a scale of a millimeter.

    *Assigning these tracking parameters takes a lot of time. To save the hassle, you can use "parameter_id" from the GUI (After running fiber tracking in GUI, the parameter ID will be shown in the method text in the right bottom window) to override all parameters in one shot (e.g. --action=trk --source=some.fib.gz --parameter_id=c9A99193Fba3F2EFF013Fcb2041b96438813dcb). Please note that parameter ID does not overrider ROI settings. You may still need to assign ROI/ROA...etc. in the commnd line. 


    The following are ROI parameters

    seed: specify the seeding file. Supported file format includes text files, Analyze files, and nifti files.

    roispecify the roi file. Supported file format includes text files, Analyze files, and nifti files. Multiple input is supported.

          You may use atlas regions as the roi, roa, end, or ter regions. Specify the atlas and region name (case sensitive!) as follows:

          --roi=aal:Precentral_L  

          An ROI (and also other region types) can be modified by the following action code: "smoothing", "erosion", "dilation",  "defragment", "negate", "flipx", "flipy", "flipz", "shiftx" (shift the roi by 1 in x direction), "shiftnx" (shift the roi by -1 in x direction), shifty, "shiftny", "shiftz", "shiftnz". For example, this following command line dilate the aal:Precentral_L twice and smooth it:
 
          --roi=aal:Precentral_L,dilate,dilate,smoothing

          You may assign as most 5 rois (e.g. --roi5=...) 

    roaspecify the roa. You may assign as most 2 roas (e.g. --roa2=...) 

    end: specify the endpoint. You may assign as most 2 ends (e.g. --end2)

    ter: specify the terminative region. You may assign as most 5 ters (e.g. --ter5=...) 

    t1t2: specify t1w or t2w images as the ROI reference image (e.g. --t1t2=my_t1.nii.gz)
    
    The following are post-processing parameters

The following is a list of the track post-processing command (can also be used in --action=ana without fiber tracking)

    delete_repeat: assign the distance for removing repeat tracks (e.g. --delete_repeat=1 removes repeat tracks with distance smaller than 1 mm)

    output: specify the output file that stores the tracking result. Supported file format include text file and .trk file. You may set this parametr to no_file to disable tracotgraphy output. You may also assign .nii file as the output. DSI Studio will convert tracks into a region and save it in nifti file format. 

    You can assign multiple output files (e.g. output=track.trk.gz,track.nii.gz,track.txt)

    end_point: output end point as a txt file or mat file. specify the file name using --end_point=file_name.txt

    export: export along tack indices, statistics, TDI, or track analysis report. See the export option documented under --action=ana (below) for detail.

    connectivity: output connectivity matrix using ROIs or atlas as the matrix entry. For example, "--connectivity=aal" uses AAL atlas (there should be an aal.nii.gz file under the /atlas folder) as the matrix entry to get the connectivity of the tracks. 

    You can assign multiple atlas (e.g., --connectivity=aal,brodmann), and each atlas will generate a connectivity matrix. 

    You can assign an MNI space roi file, e.g., --connectivity="C:\test files\my_roi.nii.gz". The output will include (1) connectivity matrix as *.connectivity.mat, (2) a connectogram text file as *.connectogram.txt, and (3) network measures calculated using graph theoretical analysis as *.network_measures.txt.

    You can assign a file list text file to include a set of ROI files in the native space. The file list should be placed with the ROI files, and each line records the file name of the ROIs to be loaded (no path needed).

    connectivity_type: specify whether to use "pass" or "end" to count the tracks. The default setting is "end".

    connectivity_value: specify the way to calculate the matrix value. The default is "count", which means the number of tracks passing/ending in the regions. "ncount" is the number of tracks normalized by the median length. "mean_length" outputs the mean length of the tracks. "trk" outputs a trk file each connectivity matrix entry. Other options include "fa" (if DTI reconstruction is used), "qa", "adc" (if DTI reconstruction is used). The name of the scalar values can be found by opening the FIB file in STEP fiber tracking. There will be a list of scalar value in the region window to the left. 

    You can output multiple results by separating the parameters with ",". (e.g. --connectivity_value=count,ncount,trk)

    Please note that if the number of the connecting tracks are not enough (determined by connectivity_threshold), the connectivity value will not be calculated. This strategy is used to avoid inclusion of accidental connections due to false tracks.

    connectivity_threshold: specify the threshold for calculating binarized graph measures and connectivity values. The default value is 0.001. This means if the maximum connectivity count is 1000 tracks in the connectivity matrix, then at least 1000 x 0.001 = 1 track is needed to pass the threshold. Otherwise, the values will be set to zero.

    ref: output track coordinate based on a reference image (e.g. T1w or T2w).

    cluster: run track clustering after fiber tracking. 4 parameters separated by comma are needed: --cluster=METHOD_ID,CLUSTER_COUNT,RESOLUTION,OUTPUT FILENAME
 
                  METHOD_ID: 0=single-linkage clustering 1=k means 2=EM
                  CLUSTER_COUNT: The total number of clusters. In k-means or EM, this is the total number of clusters assigned. In single-linkage, it is the maximum number of clusters allowed to avoid over-segmentation (the remaining small clusters will be group in the last clusters).
                  RESOLUTION: only used in single-linkage clustering. The value is the mini meter resolution for merging the clusters.
                  OUTPUT FILENAME: the file name for output the cluster label (should be a txt file). The file name should not contain a space.

                  Example: --cluster=0,500,2,label.txt  run a single-linkage cluster with 500 maximum cluster count and 2-mm resolution, saved as label.txt

Example


    1. Perform fiber tracking using parameter ID 

        dsi_studio --action=trk --source=test.fib.gz --parameter_id=c9A99193Fba3F2EFF013Fcb2041b96438813dcb --output=track.trk

    2. Use the left and right precentral region from AAL atlas as the ROIs to perform fiber tracking: 

        dsi_studio --action=trk --source=test.fib.gz --roi=aal:Precentral_L --roi2=aal:Precentral_R --fiber_count=1000

    3. Use the left and right precentral region from AAL atlas as the ROIs. Dilate them twice and smooth them for fiber tracking: 

        dsi_studio --action=trk --source=test.fib.gz --roi=aal:Precentral_L,dilate,dilate,smoothing --roi2=aal:Precentral_R,dilate,dilate,smoothing --fiber_count=1000

    4. Fiber tracking using two ROIs and whole brain seeding (from wholeBrain.nii)

        dsi_studio --action=trk --source=subject1.fib --seed=wholeBrain.nii --roi=my_roi1.nii --roi2=myroi2.nii --seed_count=5000 --fa_threshold=0.0241 --turning_angle=80 --step_size=.5 --smoothing=0.85 --min_length=20 --max_length=140 --output=track.txt


    5. Perform fiber tracking and output connectivity matrix:    

        dsi_studio --action=trk --source=CMU_60_20130923build.fib.mean.fib.gz --fiber_count=1000000 --output=no_file --connectivity=aal

    6. Perform fiber tracking and output along track FA, track statistics, and TDI    

        dsi_studio --action=trk --source=CMU_60_20130923build.fib.mean.fib.gz --fiber_count=1000000 --output=tracks.trk.gz --export=fa,statistics,tdi


    7. [Batch file for windows system] Search for all fib file under the current directory and perform fiber tracking to get the AAL connectivity matrix

       
path=C:\dsi_studio_64
for /f "delims=" %%x in ('dir *.fib.gz /b /d /s') do (
    call dsi_studio.exe --action=trk --source="%%x" --seed_count=1000000 --thread_count=8 --output=no_file --connectivity=AAL > "%%x.log.txt"
)


    *The default value will be used if the parameters have no value assigned.

Image reconstruction


    The reconstruction on DSI Studio can be executed by command line. For parameters not assigned explicitly, default values will be used instead. 


Parameters


    action: use "rec" for image reconstruction

    source: assign the .src file for reconstruction

    thread_count: number of multi-thread used to conduct reconstruction.

    mask: assign the mask file in nifti format. You may skip this parameter to use the default mask.

    method: assign the reconstruction methods. 0:DSI, 1:DTI, 2:Funk-Randon QBI, 3:Spherical Harmonic QBI, 4:GQI 6: Convert to HARDI 7:QSDR. For detail, please refer to the reconstruction page

                  If you are using QSDR, you may also specify the template file for spatial normalization by adding ""--template=full_template_file_path"

    param0, param1, ...: the parameters for reconstruction. For DSI, param0 stands for the width of the hanning filter (e.g. --param0=16), and other parameters are not used. For QBI, param0 is the regularization parameter (e.g. --param0=0.006, and param1 is the order of spherical harmonics (e.g. --param1=8). For GQI, param0 is the ratio of the mean diffusion distance. For QSDR, param0 is the mean diffusion distance ratio, and param1 is the output resolution in mm. For "Convert to HARDI", param0 is the ratio of the mean diffusion distance, param1 is the b-value for the HARDI, and param2 is the regularization parameter.

    
    odf_order: assign the tesellation number of the odf. Supported values include 4, 5, 6, 8, 10, 12, 16, 20. The default value is 8.

    num_fiber: the maximum count of the resolving fibers for each voxel, default=5.

    scheme_balance: set "--scheme_balance=1" to enable scheme balance.

    half_sphere: set "--half_sphere=1" if the data were acquired with half sphere DSI.

    deconvolution: set "--deconvolution=1" to apply deconvolution. Use --param2=0.5 to assign the regularization parameter.

    decomposition: set "--decomposition=1" to apply decomposition. Use --param3=0.05 to assign the decomposition fraction and --param4=10 to assign the m value.

    r2 weighted: set "--r2_weighted=1" to apply r2-weighted GQI reconstruction.

    other_src: assign the src file for correcting the phase distortion (e.g. --source=PA_scan.src.gz --other_src=AP_scan.src.gz). It does not matter whether the other src is AP or PA.

    reg_method: In QSDR reconstruction, set 

                         --reg_method=0 to use SPM 7-9-7 for normalization.
                         --reg_method=1 is for SPM 14-18-14
                         --reg_method=2 is for SPM 21-27-21
                         --reg_method=3 for CDM (recommended #2)
                         --reg_method=4 for T1W-CDM (recommended #1) please use --t1w=subject_t1w.nii.gz to assign the T1W file for this registration

    affine: specify the file name of a text file containing a transformation matrix. DWI and its b-table will be rotated according to the matrix. 

               An example of the matrix is the following (shift in x and y directions by 10 voxels)
  
               1 0 0 -10
               0 1 0 -10 
               0 0 1 0

    flip: flip image volume and b-table. 0: flip x,  1: flip y, 2: flip z, 3: flip xy, 4: flip yz, 5: flip xz. For example, flip=301 perform "flip xy" first, followed by "flip x" and "flip y".

    rotate_to: specify a T1W or T1W to rotate DWI to its space.

    motion_correction: set "--motion_correction=1" to apply motion and eddy current correction. This correction works only on DTI dataset.

    interpo_method: assign the interpolation method used in QSDR. 0:trilinear 1:gaussian radial basis 2: tricubic interpolation

    check_btable: set "--check_btable=0" to disable automatic b-table flipping.

    other_image: assign other image volumes (e.g., T1W, T2W image) to be wrapped with QSDR. For example: --other_image=t1w,/directory/my_t1w.nii.gz;t2w,/directory/my_t1w.nii.gz

    output_mapping: used in QSDR to output mapping for each voxel

    output_jac: used in QSDR to output jacobian determinant

    output_dif: used in DTI to output diffusivity (default is 1)

    output_tensor: used in DTI to output the whole tensor
   
    output_rdi: used in GQI to output restricted diffusion imaging

    record_odf: set "--record_odf=1" to output the ODF for connectometry analysis.

    csf_calibration: set "--csf_calibration=1" to enable CSF calibration in GQI

Example


    1.DSI reconstruction with hanning filter of 16 and record the ODF

        dsi_studio --action=rec --source=20081006_M025Y_1Grid.src.gz --method=0 --param0=16 --record_odf=1

    2.GQI reconstruction with 1.25 mean diffusion distance

        dsi_studio --action=rec --source=20081006_M025Y_1Shell.src.gz --mask=mask100.nii --method=4 --param0=1.25

    3. Multi-thread QSDR reconstruction with 1.25 mean diffusion distance and 2mm output resolution. Also, export jacobian determinant and transformation map 

        dsi_studio --action=rec --thread=2 --source=20081006_M025Y_1Shell.src.gz --method=7 --param0=1.25 --output_jac=1 --output_map=1

    4. QSDR reconstruction with 1.25 sampling length ratio using SPM norm. The t1w and t2w were also warpped with QSDR

        dsi_studio --action=rec --source=20081006_M025Y_1Shell.src.gz --method=7 --param0=1.25 --reg_method=0 --other_image=t1w,my_tiw.nii.gz;t1w,my_t2w.nii.gz

    5. QSDR reconstruction with 1,25 sampling length ratio using T1W guided constrained diffeormophic mapping (T1W-CDM)

        dsi_studio --action=rec --source=20081006_M025Y_1Shell.src.gz --method=7 --record_odf=1 --param0=1.25 --reg_method=4 --t1w=subject_t1w.nii.gz

    6. A bash script that reconstructs all src.gz files in the directory

#!/bin/bash
# Reconstruct all src.gz file in the directory
# Output logging
exec 1>log_qsdr.out 2>&1

# List all src.gz files
subs=$(ls *.src.gz)

# Reconstruction Parameters
method=7          # 7 for QSDR
param0="1.25"
voxel_res="1"     # 1mm voxels
thread="16"

for sub in $subs
do
    echo
dsi_studio --action=rec --thread=${thread} --source=${sub} --method=${method} --param0=${param0} --param1=${voxel_res} --output_jac=1 --output_map=1 --record_odf=1 --reg_method=2
    echo
done

   

Generate SRC files from DICOM/NIFTI/2dseq images


    DSI Studio supports SRC file output using a command line. The DICOM images are required to be stored under a directory, and DSI Studio will search for all files using the filter "*.dcm".

Parameters


    action: use "src" for generating src file.

    source: assign the directory that stores the DICOM files or the file name for 4D nifti file.

    output: assign the output src file name.

    b_table: assign the replacement b-table

    bval: assign the b value text file

    bvec: assign the b vector text file

    recursive: search files in the subdirectories. e.g. "--recursive=1".

Example


    1. Search all Dicom files under the assigned directory and output the result to 1.src

        dsi_studio --action=src --source=C:\20081006_11_00814348_DWI_WIP_DSI_203 --output=c:\1.src.gz

    2. Parse the assigned 4d nifti file with a replacement b-table

        dsi_studio --action=src --source=c:\4d_image.nii --b_table=c:\replacement_table.txt --output=c:\1.src.gz

    3. Parse the assigned 4d nifti file with a replacement bval and bvec file

        dsi_studio --action=src --source=4d_image.nii --bval=bvals --bvec=bvals --output=1.src.gz

    4. Windows batch file for creating src files from HCP datasets

path=C:\dsi_studio_64
cd F:\HCP\
dir ?????? /b > file_list.txt
for /f "delims=" %%x in (file_list.txt) do (
call dsi_studio.exe --action=src --source=F:\HCP\%%x\T1w\Diffusion\data.nii.gz --output=F:\%%x.src.gz > F:\%%x.txt
)

    5. Windows batch script for create src from nii data

path=C:\dsi_studio_64
dir ????? /b > file_list.txt
for /f "delims=" %%x in (file_list.txt) do (
call dsi_studio.exe --action=src --source=%%x\%%x_dwi_QCed.nii --bval=%%x\%%x_QC.bval --bvec=%%x\%%x_QC.bvec --output=%%x.src.gz
)
    

Atlas related computation


The functions here include (1) creating an atlas (2) creating connectometry database, (3) saving QSDR space track to native space, or (4) saving the atlas ROIs to the subject space.

Parameters


    action: use "atl" 

    source: assign the fib.gz file(s).

    cmd: specify the operation here. 

            "template": averaging the FIB files to construct a group average template.

            "db": create a connectometry database

            "trk": convert QSDR space track to native space

            "roi": convert atlas ROIs to the subject space
 

    template: used in --cmd=db for specifying the template for creating the connectometry db. You may ignore this parameter to use the default template in DSI Studio

    index_name: used in --cmd=db for specifying the diffusion metric to extract. The default value is "sdf". Other choices include "iso" or DTI measures (if FIB files has DTI volume included)

    atlas: used in --cmd=roi for specifying the name of the atlas to convert. The name specifies which "nii.gz" file in atlas directory to use. 
      
              To include multiple atlases, use "," to separate them:

              --atlas=aal,brodmann

    tract: used in --cmd=trk for specifying the trk file for conversion.

Example


    1. Construct a group average template by averaging FIB files

        dsi_studio --action=atl --source=folder_containing_fib_files --cmd=template

    2. Construct a connectometry db

        dsi_studio --action=atl --source=folder_containing_fib_files --cmd=db 

    3. Convert a QSDR track to the native space

        dsi_studio --action=atl --source=qsdr_reconstructed_fib.gz --cmd=trk --tract=qsdr_tracts.trk.gz 

    3. Write the aal and brodmann atlas to the subject space. The output will be an nifti files of the transformed atlas 

        dsi_studio --action=atl --source=subject.fib.gz --atlas=aal,brodmann --output=single --cmd=roi

    4. Write the aal atlas to the subjects space. The output will be multiple nifti files for each of the regions.

        dsi_studio --action=atl --source=subject.fib.gz --atlas=aal --output=multiple --cmd=roi
 

Tract-specific analysis, voxel-based analysis, connectivity matrix, and network measures


Parameters


    action: use "ana" for analysis. The output of the results will be stored in the same directory of the tract file.

    source: assign the fib.gz file.

    The following setting applies to tract-specific analysis:

    tract: assign the tract file (*.trk or *.txt).

    output: use"--output=Tract.txt" to convert trk file to other format or ROI (assigned output file as *.nii.gz)

    exportexport additional information related to the fiber tracts 

               use "--export=tdi" to generate track density image in the diffusion space.

               use "--export=tdi2" to generate track density image in the subvoxel diffusion space.

               use "--export=tdi_color" or "--export=tdi2_color" to generate track color density image.

               use "--export=stat" to export tracts statistics like along tract mean fa, adc, or morphology index such as volume, length, ... etc.

               To export TDI endpoints, use tdi_end or tdi2_end.

               use "--export=report:fa:0:1" to export the tract reports on "fa" values with a profile style at x-direction "0" and a bandwidth of "1" 
               the profile style can be the following:

               0 x-direction
               1 y-direction
               2 z-direction
               3 along tracts
               4 mean of each tract

               for detail of each profile style, please refer to the following link.

               You can export multiple outputs separated by ",". For example, 

               --export=stat,tdi,tdi2,qa,gfa exports tract statistics, tract density images (TDI), subvoxel TDI, along tract qa values, and along tract gfa values.

    The following are post-processing parameters:

    The "ana" action is compatible with the track post-processing commands listed under "--action=trk", including "delete_repeat","output", "export", "end_point", "ref", "connectivity", "connectivity_type", "connectivity_value", and ROI related commands, such as "roi", "roi2", "roi3", "roi4", "roi5", "roa", "roa2", "roa3", "roa4", "roa5", "end", "end2", and "ter". Please check out "--action=trk" for details.

    The following setting applies to region-based analysis: 

    Do not assign "--tract", or DSI Studio will run tract-specific analysis.

    roi: assign the file name(s) of the ROI file. Different files are separated by ";". The format can be a txt file or nifti file or from the atlas regions (e.g. -roi=aal:Precentral_R;aal:Precentral_L)

    atlas: assign the name of an atlas to provide a set of ROI to export the diffusion indices (e.g, atlas=aal)

    export: use "--export=stat" to export region statistics
 

Example


Tract-specific analysis:

    1. Convert trk file to txt file

        dsi_studio --action=ana --source=avg.mean.fib.gz --tract=Tracts1.trk --output=Tracts1.txt

    2. Read track trk file, filter it by ROIs, and output as another trk file

        dsi_studio --action=ana --source=avg.mean.fib.gz --tract=Tracts.trk.gz --roi=roi.nii.gz --roi2=roi2.nii.gz --output=filtered_track.trk.gz

    3. Convert trk file to ROI file

        dsi_studio --action=ana --source=avg.mean.fib.gz --tract=Tracts1.trk --output=ROI.nii.gz

    4. Generate tract density imaging of from a trk file.

        dsi_studio --action=ana --source=avg.mean.fib.gz --tract=Tracts1.trk --export=tdi

    5. Generate a tract report on gfa values with profile style=fiber orientation and a bandwith=2

        dsi_studio --action=ana --source=my.fib.gz --tract=tract.txt --export=report,gfa,3,2

    6. Calculate the connectivity using the tractography and ROI files

        dsi_studio --action=trk --source=my.fib.gz --tract=tract.trk.gz --connectivity=AAL,my_roi.nii.gz,another_roi.nii.gz --connectivity_value=qa,count,ncount --connectivity_type=pass,end

Region-based analysis

    1. Get the statistics of one or multiple ROIs
        
        dsi_studio --action=ana --source=my.fib.gz --roi=native_space_roi.nii.gz

        dsi_studio --action=ana --source=my.fib.gz --roi=HCP842_tractography:Cingulum_L;HCP842_tractography:Cingulum_R;HCP842_tractography:Corpus_Callosum

    2. Get the statistics from multiple ROIs of an atlas

        dsi_studio --action=ana --source=my.fib.gz --atlas=aal

Export data from fib.gz or src.gz file


Parameters


    action: use "exp" for exporting matrix information.

    source: assign the fib.gz or src.gz file.

    exportuse "--export=fa0,fa1" to export the fa0 and fa1 image as nifti files. Please be noted that in DSI, QBI, and GQI, the QA values are stored in matrix fa0, fa1,..etc. In DTI, fa0 stores the fa values.

               use "--export=dirs" to export all fiber orientations as an 4D nifti file. The fiber orientations are unit vectors stored in the 4th dimension. Since each voxel may have multiple fiber orientations, each voxel can have, for example, 15 values, which is 5 fibers x 3 vector dimensions. The storage sequence is [x direction of 1st fiber][y direction of 1st fiber][z direction of 1st fiber][x direction of 2nd fiber][y direction of 2nd fiber]....

               use "--export=4dnii" to export DWI data and b table from an SRC file. The output is a 4d nifti file and text files recording the b-table.

               You may use the following matlab codes to get the values for x, y,and z directions:

I = load_nii('sample.dirs.nii.gz');
dir_x = squeeze(I.img(:,:,:,1));
dir_y = squeeze(I.img(:,:,:,2));
dir_z = squeeze(I.img(:,:,:,3)); 

               use "--export=dir0" to export only the 1st (primary) fiber orientation as an 4D nifti file. The fiber orientations are stored in the 4th dimension. The sequence is [x of 1st fiber][y of 1st fiber]. To export the 2nd fiber, use "--export=dir1".
 
               You may combine multiple export targets. (e.g., --export=dirs,dir0,dir1,fa0,fa1)
        

Example


    1. Get the qa0 and gfa mapping from a GQI fib file

        dsi_studio --action=exp --source=my.gqi.1.25.fib.gz --export=fa0,gfa


    2. The first diffusion weighted image stored in an src.gz file

        dsi_studio --action=exp --source=test.src.gz --export=image0

    3. Export all fiber orientations in the fib file

        dsi_studio --action=exp --source=test.fib.gz --export=dirs

     4. Convert an SRC file to a 4D nifti file

        dsi_studio --action=exp --source=test.src.gz --export=4dnii

Connectometry analysis


Parameters


    action: use "cnt" for running connectometry.

    source: assign the db.fib.gz file

    variable_list: assign the study varibles to be included in the regression model. use comma to include multiple variables. For example, use --variable_list=0,1,2 to include the first, second, and third variable.

    voi: specify variable of interest (used only in multiple regression). --foi=0 will analyze the "first" variable listed in the demographic file, --foi=1 will analyze the second one.

    demo: assign the path to the demographic file.

    missing_value: specify the missing value in the demographic file. For example, --missing_value=9999 will ignore any subject having 9999 in any field.

    threshold: assign the threshold for tracking. In multiple regression, this threshold is the t-score threshold. In group comparison and paired difference, a percentage threshold is used (e.g. --threshold=5 assigns 5% difference). 

    *If no threshold is assigned, a default threshold will be calculated from the otsu method.

    seed_count: assign the number of seeds for tracking. 

    permutation: assign the number of permutation used in statistical analysis.

    thread_count: assign the number of threads used in computation.

    trim: assign the number of track pruning.

    seed, roi, roi2, roa...: assign regions to limit the tracking region. (see the region setting in --action=trk section for detail)

    track_fdr or track_length: Please choose either one. Assigning the length threshold for tracks (e.g. --track_length=40) will remove tracks shorter than this threshold and reports the overall FDR. Assigning the FDR for tracks (e.g. --track_fdr=0.05) will remove tracks that has FDR greater than the value. 

    normalized_qa: assign --normalized_qa=1 to normalize qa
        
    output_report: assign --output_report=0 to disable connectometry report (default: on)

    output_track_image: assign --output_track_image=0 to disable track image (default: on)

    output_track_data: assign --output_track_data=0 to disable trk file output (default: on)

    output_fdr: assign --output_fdr=1 to output FDR table (default: off)

    output_dist: assign --output_dist=1 to output length distribution table (default: off)

Example


    1. Use a multiple regression model with three variables (0:SEX, 1:BMI, 2:AGE) to study how BMI (the second variable) affects the brain connection in the CMU 60 connectometry database.

        dsi_studio --action=cnt --source=CMU60.db.fib.gz --demo=CMU60.txt --variable_list=0,1,2 --voi=1 --length_threshold=20 --roi=aal:Temporal_Inf_L 



3D rendering


    DSI Studio will use previous GUI rendering setting (e.g. opacity, line verus tube) to draw the images. 

Parameters


    action: use "vis" for 3d rendering.

    source: assign the fib.gz file

    track (optional): assign the track trk files. To load multiple files, use "," to separate multiple track files. 

    stay_open: assign "--stay_open=1" to allow GUI to stay open after the command line

    cmd: You can run a series of commands by using ";" as the separator (e.g. --cmd="add_surface;save_image")

            The following commands are for controlling the interface:

            "add_surface": add an full brain isosurface. To add partial brain isosurface, use "add_surface,1" "add_surface,2" .... "add_surface,6"

            "add_slice,t1w.nii.gz": add t1w.nii.gz as the slice

            "move_slice,0,20": move sagittal slice (0) to position 20. To move the sagittal slice, use "move_slice,1,20". To move the axial slice, use "move_slice,2,20"   

            "slice_on": make slices visible. To enable only sagittal slice, use "slice_on,0". (0: sagittal, 1: coronal, 2:axial)

            "slice_off": make slices invisible. To disable only sagittal slice, use "slice_off,0". (0: sagittal, 1: coronal, 2:axial)

            "set_zoom": set the zoom-in scale. e.g., set_zoom,0.6

            "set_view,0" "set_view,1" "set_view,2": set the current view to sagittal, coronal, and axial view. Call the same command twice to view from the opposite side (e.g. --cmd="set_view,2;set_view,2" will view from the top)

            "set_roi_view_index": set the background map of the ROI window, e.g. "set_roi_view_index,0" will show the FA or QA map.

            "set_param": configure the rendering options. A list of the rendering options can be found at https://github.com/frankyeh/DSI-Studio/blob/master/options.txt   For example, the first option is "orientation_convention", and you may set it to 0 by "set_param,orientation_convention,0" to use Radiology convention


            The following commands are for saving a file. 

            You may specify the file name after adding a ",". For example: "save_image,file_name.jpg"

            "save_image": save a 3D rendering image. 

            "save_lr_image": save a left right viewed 3D rendering image.           

            "save_3view_image", "save_h3view_image": save 3D rendering image in 3 views

            "save_rotation_video": save a rotation video

            "save_stereo_rotation_video": save a left right viewed rotation video

            "save_roi_image": save the ROI window as an image

            "save_mapping": save fa qa or adc mapping as a nifti image

            "save_tracks": save current ractography as a trk file. For example, "save_tracks,tracks.trk.gz"

            The following commands are for fiber tracking and editing

            "run_tracking": run tracking using the current parameters

            "cut_by_slice": cut tracks by the current slice position. Specify slice orientation by 0:sagittal 1:coronal, 2:axial. and direction by 0:lesser 1:greater. For example, "cut_by_slice,2,1" cut tracks at Z+

            More commands can be supported. If you have specific request, please send an email to frank.yeh (at) gmail.com

Example


    1. Load an fib file and a trk file. Add an isosurface,switch to an axial view, and save the rendering image.

        dsi_studio --action=vis --source=test.fib.gz --track="whole_brain.trk.gz" --cmd="add_surface;set_view,2;save_image"

    2. Load an fib file and a trk file. Set the view from the top and save the rendering image as 1.jpg.

        dsi_studio --action=vis --source=test.fib.gz --track="whole_brain.trk.gz" --cmd="set_view,2;set_view,2;save_image,1.jpg"

    3. Load an FIB file and keep GUI open:

        dsi_studio --action=vis --source=test.fib.gz --cmd=" " --stay_open=1

    4. Load multiple TRK files and keep GUI open:

        dsi_studio --action=vis --source=test.fib.gz --track="TRACK1.trk,TRACK2.trk" --cmd=" " --stay_open=1

    5. Load trk and fib files to rendering their 3D images (Windows batch script)

path=C:\Users\frank\Documents\GitHub\DSI-Studio-WIN64\dsi_studio_64
FOR /F "delims=" %%A in ('dir *.fib.gz /b /on') do (
    call dsi_studio.exe --action=vis --source=%%A --track=%%A.trk.gz --cmd="add_surface,0,0;slice_off;save_h3view_image,%%A.jpg;save_h3view_image,%%A.jpg" > %%A_.txt
)
 

Rename DICOM files



Parameters


    action: use "ren"

    source: assign the full directory containing the DICOM files. The subdir will be searched.

    output (optional): output the rename file to the output directory. If not assigned, the source directory will be the output directory.

Example



    1. Rename DICOM files under the raw_data directory

    dsi_studio.exe --action=ren --source=d:/draw_data

    2. For each directory, rename DICOM

for /f "delims=" %%x in ('dir * /b') do (
    call dsi_studio.exe --action=ren --source="D:\MRI\CA\%%x" > %%x.log.txt 
)


Debug and trace


    To debug the command line, you may redirect the log to a file for inspection. (e.g. dsi_studio --action=exp --source=test.src.gz --export=image0 > log.txt)


Use Case  Example


     Here is an example of processing diffusion MRI data using the windows batch file. DSI Studio folder is located at D:\dsi_studio_64. The study data are stored under D:/study , and the DICOM files of each subject are stored in folder named by their ID (e.g. subject 1 is in D:/study/C01, subject 2 is in D:/study/C02

     STEP1: create a rename.bat under D:\study with the following content and run it. This will rename all the DICOM files within each subject's folder

 path=D:\dsi_studio_64
 for /f "delims=" %%x in ('dir * /b /ad') do (
     call dsi_studio.exe --action=ren --source="D:\study\%%x"
 )

     STEP2: create a src.bat file under D:\study with the following content and run it. This will create an SRC file using the DICOM files acquired by the diffusion sequence with "ep2d_diff" as the sequence name (SIEMENS convention). You may need to change this name if the diffusion MRI were acquired with a different sequence name.

 path=D:\dsi_studio_64
 for /f "delims=" %%x in ('dir * /b /ad') do (
 cd %%x
     for /f "delims=" %%y in ('dir *ep2d_diff* /b /s /ad') do (
         call dsi_studio.exe --action=src --source="%%y" --output="D:/study/%%x.src.gz"> D:/study/%%x.log.txt
     )
 cd ..
 )

     STEP3: move all src.file.gz to a folder named D:/study/src and in the folder, create a rec.bat file with the following command and run it. It will run reconstruction for each subject and generate a fib file.

path=D:\dsi_studio_64
for /f "delims=" %%x in ('dir *.src.gz /b') do (
    if exist %%x.odf* (
         echo has %%x.odf* file..skipping
    ) ELSE (
         call dsi_studio.exe --action=rec --source="%%x" --thread=6 --method=7 --param0=1.25 --param1=2 --record_odf=1
    )
)

     STEP4: create connectometry database

Other resources


     
     A python script and some BASH scripts for running DSI studio: https://github.com/GlennRFox/DSI_Studio



Comments