Connectoflow pipeline

=====================

Run our state-of-the-art connectivity pipeline.

T1 and labels must be provided in their original space (output from freesurfer

or civet) and the affine and nonlinear transformation must bring these images

to diffusion space. We recommand running the command scil_verify_space_attributes_compatibility

with the t1 and labels to ensure they are indeed in the same space.

The atlas must be stripped of the WM and CSF labels and only keep the cortical and

subcortical labels (brainstem/cerebelum optional).

The rest of the input (tracking, dwi, peaks, fodf and all metrics)

must be in diffusion space with compatible headers. We recommand running the command

scil_verify_space_attributes_compatibility with the all the files mentioned above

to ensure they are indeed in the same space.

It is mandatory that all grouped input either have identical prefix or no

prefix at all.

- *labels.nii.gz and t1.nii.gz must have the same prefix in order to be read properly.

t1 MUST overlay with the labels and MUST be skull-strip.

If you launched Tractoflow using the same input T1w image. Then, connectoflow 'expects'

the T1w from the BET_T1 process.

- *dwi.nii.gz, *dwi.bval, *dwi.bvec, *fodf.nii.gz, *peaks.nii.gz must also have

the same prefix in order to be read properly.

If you launched Tractoflow, the dwi.nii.gz comes from RESAMPLE_DWI and if you used

Eddy make sure to use the corrected bvecs from the EDDY process.

- *tracking*.[fib,trk,tck] must also have the same prefix.

This support multiple files (with suffixes).

If you do not provide dwi.nii.gz/bval/bvec, use --run_commit false

If you do not provide fodf, use --run_afd_rd false

If you use a large number of cpu per node (e.g >20) makes sure the option

--processes_avg_similarity is set to that number to use all the cpu of the node.

Most processes have a duration directly related to the number of connections.

Which is (NBR_PARCEL) * (NBR_PARCEL-1) / 2. Running connectoflow with a freesurfer

parcellation is A LOT faster than with Brainnetome, which is A LOT faster than

with Glasser, make sure to test & optimize calls before launching on clusters.

If providing a lesion mask, the nifti should be a uint8 binary image representing

the voxel that are considered lesions. These lesions should have been taken into account

when generating the tractogram (to allow tractography within the lesions).

The lesion mask MUST BE in the same space as the DWI with the same header.

USAGE

nextflow run main.nf [OPTIONAL_ARGUMENTS] --input --template --labels_list

DESCRIPTION

--input=/path/to/[root] Root folder containing multiple subjects

[root]

├── S1

│ │── *tracking*.[fib,trk,tck]

│ │── *labels.nii.gz (native T1 space)

│ │── *t1.nii.gz (native T1 space)

│ │── *1Warp.nii.gz (native T1 space to diff space)

│ │── *0GenericAffine.mat (native T1 space to diff space)

│ │── *dwi.nii.gz (optional)

│ │── *dwi.bval (optional)

│ │── *dwi.bvec (optional)

│ │── *peaks.nii.gz (optional)

│ │── *fodf.nii.gz (optional)

│ │── *lesion_mask.nii.gz (optional, diff space)

| └── metrics (optional)

| └── METRIC_NAME.nii.gz

└── S2

└── *

--template Template used for registration in a common space for similarity/viz

--labels_list Complete (expected) labels_list of the atlas used

OPTIONAL ARGUMENTS (current value)

--labels_img_prefix Specify a prefix for the labels to use (when dealing with multiple input labels)

--output_dir Specify a new output directory to avoid overwriting results (when dealing with multiple input labels) ($output_dir)

--apply_t1_labels_transfo Apply the provided transformation to T1/Labels, typically used if the T1/Labels are not in diffusion space ($apply_t1_labels_transfo)

--run_commit Run COMMIT1 on the tractogram ($run_commit)

--use_commit2 Use COMMIT2 rather than the original COMMIT1

(will replace the COMMIT1 output with COMMIT2) ($use_commit2)

--b_tol Tolerance value to match b-value is on the same shell ($b_tol)

--nbr_dir Number of directions, (half sphere), representing the possible orientations of the response functions ($nbr_dir)

--ball_stick Use the ball&Stick model. Disable the zeppelin compartment for single-shell data ($ball_stick)

--para_diff Parallel diffusivity in mm^2/s ($para_diff)

--perp_diff Perpendicular diffusivity in mm^2/s ($perp_diff)

--iso_diff Istropic diffusivity in mm^2/s ($iso_diff)

--no_pruning If set, will NOT prune on length ($no_pruning)

--no_remove_loops If set, will NOT remove streamlines making loops ($no_remove_loops)

--no_remove_outliers If set, will NOT remove outliers using QB ($no_remove_outliers)

--min_length Pruning minimal segment length ($min_length)

--max_length Pruning maximal segment length ($max_length)

--loop_max_angle Maximal winding angle over which a streamline is considered as looping ($loop_max_angle)

--outlier_threshold Outlier removal threshold when using hierarchical QB ($outlier_threshold)

--run_afd_rd Run the computation of AFD/RD on all pairs of connections ($run_afd_rd)

--length_weighting If set, will weigh the AFD values according to segment lengths for afd/rd ($length_weighting)

--sh_basis Spherical harmonics basis used for the SH coefficients ($sh_basis)

--min_lesion_vol To be consider 'a lesion' for the pipeline, a lesion must be at least ($min_lesion_vol) mm3.

--use_similarity_metric Compute the average shape distance for each connection ($use_similarity_metric)

--nbr_subjects_for_avg_connections The average shape is computed from a random subset of subjects, must be equal or lower than the total number of subjects ($nbr_subjects_for_avg_connections)

--processes_register Number of processes for registration task ($processes_register)

--processes_commit Number of processes for COMMIT task ($processes_commit)

--processes_afd_rd Number of processes for AFD/RD task ($processes_afd_rd)

--processes_avg_similarity Number of processes for average similarity task ($processes_avg_similarity)

--processes_connectivity Number of processes for compute connectivity task ($processes_connectivity)

--processes The number of parallel processes to launch ($cpu_count).

Only affects the local scheduler.

AVAILABLE PROFILES (using -profile option (e.g. -profile use_cuda,fully_reproducible))

macos When this profile is used, TractoFlow will modify a parameter (scratch) for MacOS users.

fully_reproducible When this profile is used, all the parameters will be set to have 100% reproducible results.

NOTES

To set the number of parallel processes to launch, please use:

'nextflow run -qs {nb_processes}'.

The intermediate working directory is, by default, set to './work'.

To change it, use the '-w WORK_DIR' argument.

The default config file is connectoflow/nextflow.config.

Use '-C config_file.config' to specify a non-default configuration file.

The '-C config_file.config' must be inserted after the nextflow call

like 'nextflow -C config_file.config run ...'.