Skip to content

ARAGORN

Jump to bottom Edit New page
Phil Owen 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 tool 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.

The ARAGORN tool relies on a number of external services to perform a standardized ranking of a user-specified question.

  • Strider - Accepts a query and provides knowledge-provider querying, answer generation and ranking.
  • Answer Coalesce - Accepts a query containing Strider answers and returns answers that have been coalesced by property, graph and/or ontology analysis.
  • Node normalization - Accepts a query containing coalesced answers and provides the preferred CURIE and equivalent identifiers for data in the query.
  • ARAGORN Ranker - Accepts a query and provides Omnicorp overlays, score and weight-correctness rankings of coalesced answers.

Team Contact:

Patrick Wang ( patrick@covar.com )

TODO: Disclose more team members?

ARAGORN Tool Description

This tool performs a ranking operation which relies on data from numerous ARAGORN agent services. The services are called in the following order, each passing their output to the next service as an input:

Strider -> (optional) Answer Coalesce (graph, ontology and proerty) -> Node normalization -> One (or all) of the ARAGORN Ranker services (omnicorp overlay, score or weight correctness) -> final output.

Strider is an ARA that implements the Translator Reasoner API (TRAPI). It is the KP-querying, result-assembling module of ARAGORN.

Answer coalesce offers coalescence operations that include processing by property, graph or ontology. ARAGORN defaults to the graph operation but also allows the user to select any single method or all coalescence types.

Node normalization is done after Answer coalescence and prior to calling ARAGORN ranking services. The normalization operation insures that preferred CURIE identifiers and equivalent CURIE identifiers are assigned to each graph node.

ARAGORN ranker offers three types of ranking operations that include processing by Omnicorp overlay, score or weight correctness. ARAGORN by default calls on all 3 of these operations where the output of one ranking operation is fed into the next.

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 disease CURIEs.
  • 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 (JSON format) that declares the parameters noted above.

This example shows the resultant a TRAPI query message (JSON) that uses the example entities shown 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)"

{
   "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