Skip to content

Commit

Permalink
DOC: Altered CLI option grouping (#2944)
Browse files Browse the repository at this point in the history 
Back when I commenced some work on #2207 (from which I'll need to
familiarise myself with #2913), I started by looking at the CLI and
thinking about what the right interface would be for such a capability
(see eg. #2805, #2806). I immediately found some command-line options
that really felt as though they were in the wrong place. So here I've
separated out the set of CLI changes that I'd generated in the course of
that little experiment.

The git diff is quite unclean, so I've produced the set of options that
would be moved and their corresponding old and new option groups.

| Option | Old option group | New option group |

|-----------------------------|-------------------------------|------------------------------------------------------|
| `--anat-only` | Options to handle performance | Options for performing
only a subset of the workflow |
| `--boilerplate-only` | Options to handle performance | Options for
performing only a subset of the workflow |
| `--md-only-boilerplate` | Options to handle performance | Options for
modulating outputs |
| `--cifti-output` | Surface preprocessing options | Workflow
configuration |
| `--error-on-aroma-warnings` | Options to handle performance | Specific
options for running ICA_AROMA |
| `--verbose` | Options to handle performance | Other options |
| `--me-output-echos` | Workflow configuration | Options for modulating
outputs |
| `--medial-surface-nan` | Workflow configuration | Options for
modulating outputs |
| `--no-submm-recon` | Surface preprocessing options | Specific options
for FreeSurfer processing |
| `--output-layout` | Other options | Options for modulating outputs |
| `--sloppy` | Other options | Options to handle performance |
| `--track-carbon` | Other options | Options for carbon tracking |
| `--country-code` | Other options | Options for carbon tracking |

New option groups:
-   "Options for performing only a subset of the workflow"
-   "Options for modulating outputs"
-   "Options for carbon tracking"

Deleted option groups:
-   "Surface preprocessing options"

In particular, "Options for performing only a subset of the workflow" is
what I was looking for in the context of #2207, where I had initially
added command-line options "`--fmri_withhold`" and "`--fmri_regenerate`"
(the naming of such options should perhaps be discussed in #2913).

Open to modification of proposed changes, or indeed addition of other
changes (since this would be a good opportunity to review placement of
the complete set of command-line options). For instance I'm currently
looking at `[ --output-spaces, --cifti-output, --me-output-echos ]` as a
candidate option group.
  • Loading branch information
@effigies
effigies committed Feb 2, 2023
2 parents 1df7089 + d3f3807 commit fc22100
Show file tree
Hide file tree
Showing 2 changed files with 114 additions and 100 deletions.
9 changes: 7 additions & 2 deletions .maint/contributors.json
View file
Expand Up @@ -141,8 +141,8 @@
"orcid": "0000-0002-5740-9451"
},
{
"affiliation": "Department of Psychology, Harvard University",
"name": "Plunkett, Dillon",
"affiliation": "Department of Psychology, Harvard University",
"name": "Plunkett, Dillon",
"orcid": "0000-0001-7822-6024"
},
{
Expand Down Expand Up @@ -170,6 +170,11 @@
"name": "Sitek, Kevin R.",
"orcid": "0000-0002-2172-5786"
},
{
"Affiliation": "Florey Institute of Neuroscience and Mental Health",
"name": "Smith, Robert E.",
"orcid": "0000-0003-3636-4642"

{
"affiliation": "Center for Lifespan Changes in Brain and Cognition, University of Oslo",
"name": "Sneve, Markus H.",
Expand Down
205 changes: 107 additions & 98 deletions fmriprep/cli/parser.py
View file
Expand Up @@ -144,9 +144,6 @@ def _slice_time_ref(value, parser):
"fMRIPrep (see BIDS-Apps specification).",
)

# optional arguments
parser.add_argument("--version", action="version", version=verstr)

g_bids = parser.add_argument_group("Options for filtering BIDS queries")
g_bids.add_argument(
"--skip_bids_validation",
Expand Down Expand Up @@ -247,34 +244,28 @@ def _slice_time_ref(value, parser):
type=IsFile,
help="Nipype plugin configuration file",
)
g_perfm.add_argument("--anat-only", action="store_true", help="Run anatomical workflows only")
g_perfm.add_argument(
"--boilerplate_only",
"--sloppy",
action="store_true",
default=False,
help="Generate boilerplate only",
help="Use low-quality tools for speed - TESTING ONLY",
)
g_perfm.add_argument(
"--md-only-boilerplate",

g_subset = parser.add_argument_group("Options for performing only a subset of the workflow")
g_subset.add_argument("--anat-only", action="store_true", help="Run anatomical workflows only")
g_subset.add_argument(
"--boilerplate-only",
"--boilerplate_only",
action="store_true",
default=False,
help="Skip generation of HTML and LaTeX formatted citation with pandoc",
help="Generate boilerplate only",
)
g_perfm.add_argument(
"--error-on-aroma-warnings",
g_subset.add_argument(
"--reports-only",
action="store_true",
dest="aroma_err_on_warn",
default=False,
help="Raise an error if ICA_AROMA does not produce sensible output "
"(e.g., if all the components are classified as signal or noise)",
)
g_perfm.add_argument(
"-v",
"--verbose",
dest="verbose_count",
action="count",
default=0,
help="Increases log verbosity for each occurence, debug level is -vvv",
help="Only generate reports, don't run workflows. This will only rerun report "
"aggregation, not reportlet generation for specific nodes.",
)

g_conf = parser.add_argument_group("Workflow configuration")
Expand All @@ -288,11 +279,6 @@ def _slice_time_ref(value, parser):
help="Ignore selected aspects of the input dataset to disable corresponding "
"parts of the workflow (a space delimited list)",
)
g_conf.add_argument(
"--longitudinal",
action="store_true",
help="Treat dataset as longitudinal - may increase runtime",
)
g_conf.add_argument(
"--output-spaces",
nargs="*",
Expand All @@ -311,14 +297,10 @@ def _slice_time_ref(value, parser):
% (currentv.base_version if is_release else "latest"),
)
g_conf.add_argument(
"--me-output-echos",
"--longitudinal",
action="store_true",
default=False,
help="""\
Output individual echo time series with slice, motion and susceptibility correction. \
Useful for further Tedana processing post-fMRIPrep.""",
help="Treat dataset as longitudinal - may increase runtime",
)

g_conf.add_argument(
"--bold2t1w-init",
action="store",
Expand Down Expand Up @@ -350,14 +332,6 @@ def _slice_time_ref(value, parser):
default=None,
help="Do not use boundary-based registration (no goodness-of-fit checks)",
)
g_conf.add_argument(
"--medial-surface-nan",
required=False,
action="store_true",
default=False,
help="Replace medial wall values with NaNs on functional GIFTI files. Only "
"performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).",
)
g_conf.add_argument(
"--slice-time-ref",
required=False,
Expand Down Expand Up @@ -386,7 +360,50 @@ def _slice_time_ref(value, parser):
help="Initialize the random seed for the workflow",
)

# ICA_AROMA options
g_outputs = parser.add_argument_group("Options for modulating outputs")
g_outputs.add_argument(
"--output-layout",
action="store",
default="bids",
choices=("bids", "legacy"),
help="Organization of outputs. \"bids\" (default) places fMRIPrep derivatives "
"directly in the output directory, and defaults to placing FreeSurfer "
"derivatives in <output-dir>/sourcedata/freesurfer. \"legacy\" creates "
"derivative datasets as subdirectories of outputs.",
)
g_outputs.add_argument(
"--me-output-echos",
action="store_true",
default=False,
help="Output individual echo time series with slice, motion and susceptibility "
"correction. Useful for further Tedana processing post-fMRIPrep.",
)
g_outputs.add_argument(
"--medial-surface-nan",
required=False,
action="store_true",
default=False,
help="Replace medial wall values with NaNs on functional GIFTI files. Only "
"performed for GIFTI files mapped to a freesurfer subject (fsaverage or fsnative).",
)
g_outputs.add_argument(
"--md-only-boilerplate",
action="store_true",
default=False,
help="Skip generation of HTML and LaTeX formatted citation with pandoc",
)
g_outputs.add_argument(
"--cifti-output",
nargs="?",
const="91k",
default=False,
choices=("91k", "170k"),
type=str,
help="Output preprocessed BOLD as a CIFTI dense timeseries. "
"Optionally, the number of grayordinate can be specified "
"(default is 91k, which equates to 2mm resolution)",
)

g_aroma = parser.add_argument_group("Specific options for running ICA_AROMA")
g_aroma.add_argument(
"--use-aroma",
Expand All @@ -403,9 +420,16 @@ def _slice_time_ref(value, parser):
help="Exact or maximum number of MELODIC components to estimate "
"(positive = exact, negative = maximum)",
)
g_aroma.add_argument(
"--error-on-aroma-warnings",
action="store_true",
dest="aroma_err_on_warn",
default=False,
help="Raise an error if ICA_AROMA does not produce sensible output "
"(e.g., if all the components are classified as signal or noise)",
)

# Confounds options
g_confounds = parser.add_argument_group("Specific options for generating confounds")
g_confounds = parser.add_argument_group("Options relating to confounds")
g_confounds.add_argument(
"--return-all-components",
dest="regressors_all_comps",
Expand Down Expand Up @@ -436,7 +460,7 @@ def _slice_time_ref(value, parser):
help="Threshold for flagging a frame as an outlier on the basis of standardised DVARS",
)

# ANTs options
# ANTs options
g_ants = parser.add_argument_group("Specific options for ANTs registrations")
g_ants.add_argument(
"--skull-strip-template",
Expand All @@ -462,6 +486,21 @@ def _slice_time_ref(value, parser):
"based on the outcome of a heuristic to check whether the brain is already masked).",
)

# Fieldmap options
g_fmap = parser.add_argument_group("Specific options for handling fieldmaps")
g_fmap.add_argument(
"--fmap-bspline",
action="store_true",
default=False,
help="Fit a B-Spline field using least-squares (experimental)",
)
g_fmap.add_argument(
"--fmap-no-demean",
action="store_false",
default=True,
help="Do not remove median (within mask) from fieldmap",
)

# SyN-unwarp options
g_syn = parser.add_argument_group("Specific options for SyN distortion correction")
g_syn.add_argument(
Expand Down Expand Up @@ -498,44 +537,42 @@ def _slice_time_ref(value, parser):
help="Path to existing FreeSurfer subjects directory to reuse. "
"(default: OUTPUT_DIR/freesurfer)",
)

g_surfs = parser.add_argument_group("Surface preprocessing options")
g_surfs.add_argument(
g_fs.add_argument(
"--no-submm-recon",
action="store_false",
dest="hires",
help="Disable sub-millimeter (hires) reconstruction",
)
# Surface generation xor
g_surfs_xor = g_surfs.add_mutually_exclusive_group()
g_surfs_xor.add_argument(
"--cifti-output",
nargs="?",
const="91k",
default=False,
choices=("91k", "170k"),
type=str,
help="Output preprocessed BOLD as a CIFTI dense timeseries. "
"Optionally, the number of grayordinate can be specified "
"(default is 91k, which equates to 2mm resolution)",
)
g_surfs_xor.add_argument(
g_fs.add_argument(
"--fs-no-reconall",
action="store_false",
dest="run_reconall",
help="Disable FreeSurfer surface preprocessing.",
)

g_carbon = parser.add_argument_group("Options for carbon usage tracking")
g_carbon.add_argument(
"--track-carbon",
action="store_true",
help="Tracks power draws using CodeCarbon package",
)
g_carbon.add_argument(
"--country-code",
action="store",
default="CAN",
type=str,
help="Country ISO code used by carbon trackers",
)

g_other = parser.add_argument_group("Other options")
g_other.add_argument("--version", action="version", version=verstr)
g_other.add_argument(
"--output-layout",
action="store",
default="bids",
choices=("bids", "legacy"),
help="Organization of outputs. bids (default) places fMRIPrep derivatives "
"directly in the output directory, and defaults to placing FreeSurfer "
"derivatives in <output-dir>/sourcedata/freesurfer. legacy creates "
"derivative datasets as subdirectories of outputs.",
"-v",
"--verbose",
dest="verbose_count",
action="count",
default=0,
help="Increases log verbosity for each occurence, debug level is -vvv",
)
g_other.add_argument(
"-w",
Expand All @@ -558,13 +595,6 @@ def _slice_time_ref(value, parser):
default=False,
help="Enable Nipype's resource monitoring to keep track of memory and CPU usage",
)
g_other.add_argument(
"--reports-only",
action="store_true",
default=False,
help="Only generate reports, don't run workflows. This will only rerun report "
"aggregation, not reportlet generation for specific nodes.",
)
g_other.add_argument(
"--config-file",
action="store",
Expand Down Expand Up @@ -601,27 +631,6 @@ def _slice_time_ref(value, parser):
help="Debug mode(s) to enable. 'all' is alias for all available modes.",
)

g_other.add_argument(
"--sloppy",
action="store_true",
default=False,
help="Use low-quality tools for speed - TESTING ONLY",
)

# Carbon tracker options
g_other.add_argument(
"--track-carbon",
action="store_true",
help="Tracks power draws using CodeCarbon package",
)
g_other.add_argument(
"--country-code",
action="store",
default="CAN",
type=str,
help="Country ISO code used by carbon trackers",
)

latest = check_latest()
if latest is not None and currentv < latest:
print(
Expand Down

0 comments on commit fc22100

Please sign in to comment.