Inputs

Default input format - BIDS

sf-tractomics input folder must follow a valid BIDS format, that minimally contains diffusion (dwi) and T1-weighted (T1w) MRI acquisitions:

Directoryinput_bids_directory
- dataset_description.json
- participants.json
- participants.tsv
- Directorysub-01
  - Directorydwi
    sub-01_dwi.nii.gz
    sub-01_dwi.bval
    sub-01_dwi.bvec
    sub-01_dwi.json
  - Directoryanat
    sub-01_T1w.nii.gz
    sub-01_T1w.json
- Directorysub-02
  - Directorydwi
    sub-02_dwi.nii.gz
    sub-02_dwi.bval
    sub-02_dwi.bvec
    sub-02_dwi.json
  - Directoryanat
    sub-02_T1w.nii.gz
    sub-02_T1w.json

participants.tsv

The participants.tsv file is not required for most modules of the pipeline. However, if you’re planning on performing harmonization (e.g. using ClinicalCombat) you should provide a participants.tsv file listing different covariates for each subject, session and acquisition run. Also, even if no harmonization is being done and you’re performing tractometry, you could also supply this file to carry the covariates along with your tractometry results. The participants.tsv file should contain a particular structure. Minimally, the participants.tsv should contain the following columns (it can also contain more columns):

participant_label	session	site	age	sex	handedness	disease
sub-001	1	Sherbrooke	78	2	1	HC
sub-001	2	Sherbrooke	78	2	1	HC
sub-002	1	Sherbrooke	81	2	2	HC
sub-002	2	Sherbrooke	81	2	2	HC

Notice in the example above that even for an optional column that doesn’t have any values, the column header still is represented and the values for that column are simply empty.

participant_label: The participant’s ID prepended with “sub-”.
session (optional): The participant’s acquisition session ID (without the ses- prefix). If no session is provided, leave empty.
run (optional): The participant’s acquisition run ID (without the run- prefix). If no run is provided, leave empty.
site: Acquisition site name.
age: Age (in years) of the participant.
sex: Sex of the participant. 1 for male, 2 for female.
handedness (optional): Handedness of the participant. 1 for right, 2 for left.
disease: Whether the participant is affected by a disease. Use minimally “HC” for healthy controls.

Although completely optional and in line with the BIDS specification, we recommend having a participants.json which briefly details the meaning of each column of the participants.tsv file. For more details, consult this section of the specification.

Perform Motion and Eddy currents correction

sf-tractomics automatically detects reverse-phase acquired images and epi references from the BIDS dataset organization. To be detected, those images need to have a valid direction entity. The same is expected for the main diffusion volume as well (AP and PA are used as example) :

Reverse b0
Reverse DWI

Directoryinput_bids_directory
- dataset_description.json
- Directorysub-01
  - Directorydwi
    sub-01_dir-AP_dwi.nii.gz
    sub-01_dir-AP_dwi.bval
    sub-01_dir-AP_dwi.bvec
    sub-01_dir-AP_dwi.json
  - Directoryanat
    sub-01_T1w.nii.gz
    sub-01_T1w.json
  - Directoryepi
    sub-01_dir-PA_sbref.nii.gz
    sub-01_dir-PA_sbref.json
- Directorysub-02
  - Directorydwi
    sub-02_dir-AP_dwi.nii.gz
    sub-02_dir-AP_dwi.bval
    sub-02_dir-AP_dwi.bvec
    sub-02_dir-AP_dwi.json
  - Directoryanat
    sub-02_T1w.nii.gz
    sub-02_T1w.json
  - Directoryepi
    sub-02_dir-PA_sbref.nii.gz
    sub-02_dir-PA_sbref.json

Unstructured datasets

sf-tractomics also supports parsing its input from a samplesheet.csv in Comma Separated Values format, in case your dataset doesn’t follow the BIDS format yet. The samplesheet must respect the header below :

subject,dwi,bval,bvec,sbref,rev_dwi,rev_bval,rev_bvec,rev_sbref,t1,wmparc,aparc_aseg,lesion


subject	Identifier to tag the subject’s files when producing outputs
dwi	Diffusion Weighted volume in Nifti format
bval	b-values file following FSL format
bvec	b-vectors file following FSL format
sbref	Single-band b0 reference for the DWI volume in Nifti format
rev_dwi	Reverse-phase acquired Diffusion Weighted volume in Nifti format
rev_bval	b-values file for the reverse-phase DWI following FSL format
rev_bvec	b-vectors file for the reverse-phase DWI following FSL format
rev_sbref	Single-band b0 reference for the reverse-phase DWI volume in Nifti format
t1	Anatomical T1-Weighted volume in Nifti format
wmparc	White matter parcellation from FreeSurfer
aparc_aseg	Tissue segmentation and cortical parcellation from FreeSurfer

Example of a samplesheet.csv file:

subject,dwi,bval,bvec,sbref,rev_dwi,rev_bval,rev_bvec,rev_sbref,t1,wmparc,aparc_aseg,lesion
sub-01_ses-1,/my/path/to/data/sub-01/dwi.nii.gz,/my/path/to/data/sub-01/dwi.bval,/my/path/to/data/sub-01/dwi.bvec,,,,,/my/path/to/data/sub-01/t1.nii.gz,/my/path/to/data/sub-01/wmparc.nii.gz,/my/path/to/data/sub-01/aparc+aseg.nii.gz,
sub-02,/my/path/to/data/sub-02/dwi_ap.nii.gz,/my/path/to/data/sub-02/dwi_ap.bval,/my/path/to/data/sub-02/dwi_ap.bvec,,/my/path/to/data/sub-02/dwi_pa.nii.gz,/my/path/to/data/sub-02/dwi_pa.bval,/my/path/to/data/sub-02/dwi_pa.bvec,/my/path/to/data/sub-02/t1.nii.gz,/my/path/to/data/sub-02/wmparc.nii.gz,/my/path/to/data/sub-02/aparc+aseg.nii.gz,
sub-03,/my/path/to/data/sub-03/dwi_ap.nii.gz,/my/path/to/data/sub-03/dwi_ap.bval,/my/path/to/data/sub-03/dwi_ap.bvec,,/my/path/to/data/sub-03/dwi_pa.nii.gz,/my/path/to/data/sub-03/dwi_pa.bval,/my/path/to/data/sub-03/dwi_pa.bvec,/my/path/to/data/sub-03/t1.nii.gz,,,