Skip to content

ARAGORN

Jump to bottom Edit New page
cbizon edited this page May 6, 2021 · 54 revisions

Back to Home

ARAGORN Knowledge Provider Wiki Page

Autonomous Relay Agent for Generation Of Ranked Networks (ARAGORN)

A Translator ARA to query Knowledge Providers (KPs) and synthesize highly ranked answers relevant to user-specified questions.

  • Operates in a federated knowledge environment.
  • Bridges the precision mismatch between data specificity in KPs and more abstract levels of user queries.
  • Generalizes answer ranking.
  • Normalizes data to use preferred and equivalent identifiers.

Team Contact:

Patrick Wang ( patrick@covar.com )

TODO: Disclose more team members?

ARAGORN Tool Description

ARAGORN provides unified access to multiple operations(see glossary and the Operations repo) including fill/bind/complete (Strider), Merge Answers (Answer Coalescence), Edge Weighting, and Result Scoring (Aragorn Ranker). Currently, ARAGORN composes these operations into a fixed workflow, but the individual components are available as their own TRAPI endpoints.

The current ARAGORN workflow consists of:

  • Strider takes a TRAPI query graph, and calls distributed KPs to construct a TRAPI KG and results.
  • AnswerCoalescence finds and adds to the TRAPI message new answers by combining similar or related answers from Strider.
  • AragornRanker adds literature co-occurrence edges to the graph, adds a weight to each edge binding, and scores each result based on these weights.

Technical user guide

The ARAGORN service requires that you submit your query in a TRAPI formatted query graph (JSON) request.

TODO: More details on what each component does is most likely needed here.

Steps to create your own query

The creation of a ARAGORN starts with conceptually defining two entities or concepts that may share an interesting relationship.

The process is as follows:

  • Specify a CURIE(s) (a Compact URI such as MONDO:0004979 or MONDO:0004980) that has a category (e.g. biolink:Disease).
  • Specify a Concept(s) (a biolink entity such as biolink:ChemicalSubstance or biolink:AnatomicalEntity) that will be associated to the CURIE(s).
  • Specify a biolink predicate to discover links between the CURIE(s) and Concept(s) (e.g. biolink:correlated_with, etc).
  • Create a TRAPI compliant query graph in JSON format that declares the parameters noted above.

This query can be plainly stated as: "What chemical substances or anatomical entities are correlated with asthma (disease code MONDO:0004949) or atopic eczema (MONDO:0004980)"

This example shows the resultant a TRAPI query message JSON that uses the example parameters shown above.

{
   "message": {
    "query_graph": {
      "nodes": {
        "n0": {
          "ids": ["MONDO:0004979", "MONDO:0004980"],
          "category": "biolink:Disease"
        },
        "n1": {
          "categories": ["biolink:ChemicalSubstance", "biolink:AnatomicalEntity"]
        }
      },
      "edges": {
        "e01": {
          "subject": "n0",
          "object": "n1",
          "predicate": "biolink:correlated_with"
        }
      }
    }
  } 
}

How to submit your query and get results

The ARAGORN user interface accepts a TRAPI compliant message query. For more information on the TRAPI standard please refer to https://github.com/NCATSTranslator/ReasonerAPI.git.

The goal is to submit a properly formatted TRAPI question graph to ARAGORN. There are two ways to do this:

  • Use the ARAGORN website, a SmartAPI web based tool to submit your TRAPI query, or
  • Use curl, a command line tool to post messages to a URL.
Using the website:

To start, please direct your browser to the ARAGORN website located at: https://aragorn.renci.org/docs

Then:

  • Select the ARAGORN "Post" (/query) button on the page.
  • Select the "try it out" button.
  • Select an "Answer coalesce type" from the drop down.
  • Type (or cut/paste) your TRAPI question graph JSON into the request text area.
  • Finally, select the "Execute" button.

In the sections below the submission area on the web page you will see an area for a "Successful response" or "Validation error" messages.

Using the curl command

The curl command is supported by both linux and Windows operating systems and can be used to POST a message directly to a ARAGORN web service.

In this example, the TRAPI JSON is located in a file (query.json) which is POSTed to the ARAGORN web service /query endpoint.

curl -X POST https://aragorn.renci.org/query -d @query.json

Tips and common errors

Receiving a message of "Not a valid Translator query" from ARAGORN indicates a problem with the query graph JSON failing validation. This is commonly due to the query_graph not being wrapped in a "message" element.

Receiving a 500 server can also indicate invalid JSON sent to web service. JSON can be validated easily here:

Issue support

To declare an issue with this software:

  • Please browse to: https://github.com/ranking-agent/aragorn/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.

TRAPI link

TODO: Include preface here.

  • TODO: What exactly is expected here?

Smart API Registry link

The Smart-API open API specification and registration can be found here

How to build a ARAGORN instance for a NCATS Deployment pipeline

TODO: Include preface here.

TODO: How is it installed? Provide a link to the ARAGORN code readme? if so, it needs updating to include the actual installation procedures.

TODO: Use cases

TODO: Include preface here.

  • TODO: How is this different from the "Steps to create your own query" above? Is it just more examples of interesting things?
  • TODO: Is this to showcase different approaches for discovering interesting things?
  • TODO: Is this to showcase a jupiter notebook or two?

Supporting APIs

Below you will find the external web services that are used within the ARAGORN tool.

Knowledge Providers Accessed

Below is a list of knowledge providers accessed by ARAGORN and supporting web services.

TODO: Is this is a comprehensive list? is more needed?

  • Genetic Knowledge Provider
  • Molecular Data Provider
  • Service Provider
  • Exposure Provider
  • Automat
  • Data normalization services

Source Code

Below you will find references that detail the standards, web services and supporting tools that are part of ARAGORN.

External Documentation

TODO: Need more links here? Should the other wiki pages be referenced here?

Add a custom footer

Knowledge Providers (KP)

Autonomous Relay Agents (ARA)

Autonomous Relay System (ARS)

Standards and Reference Implementation (SRI)

Clone this wiki locally