From 003068d578369f2affad4c6305af6532a27d8e3d Mon Sep 17 00:00:00 2001 From: tokebe <43009413+tokebe@users.noreply.github.com> Date: Fri, 20 Oct 2023 14:22:27 -0400 Subject: [PATCH] docs: update readme --- README.md | 84 ++++--------------------------------------------------- 1 file changed, 5 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index c647f799..e6fe0b45 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,13 @@ -# BioThings Explorer TRAPI API +# BioThings Explorer Server [![Test with workspace](https://github.com/biothings/biothings_explorer/actions/workflows/test_ws_codecov.yml/badge.svg)](https://github.com/biothings/biothings_explorer/actions/workflows/test_ws_codecov.yml) [![codecov](https://codecov.io/gh/biothings/biothings_explorer/branch/main/graph/badge.svg?token=I4A29PQQJK)](https://codecov.io/gh/biothings/biothings_explorer) [![ci-cd](https://github.com/biothings/biothings_explorer/actions/workflows/deploy.yml/badge.svg)](https://github.com/biothings/biothings_explorer/actions/workflows/deploy.yml) -## Introduction +## Welcome to @biothings-explorer/bte-server 👋 -This Repository serves as the development workspace for the TRAPI implementation of **BioThings Explorer (BTE)**. BTE is an engine for autonomously querying a distributed knowledge graph. The distributed knowledge graph is made up of biomedical APIs that have been annotated with semantically-precise descriptions of their inputs and outputs in the [SmartAPI registry](https://smart-api.info/). This project is primarily funded by the [NCATS Translator project](https://ncats.nih.gov/translator). There is also an older [python version of BioThings Explorer](https://github.com/biothings/biothings_explorer_archived) that is now deprecated. +The server module for the Biothings Explorer workspace. -An older version of the meta knowledge graph that is consumed by BTE is in this figure (which, although older, gives a nice conceptual visualization of API interoperability): +## Usage -![BTE Meta-KG](./diagrams/smartapi_metagraph.png "BioThings Explorer metagraph") - -### What's TRAPI? - -TRAPI stands for [Translator Reasoner API](https://github.com/NCATSTranslator/ReasonerAPI). It is a standard defined for APIs developed within NCATS Biomedical Translator project to facilitate information exchange between resources. BTE exports results via TRAPI to maintain interoperability with other Translator tools. BTE can also _consume_ knowledge resources that expose the TRAPI interface, but it also can consume APIs that have been annotated in the [SmartAPI registry](https://smart-api.info/) using the [x-bte extension](https://x-bte-extension.readthedocs.io/en/latest/index.html) to the OpenAPI specification. - -### Trapi API Implementation - -Below is a process diagram depicting BTE's internal workflow when processing a query. - -```mermaid -sequenceDiagram -autonumber -participant I as index.js - query() -participant QG as query_graph.js -participant BEQ as batch_edge_query.js -participant Q2A as qedge2apiedge.js -participant R as query_results.js -participant C as call-apis module - -note over I, R: query_graph_handler module - -I->>QG: processQueryGraph() -QG->>QG: Process TRAPI Query Graph Object into
internal qEdge and qXEdge representation -note right of QG: qEdge - Edge in TRAPI query graph
qXEdge - Internal UpdatedExeEdge representation
of a qEdge to be executed -QG->>I: return qXEdges - -I->>I: Inferred Mode: create
templated queries - -loop Executing with Edge Manager -I->>I: while there are unexecuted qXEdges,
get next qXEdge - -I->>BEQ: BatchEdgeQueryHandler() -BEQ->>BEQ: NodesUpdateHandler(): get equivalent IDs -BEQ->>BEQ: cacheHandler(): fetch cached records - -alt if there are uncached qXEdges -BEQ->>Q2A: QEdge2APIEdgeHandler() -Q2A->>Q2A: convert qXEdges into API calls by using
metaKG to get metaEdges for qXEdge -Q2A->>BEQ: return metaXEdges -note right of BEQ: metaEdge - An edge in the metaKG
metaXEdge - A metaEdge pair with a qXEdge -BEQ->>C: query() -C->>C: make API calls in batches
and merge results -C->>BEQ: return records from APIs -end - -BEQ->>BEQ: cacheHandler(): cache result records -note right of BEQ: record - A single unit of transformed
data from a sub-query response - -BEQ->>I: return records - -I->>I: Store records/update edge manager -I->>I: Mark Edge as Executed -end - -I->>R: trapiResultsAssembler -R->>R: assemble and convert records into
final return results -R->>I: put results in bteGraph -note left of R: result - 1 item of the array in the
TRAPI response (message.results) -I->>I: bteGraph: prune not fully connected
results from graph -``` - -## Try it Out! - -### Live TRAPI Instance - -We maintain a live instance of this application at https://api.bte.ncats.io/ that can be used for testing. Query Examples can be found [here](./examples). - -### Local installations - -BTE can be used locally using Docker, or by installing the workspace for further tinkering. See the [Installation documentation](./docs/INSTALLATION.md). - -### Usage - -Using BTE can be as simple or complex as you'd like. See the [Usage documentation](./docs/USAGE.md) to get started using BTE! +See the [workspace](https://github.com/biothings/biothings_explorer) for all relevant documentation