.. _scil_tracking_local_dev: scil_tracking_local_dev ======================= :: 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