Explanatory Agent

Back to Home

Description

The explanatory autonomous relay agent (xARA) utilizes a case-based reasoning (CBR) approach to execute ARS queries by obtaining results from multiple knowledge providers (KPs) and relies on natural language understanding models to seek explanations in the biomedical literature to rank KP’s results.
The xARA executes five steps to answer queries: Query analysis, KP selection, Ranking results, Grouping results, and Response.

The current Explanatory Agent Workflow consists of:

• Analogical reasoning engine
• Ranking results through explanations
  • Explanatory evidence via NLU model
  • Explanatory evidence via other methods
• User-centered working group
• Translator Quality Management System (QMS)

Team Contact:

• Rosina Weber ([email protected])
• Eugene Hinderer ([email protected])

User Guide

• TRAPI Interface

To interact with the web service, you may send queries directly or via the SmartAPI Swagger interface. Please refer to our page on the SmartAPI Registry for the latest URL. The Swagger interface contains a sample query you may send to review our response.

Knowledge Providers Accessed

• Genetic Knowledge Provider
• Molecular Data Knowledge Provider
• Clinical Data Knowledge Provider
  • Clinical Open Health Data
  • OpenPredict API
  • Translator Knowledge Collaboratory API
• Multiomics Knowledge Provider
  • Wellness Knowledge Provider API
  • Drug Response Knowledge Provider API
  • TCGA Mutation Knowledge Provider API
  • Clinical Risk Knowledge Provider API

Issue Support

To declare an issue:

• Browse to: https://github.com/NCATSTranslator/Explanatory-Agent/issues
• Create a new issue by selecting the "New issue" button.
• Populate the form displayed. Please enter a concise description of the issue. Include test data if available.

Source Code

• Jupyter Notebook Implementation
• Explanatory Agent

Deployment Pipeline

The Explanatory Agent web service has been tested on Ubuntu 20.04. Any other Ubuntu versions or operating systems are unsupported. The following software is required to be installed before proceeding:

• Python 3.8
• Pipenv
• PostgreSQL
• Docker

Once the above software is installed on your system, perform the following steps:

• Configure the PostgreSQL database:
  • Create a database named xARA.
    • Ensure a user is present with read and write permissions. By default, a user named postgres will be created when the software is installed.
  • Run run.sh to start the Docker container for the xARA web service. If you have created a non-default user in step 1b, you must set environment variables before running this step. Refer to the Dockerfile in the base directory for environment variable names.
  • Run the ETL process to populate the PostgreSQL database:
    • Open a command line terminal at xARA_ETL/
    • Configure a Python Pip environment with the command pipenv install –deploy
      • Run src/modMain.py to populate the xARA database.
  • Connect to https://localhost and from within the Swagger UI run the example for the query/ endpoint.
  • Once you receive a 200 response from the example query your xARA web service is running and ready to accept queries.

External Documentation

• Explanatory Agent System Design