Interactive user experience

[ghisvail]

Context

Clinica is designed for use by both technical and non-technical audiences. For the former, we have been improving our command line interface (CLI) to become more consistent, better documented and more pleasant to use as a result.

For non-technical users however, I believe further work is required to make Clinica simpler to interact with. As of today, discovering Clinica requires reading a large chunk of documentation, complemented by pages of contextual help in the CLI. From the perpsective of a user completely foreign to Clinica, this is a heavy investment simply to assess whether the tool is worth sticking with long term. A well-designed interactive user experience would be a significant leap forward.

Proposal

Design a proper interactive mode for Clinica. Put interactivity at the forefront of Clinica's UX design.

• Interactive mode could guide users through choosing the right command to use.

  Typing clinica would prompt for a pick between available commands (convert, run, ...)

  Typing clinica convert would prompt for the dataset to convert (adni, habs, oasis, ...)

• Interactive mode could help users choose appropriate values for CLI parameters.

  Typing clinica convert adni-to-bids would prompt for the source data directory, the target BIDS directory and whether optional values are to be specified if any. Path-like parameters could be selected using a file selector instead of being typed as text, which is less prone to errors.

• Interactive mode could be opt-in or opt-out with --interactive/--no-interactive and a clinica specific envvar CLINICA_INTERACTIVE / CLINICA_NO_INTERACTIVE.

There are probably more ideas to develop.

[ghisvail]

In the interest of maintenance, all the code dealing with interactivity should happen at the beginning of the data flow. Meaning once a converter or a pipeline starts its execution, no further interactive prompt should be happening.

[mdiazmel]

At some point of Clinica, the "interactive mode guiding users to chose the right command" was the main argument to activate shell completion proposed by argcomplete. We need maybe to verify that this functionality is still available (I'm afraid that something got broken after the migration of the command line to Click).

Interactive mode could be opt-in or opt-out with --interactive/--no-interactive and a clinica specific envvar CLINICA_INTERACTIVE / CLINICA_NO_INTERACTIVE.

We must pay special attention to the --no-interactive mode because it should be the default mode when running in particular environments (I'm thinking in computer clusters, for example).

[ghisvail]

We need maybe to verify that this functionality is still available (I'm afraid that something got broken after the migration of the command line to Click).

Still available, nothing is broken.

the "interactive mode guiding users to chose the right command" was the main argument to activate shell completion [...]

I'd argue shell completion is quite different from an interactive user experience.

Besides, based on past experience, using tab to summon autocompletion is something very few developers actually know about, so for non-developers that's a no go.

[ghisvail]

We must pay special attention to the --no-interactive mode because it should be the default mode when running in particular environments (I'm thinking in computer clusters, for example).

Agreed, that's why most tools supporting interactivity implement both a CLI option and an envvar in case the command is wrapped downstream. A good example is apt with DEBIAN_FRONTEND="noninteractive" which bypasses confirmation prompts.

[omar-rifai]

We need maybe to verify that this functionality is still available (I'm afraid that something got broken after the migration of the command line to Click).

Still available, nothing is broken.

That's a nice feature already but I'm afraid a lot of users might miss it since it requires an additional step. Maybe we can try integrating this in the install procedure so that it is added by default