-
Notifications
You must be signed in to change notification settings - Fork 1
/
USAGE
233 lines (193 loc) · 20.3 KB
/
USAGE
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
versaFlow
===========
Usage
nextflow run [-resume] [-with-singularity <sif> | -with-docker [<docker_image> | avcaron/versa:<latest|v*.*.*>]] [-w <workdir>] [-profile <profile>] -dsl2 main.nf --data_root <root> [ additional parameters ... ]
DESCRIPTION
--data_root=/path/to/[root] Root directory containing the subjects to process. The
organisation must agree to the following convention :
[root]
|-<sub-1-tag>
| |-<ses-1-tag>
| |-<sub-1-tag>_<ses-1-tag>_dwi.nii.gz
| |-<sub-1-tag>_<ses-1-tag>_dwi.bval
| |-<sub-1-tag>_<ses-1-tag>_dwi.bvec
| |-<sub-1-tag>_<ses-1-tag>_dwi_mask.nii.gz (optional)
| |-<sub-1-tag>_<ses-1-tag>_dwi.json (see below)
| |-<sub-1-tag>_<ses-1-tag>_t1.nii.gz
| |-<sub-1-tag>_<ses-1-tag>_t1_mask.nii.gz (optional)
| |-<sub-1-tag>_<ses-1-tag>_rev.nii.gz (optional)
| |-<sub-1-tag>_<ses-1-tag>_rev.bval (optional)
| |-<sub-1-tag>_<ses-1-tag>_rev.bvec (optional)
| |-<sub-1-tag>_<ses-1-tag>_rev.json (see below)
| |-<sub-1-tag>_<ses-1-tag>_wm_pvf.nii.gz (optional)
| |-<sub-1-tag>_<ses-1-tag>_gm_pvf.nii.gz (optional)
| |-<sub-1-tag>_<ses-1-tag>_csf_pvf.nii.gz (optional)
| |-<ses-2-tag>
| |-<sub-1-tag>_<ses-2-tag>_dwi.nii.gz
| |- ...
|-<sub-1-tag>
| |-<ses-1-tag>
| |-<sub-1-tag>_<ses-1-tag>_dwi.nii.gz
| |- ...
In the case no .json files specifying the diffusion acquisition are provided with the input DWI images, the
following parameters are required :
--default_readout Default readout value to assign to datasets missing it
--default_multiband_factor Default multiband factor to assign to datasets missing it. In case multiband is not used, this parameter must be 1
--default_is_interleaved Specify input images as slice interleaved if not specified for a dataset [true|false]
--default_slicing_direction Default slicing direction of input volumes to assign to datasets missing it [IS|SI|AP|PA|RL|LR]
--default_phase_direction Default phase encoding direction to assign to datasets missing it. This value
will be automatically reversed for reverse phase images [IS|SI|AP|PA|RL|LR]
DIFFUSION ACQUISITION SPECIFICATION
The .json file supplied with each DWI volumes describes some parameters of the diffusion acquisition
protocol required for the pipeline to run. For a subject <sub-i> and a session <ses-j>, the file must be named <sub-i>_<ses-i>_[dwi|rev].json, and contain :
{
"direction" : <phase encoding direction>,
"slice_direction" : <slicing direction>,
"readout" : <readout>,
"interleaved" : <false|true>,
"multiband_factor" : <multiband factor>
}
Optionally, one can omit the last two items and replace them by the parameter "slice_indexes", which is a list of list containing the indexes of
the different slices acquired in order. Two examples :
- An image with interleaved slices, multiband factor of 1, 10 slices : [[0], [2], [4], [6], [8], [1], [3], [5], [7], [9]]
- An image with interleaved slices, multiband factor of 2, 10 slices : [[0, 5], [2, 7], [4, 9], [1, 6], [3, 8]]
OPTIONAL ARGUMENTS [possible values] (default values)
- I/O :
--output_root Output directory where to put processed datasets ($output_root)
--include_sid Include ONLY list of subject's SID in the processing
--exclude_sid Exclude list of subject's SID from the processing
--publish_all Publish all files generated by each process in a directory named
"all" under the output root [true|false] ($publish_all)
--publish_mode Strategy used to copy the processed files in the output root
[symlink|rellink|link|copy|copyNoFollow|move] ($publish_mode)
--publish_all_mode Strategy used to copy to whole processing tree in the output root
[symlink|rellink|link|copy|copyNoFollow|move] ($publish_all_mode)
--verbose_outputs Output of additional files and of debug messages in logs [true|false] ($verbose_outputs)
--random_seed Random seed to input to all random number generators ($random_seed)
--check_memory_requirements Check if enough memory is available to run the pipeline [true|false] ($check_memory_requirements)
- Resource allocation :
--use_cuda Enable usage of CUDA for Eddy (Require a Nvidia GPU) [true|false] ($use_cuda)
--conservative_resources Keep some processing cores when allocating multi-processed tasks [true|false] ($conservative_resources)
--free_processes Number of processes to keep free when using conservative resources ($free_processes)
--max_cpu_per_process Maximum number of processing cores to allocate to a multi-processed task ($max_cpu_per_process)
--max_attempts Maximum number of attempt at a failed task ($max_attempts)
--memory_buffer_gb Limit the amount of RAM available to dispatch processes ($memory_buffer_gb)
- Processing steps activation/deactivation :
- DWI preprocessing :
--gaussian_noise_correction Do initial background noise removal on diffusion [true|false] ($gaussian_noise_correction)
--gibbs_ringing_correction Do gibbs ringing artifact correction [true|false] ($gibbs_ringing_correction)
ONLY USE ON DATA WITHOUT PARTIAL FOURIER
--normalize_inter_b0 Normalize diffusion volumes between sets of b0 volumes [true|false] ($normalize_inter_b0)
--epi_correction Correct for EPI susceptibility artifacts [true|false] ($epi_correction)
--eddy_correction Run Eddy to correct for motion and eddy currents [true|false] ($eddy_correction)
--dwi_intensity_normalization Do N4 intensity normalization of diffusion volumes [true|false] ($dwi_intensity_normalization)
- T1 preprocessing :
--denoise_t1 Do initial background noise removal on T1 [true|false] ($denoise_t1)
--t1_intensity_normalization Do N4 intensity normalization for T1 volumes [true|false] ($t1_intensity_normalization)
- Registration :
--dwi_mask_from_t1_mask Perform registration of T1 mask to diffusion space [true|false] ($dwi_mask_from_t1_mask)
--register_t1_to_dwi Perform registration of T1 volumes to diffusion space after denoising [true|false] ($register_t1_to_dwi)
- Upscaling :
--resample_data Resample T1 and diffusion volumes after denoising [true|false] ($resample_data)
- Segmentation :
--generate_tissue_segmentation Generate T1 tissue segmentation [true|false] ($generate_tissue_segmentation)
--generate_wm_segmentation Generate white matter parcellation [true|false] ($generate_wm_segmentation)
- Model reconstruction :
--recons_dti Reconstruct the diffusion tensor model [true|false] ($recons_dti)
--recons_csd Reconstruct the fODF through constrained spherical deconvolution [true|false] ($recons_csd)
--recons_diamond Reconstruct the multi-tensor distribution through DIAMOND [true|false] ($recons_diamond)
- Tracking :
--pft_tracking Execute PFT tracking on reconstructed fodf [true|false] ($pft_tracking)
- Miscellaneous :
--raw_to_processed_space Transform raw DWI input to processed output space, for comparison purposes [true|false] ($raw_to_processed_space)
- Processing steps customization :
--nlmeans_t1 Use Non-local means to denoise T1 (if false, uses a basic gaussian denoising) [true|false] ($nlmeans_t1)
--epi_algorithm Algorithm to use for EPI correction [topup|bmepi] ($epi_algorithm)
--eddy_force_shelled Disable Eddy check on b-value shells of diffusion volumes [true|false] ($eddy_force_shelled)
--eddy_with_reverse Perform Eddy correction using reverse phase acquisition also [true|false] ($eddy_with_reverse)
--eddy_select_gpu Do automatic GPU selection for Eddy cuda [true|false] ($eddy_select_gpu)
This is practical when running on multi-GPU architectures
--cuda_max_parallel Limit number of parallel Eddy computations to prevent GPU memory busting ($cuda_max_parallel)
--b0_threshold Largest b-value to be considered as b0 ($b0_threshold)
--b0_normalization_strategy Strategy to use to select which b0(s) pairs with a set of diffusion volumes when performing
normalization to correct for signal drift [linear|first|last] ($b0_normalization_strategy)
- linear : do linear interpolation between b0s appearing before and after a contiguous group of diffusion volumes
- first : take the b0 appearing before a contiguous group of diffusion volumes
- last : take the b0 appearing after a contiguous group of diffusion volumes
--quick_t1_mask_registration Use Quick parametrization to perform T1 mask to DWI registration [true|false] ($quick_t1_mask_registration)
--quick_denoised_t1_registration Use Quick parametrization to perform T1 to DWI registration [true|false] ($quick_t1_mask_registration)
--t1_registration_in_subject_space Use subject anatomical image resolution to perform T1 to b0 registration, instead of the template's finer native resolution [true|false] ($t1_registration_in_subject_space)
--resampling_subdivision Number of subdivisions of the image spacing to perform when resampling ($resampling_subdivision)
--resampling_min_resolution Minimum resolution possible for resampled images ($resampling_min_resolution)
--force_resampling_resolution Force final resampling resolution of T1 and diffusion volumes. ($force_resampling_resolution)
--force_resampling_sequential Force the resampling processes to reserve all the resources, to prevent busting RAM [true|false] ($force_resampling_sequential)
This is useful when processing large sized diffusion volumes
--bet_f Fractional intensity threshold for FSL bet [0 > 1] ($bet_f)
--atropos_prior_weight Weight of the prior segmentation for Atropor ($atropos_prior_weight)
--default_blur_factor Default blur factor to apply on the classes priors before Atropos ($default_blur_factor)
--csf_blur_factor Blur factor to apply on the CSF prior before Atropos ($csf_blur_factor)
--segmentation_classes Names of classes associated to the indices in the tissue segmentation, in numerical order ($segmentation_classes)
--atropos_mrf_weight Weight of the Markov Random Field term in Atropos ($atropos_mrf_weight)
--atropos_mrf_neighborhood Isotropic neighborhood size of the Markov Random Field term in Atropos ($atropos_mrf_neighborhood)
--atropos_n4_tissues Name of the classes used as masks when performing N4 bias correction inside of Atropos ($atropos_n4_tissues)
--atropos_n4_iterations Number of iterations of N4 bias correction inside of Atropos ($atropos_n4_iterations)
--atropos_n4_convergence_eps Convergence threshold for N4 bias correction inside of Atropos ($atropos_n4_convergence_eps)
--atropos_n4_shrink_factor Shrink factor for N4 bias correction inside of Atropos ($atropos_n4_shrink_factor)
--atropos_n4_bspline_fitting B-Spline fitting distance for N4 bias correction inside of Atropos ($atropos_n4_bspline_fitting)
--default_distance_lambda Default lambda parameter for the distance prior on tissues ($default_distance_lambda)
--default_distance_probability Default boundary probability for the distance prior on tissues ($default_distance_probability)
--csf_distance_lambda Lambda parameter for the distance prior on CSF ($csf_distance_lambda)
--csf_distance_probability Boundary probability for the distance prior on CSF ($csf_distance_probability)
--min_pvf_threshold Minimal partial fraction value considered inside the tissue mask ($min_pvf_threshold)
--max_safe_csf_pvf_threshold Maximal partial fraction of CSF than can overlap a fraction of safe WM ($max_safe_csf_pvf_threshold)
--max_safe_gm_pvf_threshold Maximal partial fraction of GM than can overlap a fraction of safe WM ($max_safe_gm_pvf_threshold)
--safe_csf_mask_dilation Dilation of thresholded CSF partial fraction map for safe WM exclusion ($safe_csf_mask_dilation)
--safe_gm_mask_dilation Dilation of thresholded GM partial fraction map for safe WM exclusion ($safe_gm_mask_dilation)
--register_d99 Register the D99 atlas [true|false] ($register_d99)
--register_charm Register the CHARM atlas [true|false] ($register_charm)
--register_sarm Register the SARM atlas [true|false] ($register_sarm)
--register_inia19 Register the INIA19 atlas [true|false] ($register_inia19)
--max_dti_bvalue Maximum b-value used to reconstruct the DTI model ($max_dti_bvalue)
--msmt_odf Perform multi-shell, multi-tissue CSD [true|false] ($msmt_odf)
--use_mrtrix_csd Perform CSD using Mrtrix instead of Scilpy. RECOMMENDED for MSMT fitting for now, as it not handled well in dipy [true|false] ($use_mrtrix_csd)
--frf_on_dti_shell Use the shell selected for DTI to compute the response function [true|false] ($frf_on_dti_shell)
--frf_fa When building the single-fiber response function, higher FA threshold for valid voxels ($frf_fa)
--frf_min_fa When building the single-fiber response function, lower FA threshold for valid voxels ($frf_min_fa)
--frf_min_nvox Minimal number of voxels to consider for building the single-fiber response function ($frf_min_nvox)
--frf_radii Triplets of number defining a search ROI for single-fiber voxels ($frf_radii)
--frf_center Triplets of number defining the center of search for single-fiber voxels in voxel space ($frf_center)
--max_fa_ventricle Maximum FA value in voxels considered in ventricles ($max_fa_ventricle)
--min_md_ventricle Minimal MD value in voxels considered in ventricles ($min_md_ventricle)
--ventricles_center Triplets of number defining the center of search for ventricle voxels in voxel space ($ventricles_center)
--fodf_wm_max_absolute_factor Absolute thresholding factor of fODF peaks in WM. Habitually between 1.5 and 2.0 ($fodf_wm_max_absolute_factor)
--fodf_wm_relative_thr Relative threshold on fODF peaks in WM ($fodf_wm_relative_thr)
--fodf_gm_max_absolute_factor Absolute thresholding factor of fODF peaks in GM. EXPERIMENTAL ($fodf_gm_max_absolute_factor)
--fodf_gm_relative_thr Relative threshold on fODF peaks. EXPERIMENTAL ($fodf_gm_relative_thr)
--sh_order Spherical harmonics order for fODF reconstruction ($sh_order)
--n_fascicles Maximal number of fascicles (single-fibers) for DIAMOND to estimate in each voxel ($n_fascicles)
--fascicle_model Fascicle model for DIAMOND to use ($fascicle_model)
--model_selection_with_tensor Make DIAMOND compute the model selection using Tensors instead of sticks [true|false] ($model_selection_with_tensor)
--estimate_restriction Make DIAMOND estimate an additional restricted isotropic diffusion compartment [true|false] ($estimate_restriction)
--estimate_hindered Make DIAMOND estimate an additional hindered diffusion compartment per fascicle using a tortuosity model [false|true] ($estimate_hindered)
--normalized_fractions Normalize fractions between compartments [true|false] ($normalized_fractions)
--free_water_tensor Make DIAMOND estimate a distribution over tensors for the free water compartment [true|false] ($free_water_tensor)
--strict_parameters If false, will try to optimize the model parameters to the number of DWI directions available [true|false] ($strict_parameters)
--pve_threshold Minimal volume fraction for GM and WM to be considered part of the interface ($pve_threshold)
--pft_random_seed List of random seeds to use to produce a variety of tractograms ($pft_random_seed)
--tracking_algorithm Type of tracking algorithm to use. Can be one or a list containing both [det|prob] ($pft_tracking_algorithm)
--streamline_compression_factor Compression factor to use for output tractograms. Zero leads to no compression ($streamline_compression_factor)
--pft_seeding_strategy Seeding strategy to initialize tracking [npv|nt] ($pft_seeding_strategy)
--pft_number_of_seeds Number of seeds. With "npv", it is the number of seeds per voxels, with "nt" the total number to use ($pft_number_of_seeds)
--pft_step_size Stepping size for the tracking algorithm in mm ($pft_step_size)
--pft_theta_max Maximal angle between two valid tracking steps ($pft_theta_max)
--pft_sfthres Relative threshold on fodf ($pft_sfthres)
--pft_sfthres_init Relative threshold on fodf for the initial tracking direction ($pft_sfthres_init)
--pft_min_tract_length Minimal length for valid tracts in mm ($pft_min_tract_length)
--pft_max_tract_length Maximal length for valid tracts in mm ($pft_max_tract_length)
--pft_number_of_particles Number of particles emitted when tracking enters Map Exclude ($pft_number_of_particles)
--pft_back_tracking_length Length of back tracking in mm ($pft_back_tracking_length)
--pft_forward_tracking_length Length of forward tracking in mm ($pft_forward_tracking_length)
PROFILES
Some computation environments require specific configurations. Those have been encapsulated in profiles :
- macos : Execution on Macintosh OS
- hcp : Execution on a cluster of Linux machines using Apache Ignite