From c1bd95318ecd042114b19e7a74a5d564229b4f67 Mon Sep 17 00:00:00 2001 From: Max Wang Date: Tue, 24 Sep 2024 22:23:19 -0400 Subject: [PATCH] Add ranking agent docs (#79) * Add ranking agent docs * updates --------- Co-authored-by: Chris Bizon --- docs/architecture/ara/aragorn.md | 29 +++++++++++++++++++++++++++++ docs/architecture/ara/index.md | 2 +- docs/teams/index.md | 1 + docs/teams/ranking-agent.md | 9 +++++++++ 4 files changed, 40 insertions(+), 1 deletion(-) create mode 100644 docs/architecture/ara/aragorn.md create mode 100644 docs/teams/ranking-agent.md diff --git a/docs/architecture/ara/aragorn.md b/docs/architecture/ara/aragorn.md new file mode 100644 index 00000000..b86b1efc --- /dev/null +++ b/docs/architecture/ara/aragorn.md @@ -0,0 +1,29 @@ +[Back to ARAs](index.md) + +# Aragorn Autonomous Relay Agent Page + +Autonomous Relay Agent for Generation Of Ranked Networks (ARAGORN) is an autonomous relay agent supported by the ranking-agent team. Aragorn operates in a federated knowledge environment and queries all known Knowledge Providers (KPs) found in the [SmartAPI registry](https://smart-api.info/). + +Aragorn processes data using a collection of supporting services also managed by the ranking-agent team: + +* [Strider](https://github.com/ranking-agent/strider) - Responsible for federated querying of known KPs, normalizing identifiers using the Node Normalizer, and formating results. +* [Omnicorp](https://github.com/ranking-agent/aragorn-ranker/blob/master/ranker/modules/omnicorp_overlay.py) - Responsible for annotating nodes and edges with literature co-occurence information to support ranking. +* [Aragorn Ranker](https://github.com/ranking-agent/aragorn-ranker) - Responsible for ranking results using available meta-data information and an algorithm inspired by information flow. + +In addition, Aragorn contains algorithms to orchestrate these services to support inferred edges, set-input queries, and path queries. + +## Inferred Edges +Aragorn uses a collections of rules learned using AMIE+ on the ROBOKOP graph to expand an inferred query edge into a collection of non-inferred queries. Each of these queries is then sent to Strider. Aragorn then merges the set of results and formats the results, before completing ranking. + +## Set-Input Queries +Set-Input queries are primarily handled in Strider, which calls KPs capable of responding to the queries. + +## Implementation +Aragorn is asynchronous with results from requests to supporting services returned via callback URLs. Redis is used to handle communication between worker threads to ensure that requests are available despite any difference from the initiating worker. + +## Ranking +The Aragorn ranking algorithm transforms a set of known attributes into measures between 0 and 1, and then uses these measures to model flow of information between sets of nodes. An algorithm is used to identify which nodes should be measured (probes) using the query graph connectivity and specificity. The ranking algorithm also transforms weights into the range of [0, 1] to normalize the score between any two prob nodes. The ranking algorithm operates on arbitrary graph shapes and does not directly penalize for path length, result graph structure or query structure. A full list of attributes and how they are transformed for ranking is available in the [Aragron ranker source code](https://github.com/ranking-agent/aragorn-ranker/blob/master/ranker/shared/sources.py). + +## Additional Links + +- [Ranking Agent](https://github.com/NCATSTranslator/Translator-All/wiki/Ranking-Agent/) diff --git a/docs/architecture/ara/index.md b/docs/architecture/ara/index.md index 6b069435..b75032bb 100644 --- a/docs/architecture/ara/index.md +++ b/docs/architecture/ara/index.md @@ -12,7 +12,7 @@ Translator "Autonomous Relay Agents" (ARAs) build build upon the knowledge contr | Team | Name | Documentation | Github Repository | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -| [Ranking Agent](https://github.com/NCATSTranslator/Translator-All/wiki/Ranking-Agent) | Ranking Agent ('Aragorn') | [Aragorn Wiki](https://github.com/NCATSTranslator/Translator-All/wiki/ARAGORN) | [ranking-agent/aragorn](https://github.com/ranking-agent/aragorn) | +| [Ranking Agent](../../teams/ranking-agent.md) | Aragorn | [Aragorn Page](aragorn.md) | [ranking-agent/aragorn](https://github.com/ranking-agent/aragorn) | | [Expander Agent](../../teams/expander-agent.md) | ARAX | [ARAX Page](arax.md)
[ARAX Wiki](https://github.com/NCATSTranslator/Translator-All/wiki/ARAX) | [RTXteam/RTX](https://github.com/RTXteam/RTX) | | (im)Proving Agent | Scalable Precision Medicine
Oriented Knowledge Engine ('SPOKE') | [SPOKE Wiki](https://github.com/NCATSTranslator/Translator-All/wiki/imProving-Agent) | [BaranziniLab/PSEV](https://github.com/BaranziniLab/PSEV) | | [Exploring Agent](../../teams/exploring-agent.md) | [BioThings Explorer](https://explorer.biothings.io/) | [BioThings Explorer Page](bte.md) [BioThings Explorer Wiki]() | [biothings/biothings_explorer](https://github.com/biothings/biothings_explorer) | diff --git a/docs/teams/index.md b/docs/teams/index.md index 9b8fc698..6c699f89 100644 --- a/docs/teams/index.md +++ b/docs/teams/index.md @@ -6,4 +6,5 @@ - [Exploring Agent](exploring-agent.md) - [Genetics Data Services Provider](genetics-data.md) - [Multiomics Provider](multiomics-provider.md) +- [Ranking Agent](ranking-agent.md) - [Service Provider](service-provider.md) diff --git a/docs/teams/ranking-agent.md b/docs/teams/ranking-agent.md new file mode 100644 index 00000000..d8496840 --- /dev/null +++ b/docs/teams/ranking-agent.md @@ -0,0 +1,9 @@ +[Back to Teams](index.md) + +# Team Ranking Agent + +Ranking Agent is the team responsible for the ["ARAGORN"](../architecture/ara/aragorn.md) autonomous relay agent. + +## Ranking Agent PIs: + +- Alex Tropsha: alex\_tropsha@unc.edu