usage: __main__.py [-h] [--in_odf IN_ODF | --rap_params RAP_PARAMS]
[--step STEP_SIZE] [--min_length m] [--max_length M]
[--theta THETA] [--sfthres sf_th]
[--global_sf_rel_thr [FACTOR] | --global_sf_abs_thr
ABS_THR]
[--sh_basis {descoteaux07,tournier07,descoteaux07_legacy,tournier07_legacy}]
[--npv NPV | --nt NT | --in_custom_seeds IN_CUSTOM_SEEDS]
[--algo {det,prob}]
[--sphere {repulsion100,repulsion200,repulsion724,symmetric362,symmetric642,symmetric724}]
[--sub_sphere SUB_SPHERE] [--sfthres_init sf_th]
[--rk_order K] [--max_invalid_nb_points MAX]
[--forward_only] [--sh_interp {nearest,trilinear}]
[--mask_interp {nearest,trilinear}] [--keep_last_out_point]
[--n_repeats_per_seed N_REPEATS_PER_SEED]
[--rng_seed RNG_SEED] [--skip SKIP]
[--rap_mask RAP_MASK | --rap_labels RAP_LABELS]
[--rap_method {None,continue,switch}]
[--rap_save_entry_exit RAP_SAVE_ENTRY_EXIT]
[--processes NBR] [--compress [COMPRESS_TH]] [-f]
[--save_seeds] [-v [{DEBUG,INFO,WARNING,ERROR}]]
in_seed in_mask out_tractogram
Local streamline HARDI tractography using scilpy-only methods -- no dipy (i.e
no cython). The goal of this is to have a python-only version that can be
modified more easily by our team when testing new algorithms and parameters,
and that can be used as parent classes in sub-projects of our lab such as in
dwi_ml.
WARNING. MUCH SLOWER THAN scil_tracking_local. We recommand using multi-
processing with option --nb_processes.
Similar to scil_tracking_local:
The tracking direction is chosen in the aperture cone defined by the
previous tracking direction and the angular constraint.
- Algo 'det': the maxima of the spherical function (SF) the most closely
aligned to the previous direction.
- Algo 'prob': a direction drawn from the empirical distribution function
defined from the SF.
Contrary to scil_tracking_local:
- Algo 'eudx' is not yet available!
- Input nifti files do not necessarily need to be in isotropic resolution.
- The script works with asymmetric input ODF.
- The interpolation for the tracking mask and spherical function can be
one of 'nearest' or 'trilinear'.
- Runge-Kutta integration is supported for the step function.
A few notes on Runge-Kutta integration.
1. Runge-Kutta integration is used to approximate the next tracking
direction by estimating directions from future tracking steps. This
works well for deterministic tracking. However, in the context of
probabilistic tracking, the next tracking directions cannot be estimated
in advance, because they are picked randomly from a distribution. It is
therefore recommended to keep the rk_order to 1 for probabilistic
tracking.
2. As a rule of thumb, doubling the rk_order will double the computation
time in the worst case.
A few notes on Region-Adaptive Propagation (RAP):
RAP allows dynamic parameter switching during tracking based on a label
volume (--rap_labels) or a binary mask (--rap_mask)
- Method 'continue': continues tracking with the same parameters inside the
RAP region.
- Method 'switch': switches algo, theta, step_size, and fODF model per
label, based on a JSON policy file (--rap_params). --in_odf and
--rap_params are mutually exclusive. Each label in the JSON must specify
a propagator type, filename and sh_basis. Multiple labels can share the
fODF file without loading it twice in memory. See --rap_params help for
expected JSON format
-------------------------------------------------------------------------------
Reference:
[1] Girard, G., Whittingstall K., Deriche, R., and Descoteaux, M. (2014).
Towards quantitative connectivity analysis:reducing tractography biases.
Neuroimage, 98, 266-278.
-------------------------------------------------------------------------------
positional arguments:
in_seed Seeding mask (.nii.gz).
in_mask Tracking mask (.nii.gz).
Tracking will stop outside this mask. The last point of each
streamline (triggering the stopping criteria) IS added to the streamline.
out_tractogram Tractogram output file (must be .trk or .tck).
options:
-h, --help show this help message and exit
--in_odf IN_ODF File containing the orientation
diffusion function as spherical harmonics
file (.nii.gz). Ex: ODF or fODF.
If not provided, fODF info must be
specified in rap_policies.json.
--rap_params RAP_PARAMS
JSON file containing RAP parameters, mutually exclusive with --in_odf.
Required for --rap_method switch.
Expected format:
{
"methods": {
"1": {"propagator": "ODF", "filename": str,
"sh_basis": str, "algo": str,
"theta": float, "step_size": float},
"2": {"propagator": "ODF", "filename": str,
"sh_basis": str, "algo": str,
"theta": float, "step_size": float}
}
}
-v [{DEBUG,INFO,WARNING,ERROR}]
Produces verbose output depending on the provided level.
Default level is warning, default when using -v is info.
Tracking options:
--step STEP_SIZE Step size in mm. [0.5]
--min_length m Minimum length of a streamline in mm. [10.0]
--max_length M Maximum length of a streamline in mm. [300.0]
--theta THETA Maximum angle between 2 steps. If the angle is too big, streamline is
stopped and the following point is NOT included.
["eudx"=60, "det"=45, "prob"=20, "ptt"=20]
--sfthres sf_th Spherical function relative threshold within each voxel. [0.1]
--global_sf_rel_thr [FACTOR]
Global SF relative threshold factor. If set, masks voxels where
maximum SF amplitude < FACTOR * global maximum SF amplitude.
If used without a value, default is [0.1].
--global_sf_abs_thr ABS_THR
Global SF absolute threshold. If set, masks voxels where
maximum SF amplitude < ABS_THR.
--sh_basis {descoteaux07,tournier07,descoteaux07_legacy,tournier07_legacy}
Spherical harmonics basis used for the SH coefficients.
Must be either descoteaux07', 'tournier07',
'descoteaux07_legacy' or 'tournier07_legacy' [['descoteaux07_legacy']]:
'descoteaux07' : SH basis from the Descoteaux et al.
MRM 2007 paper
'tournier07' : SH basis from the new Tournier et al.
NeuroImage 2019 paper, as in MRtrix 3.
'descoteaux07_legacy': SH basis from the legacy Dipy implementation
of the Descoteaux et al. MRM 2007 paper
'tournier07_legacy' : SH basis from the legacy Tournier et al.
NeuroImage 2007 paper.
--algo {det,prob} Algorithm to use. [prob]
--sphere {repulsion100,repulsion200,repulsion724,symmetric362,symmetric642,symmetric724}
Dipy sphere; set of possible directions.
Default: [repulsion724]
--sub_sphere SUB_SPHERE
Subdivides each face of the sphere into 4^s new faces. [0]
--sfthres_init sf_th Spherical function relative threshold value for the
initial direction. [0.5]
--rk_order K The order of the Runge-Kutta integration used for the step function.
For more information, refer to the note in the script description. [1]
--max_invalid_nb_points MAX
Maximum number of steps without valid direction,
ex: if threshold on ODF or max angles are reached.
Default: 0, i.e. do not add points following an invalid direction.
--forward_only If set, tracks in one direction only (forward) given the
initial seed. The direction is randomly drawn from the ODF.
--sh_interp {nearest,trilinear}
Spherical harmonic interpolation: nearest-neighbor
or trilinear. [trilinear]
--mask_interp {nearest,trilinear}
Mask interpolation: nearest-neighbor or trilinear. [nearest]
--keep_last_out_point
If set, keep the last point (once out of the tracking mask) of
the streamline. Default: discard them. This is the default in
Dipy too. Note that points obtained after an invalid direction
(ex when angle is too sharp or sh_threshold not reached) are
never added.
--n_repeats_per_seed N_REPEATS_PER_SEED
By default, each seed position is used only once. This option
allows for tracking from the exact same seed n_repeats_per_seed
times. [1]
Seeding options:
When no option is provided, uses --npv 1.
--npv NPV Number of seeds per voxel.
--nt NT Total number of seeds to use.
--in_custom_seeds IN_CUSTOM_SEEDS
Path to a file containing a list of custom seeding
coordinates (.txt, .mat or .npy). They should be in
voxel space. In the case of a text file, each line should
contain a single seed, written in the format: [x, y, z].
Random seeding options:
--rng_seed RNG_SEED Initial value for the random number generator. [0]
--skip SKIP Skip the first N random number.
Useful if you want to create new streamlines to add to
a previously created tractogram with a fixed --rng_seed.
Ex: If tractogram_1 was created with -nt 1,000,000,
you can create tractogram_2 with
--skip 1,000,000.
Region-Adaptive Propagation options:
--rap_mask RAP_MASK Region-Adaptive Propagation mask (.nii.gz).
Region-Adaptive Propagation tractography will start within this mask.
--rap_labels RAP_LABELS
Region-Adaptive Propagation label volume (.nii.gz) .
Voxel values are integer labels (0=background, 1..N=regions) .
Used with --rap_method switch to select policies per label.
--rap_method {None,continue,switch}
Region-Adaptive Propagation tractography method.
'continue': continues tracking with same params,
'switch': switches tracking params inside RAP mask.
[None]
--rap_save_entry_exit RAP_SAVE_ENTRY_EXIT
Save RAP entry/exit coordinates as a binary mask.
Provide output filename (.nii.gz).
Memory options:
--processes NBR Number of sub-processes to start.
Default: [1]
Output options:
--compress [COMPRESS_TH]
If set, compress the resulting streamline. Value is the maximum
compression distance in mm.
A rule of thumb is to set it to 0.1mm for deterministic
streamlines and to 0.2mm for probabilistic streamlines.[0.1]
-f Force overwriting of the output files.
--save_seeds If set, save the seeds used for the tracking
in the data_per_streamline property.
Hint: you can then use scil_tractogram_seed_density_map.
2.3.0