pstlab/preact_xai_api repository overview

⁠PRE-ACT XAI Module

This repository contains a service to enhance the explainability of a rule-based prediction model developed within the Horizon Europe PRE-ACT project. The services produced within the current repository aim to enrich the interpretability of prediction rules through statistical techniques borrowed from Information Retrieval.

⁠Explanation Approach

The service implements an attribution-based explanation methodology to support the interpretation of prediction rules computed by an AI-based module. The interpretation analyzes the correlations between the conditions appearing in the set of rules activated for each user (local rules) and the outcome of the prediction. The analysis implements an attribution-based explanation methodology by computing the relevance of rules' attributes to predictions.

Specifically, our approach first classifies attributes of the AI module into coherent clusters that correspond to identified factors that influence the risk computation. Given the mapping between the attributes of the model and the clusters the XAI service then elaborates the rules to compute the influence of the factors on the prediction (i.e., the subset of rules activated for a given user input). It is worth noticing that the proposed interpretation methodology is flexible to the clustering. Namely, it is possible to consider different clustering with different levels of details on the set of variables of the prediction model. Such flexibility is well suited to support personalization and tailor the explanation (and thus the interpretation process) to the profile or level of expertise of the user.

The relevance (or influence) of factors (or clusters) is computed according to the Information Retrieval (IR) principles. Specifically, we adapt IR metrics tf (term frequency), idf (inverse document frequency), and tf-idf to determine: (i) the (sub)set of factors determining the prediction of a given user, and; (ii) how such factors influence the prediction in terms of relevance. Since there can be more than one rule activated for each user, we assume that the more a factor is present in the precondition of the rules the higher the relevance (or influence) of that factor to the prediction.

Recalling IR concepts, the objective of tf-idf is to infer the amount of information conveyed by a token to classify the content of documents within a collection. The metric generally assigns higher values to tokens that are not widely used over the collection but are specific to a subset of documents (i.e., tokens that are specific to only a limited number of documents with respect to the collection). The assumption is that tokens that are not common but frequent only in some documents are more specific and thus better capture the content of those documents.

To compute the relevance of factors in a collection of rules (i.e., the set of rules activated for a given user) we adapt IR metrics to the rule-based prediction model considered in the current work. We interpret each rule as a document and each factor as a token that can be present in a document, according to the attributes in the rules' predictions. Differently from standard tf-idf we want to assign larger scores to the factors that appear in many rules within the prediction, we thus use the reversed idf metric to invert the standard interpretation.

⁠Score Computation

The XAI module relies on a clustering of rules' attributes to abstract the syntactic features of the AI model. Each cluster is therefore a set of coherent attributes of the model that appear in the preconditions of the rules. Multiple attributes of the same cluster/factor might appear in the preconditions of a rule. So, considering n_ij as the number of attributes related to the factor i that appear in the rule j, and d_j as the number of attributes in the rule, then

tf_ij = n_ij / d_j

In addition, the tf score is weighted according to the coverage of a rule as follows. I first compute the total coverage (c_all) of all the rules activated for the current patient and then compute the weight w_j by considering its coverage c_j as follows:

w_j = c_j / c_all

therefore the resulting frequency metric is

tf_ij = w_j * (n_ij / d_j)

Differently from the standard idf I want higher scores for factors that are used in many rules. This means that the idf should be directly proportional to the "diffusion" of a factor over the activated rules. Considering s_i as the number of rules that contain the factor i and s_all the total number of rules in the prediction, the "reversed" idf is computed as

idf_i = s_i / s_all

which gives a decimal number in [0, 1]. The tfidf_ij of a certain category i over a rule j is then computed as

tfidf_ij = tf_ij * idf_i

The final relevance score of a factor i considers the average tfidf_ij over all the activated rules j of the prediction.

tfidf_i = avg(tfidf_ij)

The final score returned to the spider-graph is then computed by applying a standard logistic function as follows:

score = 1 / [1 + e^(-x)]

where x = tfidf_i. This keeps the computed scores in the interval [0, 1].

⁠Deployment

The service has been implemented using the Spring boot framework⁠. Running the service would install and execute a Tomcat application server on the standard 8080 port of the host machine.

A technical description of the REST API is available on Swagger Hub⁠

⁠Docker Image

We have released a docker image that is publicly available on the Docker Hub⁠.

To run the Docker image it is necessary to have correctly installed and running Docker on the host machine. Please refer to the (official website)[https://docs.docker.com/⁠] and documentation to find the instructions to download and run Docker on the specific OS used in your host machine.

We assume having installed Docker on a Linux host machine and thus having the Docker Engine correctly configured and running. Execute the instructions inside your host machine by directly logging into it or by remotely connecting to it using secure protocols like SSH.

Download the current document image by issuing the following command on the terminal.

~$ docker pull pstlab/preact_xai_api

This command will automatically download the latest image from the Docker Hub into your host machine. Once the download is finished, you can easily run a container (i.e., a virtual machine instantiating the downloaded image) through the following command.

~$ docker run --name preact_xai_api -p 8181:8080  -td pstlab/preact_xai_api

The parameter --name preact_xai_api assigns the specified name (preact_xai_api) to the container and you can use it to refer to it in future docker commands. The parameter -td pstlab/preact_xai_api runs a container from the specified image (pstlab/preact_xai_api) and keeps it running in the background as a daemon.

The parameter -p 8181:8080 is necessary to map the port of the host machine to the port of the process inside the container. In this case, we are redirecting the request received by the host machine on the port 8181 to the port 8080 of the container. In general, you may specify any mapping between the free ports of the host machine and the 8080 port used by the Tomcat service inside the container.

Now you should see your container instantiated and running through the following command.

~$ docker container ls

You can log into the container (a Linux virtual machine) with the following command.

~$ docker exec -it preact_xai_api /bin/bash

This command executes the bash terminal in the container virtual machine and attaches the TTY of the host machine to the container (option -it). It means you are logged into the virtual machine as a root and can issue commands inside the container. This is necessary to start the XAI service inside the container. Once logged into the container through the above commands, type the following commands inside the container.

~# cd /root/bin
~# ./install_and_run_preact_xai

IMPORTANT: Please note that the above commands (starting with ~#) are typed inside the docker container (i.e., after executing the command docker exec -it preact_xai_api /bin/bash on the host machine).

When the XAI Tomcat application has been launched you should be able to check the log file inside the container:

~# cat /root/log/preact_xai.log

The content of the log file should be something like the following output:

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::               (v2.7.18)

2024-08-07 15:59:03.336  INFO 563 --- [           main] it.cnr.istc.pst.preact.xai.api.XaiAPI    : Starting XaiAPI v1.0-SNAPSHOT using Java 17.0.7 on d119da5728be with PID 563 (/root/PreactXAI/target/xai-1.0-SNAPSHOT.jar started by root in /root)
2024-08-07 15:59:03.339  INFO 563 --- [           main] it.cnr.istc.pst.preact.xai.api.XaiAPI    : No active profile set, falling back to 1 default profile: "default"
2024-08-07 15:59:04.080  INFO 563 --- [           main] trationDelegate$BeanPostProcessorChecker : Bean 'org.springframework.ws.config.annotation.DelegatingWsConfiguration' of type [org.springframework.ws.config.annotation.DelegatingWsConfiguration$$EnhancerBySpringCGLIB$$b25d449d] is not eligible for getting processed by all BeanPostProcessors (for example: not eligible for auto-proxying)
2024-08-07 15:59:04.118  INFO 563 --- [           main] .w.s.a.s.AnnotationActionEndpointMapping : Supporting [WS-Addressing August 2004, WS-Addressing 1.0]
2024-08-07 15:59:04.364  INFO 563 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat initialized with port(s): 8080 (http)
2024-08-07 15:59:04.374  INFO 563 --- [           main] o.apache.catalina.core.StandardService   : Starting service [Tomcat]
2024-08-07 15:59:04.374  INFO 563 --- [           main] org.apache.catalina.core.StandardEngine  : Starting Servlet engine: [Apache Tomcat/9.0.83]
2024-08-07 15:59:04.441  INFO 563 --- [           main] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
2024-08-07 15:59:04.441  INFO 563 --- [           main] w.s.c.ServletWebServerApplicationContext : Root WebApplicationContext: initialization completed in 1037 ms
2024-08-07 15:59:04.907  INFO 563 --- [           main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 8080 (http) with context path ''
2024-08-07 15:59:04.918  INFO 563 --- [           main] it.cnr.istc.pst.preact.xai.api.XaiAPI    : Started XaiAPI in 1.975 seconds (JVM running for 2.32)

If the above steps went successfully you have an XAI service instance correctly running on your host machine and can send requests to its REST API by using the IP address of the host machine (or using localhost if the docker is running locally with respect to the client application). Here is an example of a request you may send through curl (just replace <IP_ADDRESSS> with the actual IP of the host machine).

~$ curl -X POST -H "Content-Type: application/json" http://<IP_ADDRESSS>:8181/xai -d '{"query": "spider-table", "input": [0.1,12.3,22.3],"rules": [{"rule": "WEIGHT>=84.500000 PLANNED_AXILLARY_DISSECTION>=0.500000 ADJUVANT_CHEMOTHERAPY>=0.500000 HEIGHT<166.500000 -> FOLLOW_UP_ARM_LYMPHEDEMA","covering": 0.8,"accuracy": 0.3,"fidelity": 0.6}],"lang": "en_us"}' -v