Skip to content

Commit 34552e9

Browse files
mgxdmgxd
authored
Merge pull request #65 from mgxd/doc/usage
MAINT: Add more helpful documentation, purge debugging arguments
2 parents bfe9bcb + ad28045 commit 34552e9

File tree

5 files changed

+299
-22
lines changed

5 files changed

+299
-22
lines changed

‎README.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,3 +4,300 @@
44
</p>
55

66
*NiBabies* is an extension of [fMRIPrep](https://fmriprep.org/en/stable/) designed and tested for infants 0-2 years old. *NiBabies* offers structural and functional MRI preprocessing.
7+
8+
----
9+
### Requirements
10+
11+
Given its extensive dependencies, the easiest way to get up and running with *NiBabies* is by using the available Docker / Singularity containers.
12+
13+
If you insist on installing this tool locally, you can use the [Dockerfile](./Dockerfile) as a guide.
14+
15+
16+
### Usage
17+
18+
*NiBabies* follow the [BIDS App Specifications](http://bids-apps.neuroimaging.io/about/), meaning you only need to provide three positional arguments:
19+
20+
- **bids_dir** - the root folder of a BIDS valid dataset.
21+
- **output_dir** - folder to store outputs and reports.
22+
- **level** - processing stage to be run, currently can only be `participant`.
23+
24+
25+
However, as infant brains can vastly differ depending on age, providing the following arguments is highly recommended:
26+
27+
- **--age-months** - participant age in months
28+
- **--segmentation-dir** - directory containing pre-labeled segmentations to use for Joint Label Fusion.
29+
30+
<details>
31+
<summary>Extensive argument list</summary>
32+
33+
```
34+
usage: nibabies [-h] [--version] [--skip_bids_validation]
35+
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
36+
[-t TASK_ID] [--echo-idx ECHO_IDX] [--bids-filter-file FILE]
37+
[--anat-derivatives PATH] [--bids-database-dir PATH]
38+
[--nprocs NPROCS] [--omp-nthreads OMP_NTHREADS]
39+
[--mem MEMORY_GB] [--low-mem] [--use-plugin FILE]
40+
[--anat-only] [--boilerplate_only] [--md-only-boilerplate]
41+
[--error-on-aroma-warnings] [-v]
42+
[--ignore {fieldmaps,slicetiming,sbref,t2w,flair} [{fieldmaps,slicetiming,sbref,t2w,flair} ...]]
43+
[--longitudinal]
44+
[--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]]
45+
[--bold2t1w-init {register,header}] [--bold2t1w-dof {6,9,12}]
46+
[--force-bbr] [--force-no-bbr] [--medial-surface-nan]
47+
[--dummy-scans DUMMY_SCANS] [--random-seed _RANDOM_SEED]
48+
[--use-aroma]
49+
[--aroma-melodic-dimensionality AROMA_MELODIC_DIM]
50+
[--return-all-components]
51+
[--fd-spike-threshold REGRESSORS_FD_TH]
52+
[--dvars-spike-threshold REGRESSORS_DVARS_TH]
53+
[--skull-strip-template SKULL_STRIP_TEMPLATE]
54+
[--skull-strip-fixed-seed]
55+
[--skull-strip-t1w {auto,skip,force}] [--fmap-bspline]
56+
[--fmap-no-demean] [--use-syn-sdc] [--force-syn]
57+
[--fs-license-file FILE] [--fs-subjects-dir PATH]
58+
[--no-submm-recon] [--cifti-output [{91k,170k}] |
59+
--fs-no-reconall] [--output-layout {bids,legacy}]
60+
[-w WORK_DIR] [--clean-workdir] [--resource-monitor]
61+
[--reports-only] [--config-file FILE] [--write-graph]
62+
[--stop-on-first-crash] [--notrack]
63+
[--debug {compcor,registration,fieldmaps,all} [{compcor,registration,fieldmaps,all} ...]]
64+
[--sloppy]
65+
[--age-months AGE_MONTHS]
66+
[--segmentation-atlases-dir SEGMENTATION_ATLASES_DIR]
67+
[--ants-affine-init {random,search}]
68+
bids_dir output_dir {participant}
69+
70+
NiBabies: Preprocessing workflows for infants (version 0.1.0)
71+
72+
positional arguments:
73+
bids_dir the root folder of a BIDS valid dataset (sub-XXXXX
74+
folders should be found at the top level in this
75+
folder).
76+
output_dir the output path for the outcomes of preprocessing and
77+
visual reports
78+
{participant} processing stage to be run, only "participant" in the
79+
case of NiBabies (see BIDS-Apps specification).
80+
81+
optional arguments:
82+
-h, --help show this help message and exit
83+
--version show program's version number and exit
84+
85+
Options for filtering BIDS queries:
86+
--skip_bids_validation, --skip-bids-validation
87+
assume the input dataset is BIDS compliant and skip
88+
the validation (default: False)
89+
--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
90+
a space delimited list of participant identifiers or a
91+
single identifier (the sub- prefix can be removed)
92+
(default: None)
93+
-t TASK_ID, --task-id TASK_ID
94+
select a specific task to be processed (default: None)
95+
--echo-idx ECHO_IDX select a specific echo to be processed in a multiecho
96+
series (default: None)
97+
--bids-filter-file FILE
98+
a JSON file describing custom BIDS input filters using
99+
PyBIDS. For further details, please check out
100+
https://fmriprep.readthedocs.io/en/0.0.3/faq.html#how-
101+
do-I-select-only-certain-files-to-be-input-to-fMRIPrep
102+
(default: None)
103+
--anat-derivatives PATH
104+
Reuse the anatomical derivatives from another NiBabies
105+
run or calculated with an alternative processing tool
106+
(NOT RECOMMENDED). (default: None)
107+
--bids-database-dir PATH
108+
Path to an existing PyBIDS database folder, for faster
109+
indexing (especially useful for large datasets).
110+
(default: None)
111+
112+
Options to handle performance:
113+
--nprocs NPROCS, --nthreads NPROCS, --n_cpus NPROCS, --n-cpus NPROCS
114+
maximum number of threads across all processes
115+
(default: None)
116+
--omp-nthreads OMP_NTHREADS
117+
maximum number of threads per-process (default: None)
118+
--mem MEMORY_GB, --mem_mb MEMORY_GB, --mem-mb MEMORY_GB
119+
upper bound memory limit for NiBabies processes
120+
(default: None)
121+
--low-mem attempt to reduce memory usage (will increase disk
122+
usage in working directory) (default: False)
123+
--use-plugin FILE, --nipype-plugin-file FILE
124+
nipype plugin configuration file (default: None)
125+
--anat-only run anatomical workflows only (default: False)
126+
--boilerplate_only generate boilerplate only (default: False)
127+
--md-only-boilerplate
128+
skip generation of HTML and LaTeX formatted citation
129+
with pandoc (default: False)
130+
--error-on-aroma-warnings
131+
Raise an error if ICA_AROMA does not produce sensible
132+
output (e.g., if all the components are classified as
133+
signal or noise) (default: False)
134+
-v, --verbose increases log verbosity for each occurence, debug
135+
level is -vvv (default: 0)
136+
137+
Workflow configuration:
138+
--ignore {fieldmaps,slicetiming,sbref,t2w,flair} [{fieldmaps,slicetiming,sbref,t2w,flair} ...]
139+
ignore selected aspects of the input dataset to
140+
disable corresponding parts of the workflow (a space
141+
delimited list) (default: [])
142+
--longitudinal treat dataset as longitudinal - may increase runtime
143+
(default: False)
144+
--output-spaces [OUTPUT_SPACES [OUTPUT_SPACES ...]]
145+
Standard and non-standard spaces to resample
146+
anatomical and functional images to. Standard spaces
147+
may be specified by the form
148+
``<SPACE>[:cohort-<label>][:res-<resolution>][...]``,
149+
where ``<SPACE>`` is a keyword designating a spatial
150+
reference, and may be followed by optional, colon-
151+
separated parameters. Non-standard spaces imply
152+
specific orientations and sampling grids. Important to
153+
note, the ``res-*`` modifier does not define the
154+
resolution used for the spatial normalization. To
155+
generate no BOLD outputs, use this option without
156+
specifying any spatial references. For further
157+
details, please check out
158+
https://fmriprep.readthedocs.io/en/0.0.3/spaces.html
159+
(default: None)
160+
--bold2t1w-init {register,header}
161+
Either "register" (the default) to initialize volumes
162+
at center or "header" to use the header information
163+
when coregistering BOLD to T1w images. (default:
164+
register)
165+
--bold2t1w-dof {6,9,12}
166+
Degrees of freedom when registering BOLD to T1w
167+
images. 6 degrees (rotation and translation) are used
168+
by default. (default: 6)
169+
--force-bbr Always use boundary-based registration (no goodness-
170+
of-fit checks) (default: None)
171+
--force-no-bbr Do not use boundary-based registration (no goodness-
172+
of-fit checks) (default: None)
173+
--medial-surface-nan Replace medial wall values with NaNs on functional
174+
GIFTI files. Only performed for GIFTI files mapped to
175+
a freesurfer subject (fsaverage or fsnative).
176+
(default: False)
177+
--dummy-scans DUMMY_SCANS
178+
Number of non steady state volumes. (default: None)
179+
--random-seed _RANDOM_SEED
180+
Initialize the random seed for the workflow (default:
181+
None)
182+
183+
Specific options for running ICA_AROMA:
184+
--use-aroma add ICA_AROMA to your preprocessing stream (default:
185+
False)
186+
--aroma-melodic-dimensionality AROMA_MELODIC_DIM
187+
Exact or maximum number of MELODIC components to
188+
estimate (positive = exact, negative = maximum)
189+
(default: -200)
190+
191+
Specific options for estimating confounds:
192+
--return-all-components
193+
Include all components estimated in CompCor
194+
decomposition in the confounds file instead of only
195+
the components sufficient to explain 50 percent of
196+
BOLD variance in each CompCor mask (default: False)
197+
--fd-spike-threshold REGRESSORS_FD_TH
198+
Threshold for flagging a frame as an outlier on the
199+
basis of framewise displacement (default: 0.5)
200+
--dvars-spike-threshold REGRESSORS_DVARS_TH
201+
Threshold for flagging a frame as an outlier on the
202+
basis of standardised DVARS (default: 1.5)
203+
204+
Specific options for ANTs registrations:
205+
--skull-strip-template SKULL_STRIP_TEMPLATE
206+
select a template for skull-stripping with
207+
antsBrainExtraction (default: UNCInfant:cohort-1)
208+
--skull-strip-fixed-seed
209+
do not use a random seed for skull-stripping - will
210+
ensure run-to-run replicability when used with --omp-
211+
nthreads 1 and matching --random-seed <int> (default:
212+
False)
213+
--skull-strip-t1w {auto,skip,force}
214+
determiner for T1-weighted skull stripping ('force'
215+
ensures skull stripping, 'skip' ignores skull
216+
stripping, and 'auto' applies brain extraction based
217+
on the outcome of a heuristic to check whether the
218+
brain is already masked). (default: force)
219+
220+
Specific options for handling fieldmaps:
221+
--fmap-bspline fit a B-Spline field using least-squares
222+
(experimental) (default: False)
223+
--fmap-no-demean do not remove median (within mask) from fieldmap
224+
(default: True)
225+
226+
Specific options for SyN distortion correction:
227+
--use-syn-sdc EXPERIMENTAL: Use fieldmap-free distortion correction
228+
(default: False)
229+
--force-syn EXPERIMENTAL/TEMPORARY: Use SyN correction in addition
230+
to fieldmap correction, if available (default: False)
231+
232+
Specific options for FreeSurfer preprocessing:
233+
--fs-license-file FILE
234+
Path to FreeSurfer license key file. Get it (for free)
235+
by registering at
236+
https://surfer.nmr.mgh.harvard.edu/registration.html
237+
(default: None)
238+
--fs-subjects-dir PATH
239+
Path to existing FreeSurfer subjects directory to
240+
reuse. (default: OUTPUT_DIR/freesurfer) (default:
241+
None)
242+
243+
Surface preprocessing options:
244+
--no-submm-recon disable sub-millimeter (hires) reconstruction
245+
(default: True)
246+
--cifti-output [{91k,170k}]
247+
output preprocessed BOLD as a CIFTI dense timeseries.
248+
Optionally, the number of grayordinate can be
249+
specified (default is 91k, which equates to 2mm
250+
resolution) (default: False)
251+
--fs-no-reconall disable FreeSurfer surface preprocessing. (default:
252+
True)
253+
254+
Other options:
255+
--output-layout {bids,legacy}
256+
Organization of outputs. legacy (default) creates
257+
derivative datasets as subdirectories of outputs. bids
258+
places NiBabies derivatives directly in the output
259+
directory, and defaults to placing FreeSurfer
260+
derivatives in <output-dir>/sourcedata/freesurfer.
261+
(default: legacy)
262+
-w WORK_DIR, --work-dir WORK_DIR
263+
path where intermediate results should be stored
264+
(default: /tmp/work)
265+
--clean-workdir Clears working directory of contents. Use of this flag
266+
is notrecommended when running concurrent processes of
267+
NiBabies. (default: False)
268+
--resource-monitor enable Nipype's resource monitoring to keep track of
269+
memory and CPU usage (default: False)
270+
--reports-only only generate reports, don't run workflows. This will
271+
only rerun report aggregation, not reportlet
272+
generation for specific nodes. (default: False)
273+
--config-file FILE Use pre-generated configuration file. Values in file
274+
will be overridden by command-line arguments.
275+
(default: None)
276+
--write-graph Write workflow graph. (default: False)
277+
--stop-on-first-crash
278+
Force stopping on first crash, even if a work
279+
directory was specified. (default: False)
280+
--notrack Opt-out of sending tracking information of this run to
281+
the NiBabies developers. This information helps to
282+
improve NiBabies and provides an indicator of real
283+
world usage crucial for obtaining funding. (default:
284+
False)
285+
--debug {compcor,registration,fieldmaps,all} [{compcor,registration,fieldmaps,all} ...]
286+
Debug mode(s) to enable. 'all' is alias for all
287+
available modes. (default: None)
288+
--sloppy Use low-quality tools for speed - TESTING ONLY
289+
(default: False)
290+
291+
NiBabies specific options:
292+
--age-months AGE_MONTHS
293+
Age in months (default: None)
294+
--segmentation-atlases-dir SEGMENTATION_ATLASES_DIR
295+
Directory containing precalculated segmentations to
296+
use for JointLabelFusion. (default: None)
297+
```
298+
299+
</details>
300+
301+
### Outputs
302+
303+
TODO - Refer to [fMRIPrep's outputs](https://fmriprep.org/en/20.2.1/outputs.html) for now.

‎nibabies/cli/parser.py‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -584,12 +584,6 @@ def _bids_filter(value):
584584

585585
# Add new options
586586
g_baby = parser.add_argument_group("NiBabies specific options")
587-
g_baby.add_argument(
588-
"--anat-modality",
589-
default="t1w",
590-
choices=("t1w", "t2w"),
591-
help="Preferred modality to use for anatomical processing",
592-
)
593587
g_baby.add_argument(
594588
"--age-months",
595589
dest="age_months",
@@ -600,11 +594,6 @@ def _bids_filter(value):
600594
"--segmentation-atlases-dir",
601595
help="Directory containing precalculated segmentations to use for JointLabelFusion."
602596
)
603-
g_baby.add_argument(
604-
"--ants-affine-init",
605-
choices=("random", "search"),
606-
help="TESTING: Customize parameters for ants AI initialization."
607-
)
608597
return parser
609598

610599

‎nibabies/config.py‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -491,10 +491,6 @@ class workflow(_Config):
491491
"""Age (in months)"""
492492
anat_only = False
493493
"""Execute the anatomical preprocessing only."""
494-
anat_modality = "t1w"
495-
"""Structural MRI modality"""
496-
ants_affine_init = None
497-
"""Customize ants affine initialization"""
498494
aroma_err_on_warn = None
499495
"""Cast AROMA warnings to errors."""
500496
aroma_melodic_dim = None

‎nibabies/workflows/anatomical/brain_extraction.py‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -257,11 +257,6 @@ def init_infant_brain_extraction_wf(
257257
verbose=True,
258258
)
259259

260-
if ants_affine_init == "random":
261-
ants_kwargs["metric"] = ("Mattes", 32, "Random", 0.2)
262-
if ants_affine_init == "search":
263-
ants_kwargs["search_grid"] = (20, (20, 40, 40))
264-
265260
init_aff = pe.Node(
266261
AI(**ants_kwargs),
267262
name="init_aff",

‎nibabies/workflows/base.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ def init_single_subject_wf(subject_id):
152152

153153
anat_only = config.workflow.anat_only
154154
anat_derivatives = config.execution.anat_derivatives
155-
anat_modality = config.workflow.anat_modality
155+
anat_modality = "t1w" if subject_data["t1w"] else "t2w"
156156
spaces = config.workflow.spaces
157157
# Make sure we always go through these two checks
158158
if not anat_only and not subject_data["bold"]:
@@ -286,7 +286,7 @@ def init_single_subject_wf(subject_id):
286286

287287
# Preprocessing of anatomical (includes registration to UNCInfant)
288288
anat_preproc_wf = init_infant_anat_wf(
289-
ants_affine_init=config.workflow.ants_affine_init or True,
289+
ants_affine_init=True,
290290
age_months=config.workflow.age_months,
291291
anat_modality=anat_modality,
292292
t1w=subject_data["t1w"],

0 commit comments

Comments
 (0)