-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Restructured navigation and revised text to enhance usability
- Loading branch information
1 parent
c8cfa8f
commit aa0511b
Showing
10 changed files
with
103 additions
and
110 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,3 @@ | ||
| # Translator User Interface | ||
|
|
||
| The Translator User Interface (UI) is under development as a Web interface to the Translator system that receives scored results and evidence, confidence, and provenance from the ARS and exposes results to users. This section doesn't cover the use of the UI, but rather, technical details facilitating its further development and maintenance. | ||
|
|
||
| * Andy Crouse _et al_ to elaborate. | ||
|
|
||
| ## Tutorials | ||
|
|
||
| * [Translator User Interface tutorials](../development-guide/tutorials/index.md) | ||
| The primary Translator User Interface (UI) is under development as a [web portal](https://ui.transltr.io/) to the Translator system that receives scored results and evidence, confidence, and provenance from the ARS and exposes results to users. This section doesn't cover the use of the UI, but rather, technical details facilitating its further development and maintenance. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,40 +1,31 @@ | ||
|  | ||
|
|
||
| # Guide for Developers | ||
|
|
||
| This section of the Technical Documentation provides several resources for developers designing, implementing and maintaining Translator software. | ||
| This section of the Technical Documentation provides several resources for developers designing, implementing, testing and maintaining Translator software. | ||
|
|
||
| - [Quick Start](quickstart.md) | ||
| - **Graph Modeling Paradigms:** | ||
| - [Core knowledge graph principles](../architecture/biolink/knowledge_graphs.md) | ||
| - [Key Biolink Model components](https://biolink.github.io/biolink-model/guidelines/understanding-the-model.html) | ||
| - [Getting started with Biolink](https://biolink.github.io/biolink-model/guidelines/using-the-modeling-language.html) | ||
| - [Working with the model (tutorial)](https://biolink.github.io/biolink-model/guidelines/working-with-the-model.html) | ||
| - [Developer Cookbook](cookbook.md) | ||
| - [Tutorials](tutorials/index.md) | ||
| - [Testing Resources](../architecture/sri/testing/index.md) | ||
| - [Frequently Asked Questions (FAQ)](../faq.md) | ||
| ## Overview of Primary Translator standards | ||
| - [Introduction to Knowledge Graphs and the Biolink Model](../architecture/biolink/knowledge_graphs.md) | ||
| - [Translator networking protocol: the Translator Reasoner Application Programming Interface (TRAPI)](../architecture/sri/trapi.md) | ||
| - [Workflows](../architecture/workflows.md) | ||
|
|
||
| The actual deployment of the system is further documented in the [Deployment Guide](../deployment-guide/index.md). | ||
| ## Coding against Translator | ||
| - [“Hello Translator” Jupyter Notebook](https://github.com/NCATSTranslator/TranslatorTechnicalDocumentation/blob/master/docs/development-guide/HelloTranslator.ipynb) providing a quick (Python) programmatic introduction to Translator interfaces and knowledge graph data. | ||
| - [Tutorials](tutorials/index.md) | ||
| - [Guidance for Testing](../architecture/sri/testing/index.md) | ||
|
|
||
| An overview of the Translator Architecture is provided in the [Architecture overview page](index.md). | ||
| Briefly, the system is composed of the following components: | ||
| An overview of the Translator platform is provided in the [Architecture overview page](index.md). Briefly, the system is composed of the following components: | ||
|
|
||
| 1. [User Interface (UI)](../architecture/ui.md) | ||
| 2. [Autonomous Relay System (ARS)](../architecture/ars_usage.md) | ||
| 3. [Workflow Runner](../architecture/workflows.md) | ||
| 4. [Translator Reasoner Application Programming Interface (TRAPI)](../architecture/sri/trapi.md) | ||
| 5. [Translator SmartAPI Registry](../architecture/registry.md) | ||
| 6. [Autonomous Relay Agents (ARAs)](../architecture/ara/index.md) | ||
| 7. [Knowledge Providers (KPs)](../architecture/kp/index.md) | ||
| 3. [Autonomous Relay Agents (ARAs)](../architecture/ara/index.md) | ||
| 4. [Knowledge Providers (KPs)](../architecture/kp/index.md) | ||
| 5. [Workflow Runner](../architecture/workflows.md) | ||
| 6. [Translator SmartAPI Registry](../architecture/registry.md) | ||
|
|
||
| Tying together the above components are the activities, standards and service components of the Translator | ||
| Tying together the above components are the activities, aforementioed primary standards and service components of the Translator | ||
| [Standards and Reference Implementation ("SRI")](../architecture/sri/index.md) project team. | ||
|
|
||
| Additional architecture details are stored in the | ||
| [Translator Architecture repository](https://github.com/NCATSTranslator/TranslatorArchitecture). | ||
|
|
||
| ## Joining the Translator Community as a Developer [draft] | ||
|
|
||
| * What are the mandatory technical requirements of having your stuff in Translator (Minimal standards; QA) | ||
| * How do keep quality assurance / gatekeeping in place; rubber-stamping; governance; vetting process for new internal KP's etc. - Governance issues? | ||
| ## Getting Involved | ||
| - [Consortium Development Guidelines](tutorials/consortium_development_guidelines.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,3 @@ | ||
| # Quick Start | ||
|
|
||
| A [“Hello Translator” Jupyter Notebook](https://github.com/NCATSTranslator/TranslatorTechnicalDocumentation/blob/master/docs/development-guide/HelloTranslator.ipynb) is available to help orient newcomers to software development against the Translator platform. | ||
| A [“Hello Translator” Jupyter Notebook](https://github.com/NCATSTranslator/TranslatorTechnicalDocumentation/blob/master/docs/development-guide/HelloTranslator.ipynb) is a quick (Python) programmatic introduction to Translator interfaces and knowledge graph data. |
21 changes: 21 additions & 0 deletions
21
docs/development-guide/tutorials/component_builders_roadmap.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # A Translator Component Builder's Road Map | ||
|
|
||
| The Phase 2 - Development projects of Translator created a cluster of KP and ARA components, queried by the ARS. Knowledge coverage was constrained to a priority set of knowledge sources highlighted by Phase 2 teams, but obviously, don't completely reflect every knowledge sources nor knowledge graph processing strategy imaginable. The need to integrate such novel resources into Translator suggest the need to develop and integrate novel KP, ARA or utility components in the platform. | ||
|
|
||
| In addition, future development of Translator (e.g. Phase 3 - Performance, starting _circa_ December 2024) will likely draw in new teams and their developers, interested in contributing to the platform, hence, needing a clear starting point to get up to speed on component development. | ||
|
|
||
| Even with Phase 2 project teams, already familiar with the platform, the maintenance of Translator components will sometimes run up against the challenge of complexity of the Translator platform thus, highlighting an ongoing need to refresh knowledge about platform standards, available software and best practices relating to those components. | ||
|
|
||
| The purpose of this document is to provide a concrete one-stop, step-by-step road map about component design and implementation which serves all the above development needs. | ||
|
|
||
| # Resources | ||
|
|
||
| 1. Turnkey Options for Knowledge Provider creation: | ||
| 2. [BioThings Service Provider](../../architecture/kp/service-provider.md) | ||
| 3. [PLOVER](https://github.com/RTXteam/PloverDB) | ||
| [Plater](https://github.com/TranslatorSRI/Plater) | ||
| 5. [Biolink Model](https://biolink.github.io/biolink-model/working-with-the-model/) | ||
| 6. [Implementing TRAPI](https://github.com/NCATSTranslator/ReasonerAPI/tree/master/ImplementationGuidance) | ||
| 7. [Specifying Workflows](workflows.md) | ||
| 8. [Deploying a Translator Component](../../deployment-guide/index.md) | ||
| 9. [Registering a TRAPI service](../../architecture/registry.md#adding-an-api-to-the-translator-smartapi-registry) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,19 +1,6 @@ | ||
|  | ||
|
|
||
| # Tutorials | ||
|
|
||
| 1. [Biolink Model](https://biolink.github.io/biolink-model/working-with-the-model/) | ||
| 2. [Implementing TRAPI](https://github.com/NCATSTranslator/ReasonerAPI/tree/master/ImplementationGuidance) | ||
| 3. [Registering a TRAPI service](../../architecture/registry.md#adding-an-api-to-the-translator-smartapi-registry) | ||
| 4. [Workflows](workflows.md) | ||
|
|
||
|
|
||
| # Purpose of this page (work-in-progress) | ||
| * Brainstorm outline all the specific necessary technical and sociological steps required to "plug into" the Translator ecosystem? | ||
| * Add link outs to videos (existing?) for various stuff | ||
|
|
||
| ## Additional Tutorial topics for composition? | ||
|
|
||
| 1. KP-starter kit | ||
| 3. Standing Up a KP/ARA | ||
| 5. Workflow runner (video) | ||
| 1. [What are knowledge graphs, why do we use them and how do we build them?](../../architecture/biolink/knowledge_graphs.md) | ||
| 2. So you are a Data Scientist wanting to directly play with Translator knowledge graphs? You can try out the available ["Hello Translator" Jupyter Notebook](../HelloTranslator.ipynb) or learn more about [how to access the Autonomous Relay System ("ARS")](https://docs.google.com/document/d/1_a4gE_lY-2oZTrdFMtaZ_pxqNgd-x_1ZYI7hRGfFjng/edit?pli=1#heading=h.pp72dzm2iy0h) | ||
| 3. So you want to build (or maintain/extend) a new (or existing) Translator Component? [Where do you start and what do you need to know?](component_builders_roadmap.md) | ||
| 4. How do I directly engage with the [Consortium Development Process](consortium_development_guidelines.md)? |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,17 +1,23 @@ | ||
| # What I want to know is... | ||
|
|
||
| ### What are knowledge graphs, why do we use them and how do we build them? | ||
| Check out our [introduction to knowledge graphs](architecture/biolink/knowledge_graphs.md)? | ||
|
|
||
| ### How can I start playing with Translator? | ||
| Translator is generally accessible to researchers via the [Translator Web portal](https://ui.transltr.io/). Python-savvy data scientists can try out the ["Hello Translator" Jupyter Notebook](development-guide/HelloTranslator.ipynb). | ||
|
|
||
| ### How can I develop software to use and/or contribute to Translator? | ||
| We composed a [set of tutorials](development-guide/tutorials/index.md) for you. | ||
|
|
||
| ### How do I find an identifier for a biomedical concept/entity? | ||
| CURIE's (Compact Uniform Resource Identifiers) are used in TRAPI messages to identify particular biomedical objects and concepts. | ||
| Here are two ways to convert from natural language to a CURIE: | ||
|
|
||
| 1. The [SRI Name Resolver](https://name-resolution-sri.renci.org/docs), specifically the `/lookup` endpoint, can take natural language and find a CURIE associated with it. | ||
| 2. The [ARAX UI](https://arax.transltr.io/) has a `Synonyms` feature on the left bar under the heading `Tools`. In it, you can type a term (with autocomplete) and find equivalent CURIES. This approach uses both the SRI Name Resolver and additional information derived from RTX-KG2. | ||
|
|
||
|
|
||
| ### How do I compute the Normalized Google Distance (NGD) between two concepts | ||
| ### How do I compute the Normalized Google Distance (NGD) between two concepts? | ||
| The endpoint [https://arax.transltr.io/api/arax/v1.4/ui/#/PubmedMeshNgd/pubmed_mesh_ngd](https://araxtransltr.io/api/arax/v1.4/ui/#/PubmedMeshNgd/pubmed_mesh_ngd) takes two natural language inputs (terms occurring in UMLS) and returns the NGD between them. | ||
|
|
||
|
|
||
| ### How can I quickly view a TRAPI response? | ||
| The ARAX UI [https://arax.transltr.io/](https://arax.transltr.io/) can take a TRAPI response <img src="https://github.com/user-attachments/assets/780025a6-9907-4802-87ba-238896c002a5" width="150"> and render the results. This is mainly helpful for debugging and development use. You can also enter a PK in the ID field <img src="https://github.com/user-attachments/assets/c3cdda80-9790-4324-99a8-057bb9a84202" width="150">. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters