Optional arguments in BIDS-Apps

[Guillaume Flandin]

Hi all,

At the moment the command line interface for a BIDS App has three positional arguments and one optional argument (--participant_label). Our submitted manuscript also mentions potential extra arguments: --template_name, --n_cpus and --mem_mb. We also agreed on --version and --help.

Looking at the existing applications, many of us have defined optional extra arguments and I was wondering whether we could agree on using predefined names for arguments that are not unique to a particular pipeline. Here is a list of the currently defined extra arguments (apologies if I forgot some):

OPPNI:
  --run_name

  --task_design

CPAC:
  --pipeline_file

  --n_cpus

  --mem

  --save_working_dir

niak:
  --config_file

mindboggle:
  --n_cpu

HCPPipelines:
  --n_cpus

  --stages

  --license_key

QAP:
  --pipeline_file

  --n_cpus

  --mem

  --save_working_dir

  --report

nipypelines:
  --target

  --subjects_dir

  --target_surfaces

  --vol_fwhm

  --surf_fwhm

  --lowpass_freq

  --highpass_freq

  --work_dir

  --plugin

  --plugin_args

hyperalignment:
  --task

  --run

aa:
  <tasklist>
  <user_customisation>

ndmg:
  --bucket

  --remote_path

FibreDensityAndCrosssection:
  --n_cpus

  -continue

  -force

  -nocleanup

  -tempdir

  -quiet

  -verbose

brainiak-srm:

  --run

  --task

  --preproc

  --mask

  --iterations

  --features

MRtrix3_connectome:

  --parc

  --streamlines

  --continue

  --force

  --nocleanup

  --nthreads/-n_cpus

  --tempdir

  --quiet

  --verbose

  --debug

freesurfer:

  --n_cpus

  --template_name

  --license_key

randomise:

  <model_file>

So maybe we could find some agreements for: --n_cpus , --mem, --run, --task, --quiet, --verbose.

My particular interest here is to specify an optional argument to provide more information about the pipeline to execute. This refers to CPAC's --pipeline_file, niak's --config_file, QAP's --pipeline_file, aa's <tasklist> and randomise's <model_file>. This could be a path to a file (*.xml, *.json, *.yaml, *.m, ...) or a name the application will make sense of. At the moment, for SPM, I have configuration files for each level of analysis: pipeline_participant*.m and pipeline_group*.m.

I am not necessary suggesting to modify the specification of the command line interface and impose argument names but to at least informally agree on a number of optional arguments that are shared across applications.

Best,

Guillaume.

[r.s...@brain.org.au]

Just a comment on my experience / perspective:

The common command-line options between MRtrix3_connectome and FibreDensityAndCrosssection come from the fact that they're both built on the MRtrix3 Python script libraries. This automatically makes a set of standard options available, which mimic those found in the MRtrix3 binary commands. So given that these pipelines may be used by MRtrix3 users outside of a 'BIDS Apps interface', I'd prefer to keep them for consistency. I did however determine that in argparse, with a bit of hacking it's possible to add alternative usages to existing options - I did this to support --n_cpus, which Chris requested as a standardised option at the sprint.

Rob

[Chris Gorgolewski]

Hi Guillaume,

Thank you for compiling this list - this is super useful. I'll open a set of issues to follow up on flags that should be renamed for consistency.

Just to make it very clear each app can have as many extra custom parameters and flags as its developers deem appropriate. We mention this in the supplementary materials although maybe we should make it more clear (currently it stands as "The script can also accept other arguments specific to your pipeline (see --template_name in FreeSurfer App"). 

The --mem_mb and --n_cpus flags are already covered in the manuscript, but we should discuss other proposals.

--task - makes a lot of sense to me, but only applies to task fMRI pipelines

--run - I'm less convinced here since run applies to many modalities (including T1ws). How can we specify which modalities should we restrict with this flag?

--quiet - seems reasonable

--verbose - ditto

As for the config file it's definitely not only a valid but in many occasions crucial flag. I am not quite sure if we need to standardize it across apps since the actual format of the config file will differ from pipeline to pipeline (and it's unlikely we will or even should try to agree on a common format here).

Let me know what do you think.

Best,

Chris

--
You received this message because you are subscribed to the Google Groups "bids-apps-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-apps-dev+unsubscribe@googlegroups.com.
To post to this group, send email to bids-a...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-apps-dev/e9cdc876-2da4-4715-ad4b-f2b1171bfb87%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

[Guillaume Flandin]

Hello,

@Rob: having alternative names for standardised arguments makes a lot of sense.

On 20 October 2016 at 04:24, Chris Gorgolewski <krzysztof....@gmail.com> wrote:

Hi Guillaume,

Thank you for compiling this list - this is super useful. I'll open a set of issues to follow up on flags that should be renamed for consistency.

Just to make it very clear each app can have as many extra custom parameters and flags as its developers deem appropriate. We mention this in the supplementary materials although maybe we should make it more clear (currently it stands as "The script can also accept other arguments specific to your pipeline (see --template_name in FreeSurfer App"). 

I think it's clear enough. It's only when many of us are defining a custom parameter referring to the same thing that we should probably agree on a common name. A great aspect of BIDS-Apps is that it makes it easy to mix and match different software so it probably makes life easier to users if there is an alignment on some arguments names where applicable.

 

The --mem_mb and --n_cpus flags are already covered in the manuscript, but we should discuss other proposals

 

Note that existing apps use --n_cpus, --n_cpu and --mem. I would personally ditch the "_mb" suffix. Also is there a specific reason for everyone to use '_' instead of '-' as separator in long names? GNU programs tend to do differently:

https://www.gnu.org/prep/standards/standards.html#Option-Table

 

--task - makes a lot of sense to me, but only applies to task fMRI pipelines

--run - I'm less convinced here since run applies to many modalities (including T1ws). How can we specify which modalities should we restrict with this flag?

--quiet - seems reasonable

--verbose - ditto

I think it's ok if some of them are modality specific. We could also have --session.

 

As for the config file it's definitely not only a valid but in many occasions crucial flag. I am not quite sure if we need to standardize it across apps since the actual format of the config file will differ from pipeline to pipeline (and it's unlikely we will or even should try to agree on a common format here).

I don't think either we should even try to agree on a common format for a config file. I'm just asking if there is a consensus for its argument name. --config would be the obvious option. So far other apps have used --pipeline_file, --config_file or positional arguments (tasklist, user_customisation, model_file).

Best,

Guillaume.

 

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-apps-dev/CAAQzouNRWZOch6Xj9vUvRZCc_w8g1XGVCB4tkS6Mec7506FDVw%40mail.gmail.com.

[Mihai Capotă]

Hi, everyone.

On Thursday, October 20, 2016 at 5:27:25 AM UTC-7, Guillaume Flandin wrote:

On 20 October 2016 at 04:24, Chris Gorgolewski <krzysztof....@gmail.com> wrote:

 

The --mem_mb and --n_cpus flags are already covered in the manuscript, but we should discuss other proposals

 

Note that existing apps use --n_cpus, --n_cpu and --mem. I would personally ditch the "_mb" suffix. Also is there a specific reason for everyone to use '_' instead of '-' as separator in long names? GNU programs tend to do differently:

https://www.gnu.org/prep/standards/standards.html#Option-Table

I agree that "-" would be a better separator. I guess that "_" comes from its usage in Python names. However, the library most of us are using for parsing arguments, argparse, automatically converts dashes to underscores:
https://docs.python.org/3/library/argparse.html#dest

I also agree with removing the "_mb" suffix and treating the value as bytes.

Regards,
Mihai

[cameron....@gmail.com]

For mem, I like specifically including the units in the flag name, but rather advocate for mem being set to GB instead of MB, and allowing floating point numbers. Since this is the amount of RAM allocated to the job, it is much more likely to be on the order of GB or more, and would be ridiculous to have to type this number in in bytes (1073741824).

[Chris Gorgolewski]

Happy to go with gb instead of mb of that's the consensus. There are not that many apps to change. 

Chris

--

You received this message because you are subscribed to the Google Groups "bids-apps-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bids-apps-dev+unsubscribe@googlegroups.com.
To post to this group, send email to bids-a...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/bids-apps-dev/4da48da3-69c0-49b6-a062-b90360478b80%40googlegroups.com.