.. _tutorial_CLI_overview:

Tutorial: Overview of the Command Line Interface (CLI)
======================================================

The ``XAI`` library comes with its own CLI tool that allows you to execute XAI
algorithms on your desired models and images directly from the command shell.
Note that for the :ref:`v0.1.0 release<release_notes>`, Grad-CAM is the only XAI
algorithm supported in the ``XAI`` library and hence the CLI tool only executes
Grad-CAM.

This tutorial serves as an overview of the CLI tool and its arguments. For a
step-by-step guide on using the CLI tool for the Food-Non-Food (FNF) and
Food Scoring (FS) models, refer to the following:

- :ref:`Method 2: Using the CLI tool for FNF<tutorial_gradcam_fnf_method2>`
- :ref:`Method 2: Using the CLI tool for FS<tutorial_gradcam_fs_method2>`

-----

Explanation of Arguments
------------------------

Invoke the XAI tool on the command line through the ``XAI`` executable. Online
``--help`` is available on the command line. Enter the following to list 
commands or options for a given command with a short description.

.. code::

    $ XAI --help

    usage: XAI [-h] [--batch_size BATCH_SIZE] [--relu_attributions]
           [--return_metadata] [--plot_gradcam]
           {FNF,FS} path_to_csv pretrained_weights_folder output_folder
           target_layer_name
    
    Performs Grad-CAM for FoodDX.
    
    positional arguments:
    {FNF,FS}              The use case for Grad-CAM. Either 'FNF' (Food-Non-
                          Food) or 'FS' (Food Scoring).
    path_to_csv           The absolute or relative path to the 'data.csv' file.
    pretrained_weights_folder
                          The absolute or relative path to the folder that
                          contains the checkpoint (.pth) file(s). These .pth
                          files should contain the pretrained weights to be
                          loaded into the model. For Food-Non-Food (FNF), there
                          should be only 1 .pth file in the folder. For Food
                          Scoring (FS), there should be 3 .pth files in the
                          folder, one for each model.
    output_folder         The absolute or relative path to save the Grad-CAM
                          outputs to. E.g. '/save/outputs/to/this/folder'.
    target_layer_name     The name of the layer to use when performing Grad-CAM.

    optional arguments:
    -h, --help            show this help message and exit
    --batch_size BATCH_SIZE
                          The batch size to split the dataset into. Default=10.
    --relu_attributions   Indicates whether to apply a ReLU operation on the
                          final attribution, returning only non-negative
                          attributions. Setting this flag to True matches the
                          original GradCAM algorithm, otherwise, by default,
                          both positive and negative attributions are returned.
    --return_metadata     If True, metadata corresponding to the input image
                          along with the Grad-CAM attribution maps will be
                          generated. If False, NaN values will be generated in
                          place of each metadata instead. Default=False.
    --plot_gradcam        If this optional argument is called, the resulting
                          Grad-CAM arrays will be plotted and saved as .png
                          files in the folder specified in `save_output_path`.
                          By default, this optional argument is not called, i.e.
                          set to False


Boolean Arguments
^^^^^^^^^^^^^^^^^

The following are optional boolean arguments:

- ``--relu_attributions``
- ``--return_metadata``
- ``--plot_gradcam``

Boolean arguments are set to ``False`` by default and have two forms:

- ``--this-option`` sets the argument to ``True``
- Not including the argument in the command sets it to ``False``

-----

General CLI Tool Workflow
-------------------------

The general workflow of the CLI tool is as such:

1. Specify whether you are performing Grad-CAM on the FNF or FS model using the
   ``{FNF,FS}`` argument.
2. Loads the model together with the pretrained weights.
   
   - In :ref:`v0.1.0<release_notes>`, the model is loaded from a class that
     contains the FNF and FS models. i.e., this is the only model that is
     available for use if you use the CLI tool.
   - The pretrained weights are loaded from the given folder in
     ``pretrained_weights_folder``. The CLI tool will check that only 1
     checkpoint file is given if you are performing Grad-CAM for FNF and only 3
     checkpoint files are given if you are performing Grad-CAM for FS.

3. Loads the ``.csv`` file in ``path_to_csv`` and creates a custom dataset using
   the images listed in the ``.csv`` file.
4. Performs the Grad-CAM on the model and images and saves the output in the
   ``output_folder``.

For specifics on how to use the CLI tool for FNF and FS models, refer to the
following:

- :ref:`Method 2: Using the CLI tool for FNF<tutorial_gradcam_fnf_method2>`
- :ref:`Method 2: Using the CLI tool for FS<tutorial_gradcam_fs_method2>`