1. CHANGE LOG FROM TORTOISE V3.0 TO TORTOISE V3.1

Common Changes To All Modules:

• All TORTOISE modules, i.e. DIFFPREP, DRBUDDI, DIFFCALC and in the future DRTAMAS, now fully support the physical coordinate systems as described by the NIFTI headers or DICOM tags. In all previous versions of TORTOISE, a given module used to overwrite the header information, specifically, the direction matrices and the origin information, based on its requirements. Therefore, images output by TORTOISE did not align in MRI viewers that used physical coordinate systems. Now they will.
• All the import routines have been changed to conform to this change.
• Support for sagittal and coronal acquisitions in addition to axial.
• All modules have been made slightly faster.

1.1. DIFFPREP Changes (in addition to common changes)

• DIFFPREP can now automatically output quality control related images for the user to quickly review them. These functionalities are based on AFNI modules are activated only if AFNI is installed. The user can enable and disable them with the tag - -do_QC.
• Instead of a listfile, bmatrix file and a NIFTI file trio, the user can now provide a NIFTI file, bvecs, bvals files and the phase encoding direction as inputs to DIFFPREP. If this is the case, the listfile will automatically be created.
• ImportDICOM_GE, ImportDICOM_Philips and ImportDICOM_Siemens executables from V.3.0.0 HAVE BEEN REMOVED. Instead, a new import routine called ImportDICOM is included. This executable is based on dcm2niix , with the permission of Dr. Chris Rorden.
• ImportBruker executable now also outputs in physical coordinate system as defined by the method file. However, for some animals, anatomical axial can be different than human axial, a new tag is introduced - -convert_to_anatomical_header. If this tag is 0, the imported header will be identical to the acquisition. If the tag is set to 1, coronal acquisitions will be assumed to be anatomical axials and the headers will be automatically rotated.
• DIFFPREP now FULLY supports gradient non-linearity maps. These maps can be provided with the tag voxelwise_gradient_tensors and they should be a 4D NIFTI file with dimensions Nx x Ny x Nz x 9, where the last dimension contains rowwise elements of a 3x3 diffusion gradient modifier matrix originating due to gradient nonlinearities.
• The tag voxelwise_gradient_space defines in which space these gradient nonlinearity tensors are defined. Do they live in the physical space of the b0 image, or do they live in the space of the structural image. Most of the time this should be the b0 image but for example, the CONNECTOME data, it will the str8uctural space.
• A new tag - -will_be_drbuddied is introduced. If this tag is 1, after motion and eddy currents distortion correction DIFFPREP will stop to save time and storage space.
• A new tag - -center_of_mass is introduced. If the tag is set to 1 (which was always the case in previous versions), the image?s center of mass will be translated to the center pixel of the image for processing. If the tag is set to 0, the image will be unaltered. Default:1. This is useful for example for non-brain data, where the acquired object is near the edge of the images instead of the center.
• Output listfile name can now be fully specified. Therefore, it can be placed in another folder and have a different name.
• In DIFFPREP V3.0.0, Gibbs ringing correction was performed first, followed by denoising. In V3.1, processing starts with denoising first, and depending on the settings performs Gibbs ringing correction on the proc.list data AND/OR proc_denoised.list data.
• The concept of template image is completely removed from DIFFPREP. Now there is only the structural and the b=0 image. Because of this change, the working field of view is not applied to the template image but the entire proc.list DWI data by resampling it. This resampling DOES change the origin of the image but DOES NOT change the physical coordinate system, i.e. all the images would overlay nicely in viewers that use physical coordinates.
• ReorientImage executable has been changed to FULL NIFTI convention. The axes have been changed accordingly as well. It can also automatically convert a non-axial image to an axial one.
• A new executable is introduced, CreateVoxelwiseBmatricesFromDeformationField. This executable can be used to create voxelwise Bmatrices due to deformation fields applied to the data, for example originating from a nonlinear registration or atlas creation procedure.
• Some optimization parameters in the Assets/settings folders have been further fine-tuned.

1.2. DRBUDDI Changes (in addition to common changes)

• Some functionalities of DRBUDDI have been made significantly faster. Default disortion level setting which has been set to medium will ensure DRBUDDI running faster. The remaining disortion level settings when set, the corrections are performed on higher resolutions and the order is as follows:The first two resolutions are performed with a time varying velocity field based transformation and the highest resolution is then performed with SyN.
• DRBUDDI now also supports QC outputs.
• DRBUDDI now also supports gradient nonlinearity maps with the same tags as DIFFPREP. Please refer to DIFFPREP changes for details.
• To fully support gradient non-linearity maps, all diffeomorphic registration operations are now performed in the space of the up b=0 image. In previous versions, these operations were performed in the space of the structural image. Due to this change, the b0_quad.nii, b0_corrected.nii bo_final_corrected.nii and structural_used.nii images will be in the space of the up b0 images. However, at the last step, DRBUDDI will still reorient all the diffusion MRI data to the space of the original structural image, or its resampled version, which is called structural.nii.
• The Jacobian calculations for the CCJac and MSJac metrics have been completely changed and made more reliable and faster. These two metrics are now significantly better than V3.0.0. However we still suggest to use a structural image and the CCSK metric alongside one of these.
• DRBUDDI now fully supports datasets with FULL up acquisitions, and a single b=0 acquisition for the down dataset.
• IF the number of volumes and the Bmatrices match between the up and down data, DRBUDDI will still output the the combined version. If they do not match, DRBUDDI will now automatically output the geometrically corrected and signal manipulated versions of both data.
• Following the previous item, in case the two datasets do not match, the signal modulation can be performed in two ways. Jacobian or least squares based. This is controlled by the new tag - -final_signal_modulation .
• The - -DWI_bval tag of V3 has been split into two: - -DWI_bval_tensor_fitting defines the largest b-value to use for tensor fitting from the ACTUAL data and - -DWI_bval_synth defines what bvalue to use with te estimated tensors to synthesize DWIs to be used in registration.
• The tag - -final_res has been changed to ?–res? to be consistent with DIFFPREP. The previous versions of DIFFPREP only have provision to enter one resolution parameter to output in isotropic dimension. Now, you can output in non isotropic dimension where you can provide three parameters.
• The tag - -start_step has been changed to - -step to be consistent with DIFFPREP.
• Some optimization parameters have further been fine tuned.

1.3. DIFFCALC Changes (in addition to common changes)

• The IDL based DIFFCALC is still mostly needed in case sophisticated tensor fitting operations such as RESTORE, iRESTORE, dual compartment fitting is needed. Additionally, to get very nice looking directionally encoded colormaps, the user is still encouraged to use IDL based DIFFCALC provided with TORTOISE download under the DIFFCALC/diffcalc2.5 folder.
• However, additional C++ executable based tensor fittings are also included in this version release: EstimateTensorWLLS weighted linear least squares, EstimateTensorNLLS nonlinear fitting.
• MAPMRI based fitting and scalar map calculations are also included.
• All C++ executable based tensor fitting operations can now accept voxelwise gradients originating either due to gradient nonlinearities or nonlinear registration.
• Several more tensor based scalar map computation executables are included.
• ComputeGlyhMaps now colors the glyphs based on their directions.

2. CHANGE LOG FROM TORTOISE V3.1 TO TORTOISE V3.1.1

DRTAMAS release.

 

4. CHANGE LOG FROM TORTOISE V3.1.2 TO TORTOISE V3.1.3

DIFFPREP

• Import PARREC, Import Bruker sorts multiple series with respect to filename before combining. In this current version sorting is not operating system dependent. If you have encountered issues with combining multiple series using either of the import option command with older versions of TORTOISE, please use the current version of the software to resolve the issue.
• If you have computed voxelwise bmatrix files from your native images using an external tool, DIFFPREP now offers full support for gradient non-linearities related voxelwise bmatrix computations and reorientations. It can output a rotated, processed version of the voxelwise bmatrix, which can be used for tensor or MAPMRI fitting. We currently do not provide a tool to compute the native space voxelwise bmatrix but this will be incorporated in the next release.

DRBUDDI

DRBUDDI has been significantly improved. If your previous processings were not up-to-par,  please try this new version. 

• Relatively easier to use than the previous versions with the removal of the tag 'distortion level'. Correction settings are adjusted internally based on the input data.
• Use of DWIs in the correction has been removed.
• a new tag --do_tensor_based   has been added that when turned on will use the DRTAMAS deviatoric similarity metric. To use this new tag, the data provided should have sufficient gradient/bvalues in the up and down data. It will compute a diffusion tensor (DT) for both and use it in the registration.
• Structural data dependency has been reduced. The default settings uses the structural data that you will provide in the command line. If you want to override the use of structural data (due to poor quality or no associated stuctural data) then provide the --metric MSJAC and it will process the data using jacobian based b0 metric.
• tags such as --shrink-factors, --convergence and --smoothing-sigmas have been reintroduced for expert users. These settings are automatically updated internally based on the data input so typical users will almost never have to provide these settings. However, for extremely distorted data, such as in-vivo experimental datasets, the users have the option to play with these settings.
• --transform and --metric tags have been made optional.
• If any of the additional tags are not provided and only input provided are the up, down and structural data the following default processing is performed:

1. Stage1: --restrict-deformation 1   --enforce_deformation_antisymmetry 1  --metric MSJac --metric Dev  --transform TVVF  --shrink-factors   6x4x2 (data dependent)   --smoothing-sigmas   (data dependent-   highly smoothed)
2. Stage 2:  --metric  CCSK (if using structural. If additional metric used in command line, that will be used here, such as MSJAC, Dev)    --transform SyN    --shrink-factors  2x1  (data dependant, but to the final resolution provided)      --smoothing-sigmas   (low smoothing)

 

DIFFCALC

• MAP MRI fitting made more robust.

      Additional tools included, namely

• DTITK to TORTOISE tensor conversion.
• Axialize diffusion tensor, to reorient diffusion tensors that have sagittal, coronal or oblique orientations.
• Computation of additional scalar maps such as axial diffusivity (AD), radial diffusivity (RD), mode of the tensor, Westin linear (WL), Westin planar (WP), Westin spherical (WS), tensor based return-to-the-origin probability (RTOP).
• We will be adding RESTORE tensor computation in the upcoming release. Currently this feature is only present in the DIFFCALC V252 GUI which is included under DIFFCALC/DIFFCALCV2

5. CHANGE LOG FROM TORTOISE V3.1.3 TO TORTOISE V3.1.4

DIFFPREP

No changes

DRBUDDI

Parameters have been further optimized to account for a wider range of distortions. It is now more robust.

 

DIFFCALC

Changes have been made to existing commands and new commands have been added. This version of DIFFCALC has made a complete transition to command line incorporating almost all the features of IDL based DIFFCALC.

Changes to existing commands

EstimateMAPMRI_NG: Now computes non gaussianity  parallel and perpendicular to the fiber.

 ComputeFAMap : It is now fixed.

New executables added

ComputeWLMap (Westin linear)

ComputeWPMap (Westin planar)

ComputeWSMap (Westin spherical)

ComputeEigVecImage (eigen vector)

ComputeLIMap (lattice index)

EstimateTensorDiagonalNLLS

EstimateTensorDiagonalWLLS

EstimateTensorNLLSDual (non linear dual compartment fitting)

EstimateTensorNLLSRESTORE  (non linear fitting with outlier rejection using robust tensor estimation)

 

Additionally, there is a script, ComputeAllTensorMaps.bash, added in the DIFFCALC folder. Running this script batch generates tensor and scalar maps from the data, similar to IDL based DIFFCALC. You can edit the script and certain commands of interest to generate them in batch processing.

 

6. CHANGE LOG FROM TORTOISE V3.1.4 TO TORTOISE V3.2

 

DIFFPREP

1. Data will now be upsampled in the initial step of DIFFPREP. The option to turn of this option has been removed.
2. Denoising has been improved to handle unconventional data where PCA numerically generates non positive eigen values.
3. proc.nii will now have the same matrix size and number of slices as the original raw.nii data.
4. rigid registration for reorienting the final processed DWIs to the structural image has been significantly improved.

 

DRBUDDI

DRBUDDI ver3.2 has been redesigned. The algorithm has some new changes that are detailed below:

1. At the initial stages before diffeomorphic registration, DRBUDDI will now output the estimated tensor, estimated b0, FA and DEC maps, for each up and down data.

The generation of these files is for data that supports computation of files i.e these files are not generated for the data containing only 1 b0.

These files will be used in the diffeomorphic registration of DRBUDDI algorithm. 

2. Initial rigid registration of b0_down.nii + structural_used.nii, to the b0_up.nii, is significantly improved:

Following steps are now introduced in DRBUDDI:

a. b0_down.nii is rigidly registered to b0_up.nii, with the improvements related to rigid registration.

b. Diffeomorphic registration of DRBUDDI is run with only MSJAC metric for a few iterations.

c. The resulting b0_down.nii from ‘step b’, is rigidly registered to the resulting b0_up.nii from ‘step b’, again.

d. The rigid transformations from ‘step a’ and ‘step c’, are concatenated to get the final rigid transformation from down to up.

e. For structural image registration, the output, b0_up.nii and b0_down.nii images, from ‘step b’, are combined into a single image and the structural image is rigidly registered to this image.

     While the above steps have been introduced as default, few of steps can be disabled under following scenarios:

Scenario 1: where up and down are very dissimilar, then skip ‘step a’ by using the tag:  --start_with_diffeomorphic_for_rigid_reg  1

Scenario 2: is phantom data, synthetic data where you know there is no motion, then ‘steps a to e’ can be disabled, by using the tag :                              --disable_initial_rigid  1

 

3. For diffeomorphic registration, TVVF that was the default has been removed and a multistage SyN approach has become the default, again. TVVF option is not available in ver3.2. While the default parameters have been fine tuned to work to handle a variety of data, for users interested in modifying certain parameters, can now control and modify each parameter of SyN registration.
4. A variety of parameters can be user controlled but if they are not specified, DRBUDDI uses default a-priori settings. It is advised to run with default parameters and examine the results. If unsatisfactory, proceed to modifying the default settings.
5. A new option is added where the use of the structural image can automatically be disabled: --do_not_use_structural  1.

If this setting is used and the structural is provided, structural data will only be used for final rigid registration.

6. MSJAC metric has significantly improved in version 3.2.
7. The CCS metric is completely revamped. Now, it compares the average of the JAC manipulated up_b0.nii and JAC manipulated down_b0.nii, to the structural image.
8. With the previous versions of DRBUDDI (including the paper) the structural based CCSK metric was the dominant metric in the processing. In this version, the processing starts with only the MSJAC metric at lower resolutions and at higher resolutions, gradually adds more metrics.

First, the FA based metric is added at mid level resolutions, followed by DEC based metrics. Only in the final stages, the CCS metric is added.

9. With previous versions of DRBUDDI, the deformations were not restricted to the phase encoding directions nor were they symmetric for up and down data. Now, this is enforced for 22 out of 23 stages of registration. Only if a structural image is used at the last stage, this is not enforced for fine tuning purposes. Therefore, DRBUDDI more closely follows the physical model, with this release.
10. A new tag, “do_jacobian_regardless” has been introduced that will output the jacobian manipulated up and down data separately and not combine them.

 

DIFFCALC

Three new executables are added in this version:

1. ConvertTORTOISEtensortoDTITKtensor
2. EstimateExperimentalDeviationScalar
3. EstimateMAPMRIRekindle