0.6.0

Preprocessing stage

MAJOR

• The core algorithm of head motion realignment was replaced to simpleitk_timeseries_motion_correction (the old implementation was based on antsMotionCorr). The new implementation offers more precise estimation of motion (notably by computing registration on isotropic resampled data), and reduces computational time by at least 20X relative to the previous default.
• All core image resampling functions are now implemented using SimpleITK instead of antsApplyTransforms (except mask and labels files still rely on antsApplyTransforms)

MINOR

• Implemented --gen_hmc_qc, which will generate a QC report and video to doublecheck the head motion realignment.

• --timeseries_interval: syntax changed from 0,80 to 0-80 (- replaces ,). And 'all' is no longer an input, but instead 'end' is read as the last index.
• --nuisance_regressors replaces --conf_list (equivalent)
• --args_3dTshift: can now provide any custom parameters to 3dTshift. This replaces to old CLI parameters --tpattern and --interp_method.
• --labels from preprocess stage was moved to --ROI_labels_file at the analysis stage, to enable more flexible customization of parcellation without rerunning previous pipeline stages.
• --no_HMC turns off head motion correction

Confound correction stage

• MSE_censoring (option within --frame_censoring): it is now an option to censore using the mean square error (MSE) timecourse relative to the image average. MSE is computed specifically between the EPI average and each frame before any censoring/detrending was applied to the data, to represent residual 'tissue movement' or intensity spikes.
• --slicewise_correction_direction: It is now possible with this parameter to conduct nuisance regression and smoothing on a per 2D slice basis. This strategy can be useful in the presence of artefacts (e.g. intensity spikes) that are not shared across slices due to time delays between slice acquisition, in which case a slicewise nuisance regression may perform better. Otherwise, in the case of images with spatial gaps between slices, smoothing should be applied slicewise using this parameter.
• RAM management is also significantly improved.

analysis stage

• A new set of pre-built seeds are made available for --seed_list without having to provide external files (e.g. ACA_seed, SS_frontal_seed)

QC reports from --data_diagnosis

• FD-DVARS corr. added as another scan-level QC metric for group-level scatter plot
• the MSE timecourse (mentioned above for MSE_censoring) is now plotted as a complementary metric of residual motion
• revising of the temporal diagnosis to scale relative to the number of frames
• censoring is now displayed on the temporal diagnosis
• temporal diagnosis now uses the Welch method for display of frequency spectrum
• functional connectivity maps are no longer smoothed before computing group statiscical reports, use --qc_smooth_maps to turn this back on
• functional connectivity maps are no longer thresholded at a fixed 4% of top voxel - it is now 10% by default, can be modified using --brainmap_percent_threshold
• Network amplitude is now also computed on SBC maps.

Bugs fixed

• FD scrubbing was only removing 1 forward frame and not 2. This is not fixed adequately to be in line with the method documented in Power et al. 2012.
• --log_transform +1 is added to data before log transformation so that 0 remains 0 post-transformation. Negative values are now removed post transformation. This is important as negative values skew registration towards errors.
• Various aspects of thread and memory management is now better optimized.

0.5.5

Main updates:

• It is now possible to compute any connectivity analysis (including seed based or dual regression) in nativespace
• with --bold_only, it is now possible to also generate preprocessed timeseries in nativespace, which are resampled to the original EPI space (no distortion correction is applied)
• The number of threads allocated to ITK commands is now properly handled by the --num_ITK_threads parameter. In previous version, ITK commands such as antsRegistration or antsMotionCorr would use all threads available.
• The calculation of the frequency spectrum in data diagnosis now takes into account censored frames, by simulating missing data points using the Lombscargle method.

Changes to the command line interface:

• --bold_nativespace can be selected to re-define the nativespace as the original EPI space as opposed to the anatomical space obtained by registration of the EPI to the anat.
• --resampling_space parameter now handles whether preprocessed timeseries are generated in nativespace, commonspace or both. By default, timeseries are only generated in commonspace now as opposed to both.
• --resample_to_commonspace parameter at the analysis stage now enables resampling the connectivity maps to commonspace if those were computed on nativespace timeseries
• --resample_to_commonspace parameter at the confound correction stage enables resampling cleaned timeseries to commonspace after cleaning, if the --nativespace_analysis parameter was selected. This is useful if one wants to conduct confound correction in nativespace, and then compute group-ICA (which requires commonspace input)
• --brainmap_percent_threshold controls the percent of voxels included when generating thresholded brain maps at the analysis pipeline stage. This determines the computation of the Dice overlap measure of network specificity.
• --plot_seed_frequencies allows to plot the frequency spectrum from specific seed timecourses at the analysis pipeline stage when using --data_diagnosis
• --num_ITK_threads controls the number of ITK threads allocated per node that runs ITK commands.
• It is now possible to disable MGIP when running MELODIC with --group_ica
• replaced --detrending_order with flexible --detrending parameter supporting custom polynomial orders and time intervals. Users can now specify any detrending order and time interval over which the trend is calculated.

0.5.4

Bugs fixed:

• all image headers are now inspected to ensure that image dimension is consistent, since this can lead to inconsistent resampling dimensions after preprocessing. If there is inconsistent image dimensions, the user must specify the resampling dimensionality with --commonspace_resampling or --nativespace_resampling

Changes to CLI parameters:

• every parameter for computing a unbiased template now includes the 'stages' sub-parameter, where one can specify the series of registration stages (i.e. rigid, affine and/or non-linear) carried for generating the template
• every registration parameter now includes winsorize_lower_bound and winsorize_upper_bound parameters that regulate the % intensity upper/lower bounds that is ignored by ANTs registration
• --log_transform is a novel option for apply a log transformation to image intensities prior to all registration operations, which can support registration for images with unusual intensity distributions
• --WM/CSF/vascular_mask and --labels are now OPTIONAL inputs - if a template file is inputted differing from the DSURQE default, then these parameters will be set to be empty unless they are provided with an explicit input. If these inputs are missing, the main pipeline will run, but downstream operations that require those inputs won't be run.

Other:

• the global signal is not plotted in the template diagnosis and saved as an output temporal feature
• Nipype/numpy/scipy packages were upgrated to speed up nipype workflow build

***Ongoing bugs with 0.5.4

• The default DSURQE template file cannot be read properly, and thus --anat_template must be provided manually.
• The 'run' iterables are not managed properly, meaning that if there are at least 2 different runs for one session, the workflow will crash. This will not happen if using the --bold_only parameter.

0.5.3

This release provides a hotfix to patch the orientation issue mentioned in #441.
It will use this GitHub repo as the source of template files until there is a fix upstream at which time RABIES will be pointed back the MiCE files.

Thank you, @kjamison, for reporting this issue.

0.5.2

• The antsApplyTransform resampling interpolator, used for resampling of functional data after preprocessing, can now be customized with the --interpolation parameter. By default, RABIES uses Linear instead of BSpline, since empirical results suggest that functional connectivity is decreased using BSpline.
• It is no longer needed to specify each sub-parameter for a CLI flag, e.g. --bold_inho_cor method=Affine,otsu_thresh=2,multiotsu=false can now be --bold_inho_cor method=Affine if one only wish to change the registration method relative to the default parameters.
• --group_avg_prior enables using the group average connectivity as a reference 'prior' for conducting --data_diagnosis
• When defining the commonspace resampling resolution based on input images, an error will now be thrown if inconsistent image resolutions are detected, in which case it will be required to manually input a resampling resolution with --commonspace_resampling to bypass the error

0.5.1

Documentation:

• new data quality assessment documentation page, which documents how the reports generated using --data_diagnosis at the analysis stage can inform quality control at the analysis stage
• improved guidelines for RABIES developers

New parameters:

• --includion_ids/--exclusion_ids: these new parameters allow to specify which list of scan should be included/excluded, at any stage of the pipeline
• --bids_filter: allow to specify which BIDS filters to use to select the functional and anatomical files of interest
• --oblique2card: new option to modify the affine in oblique images so these image don't raise an error at later stages
• --inherit_unbiased_template: this novel option allows providing the path to preprocessing outputs from a previous RABIES run, and use the already-generated unbiased template and register images directly onto it instead of creating a new one

Docker container and testing:

• important re-writing of the Dockerfile. The container is much smaller, using only minimal requirements from ANTs, AFNI and FSL, and constructing conda environment based on exact dependencies
• container built and maintained on Github https://github.com/CoBrALab/RABIES/pkgs/container/rabies instead of docker hub
• testing with error_check_rabies.py is more complete (i.e. now tests almost all parameters across pipeline stages), and can take in custom commands to test. Complete testing is also conducted during container build
• we've attached to this release a pre-built singularity image for version 0.5.1 (the file is 1.8Gb). This image can be downloaded and used directly instead of building the container from scratch using singularity.

0.3.3

Merge pull request #181 from CoBrALab/updates

Updates

0.2.1

• Introduced new QC visual outputs for the denoising steps as well as some temporal diagnosis (tSTD,tSNR)
• all data outputs from the analysis are in .csv or .nii.gz formats
• upgraded generic registration scripts to latest version as implemented in https://github.com/CoBrALab/minc-toolkit-extras/blob/master/antsRegistration_affine_SyN.sh
• introduction of a new bias field correction strategy which relies on iterative otsu masking for more robust correction of EPIs

0.2.0

RABIES image processing workflow was extended to include confound regression and some basic functional connectivity analysis within a unified workflow.
The novel features, as well as their usage and outputs, are all described in the README.

0.1.2

Improved the memory specifications for running in parallel through SGE and MultiProc.
Changed the resampling the options to user-defined resampling dimensions in native and/or common spaces.
Can now specify the data type of output files to control for file size.
Fixed an issue where the STC option couldn't be turned off.
The detection of dummy scans to generate a reference EPI volume is now optional, and is turned off by default.
The boolean parser options are now controlled through action=store_true