Configurations
The Manifest
Each study should have a manifest that describes where to find imaging data, and what are the conventions. The manifest is written in JSON (JavaScript Object Notation).
Here's an example of the manifest, we can name it conf_base.json
{
// project specific directories
"orig_path": "./orig",
"preprocessed_path": "./preprocessed",
"T1_processed_path": "./group_template",
"processed_path": "./processed",
"template_roi_path": "./orig",
"tractography_path": "./tractography",
"ind_roi_path": "./rois",
// global neuroimage repository locations
"dwi_base_path": "/media/AMMONIS/scans/normals/",
"subject_freesurfer_path" : "/media/AMMONIS/fsSubjects/subjects_archive",
"group_template_file" : "con43_average.nii.gz",
"group_prefix" : "antsT1",
"prefix": "ANTS",
"affix": "",
"imgext": ".nii.gz",
"subjects_file": "subjects.txt",
"subjects": ["C13"],
"manual_subjects": false,
}
Imports
It's possible to combine settings with import statements. For example we want to image the trigeminal nerve, can create a new manifest and call it conf_trig.json
{
"import": "conf_base.json",
}
ROI generation
We want to create the same anatomy across subjects. This is done by defining a ROI on a group template T1 image, and then project this group ROI to each individual anatomical T1 space. So we can define these as follows:
"template_def": {
"reference": "con_average.nii.gz",
"roi_img": "roi_trig.nii.gz"
},
"rois_def": {
"cnv_R": {
"type": "from_template",
"image": "roi_img",
"label": "1"
}
}
"seeds_def": {
"cnvR": {
"source": "cnv_R",
}
}
`
Here we specified where to find the template image. In this case it's a self-generated template with ANTs.
The "reference" value is manditory.
We can also define any number of ROI images in template space, in this case we defined one with name "roi_img", we can refer to it later when we define our ROIs.
We then define our ROIs semantically. In "rois_def", we defined an roi named cnv_R for the right trigeminal nerve. Its type is from_template, and its image source is from roi_img, as we had defined earlier. Its ROI label value in the roi_trig.nii.gz is 1.
Finally we need to tell SAGIT which of the ROIs should be used to start seeding for tracts. We name the tract cnvR, and it should use the ROI definition of cnv_R as we had written above.
The Selective expressions
It's very useful to be able to define regions to allow or disallow tracts to pass. In this case, the trigeminal nerve tracts often stray into the cerebellum. I can manually define the cerebellum as I had earlier on the template T1, and use that as the filtering ROI. But wait, I already have freesurfer segmentations of the cerebellum for all my subjects, wouldn't it be better if SAGIT can make use of that? Here's how I can do it:
"rois_def": {
"cnv_R": {
"type": "from_template",
"image": "roi_img",
"label": "1"
}
"cerebellum_wm": {
"type": "freesurfer",
"image": "union(@46,@7)"
},
"cerebellum_gm": {
"type": "freesurfer",
"image": "union(@47,@8)"
}
}
Turns out that there are both white-matter and grey-matter segmentations of the cerebellum. I decided to define both of them. My type now are freesurfer, and the image source is no longer predefined on the template; instead it is now an expression of union(@1,@2). The @N means to select for the label value N in the freesurfer aseg image, and union(A,B) is to take both of these labels, and generate a new image mask. Image label 46,7 are the left and right wm mask in freesurfer, and 47,8 are the gm mask values.
Now that I have my filtering ROIs defined, I can now use them:
"seeds_def": {
"cnvR": {
"source": "cnv_R",
"excludes": ["cerebellum_gm","cerebellum_wm"],
}
}
We can also force inclusion of ROIs by defining includes similarly.
tractography settings
Now that I have my ROI seeds defined, I need to decide how to generate my tracts. SAGIT supports DTI, XST and CST, here how they can be defined:
"tract_method": [
{
"method":"slicer3"
,"label" : "slicer"
,"params" : "--stoppingvalue 0.15 --stoppingcurvature 0.8 --minimumlength 5 --clthreshold 0.15 --integrationsteplength 0.5 --randomgrid --seedspacing 0.3"
},
{
"method" : "mrtrix",
"label" : "cst_ifod",
"params":"-algorithm iFOD2 -step 0.3 -angle 45 -num 500 -minlength 10 -cutoff 0.1 -initcutoff 0.15 -force"
},
{
"method" : "mrtrix",
"label" : "cst_sd",
"params":"-algorithm SD_STREAM -step 0.3 -angle 45 -rk4 -num 300 -minlength 10 -cutoff 0.1 -initcutoff 0.15 -force"
},
{
"method":"xst",
"label" : "xst",
"params" : " -stop aniso:ca2,0.1 frac:0.1 radius:0.8 minlen:5 -step 0.5"
}
]
The tract_method takes a list of tractography methods to run, and the methods will execute per subject in the order that they are written.
Each method can have a unique label, so that the same method but different parameters can be used. The params are passed directly to the method executable, refer to their software reference for exact options.
All together
Putting it togther, here's the conf_trig.json
{
"import": "conf_base.json",
"template_def": {
"reference": "con_average.nii.gz",
"roi_img": "roi_trig.nii.gz"
},
"rois_def": {
"cnv_R": {
"type": "from_template",
"image": "roi_img",
"label": "1"
}
"cerebellum_wm": {
"type": "freesurfer",
"image": "union(@46,@7)"
},
"cerebellum_gm": {
"type": "freesurfer",
"image": "union(@47,@8)"
}
},
"seeds_def": {
"cnvR": {
"source": "cnv_R",
"excludes": ["cerebellum_gm","cerebellum_wm"],
}
},
"tract_method": [
{
"method":"slicer3",
"label" : "slicer",
"params" : "--stoppingvalue 0.15 --stoppingcurvature 0.8 --minimumlength 5 --clthreshold 0.15 --integrationsteplength 0.5 --randomgrid --seedspacing 0.3"
},
{
"method" : "mrtrix",
"label" : "cst_ifod",
"params":"-algorithm iFOD2 -step 0.3 -angle 45 -num 500 -minlength 10 -cutoff 0.1 -initcutoff 0.15 -force"
},
{
"method" : "mrtrix",
"label" : "cst_sd",
"params":"-algorithm SD_STREAM -step 0.3 -angle 45 -rk4 -num 300 -minlength 10 -cutoff 0.1 -initcutoff 0.15 -force"
},
{
"method":"xst",
"label" : "xst",
"params" : " -stop aniso:ca2,0.1 frac:0.1 radius:0.8 minlen:5 -step 0.5"
}
]
}