[RF] Pass arbitrary arguments to FitLins, use click instead of Docopt

[adelavega]

This is a major refactor to the CLI, particularly with respect to the argument parsing.

• Drop docopt and use click instead
• Allow arbitrary passthrough of arguments from FitLins, allowing us to not have to validate or document any FitLins arguments
• Simplify code throughout, and remove dependency between Upload and Run/Install

Usage docs are separated based on the sub-command, of which there are three: run, install and upload

The overall usage is:

Usage: neuroscout [OPTIONS] COMMAND [ARGS]...

  Neuroscout-CLI allows you to easily run analyses created on
  https://neuroscout.org.

  Neuroscout downloads the required data, configures outputs, and uses
  FitLins to execute analyses. Results are automatically uploaded to
  NeuroVault, facilitating data sharing.

  Note: If using Docker, remember to map local volumes to the container
  using "-v" (such as OUT_DIR).

  For additional help visit: https://neuroscout.github.io/neuroscout/cli/

Options:
  --help  Show this message and exit.

Commands:
  install  Prepare for analysis.
  run      Run an analysis.
  upload   Upload results.

The main command run is used as follows:

Usage: neuroscout run [OPTIONS] [FITLINS_ARGS]... ANALYSIS_ID OUT_DIR

  Run an analysis.

  Automatically downloads and configure inputs if you haven't already run
  "install". Uploads results to NeuroVault by default.

  This command uses FitLins for analysis execution. Thus, any valid options
  can be passed through to FitLins in [FITLINS_ARGS]

Options:
  --force-upload        Force upload even if a NV collection already exists
  --no-upload           Don't automatically upload results to NeuroVault
  --upload-first-level  Upload first-level image, in addition to group
  --install-dir PATH    Directory to cache input datasets, instead of OUT_DIR
  --help                Show this message and exit.

Importantly, any arguments passed as [FITLINS_ARGS] will be simply passed through to FitLins.

The other commands upload and install are ways to do the analysis pieacemeal rather than having run do everything for you:

e.g.:

Usage: neuroscout install [OPTIONS] ANALYSIS_ID OUT_DIR

  Prepare for analysis.

  Configures the output directory, and downloads the analysis bundle and
  required imaging data.

  Inputs are downloaded to the output directory under `sourcedata`. If you
  run many analyses, you may wish to provide an `--install-dir` where
  datasets can be cached across analyses.

  Note: `run` will automatically call `install` prior to execution.

Options:
  --install-dir PATH  Directory to cache input datasets, instead of OUT_DIR
  --help              Show this message and exit.

and:

Usage: neuroscout upload [OPTIONS] ANALYSIS_ID OUT_DIR

  Upload results.

  This command can be used to upload results given a completed output
  directory.

  Note: `upload` is by `run` after execution by default.

Options:
  --force-upload        Force upload even if a NV collection already exists
  --no-upload           Don't automatically upload results to NeuroVault
  --upload-first-level  Upload first-level image, in addition to group
  --help                Show this message and exit.

Any feedback on this usage pattern? (cc: @effigies) Still need to test it more, and will update the documentation on the main Neuroscout docs for this.

[rwblair]

How does fitlins handle duplicate arguments? The last one seen in the list is valid?

[rwblair]

Does there need to be an analysis level in the fitlins args?

defaults to dataset.

[rwblair]

Fitlins uses argparse, it currently uses the last seen value for an argument if the same argument is specified multiple time.

[rwblair]

Except where nargs='+', like ignore, where all instances will be collected into a list. So overwriting that option completely is not possible as fitlins args are currently built/called here.

[rwblair]

Overall seems good to me.

May be useful to dump fitlins_args alongside original options to exactly what is passed to fitlins or else document options implicitly set by the cli.

[jdkent]

I like click a lot better, this looks nice! I just have a couple questions about how fitlins_args should be handled and how the install command works.

Could you add an example on how a user would pass in arbitrary fitlins arguments?

[jdkent]

should the --model, --ignore, and --derivatives arguments be removed from fitlins_args (if present) or would you want users to be able to overwrite those arguments?

minor typo

Suggested change

	fitlins_args.append(list(self.options['fitlings_args']))
	fitlins_args.append(list(self.options['fitlins_args']))

[jdkent]

coming at this naively, it feels a little weird that when I install I could specify two paths, one for the dataset and one for the bundle, i don't know if this should be split into two different commands so one could install the dataset (only) or install the bundle (only). looks like the current options are:

1. install bundle
2. install bundle + data

For me I was expecting a third option:

1. install bundle
2. install data (new)
3. install both
   That helped conceptually clear up that the install command can install two separate things in two separate directories.

but perhaps this is because I did not read the documentation closely enough.

[adelavega]

@jdkent I think the real answer is you need the analysis bundle to download the data. So currently it's not possible to only download the data. that said, if the bundle is already downloaded, then you could get the data only, so I think i'll add flags for this on the new get command.

[adelavega]

neuroscout get instead of neuroscout install

also add : neuroscout run --fitlins-help

and document default fitlins arguments (i.e. --model)