Skip to content

Argflow Web Portal

The web portal provides a way to visualise explanation graphs that are generated by the Argflow library.

Building

Requirements

Building the project is handled by the build.py script in the repository. To build a production ready Python package, run the following command in the root of the repository:

1
> ./build.py build

This will produce both source and binary packages in the dist/ folder. These can be installed with:

1
> pip install [path to package]

Development

In development, run the following command to setup the development environment.

1
2
3
4
5
6
# Optionally create a virtual environment
> python3 -m venv .venv
> source .venv/bin/activate

# Setup the project
> ./build.py bootstrap

This will install the depencies, and install the project in editable mode so that any changes you make are automatically picked up. It also builds the client and visualisers and copies them into the correct locations.

To run the server, a helpful script is provided in scripts/run-server.sh which runs it with watchgod, to automatically reload it as you make changes to the code.

React client

When working on the client, it is easier to use the React development server rather than building it and copying the files into the python package every time. To run the dev server:

1
2
> cd client
> npm start

This is configured to proxy api requests to the server, assuming that the server is running on port 8000.

Visualisers

You can also enable auto-reloading when working on the visualisers:

1
2
> cd visualisers
> npm run dev

This will rebuild the visualisers any time a change is made to the files, and output the resulting files into the correct place in the python package.

Warning

Make sure to run ./build.py build visualisers any time you pull changes from the remote repository, to make sure that the project is actually using the latest visualisers code. This will help to avoid much pain and misery when changes don't seem to be reflected.

Usage

The portal can be run using the following command:

1
> argflow-ui [ARGS]

In some cases, the argflow-ui executable may not be available in the environment, in which case you can use:

1
> python3 -m argflow_ui [ARGS]

The portal accepts several command line options. You can pass the path to the directory that will act as the current workspace, containing models and explanations that you are working with, like so:

1
> argflow-ui /path/to/workspace

Additionally, the following options are available:

  • --no-launch - Don't automatically launch the web browser. Useful in development when using auto-reloading.
  • --hub-url [URL] - You must supply this to enable features that use the model hub.
  • --generator [PATH] - Path to a python file containing implementations of ExplanationGenerator (detailed below).

Explanation Generation

The portal provides an interface for generating explanations for a particular model, based on provided input and other parameters. However, given the nature of a graphical interface, it is impossible to support all possible configurations that a user may want to generate.

Generating explanations is handled by the abstract ExplanationGenerator class, defined as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
class ExplanationGenerator(ABC):
    @abstractmethod
    def generate(
        self,
        resource_path: str,
        model_name: str,
        model_input: str,
        explanation_name: str,
        chi_value: str,
    ):
        pass

You can write a custom implementation of this to customise the execution. See the default implementation here for an example of how this works.

To inform the portal of your custom generator, pass the path to the Python file containing the implementation using the --generator option. Any classes in the file that inherit from ExplanationGenerator will be detected, and available for selection when generating explanations from the portal.