Command line interface of DSI Studio


    DSI Studio has a 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, please follow these steps to run a batch script.

(1) In the data folder, right click [New][Text Document] and rename the "New Text Document.txt" file as a bat file (e.g. cmd.bat)

(2) right click on the bat file to [Edit]

(3) Copy the following two-line content and paste to the bat file. Please replace "C:\dsi_studio_64" by the directory of the dsi studio.

dsi_studio.exe --action=trk --source=sample.fib.gz > log.txt

(4) Save it and double click the bat file you saved. Windows should run this script and output a log.txt

    You can replace the second line by a 3-line for loop to process through all FIB files in the folder and its subfolder in one shot: 

for /f "delims=" %%x in ('dir *.fib.gz /b /d /s') do (
    call dsi_studio.exe --action=trk --source="%%x" > "%%x.log.txt"

     Here %%x is a file name derived from the command 'dir *.fib.gz /b /d /s'

     In the macOS system, DSI Studio is distributed as an app package. To run the command line, you may need to run "./", where is the app package in the dsi_studio.dmg file. A bash script can be used to automate the processing of image data.

     Starting from the 2/26/2021 version, DSI Studio can take its own log output (*.log or *.txt") as the input to repeat the same analysis:       

dsi_studio.exe log.txt

     Here log.txt is the previously generated log output text file.

Sample Protocols

     If you have a working protocol you would like to share, please email it to

     Automatic fiber tracking:

dsi_studio --action=atk --source=./dwi.nii.gz --bval=./bval --bvec=./bvec

     Whole-brain fiber tracking:

dsi_studio --action=src --source=./dwi.nii.gz --bval=./bval --bvec=./bvec --output=./my.src.gz
dsi_studio --action=rec --source=./my.src.gz --method=4  --param0=1.25  # 4:GQI reconstruction
dsi_studio --action=trk --source=./my.src.gz.gqi.1.25.fib.gz --fiber_count=10000000

Wildcard Support 

     Many parameters support * and ? wildcards (see well as multiple files assignment separated by a comma.

     For example:

dsi_studio --action=trk --source=subject1.fib.gz,suject2.fib.gz --fiber_count=10000000       # separated by a comma
dsi_studio --action=trk --source=*.fib.gz --fiber_count=10000000                             # *wildcard
dsi_studio --action=trk --source=cohort1*.fib.gz,cohort2*.fib.gz --fiber_count=10000000      # multiple *wildcard

     The parameters supporting wildcard include --source (under all --action), --tract (only with --action=ana), --other_slices

Fiber tracking

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


    action: use "trk" to perform fiber tracking

    source: specify the .fib file for tracking. It supports wildcard (e.g., --source=*.fib.gz). It supports wildcard (e.g., --source=*.fib.gz)

Fiber 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(default=0, which means it is randomized): threshold for fiber tracking. In QBI, DSI, and GQI, "fa_threshold" will be applied to the 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 DSI Studio will select a random value between 0.5Otsu and 0.7 Otsu threshold using a uniform distribution.

    otsu_threshold(default=0.6): The default Otsu's threshold can be adjusted to any ratio.

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

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

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

    thread_count (default=CPU number): specify the thread count. 1 for a single thread. 2 for two threads...

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

    tip_iteration (deafult=16 if assigning --track_id or --dt_threshold_index)(default=0 otherwise): specify pruning iterations (mostly used for differential tractography).

    step_size, turning_angle, interpo_angle, fa_threshold, smoothing, min_length, max_length

    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 override ROI settings, dt_threshold_index, or threshold_index settings. You may still need to assign ROI/ROA...etc. in the command line. 

    track_id: specify which track to map using automatic fiber tracking. (e.g. --track_id=Arcuate_Fasciculus_L ) The value lookup list is the text file included in the DSI Studio package under the "track" folder.

ROI parameters

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

    roi, roi2, roi3, roi4, roi5: specify 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:


          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, --roi=region.nii.gz,dilate,dilate,smoothing dilates the region in the region.nii.gz file twice and smooth it:

          *You can assign the region value to be loaded (e.g. --roi=nifti.gz:1 only load regions with value=1)

    roa, roa2, roa3, roa4, roa5: specify the roa. You may assign as most 5 roa regions.

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

    ter, ter2, ter3, ter4, ter5: specify the terminative region. You may assign as most 5 terminative regions.

    t1t2: specify t1w or t2w images as the ROI reference image (e.g. --t1t2=my_t1.nii.gz)

    dt_threshold_index: trigger differential tractography. Assign "dec_qa" for finding decreased connectivity, "inc_qa for finding increased connectivity    

    dt_threshold: assign percentage change for differential tractography. assign --dt_threshold=0.1 to detect more than 10% change.

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 directory or output file name. Supported file format includes .tt.gz file or .trk.gz file. You canset this parameter to no_file to disable tractography output. You may also assign the .nii file as the output. DSI Studio will convert tracks into a region and save them in nifti file format. 

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

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

    export: export along-track 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. 

        (1) If you would like to use the built-in atlas:
        Please specify the atlas name. For example, "--connectivity=FreeSurferDKT" uses FreeSurferDKT atlas. You can assign multiple atlases (e.g., --connectivity=FreeSurferDKT,HCP-MMP

        (2) If you would like to use your customized MNI space atlas:
        Check out here about how to install a customized MNI space atlas. Then specify the name of the atlas without adding the file extension (e.g., --connectivity=mni_space_atlas)

        (3) If you would like to use subject space ROIs:       
        Please specify the full file name of the atlas file (e.g., --connectivity=/subject01/segmentation_in_dwi_space.nii.gz)
        If the ROIs is segmented based on T1W, you will need to specify the original t1w file using --t1t2 (e.g., --t1t2=subject_t1w.nii.gz) 
        Otherwise, make sure the ROI has the same dimension as the DWI so that DSI Studio can use it.

    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

    other_slices: add other imaging metrics (e.g, --other_slices=DKI.nii.gz,FW_FA.nii.gz,ODI.nii.gz or --other_slices=./other/*.nii.gz) and report them with --export or --connectivity

    1. Track the left arcuate fasciculus on all fib files

        dsi_studio --action=trk --source=*.fib.gz --seed_count=1000000 --track_id=Arcuate_Fasciculus_L

    2. Perform fiber tracking using parameter ID 

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

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

        dsi_studio --action=trk --source=test.fib.gz --roi=FreeSurferDKT:left_precentral,dilate,dilate,smoothing --roi2=FreeSurferDKT:right_precentral,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=FreeSurferDKT

    6. Perform fiber tracking and export track-specific statistics and TDI    

        dsi_studio --action=trk --source=CMU_60_20130923build.fib.mean.fib.gz --fiber_count=1000000 --export=stat,tdi

    7. Perform fiber tracking and insert other metrics (DKI, FW_FA...etc) and export track-specific statistics

        dsi_studio --action=trk --source=subject1.fib.gz --fiber_count=100000 --other_slices=./other/*.nii.gz --export=stat

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

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=FreeSurferDKT > "%%x.log.txt"

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

Automatic tracking of bundles


    action: use "atk"

    source: specify the src.gz or fib.gz file for automatic bundle tracking. 

    track_id: specify the id or the name of the bundle. The id can be found in \track\ . This text file is included in DSI Studio package (For Mac, right-click on to find content).

          example:   for tracking left and right arcuate fasciculus, assign --track_id=0,1  or --track_id=arcuate    (DSI Studio will find bundles with names containing 'arcuate', case insensitive)

          example:   for tracking left and right arcuate and cingulum, assign --track_id=0,1,2,3 or --track_id=arcuate,cingulum

          The default value is --track_id=Fasciculus,Cingulum,Aslant,Corticospinal,Thalamic_R,Optic,Fornix,Body,Forceps
    length_ratio (default=1.25): the diffusion sampling length ratio for GQI reconstruction. This is only used if the source file is an SRC file.

    tolerance (default=16): the tolerance for the bundle variations. The unit is in mm. A larger value may include larger track variation but also subject to more false results.

    track_voxel_ratio (default=2): the track-voxel ratio for the total number of streamline count. A larger value gives better mapping with the expense of computation time. For small bundles (e.g. right arcuate), a larger value may cause a large computation burden.

    tip (default=16): iterations of topology-informed pruning. A higher value will apply more pruning.

    interpolation (default=2): only used if the source is an SRC file. 

          0: no interpolation applied on DWI
          1: DWI rotated (no spatial warping) to align MNI orientation at 1mm
          2: DWI rotated (no spatial warping) to align MNI orientation at 2mm

          Please note that 1 and 2 only rotate the image volume and interpolate DWI to 1 mm or 2 mm. There is no nonlinear normalization.

    export_stat (default=1): Specify whether to output track statistics.

    export_trk (default=1): Specify whether to output tractography file.

    overwrite (default=0): Specify whether to overwrite existing files.

    default_mask (default=0): Specify whether default mask is used.


    1. Track the left and right arcuate fasciculus from all SRC files

        dsi_studio --action=atk --source=*.src.gz --track_id=Arcuate

Image reconstruction

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


    action: use "rec" for image reconstruction

    source: assign the .src file for reconstruction. It supports wildcard (e.g., --source=*.src.gz)

    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, DSI Studio will automatically determine a template. Please check log output to see if the correct template is selected. If not, please specify the right one by assigning the index number (e.g., --template=0). The index-template list will be provided in the log output.

    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. 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.

    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
    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

    cmd: run commands to modify the default mask or flip image volume or b-table. Use "+" to combine a sequence of command, and use "=" to assign value/parameters for each command

             e.g. --cmd="[Step T2a][Threshold]=0+[Step T2a][Smoothing]+[Step T2a][defragment]+[Step T2][Edit][Image flip x]"

             The available commands include:
             [Step T2a][Smoothing]
             [Step T2a][Defragment]
             [Step T2a][Dilation]
             [Step T2a][Erosion]
             [Step T2a][Negate]
             [Step T2a][Remove Background]
             [Step T2a][Threshold]=100       // assign value you like        
             [Step T2][Edit][Image flip x]
             [Step T2][Edit][Image flip y]
             [Step T2][Edit][Image flip z]
             [Step T2][Edit][Image swap xy]
             [Step T2][Edit][Image swap yz]
             [Step T2][Edit][Image swap xz]
             [Step T2][Edit][Rotate to MNI]      // rotate to 1-mm MNI
             [Step T2][Edit][Rotate to MNI2]    // rotate to 2-mm MNI
             [Step T2][Edit][Trim]
             [Step T2][Edit][Change b-table:flip bx]
             [Step T2][Edit][Change b-table:flip by]
             [Step T2][Edit][Change b-table:flip bz]
             [Step T2b(2)][Compare SRC]=file_name.src.gz
             [Step T2][Edit][Overwrite Voxel Size]=1.0
             [Step T2][Edit][Resample]=1.0


    1. Reconstruct all SRC files with GQI using 1.25 mean diffusion distance and output all FIB files to a folder

        dsi_studio --action=rec --source=*.src.gz --method=4 --param0=1.25 --output=./fib

    2. QSDR reconstruction with 1.25 sampling length ratio. The t1w and t2w were also warped with QSDR

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

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

# 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

for sub in $subs
dsi_studio --action=rec --source=${sub} --method=${method} --param0=${param0} --record_odf=1


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".


    action: use "src" for generating src file.

    source: assign the directory that stores the DICOM files or the file name for 4D nifti file. It supports wildcard (e.g., --source=*.nii.gz)

    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".

    up_sampling: upsampling the DWI. 

        --up_sampling=0 : no upsampling
        --up_sampling=1 : upsampling by 2
        --up_sampling=2 : downsampling by 2
        --up_sampling=3 : upsampling by 4
        --up_sampling=4 : downsampling by 4


    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:\.src.gz

    2. Parse the assigned 4d NIFTI file and generate a corresponding SRC file (4d_image.src.gz)

        dsi_studio --action=src --source=c:\4d_image.nii.gz 

    3. Parse all 4d NIFTI files in a folder (each of them has a bval and bvec file that shares a similar file name) and generate corresponding SRC files to a new folder (versions after May 2021)

        dsi_studio --action=src --source=*.nii.gz --output=/src

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

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

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

Quality Check for SRC files


    action: assign "qc" (e.g. --action=qa).

    source: assign an SRC file or a directory that stores the SRC files 


1. QC on SRC files stored in a folder
    dsi_studio --action=qc --source=folder_storing_src

2. QC on one SRC file 
    dsi_studio --action=qc --source=my.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.


    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:


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


    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 using 1-mm template

        dsi_studio --action=atl --source=folder_containing_fib_files --cmd=db --template=HCP1065_1mm.fib.gz

    3. Convert a QSDR track to the native space

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

    3. Write the FreeSurferDKT and HCP-MMP 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=FreeSurferDKT,HCP-MMP--output=single --cmd=roi

    4. Write the FreeSurferDKT 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=FreeSurferDKT --output=multiple --cmd=roi

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


    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 (*.tt.gz *.trk.gz *.tck).

    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:dti_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 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.

    region: regions: assign the file name(s) of a single ROI (--region) or a nifti file of multiple ROIs (--regions). 

    Different files are separated by "+". The format can be a txt file or nifti file or from the atlas regions (e.g. --region=FreeSurferDKT:right_precentral+FreeSurferDKT:left_precentral)

    If the regions are derived from T1W or T2W, please assign the original T1W/T2W using --t1t2=t1w.nii.gz
    If the regions are in the MNI space, add "mni" to the file name (e.g. mni_regions.nii.gz)

    The loaded regions can be modified using "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, --region=region.nii.gz,dilate,smoothing --regions=multiple_regions.nii.gz,flipx

    regions: assign the nifti file of multiple ROI for analysis. You may use --t1t2 to assign the original T1W/T2W for registration with the DWI.

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

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


Tract-specific analysis:

    1. Convert trk file to txt file

        dsi_studio --action=ana --source=avg.mean.fib.gz

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

        dsi_studio --action=ana --source=avg.mean.fib.gz --roi=roi.nii.gz --roi2=roi2.nii.gz

    3. Convert trk file to ROI file

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

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

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

    5. Get track statistics from a track file

        dsi_studio --action=ana --source=my.fib.gz --export=stat    

    6. Get track DKI and ODI statistics from a track file

        dsi_studio --action=ana --source=my.fib.gz --other_slices=DKI.nii.gz,ODI.nii.gz --export=stat    

    7. Calculate the connectivity using the tractography and ROI files

        dsi_studio --action=ana --source=my.fib.gz --connectivity=FreeSurferDKT,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 multiple native-space ROIs
        dsi_studio --action=ana --source=my.fib.gz --regions=native_space_roi.nii.gz

    2. Get the statistics of multiple MNI-space ROIs
        dsi_studio --action=ana --source=my.fib.gz --regions=mni_space_roi.nii.gz

    3. Get statistics from Freesurfer segmented ROIs using subjects T1W to guide the registration

        dsi_studio --action=ana --source=my.fib.gz --regions=aparc+aseg.nii.gz --t1t2=subject_t1w.nii.gz

    4. Get statistics from ROIs of atlas included in the DSI Studio package

        dsi_studio --action=ana --source=*.fib.gz --regions=HCP842_tractography:Cingulum_L,HCP842_tractography:Cingulum_R,HCP842_tractography:Corpus_Callosum

    5. Get the statistics from multiple ROIs of an atlas

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

Export data from fib.gz or src.gz file


    action: use "exp" for exporting matrix information.

    source: assign the fib.gz or src.gz

    exportuse "--export=qa,nqa,iso" to export the qa, nqa, and iso image as nifti files. 

               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]. You can also export the major fiber orientation only by --export=dir0 or the secondary by --export=dir1.

               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)


    1. Get the diffusion metrics from all GQI fib files

        dsi_studio --action=exp --source=*.gqi.1.25.fib.gz --export=fa,gfa,qa,nqa,iso

    2. Export all fiber orientations in the fib file

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

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

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

Connectometry analysis


    action: use "cnt" for running connectometry.

    source: assign the db.fib.gz file

    variable_list: assign the study variables 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.

    select: specify the selection of subjects using the demographics. For example, --selection=Gender=1,Age>20 select subjects with Gender field equal to 1 and Age older than 20 in the demographics.

    t_threshold: assign the t threshold for tracking. 

    length_threshold: assign the length threshold for tracking.

    fdr_threshold: assign the FDR threshold to enable FDR control.

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

    thread_count: assign the number of threads used in the computation.

    tip: 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)

    normalize_qa: assign --normalize_qa=1 to normalize qa.

    exclude_cb: assign --exclude_cb=1 to exclude cerebellum.

    no_tractogram: if you experience an error related to OpenGL, please specify --no_tractogram=1 so that DSI Studio will not invoke 3D rendering to generate tractogram. It will still output tractography files, which can be used later to generate tractogram separately.


    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 --roi=FreeSurferDKT:left_precentral 

    2. run analysis for each of the variable from 5 to 37, with variable 2 and 3 included as covariates

for /l %%G in (5,1,37) do (
dsi_studio --action=cnt --source=connectometry.sdf.db.fib.gz --demo=PANSS.csv --variable_list=2,3,%%G --voi=%%G > log%%G.txt

Individual Connectometry analysis


    action: use "cnt_ind" to run individual connectometry.

    source, study

                To compare repeat scans of the same subject, assign baseline FIB file to --source and followup FIB file to --study

                To compare a subject's FIB with a template, assign template FIB file to --source (e.g. --source=HCP1021.2mm.fib.gz) and the subject's FIB to --study

                *The template and the subject's FIB should have the same resolution (1mm or 2 mm)


                0: none
                1: maximum normalized to one
                2: least squared difference
                3: variance normalized to one

    dt_threshold_index: assign "dec_qa" for finding decreased connectivity, "inc_qa for finding increased connectivity    

    dt_threshold: percentage change. 

    *Any parameters used in --action=trk can also be used here. For example, --seed_count=100000 --min_length=40


    1. Finding tracks with decreased connectivity in a subject by comparing it with HCP1021 template

        dsi_studio --action=cnt_ind --source=HCP1021.2mm.fib.gz --study=data.src.gz.odf8.f5rec.cdm.qsdr.1.25.R65.fib.gz --norm=2 --dt_threshold_index=dec_qa --dt_threshold=0.2 --min_length=40 --seed_count=100000 

    2. Finding tracks with decreased connectivity in subject's repeat scans

        dsi_studio --action=cnt_ind --source=baseline.src.gz.odf8.f5rec.cdm.qsdr.1.25.R65.fib.gz --study=followup.src.gz.odf8.f5rec.cdm.qsdr.1.25.R65.fib.gz --norm=2 --dt_threshold_index=dec_qa --dt_threshold=0.2 --min_length=40 --seed_count=100000 

3D rendering

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


    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_stereoscopic":  set stereoscopic view
            "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   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. For example "add_surface+save_image,file_name.jpg"

            "save_image": save a 3D rendering image. The image dimension can be assigned after assigning the file name, e.g., --cmd="set_view,2+save_image,1.jpg,1024 800"
            "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_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 tractography as a trk file. For example, "save_tracks,"

            The following commands are for fiber tracking, visualization, and track editing

            "save_workspace,/my_work_folder/": save the workspace to a folder. The directory to the folder is specified after the comma
            "load_workspace,/my_work_folder/": load the workspace to a folder. The directory to the folder is specified after the comma
            "presentation_mode:" change the GUI to presentation mode (hide ROI window)
            "save_setting,file.ini": save all GUI setting to the file specified
            "load_setting,file.ini": load all GUI setting to the file specified
            "save_rendering_setting,file.ini": save rendering setting to the file specified
            "load_rendering_setting,file.ini": load rendering setting to the file specified
            "save_tracking_setting,file.ini": save tracking setting to the file specified
            "load_tracking_setting,file.ini": load tracking setting to the file specified
            "restore_rendering" : restore all rendering settings
            "run_tracking": run tracking using the current parameters
            "load_track_color,my_track_color_file.txt": load the track color from the specified file.
            "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 a specific request, please send an email to frank.yeh (at)


    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="" --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="" --cmd="set_view,2+save_image,1.jpg,1024 800"

    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="," --cmd=" " --stay_open=1

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

FOR /F "delims=" %%A in ('dir *.fib.gz /b /on') do (
    call dsi_studio.exe --action=vis --source=%%A --cmd="add_surface,0,0+slice_off+save_h3view_image,%%A.jpg+save_h3view_image,%%A.jpg" > %%A_.txt

Rename DICOM files


    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.


    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 

Rigid body rotation and spatial normalization


    action: use "reg" .

    from: assign the native-space subject image 

    from2: assign the second native-space image for dual-modality normalization 

    to: assign the template image 

    to2: assign the second template image for dual-modality normalization 

    warp: specify the warp field. If this field is assigned, --from, --from2, --to, --to2 will be ignored. 

    apply_warp (optional): apply the warping to additional native-space images. Multiple files can be assigned using comma separation (e.g., --apply_warp=fa.nii.gz,md.nii.gz)

    output: output subject's image to the template space in NIFTI format

    output_warp: output the warping field (e.g., which can be used by --warp

         assign 0 for rigid body rotation 
         assign 1 for nonlinear registration (affine+nonlinear) [default]

    normalize_signal: whether to normalize signal. 

         assign 1 for no
         assign 1 for yes [default]

    iteration: normalization iterations. a large value allows for more iterations for normalization. default=64

    smoothness: control the smoothness of the deformation. default=0.3, 0.6 for median sized lesion, 0.8 for large lesion.


    1. Normalize subject t1 to ICBM T1W

        dsi_studio --action=reg --from=subject_t1w.nii.gz --to=mni_icbm152_t1_tal_nlin_asym_09c.nii.gz

    2. Normalize patient's t1 to ICBM T1W and carry over t1w-based ROIs

        dsi_studio --action=reg --from=subject_t1w.nii.gz --to=mni_icbm152_t1_tal_nlin_asym_09c.nii.gz --apply_warp=t1w_segmentation.nii.gz

    3. Normalize subject qa/iso maps to template space qa/iso maps using dual-modality normalization

        dsi_studio --action=reg --from=50049_qa.nii.gz --from2=50049_iso.nii.gz --to=HCP1021_QA.nii.gz --to2=HCP1021_ISO.nii.gz

    4. Output warp field and use it later

        dsi_studio --action=reg --from=subject_t1w.nii.gz --to=mni_icbm152_t1_tal_nlin_asym_09c.nii.gz
        dsi_studio --action=reg --apply_warp=t1w_segmentation.nii.gz

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

 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.

 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.

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: