Feature: CLI work in progress

[melisande-c]

Description

Adding a CAREamics CLI !

Full functionality will include training, prediction and configuration building from the command line. Currently the prediction command is not implemented.

• What: Added an entrypoint for the careamics command in the pyproject.toml file. Added functions to wrap existing CAREamics functionality that will be called with console commands.
• Why: A CLI will be useful for benchmarking, running on the HPC, pipelines and convenience.
• How:
  • For convenience and readability the CLI has been built using third party package Typer. Typer makes it easy to manage arguments, options, commands and subcommands.
  • The train command creates a CAREamist object from a given config file and then runs the CAREamist.train method on given training and optional validation files.
  • The conf subcommands (care, n2n, n2v) are wrappers for the existing configuration building convenience functions in src/careamics/config/configuration_factory.py. The conf subcommands have the additional functionality of saving the created configuration to a .yaml file.

Changes Made

Added:

• src/careamics/cli/main.py
  • Creates the main typer.Typer object and a function to run it.
  • Contains train and predict commands.
• src/careamics/cli/conf.py
  • Contains configuration builder conf sub typer.Typer object.
  • Contains subcommands care, n2n and n2v.
• src/careamics/cli/__init__.py
• tests/cli/test_main.py
• tests/cli/test_conf.py
• tests/cli/__init__.py

Modified:

• pyproject.toml:
  • added careamics cli entrypoint (under [project.scripts])
  • added typer dependency.

Additional Notes and Examples

The --help flag can be run on all commands and subcommands. This is helpfully managed by Typer.

(careamics) [~]melisande.croft@lin-imganf-m-01$ careamics --help
                                                                                
 Usage: careamics [OPTIONS] COMMAND [ARGS]...                                   
                                                                                
 Run CAREamics algorithms from the command line, including Noise2Void and its   
 many variants and cousins                                                      
                                                                                
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --install-completion          Install completion for the current shell.      │
│ --show-completion             Show completion for the current shell, to copy │
│                               it or customize the installation.              │
│ --help                        Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ conf      Build and save CAREamics configuration files.                      │
│ predict   Create and save predictions from CAREamics models.                 │
│ train     Train CAREamics models.                                            │
╰──────────────────────────────────────────────────────────────────────────────╯

(careamics) [~]melisande.croft@lin-imganf-m-01$ careamics train --help
                                                                                
 Usage: careamics train [OPTIONS] SOURCE                                        
                                                                                
 Train CAREamics models.                                                        
                                                                                
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ *    source      FILE  Path to a configuration file or a trained model.      │
│                        [default: None]                                       │
│                        [required]                                            │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ *  --train-source     -ts                       PATH       Path to the       │
│                                                            training data.    │
│                                                            [default: None]   │
│                                                            [required]        │
│    --train-target     -tt                       PATH       Path to train     │
│                                                            target data.      │
│                                                            [default: None]   │
│    --val-source       -vs                       PATH       Path to           │
│                                                            validation data.  │
│                                                            [default: None]   │
│    --val-target       -vt                       PATH       Path to           │
│                                                            validation target │
│                                                            data.             │
│                                                            [default: None]   │
│    --use-in-memory    -m   --not-in-memory  -M             Use in memory     │
│                                                            dataset if        │
│                                                            possible.         │
│                                                            [default:         │
│                                                            use-in-memory]    │
│    --val-percentage                             FLOAT      Percentage of     │
│                                                            files to use for  │
│                                                            validation.       │
│                                                            [default: 0.1]    │
│    --val-minimum-sp…                            INTEGER    Minimum number of │
│                                                            files to use for  │
│                                                            validation,       │
│                                                            [default: 1]      │
│    --work-dir         -wd                       DIRECTORY  Path to working   │
│                                                            directory in      │
│                                                            which to save     │
│                                                            checkpoints and   │
│                                                            logs              │
│                                                            [default: None]   │
│    --help                                                  Show this message │
│                                                            and exit.         │
╰──────────────────────────────────────────────────────────────────────────────╯

As you can see from the help output above, I have decided on the design choice, for the train command, the the config file is an argument and everything else is passed as an option. So to train with a <CONFIG FILE> and <TRAIN SOURCE> the syntax would be:

careamics train <CONFIG FILE> -ts <TRAIN SOURCE>

---

• Code builds and passes tests locally, including doctests
• New tests have been added (for bug fixes/features)
• Pre-commit passes
• PR to the documentation exists (for bug fixes / features)

[jdeschamps]

I left a few notes!

I can't wait to try it!!

We should also reproduce create examples in the documentation (once the CLI is fully ready) following some of the example notebooks.

[codecov]

Codecov Report

Attention: Patch coverage is 93.10345% with 4 lines in your changes missing coverage. Please review.

Project coverage is 91.36%. Comparing base (acb456f) to head (54132fa).
Report is 7 commits behind head on main.

Files	Patch %	Lines
src/careamics/cli/conf.py	92.85%	3 Missing ⚠️
src/careamics/cli/main.py	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #130      +/-   ##
==========================================
+ Coverage   91.30%   91.36%   +0.06%     
==========================================
  Files         104      108       +4     
  Lines        2633     2698      +65     
==========================================
+ Hits         2404     2465      +61     
- Misses        229      233       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[melisande-c]

Next steps:

• Work out how to pass model params. Alternatively if a user doesn't want to use defaults they have to use a configuration file.
• Work out how to pass transform choices. Or again have to use config file.
• Write predict command.