Skip to content

Commit 0875c92

Browse files
davidmeunier79davidmeunier79
authored
Prepare major release (#307)
* modif doc for novelty (debias in prep and extract_brain with bet4animal or hd-bet) * removed -seq * 0.6-rc1
1 parent 1f2ceb8 commit 0875c92

9 files changed

Lines changed: 253 additions & 105 deletions

File tree

‎docs/command.rst‎

Lines changed: 52 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ All the data have to be in BIDS format to run properly (see `BIDS specification
4141

4242
In particular:
4343

44-
* _T1w (BIDS) extension is expected for T1 weighted images (BIDS)
45-
* _T2w (BIDS) extension is expected for T2 weighted images (BIDS)
44+
* ``_T1w`` (BIDS) extension is expected for T1 weighted images (BIDS)
45+
* ``_T2w`` (BIDS) extension is expected for T2 weighted images (BIDS)
4646

4747
.. image:: ./img/images/BIDS_orga.jpg
4848
:width: 600
@@ -54,76 +54,81 @@ In particular:
5454
Command line parameters
5555
***********************
5656

57-
--------------------------------------
58-
The following parameters are mandatory
59-
--------------------------------------
57+
--------------------
58+
mandatory parameters
59+
--------------------
6060

61-
* -data
62-
the path to your data dataset (existing BIDS format directory)
61+
* ``-data`` : path to your data dataset (existing BIDS format directory)
62+
* ``-out`` : path to the output results (an existing path)
63+
* ``-soft`` : can be one of these : SPM or ANTS ( **NB:** SPM requires a specific version of macapype/skullTo3d, not available by default)
6364

64-
* -out
65-
the path to the output results (an existing path)
65+
For ``-soft`` value, it is possible to add some key words (e.g. ``-soft ANTS_robustreg_prep``) all these options are available (to place after SPM or ANTS, e.g) and will change the brain extraction:
6666

67-
* -soft
68-
can be one of these : SPM or ANTS
69-
* with _robustreg (at the end) to have a more robust registration (in two steps)
70-
* with _test (at the end) to check if the full pipeline is coherent (will only generate the graph.dot and graph.png)
71-
* with _prep (at the end) will perform data preparation (no brain extraction and segmentation)
72-
* with _noseg (at the end) will perform data preparation and brain extraction (no segmentation)
73-
* with _seq (at the end) to run in sequential mode (all iterables will be processed one after the other; equivalent to -nprocs 1)
67+
* ``_4animal`` : will use bet4animal (FSL) for brain extraction, for faster computation (by default atlas_brex is used)
68+
* ``_quick`` : will use hd-bet (Deep Learning) for brain extraction, for faster computation (by default atlas_brex is used)
69+
**NB: ** hd-bet requires a specific version of macapype/skullTo3d, not available by default
7470
75-
--------------------------------------
76-
The following parameters are exclusive
77-
--------------------------------------
71+
This option should be used if the coregistration to template in preparation is not performed correctly:
72+
73+
* ``_robustreg`` (at the end) to have a more robust registration (in two steps)
74+
75+
Finally, these option are available (to place after SPM or ANTS) and will modify the parameters but can be launched in sequence:
76+
77+
* ``_test`` : (at the end) to check if the full pipeline is coherent (will only generate the graph.dot and graph.png)
78+
* ``_prep`` (at the end) will perform data preparation (no brain extraction and segmentation)
79+
* ``_noseg`` (at the end) will perform data preparation and brain extraction (no segmentation)
80+
81+
--------------------
82+
exclusive parameters
83+
--------------------
7884
*(but one is mandatory)*
7985

80-
* -params *(mandatory if -species is omitted)*
81-
a json file specifiying the global parameters of the analysis. See :ref:`Parameters <params>` for more details
86+
* ``-params`` : *(mandatory if -species is omitted)* a json file specifiying the global parameters of the analysis. See :ref:`Parameters <params>` for more details
87+
* ``-species`` : *(mandatory if -params is omitted)* followed the NHP species corresponding to the image, e.g. {macaque | marmo | baboon | chimp}
88+
89+
**NB** : marmoT2 can be used for segmenting from the T2w image (by default, T1w is used for marmo)
90+
91+
**NB** : baboon0, baboon1, baboon2 baboon3 can be used for template `Baba21 <doi:10.18112/openneuro.ds005424.v1.0.0>`_
92+
and matching
8293

83-
* -species *(mandatory if -params is omitted)*
84-
followed the NHP species corresponding to the image, e.g. {macaque | marmo | baboon | chimp}
85-
In extra, marmoT2 can be used for segmenting from the T2w image (by default, T1w is used)
94+
**NB** : some templates are available in downgraded versions: baboon1_0p6, baboon2_0p6 baboon3_0p6 and macaque_0p5 and show significant decrease in processing time with low redection in quality. However, not all combinations are available
8695

87-
--------------------------------------
88-
The following parameters are optional
89-
--------------------------------------
96+
-------------------
97+
optional parameters
98+
-------------------
9099
*(but highly recommanded)*
91100

92-
* dt
93-
specifies the datatype available to perform brain segmentation (can be "T1", or "T1 T2").
94-
**Note** : default is T1 if the attribute is omitted
101+
* ``-dt`` : specifies the datatype available to perform brain segmentation (can be "T1", or "T1 T2")
95102

96-
* -deriv creates a derivatives directory, with all important files, properly named following BIDS derivatives convertion
103+
**Note** : default is T1 if the attribute is omitted
97104

98-
* -pad exports (in derivatives) important files in native (original) space
105+
* ``-deriv`` : creates a derivatives directory, with all important files, properly named following BIDS derivatives convertion. See :ref:`Derivatives <derivatives>` for a descrition of the outputs
99106

100-
--------------------------------------
101-
The following parameters are optional
102-
--------------------------------------
107+
* ``-pad`` : exports most important files in native (original) space
103108

104-
* -indiv or -indiv_params : a json file overwriting the default parameters (both macapype default and parameters specified in -params json file) for specific subjects/sessions. See :ref:`Individual Parameters <indiv_params>` for more details
109+
------------------------
110+
more optional parameters
111+
------------------------
105112

106-
* -sub (-subjects), -ses (-sessions), -acq (-acquisions), -rec (-reconstructions) allows to specifiy a subset of the BIDS dataset respectively to a range of subjects, session, acquision types and reconstruction types. The arguments can be listed with space seperator. **Note** if not specified, the full BIDS dataset will be processed
113+
* ``-indiv`` or ``-indiv_params`` : a json file overwriting the default parameters (both macapype default and parameters specified in -params json file) for specific subjects/sessions. See :ref:`Individual Parameters <indiv_params>` for more details
114+
* ``-sub`` (-subjects), ``-ses`` (-sessions), ``-acq`` (-acquisions), ``-rec`` (-reconstructions) allows to specifiy a subset of the BIDS dataset respectively to a range of subjects, session, acquision types and reconstruction types. The arguments can be listed with space seperator. **Note** if not specified, the full BIDS dataset will be processed
115+
* ``-nprocs`` : an integer, to specifiy the number of processes that should be allocated by the parralel engine of macapype
107116

108-
* -mask allows to specify a precomputed binary mask file (skipping brain extraction). The best usage of this option is: precomputing the pipeline till brain_extraction_pipe, modify by hand the mask and use the mask for segmentation. Better if only one subject*session is specified (one file is specified at a time...).
117+
* typically equals to the number of subjects*session (i.e. iterables).
118+
* can be multiplied by 2 if T1*T2 pipelines are run (the first steps at least will benefit from it)
119+
* default = 4 if unspecified ; if is put to 1, then the sequential processing is used
109120

110-
**Warning: the mask should be in the same space as the data. And only works with -soft ANTS so far**
121+
* ``-mask`` allows to specify a precomputed binary mask file (skipping brain extraction). The best usage of this option is: precomputing the pipeline till brain_extraction_pipe, modify by hand the mask and use the mask for segmentation. Better if only one subject*session is specified (one file is specified at a time...).
111122

112-
* -nprocs : an integer, to specifiy the number of processes that should be allocated by the parralel engine of macapype
113-
* typically equals to the number of subjects*session (i.e. iterables).
114-
* can be multiplied by 2 if T1*T2 pipelines are run (the first steps at least will benefit from it)
115-
* default = 4 if unspecified ; if is put to 0, then the sequential processing is used (equivalent to -soft with _seq, see before)
123+
**Warning:** the mask should be in the same space as the data. And only works with -soft ANTS so far
116124

117-
***********************
118125
Command line examples
119-
***********************
120-
126+
*********************
121127

122128
.. code:: bash
123129
124130
$ python workflows/segment_pnh.py -data ~/Data_maca -out ./local_test -soft ANTS -params params.json
125131
126-
127132
.. code:: bash
128133
129134
$ python workflows/segment_pnh.py -data ~/Data_maca -out ./local_test -soft ANTS_robustreg -species macaque

‎docs/derivatives.rst‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
:orphan:
2+
3+
.. _derivatives:
4+
5+
***********
6+
Derivatives
7+
***********
8+
9+
Introduction
10+
************
11+
12+
Depending on the options provided by command line and params.json, different files will ouput
13+
14+
Derivatives will be output if option ``-deriv`` is provided to the command line (See `Commands <commands>`):
15+
16+
All files are by default in stereo space; if option ``-pad`` is provided to the command line (See `Commands <commands>`), files in native will also be output.
17+
18+
Data Preparation
19+
****************
20+
21+
Original files (possibly after reorientation and avereging):
22+
23+
*sub-Stevie_ses-01_space-native_T1w.nii.gz*
24+
25+
*sub-Stevie_ses-01_space-native_T2w.nii.gz*
26+
27+
|
28+
29+
If -pad is defined in command line (See `Commands <commands>`):
30+
31+
*sub-Stevie_ses-01_space-native_desc-denoised_T1w.nii.gz*
32+
33+
*sub-Stevie_ses-01_space-native_desc-denoised_T2w.nii.gz*
34+
35+
*sub-Stevie_ses-01_space-native_desc-debiased_T1w.nii.gz*
36+
37+
*sub-Stevie_ses-01_space-native_desc-debiased_T2w.nii.gz*
38+
39+
**NB:** Both denoise and debias are optional
40+
41+
|
42+
43+
Original files in stereo space:
44+
45+
*sub-Stevie_ses-01_space-stereo_T1w.nii.gz*
46+
47+
*sub-Stevie_ses-01_space-stereo_T2w.nii.gz*
48+
49+
|
50+
51+
After some preprocessing :
52+
53+
*sub-Stevie_ses-01_space-stereo_desc-denoised_T1w.nii.gz*
54+
55+
*sub-Stevie_ses-01_space-stereo_desc-denoised_T2w.nii.gz*
56+
57+
*sub-Stevie_ses-01_space-stereo_desc-debiased_T1w.nii.gz*
58+
59+
*sub-Stevie_ses-01_space-stereo_desc-debiased_T2w.nii.gz*
60+
61+
**NB:** Both denoise and debias are optional
62+
63+
|
64+
65+
Transformations:
66+
67+
*sub-Stevie_ses-01_space-native_target-stereo_affine.txt*
68+
69+
*sub-Stevie_ses-01_space-stereo_target-native_affine.txt*
70+
71+
Brain extraction
72+
****************
73+
74+
Brain mask:
75+
76+
*sub-Stevie_ses-01_space-stereo_desc-brain_mask.nii.gz*
77+
78+
*sub-Stevie_ses-01_space-native_desc-brain_mask.nii.gz*
79+
80+
Brain segmentation
81+
******************
82+
83+
Brainmasked files after T1*T2 Bias correction:
84+
85+
*sub-Stevie_ses-01_space-stereo_desc-debiased_desc-brain_T1w.nii.gz*
86+
87+
*sub-Stevie_ses-01_space-stereo_desc-debiased_desc-brain_T2w.nii.gz*
88+
89+
*sub-Stevie_ses-01_space-native_desc-debiased_desc-brain_T2w.nii.gz*
90+
91+
*sub-Stevie_ses-01_space-native_desc-debiased_desc-brain_T1w.nii.gz*
92+
93+
|
94+
95+
Segmentated files as probability tisses:
96+
97+
*sub-Stevie_ses-01_space-stereo_label-WM_probseg.nii.gz*
98+
99+
*sub-Stevie_ses-01_space-stereo_label-GM_probseg.nii.gz*
100+
101+
*sub-Stevie_ses-01_space-stereo_label-CSF_probseg.nii.gz*
102+
103+
*sub-Stevie_ses-01_space-native_label-WM_probseg.nii.gz*
104+
105+
*sub-Stevie_ses-01_space-native_label-GM_probseg.nii.gz*
106+
107+
*sub-Stevie_ses-01_space-native_label-CSF_probseg.nii.gz*
108+
109+
|
110+
111+
Segmentated files as indexed tisses:
112+
113+
*sub-Stevie_ses-01_space-stereo_desc-brain_dseg.nii.gz*
114+
115+
*sub-Stevie_ses-01_space-native_desc-brain_dseg.nii.gz*
116+
117+
Optional Post brain segmentation
118+
********************************
119+
120+
Segmented files in mrtrix format:
121+
122+
*sub-Stevie_ses-01_space-stereo_desc-5tt_dseg.nii.gz*
123+
124+
*sub-Stevie_ses-01_space-native_desc-5tt_dseg.nii.gz*
125+
126+
|
127+
128+
White matter + Gray matter binary mask and corresponding mesh:
129+
130+
*sub-Stevie_ses-01_space-stereo_desc-wmgm_mask.nii.gz*
131+
132+
*sub-Stevie_ses-01_space-native_desc-wmgm_mask.nii.gz*
133+
134+
*sub-Stevie_ses-01_desc-wmgm_mask.stl*
135+

‎docs/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ macapype is fairly flexible, but requires to specify multiples parameters in com
3838

3939
See :ref:`Commands <command>` for a description on the avalaible command parameters
4040

41-
41+
If ``-deriv``` is provided, see :ref:`Derivatives <derivatives>` for a descrition of the outputs
4242

4343
Table of contents
4444
******************
@@ -50,6 +50,7 @@ Table of contents
5050
docker_install
5151
quick_test
5252
command
53+
derivatives
5354
params
5455
indiv_params
5556

‎examples_doc/params_general_preparation.json‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,44 @@
100100
"copy_header" : true,
101101
"operation" : "PadImage",
102102
"op2" : "70"
103+
},
104+
105+
106+
"comment": "the following nodes are mutually exclusive, and are optional",
107+
108+
"N4debias":
109+
{
110+
"comment": "PREFERED",
111+
"comment": "OPTIONAL",
112+
"params": "N4BiasFieldCorrection (ANTS)",
113+
"comment": "same parameters for T1 and T2",
114+
115+
"dimension": 3,
116+
"bspline_fitting_distance": 200,
117+
"n_iterations": [50, 50, 40, 30],
118+
"convergence_threshold": 0.00000001,
119+
"shrink_factor": 2,
120+
"args": "-r 0 --verbose 1"
121+
},
122+
"comment": "OR",
123+
"fast":
124+
{
125+
"comment": "OPTIONAL",
126+
"comment": "same parameters for T1 and T2",
127+
"params": "FAST (FSL) used for debias not segmentation",
128+
129+
"args": "-l 3"
130+
},
131+
"comment": "OR",
132+
"itk_debias":
133+
{
134+
"comment": "OPTIONAL",
135+
"comment": "same parameters for T1 and T2",
136+
"params": "N4BiasFieldCorrectionImageFilter (SimpleITK python package) used for debias",
137+
"comment": "TODO: not wrapped properly as a node",
138+
"comment": "not really used so far"
103139
}
140+
141+
104142
}
105143
}

0 commit comments

Comments
 (0)