Parameters¶
Adding -params¶
Definition of the sequence of nodes in processing pipelines, as well as general parameters, are specified by json file. When specifying a -species and -soft (see Commands), the corresponding default parameter file will be used; They are located in the workflows directory of the package.
The original parameter file can be altered by some options in -soft (e.g. _robustreg, _prep, etc.; see Commands).
Here is an example of the params.json with parameters -soft ANTS for -species macaque:
{
"general":
{
"template_name": "NMT_v2.0_asym"
},
"short_preparation_pipe":
{
"crop_aladin_pipe":
{
"reg_T1_on_template":
{
},
"crop_z_T1":
{
"brainsize": 70
}
}
},
"N4debias":
{
"dimension": 3,
"bspline_fitting_distance": 200,
"n_iterations": [50, 50, 40, 30],
"convergence_threshold": 0.00000001,
"shrink_factor": 2,
"args": "-r 0 --verbose 1"
},
"extract_pipe":
{
"atlas_brex":
{
"f": 0.5,
"reg": 1,
"wrp": "10,10,10",
"msk": "a,0,0",
"dil": 2,
"nrm": 1
}
},
"debias":
{
"s": 2
},
"brain_segment_pipe":
{
"reg":
{
"n": 2,
"m": "ref",
"dof": 12
},
"segment_atropos_pipe":
{
"use_priors": 0.0,
"Atropos":
{
"dimension": 3
},
"tissue_dict":
{
"gm": [2, 3],
"wm": 4,
"csf": [1, 5]
}
},
"export_5tt_pipe":
{
},
"IsoSurface_brain_pipe":
{
"merge_brain_tissues":
{
"keep_indexes": [2,3,4]
}
}
}
}
It is also possible to alter values of some nodes for individual sessions/subjects. See individual parameter section).
Note: Individual parameter will not modify the pipeline sequence itself, a value specified in indiv_params for a node that do not exists in params will ignored
Advanced parameters settings¶
For advanced user, it is however possible to pass the pipeline sequence as a params.json file. In this case all further alteration will be canceled.
Here is json file with all possible nodes to be tuned; Some node are optional, some nodes are exclusive with each other (XOR). All parameters given here are give as examples and may vary:
The beginning of a params include a keyword “general”, and the definition of “short_data_preparation” is also required for both -soft ANTS and SPM:
{
"general":
{
"comment": "OPTIONAL",
"comment": "specify a path on where to put the template after download",
"comment": "By default set to the home directory of the user",
"my_path" : "/path/to/template",
"comment": "MANDOTORY, if not set as -template_path / template_files in command line",
"comment": "Template used for priors segmentation",
"comment": "see macapype/utils/templates.json for available names",
"template_name": "bma_padded",
"comment": "OPTIONAL",
"comment": "if not set, template_name will be used by default",
"comment": "Template used for crop_aladin / projection in stereo space",
"template_stereo_name": "MBM_3.0",
},
"short_preparation_pipe":
{
"use_T2":
{
"comment": "boolean marker, if present T2 and T1 are exchanged in the process, (T2 is used to register to template, and T1 is registered to T2)",
"comment": "BE CAREFUL, the name of the internal nodes are still using the original names although the files are swapped",
"comment": "Everything is swapped back as outputs of short_preparation_pipe",
},
"avg_reorient_pipe":
{
"comment": "OPTIONAL",
"reorient":
{
"params": "SwapDimensions (FSL)",
"new_dims": "x z -y"
}
},
"aladin_T2_on_T1":
{
"comment": "boolean marker, if present RegAladin to coregister T2 on T1 and pad/resample, otherwise use FSL FLIRT (default)",
},
"crop_T1":
{
"comment": "OPTIONAL",
"comment": "if present, applied to both T1w and T2w",
"params": "fslroi (FSL)",
"args": "should be specified in indiv_params"
},
"crop_aladin_pipe":
{
"remove_capsule_pipe":{},
"reg_T1_on_template":
{
"params": "RegAladin (NiftyReg)"
},
"reg_T1_on_template2":
{
"comment": "OPTIONAL",
"comment": "typically used with -soft _robustreg ",
"params": "RegAladin (NiftyReg)"
}
},
"inv_transfo_aladin":
{
"comment": "OPTIONAL",
"comment" : "not sure why it is parameterized",
"params": "RegTransform (NiftyReg)"
},
"denoise":
{
"comment": "OPTIONAL",
"params": "DenoiseImage (ANTS)",
"shrink_factor": 2
},
"pad_template":
{
"comment": "OPTIONAL",
"comment": "used for skullTo3d to keep an image bigger than brain, but is not used further in brain segmentation",
"params": "ImageMath (ANTS)",
"copy_header" : true,
"operation" : "PadImage",
"op2" : "70"
}
}
}
For -soft SPM, here is the overall structure of the pipeline:
{
"general":
{
"template_name": "Haiko_v1.5"
},
"comment": "mandatory, performing both debias and brain_extraction",
"debias":
{
"params": "T1xT2BiasFieldCorrection (local wrap of Regis Trapeau tools)",
"s": 2
},
"comment": "mandatory",
"reg":
{
"params": "IterREGBET (local wrap of Regis Trapeau tools)",
"n": 2,
"m": "ref",
"dof": 12
},
"old_segment_pipe":
{
"segment":
{
"comment": "mandatory if old_segment_pipe is defined",
"params": "Segment (SPM12)",
"gm_output_type": [false, false, true],
"wm_output_type": [false, false, true],
"csf_output_type": [false, false, true]
},
"threshold_gm":
{
"comment": "mandatory if old_segment_pipe is defined",
"params": "Threshold (FSL)",
"thr": 0.5
},
"threshold_wm":
{
"comment": "mandatory if old_segment_pipe is defined",
"params": "Threshold (FSL)",
"thr": 0.5
},
"threshold_csf":
{
"comment": "mandatory if old_segment_pipe is defined",
"params": "Threshold (FSL)",
"thr": 0.5
},
"comment": "optional (if segmentation in 5tt mrtrix format is required"),
"export_5tt_pipe":
{
"commment": "no node are parametrized"
}
},
"comment": "OPTIONAL",
"mask_from_seg_pipe":
{
"merge_indexed_mask":
{
"comment": "never used, not sure if modifying default parameters works",
"comment": "default : index_csf=1, index_gm=2, index_wm=3",
"params": "merge_masks (python)",
}
}
}
For -soft ANTS, here is the overall structure of the pipeline:
{
"comment": "the following nodes are mutually exclusive, and are optional",
"correct_bias_pipe":
{
"comment": "is problematic if hypointensities (zeros) in T2w images outside of the brain, as as division by 0 will be performed",
"comment": "N4debias or fast are preferred",
"smooth":
{
"comment": "mandatory if correct_bias_pipe is defined",
"params": "MathsCommand (FSL)",
"args": "-bin -s 2"
},
"norm_smooth":
{
"comment": "mandatory if correct_bias_pipe is defined",
"params": "MultiImageMaths (FSL)",
"op_string": "-s 2 -div %s"
},
"smooth_bias":
{
"comment": "mandatory if correct_bias_pipe is defined",
"params": "Smooth (FSL)",
"sigma": 2
}
},
"comment": "OR",
"N4debias":
{
"comment": "PREFERED",
"comment": "OPTIONAL",
"params": "N4BiasFieldCorrection (ANTS)",
"comment": "same parameters for T1 and T2",
"dimension": 3,
"bspline_fitting_distance": 200,
"n_iterations": [50, 50, 40, 30],
"convergence_threshold": 0.00000001,
"shrink_factor": 2,
"args": "-r 0 --verbose 1"
},
"comment": "OR",
"fast":
{
"comment": "OPTIONAL",
"comment": "same parameters for T1 and T2",
"params": "FAST (FSL) used for debias not segmentation",
},
"comment": "MANDATORY if mask is not provided as input of command line",
"extract_pipe":
{
"use_T2":
{
"comment": "boolean marker, if present T2 and T1 are exchanged in the process, (T2 is used to register to template)",
"comment": "Be careful that in this case, the template head and brain have to match T2w images ",
"comment": "better to specify your own template with template_path template_files in the command line"
},
"smooth":
{
"comment": "OPTIONAL",
"params": "Smooth (FSL)",
},
"atlas_brex":
{
"comment": "mandatory if extract_pipe is defined",
"params": "AtlasBREX (local wrap in macapype of Johannes Lohmeier tool)",
"f": 0.7,
"reg": 1,
"msk": "b,0.5,0,0",
"wrp": "10,10,10",
"dil": 1,
"nrm": 1
}
},
"comment": "the two following nodes are mutually exclusive, and are optional",
"masked_correct_bias_pipe":
{
"smooth":
{
"comment": "mandatory if masked_correct_bias_pipe is defined",
"params": "MathsCommand (FSL)",
"args": "-bin -s 2"
},
"norm_smooth":
{
"comment": "mandatory if masked_correct_bias_pipe is defined",
"params": "MultiImageMaths (FSL)",
"op_string": "-s 2 -div %s"
},
"smooth_bias":
{
"comment": "mandatory if masked_correct_bias_pipe is defined",
"params": "Smooth (FSL)",
"sigma": 2
}
},
"comment": "OR",
"debias":
{
"comment": "PREFERED",
"comment": "performs same operations as masked_correct_bias_pipe in bash function",
"params": "T1xT2BiasFieldCorrection (local wrap of Regis Trapeau tools)",
"s": 2
},
"brain_segment_pipe":
{
"use_T2":
{
"comment": "boolean marker, if present T2 and T1 are exchanged in the process, (T2 is used to register to template)",
"comment": "Be careful that in this case, the template priors have to match T2w images ",
"comment": "better to specify your own template with template_path template_files in the command line"
},
"comment": "If use_priors is defined in segment_atropos_pipe, one of register_NMT_pipe or reg must be defined",
"register_NMT_pipe":
{
"norm_intensity":
{
"comment": "OPTIONAL",
"params": "N4BiasFieldCorrection (ANTS)"
},
"deoblique":
{
"comment": "OPTIONAL",
"params": "boolean marker (no params) for adding a node with Refit (AFNI) deoblique=True"
},
"NMTSubjectAlign":
{
"comment": "OPTIONAL"
},
"comment": "OR",
"NMT_subject_align":
{
"comment": "default"
}
},
"comment": "OR",
"reg":
{
"params": "IterREGBET (local wrap of Regis Trapeau tools)",
"n": 2,
"m": "ref",
"dof": 12
},
"segment_atropos_pipe":
{
"comment": "if present ( a value have to be specied), priors will be projected to stereo space (possibly not the same as another template can be specified for priors)",
"comment": "(this is typically the case for marmoset: use_T2 with bma for short_preparation_pipe, and MBM for priors)",
"comment": "If no usepriors, the register_NMT_pipe or reg are not used",
"use_priors": 0.0,
"Atropos":
{
"comment": "mandatory if segment_atropos_pipe is defined",
"params" : "AtroposN4 (ANTS)",
"dimension": 3,
"comment": "numberOfClasses is OPTIONAL (default is 3)",
"numberOfClasses": 3
},
"tissue_dict":
{
"comment": "OPTIONAL",
"comment": "default are : gm: 1, wm: 2, csf: 3",
"comment": "possible to merge indexes for one label, for example csf: [1, 5], gm: [2, 3], wm: 4",
"gm": 2,
"wm": 3,
"csf": 1
}
},
"comment": "optional (if segmentation in 5tt mrtrix format is required",
"export_5tt_pipe":
{
"commment": "no node are parametrized"
}
},
"comment": "following pipelines are used for surface mesh",
"comment": "all are mutually exclusive and optional",
"comment": "prefered method",
"IsoSurface_brain_pipe":
{
"merge_brain_tissues":
{
"keep_indexes": [2,3]
}
},
"comment": "OR",
"nii2mesh_brain_pipe":
{
},
"comment": "OR",
"nii_to_mesh_pipe":
{
}
}