Skip to content

Improve conflation documentation #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
gaurav wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Improve conflation documentation #341

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef2b502
Added more information to endpoint descriptions.
gaurav Nov 5, 2025
279e4e4
Added additional documentation.
gaurav Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 91 additions & 20 deletions node_normalizer/resources/openapi.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,16 @@ info:
x-role: responsible developer
description: 'Node Normalization takes a CURIE, and returns: <ol> <li>The preferred
CURIE for this entity <li>All other known equivalent identifiers for the entity
<li>Semantic types for the entity as defined by the <a href="https://biolink.github.io/biolink-model/">BioLink
<li>Semantic types for the entity as defined by the <a href="https://biolink.github.io/biolink-model/">Biolink
Model</a> </ol> The data served by Node Normalization is created by <a href="https://github.com/TranslatorSRI/Babel">Babel</a>,
which attempts to find identifier equivalences, and makes sure that CURIE prefixes
are BioLink Model Compliant. To determine whether Node Normalization is likely
are BioLink Model Compliant. To determine whether Node Normalization is likely
to be useful, check /get_semantic_types, which lists the BioLink semantic types
for which normalization has been attempted, and /get_curie_prefixes, which lists
the number of times each prefix is used for a semantic type.'
the number of times each prefix is used for a semantic type. You can find out more about these API methods at the
<a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md">Node Normalization API documentation</a>.
To learn more about how Babel creates cliques of equivalent identifiers, you can
<a href="https://github.com/TranslatorSRI/Babel/blob/master/docs/README.md">read its documentation</a>.'
license:
name: MIT
url: https://opensource.org/licenses/MIT
Expand All @@ -41,9 +44,29 @@ tags:
- name: Interfaces
- name: trapi
paths:
/status:
get:
description: 'Returns the status of the Node Normalization service. You can read more about this endpoint in the
<a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md#status">NodeNorm API documentation</a>.'
responses:
'200':
content:
application/json:
schema:
example:
status: running
babel_version: 2025mar31
babel_version_url: https://github.com/TranslatorSRI/Babel/blob/master/releases/2025mar31.md
databases:
eq_id_to_id_db:
dbname: id-id
count: 677731045
used_memory_rss_human: 68.83G
is_cluster: false
/get_curie_prefixes:
get:
description: Returns the curies and their hit count for a semantic type(s).
description: 'Returns the curies and their hit count for a semantic type(s). You can read more about this endpoint
in the <a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md#get_curie_prefixes">NodeNorm API documentation</a>.'
parameters:
- in: query
name: semantic_type
Expand Down Expand Up @@ -78,8 +101,9 @@ paths:
- Interfaces
/get_normalized_nodes:
get:
description: Returns the equivalent identifiers and semantic types for the curie(s)
entered.
description: 'Returns the equivalent identifiers and semantic types for the curie(s)
entered. You can read more about this endpoint in the
<a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md#get_normalized_nodes">NodeNorm API documentation</a>. '
parameters:
- in: query
name: curie
Expand All @@ -97,6 +121,9 @@ paths:
schema:
example:
MESH:D014867:
id:
identifier: CHEBI:15377
label: Water
equivalent_identifiers:
- identifier: CHEBI:15377
label: Water
Expand All @@ -110,14 +137,17 @@ paths:
- identifier: INCHIKEY:XLYOFNOQVPJJNP-UHFFFAOYSA-N
- identifier: UNII:059QF0K00R
- identifier: KEGG.COMPOUND:C00001
id:
identifier: CHEBI:15377
label: Water
type:
- chemical_substance
- molecular_entity
- biological_entity
- named_thing
- biolink:SmallMolecule
- biolink:MolecularEntity
- biolink:ChemicalEntity
- biolink:PhysicalEssence
- biolink:ChemicalOrDrugOrTreatment
- biolink:ChemicalEntityOrGeneOrGeneProduct
- biolink:ChemicalEntityOrProteinOrPolypeptide
- biolink:NamedThing
- biolink:PhysicalEssenceOrOccurrent
information_content: 47.5
NCIT:C34373:
equivalent_identifiers:
- identifier: MONDO:0004976
Expand All @@ -134,10 +164,12 @@ paths:
identifier: MONDO:0004976
label: amyotrophic lateral sclerosis
type:
- disease
- disease_or_phenotypic_feature
- biological_entity
- named_thing
- biolink:Disease
- biolink:DiseaseorPhenotypicFeature
- biolink:BiologicalEntity
- biolink:ThingWithTaxon
- biolink:NamedThing
information_content: 74.9
type: object
description: Results
summary: Get the equivalent identifiers and semantic types for the curie(s)
Expand All @@ -146,8 +178,9 @@ paths:
- Interfaces
/get_semantic_types:
get:
description: Returns a distinct set of the semantic types discovered in the
compendium data.
description: 'Returns a distinct set of the semantic types discovered in the
compendium data. You can read more about this endpoint in the
<a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md#get_semantic_types">NodeNorm API documentation</a>.'
responses:
'200':
content:
Expand All @@ -167,7 +200,16 @@ paths:
- Interfaces
/get_allowed_conflations:
get:
description: Returns a list of allowed conflation options
description: 'Returns a list of allowed conflation options. Conflation allows cliques to be combined on-the-fly
on the basis of two different criteria:
<ol>
<li><code>GeneProtein</code> conflation merges protein-coding genes with the proteins they encode. The gene(s) always
appear first in the combined clique.
<li><code>DrugChemical</code> conflation merges chemicals based on their active ingredient. We attempt to ensure that
the active ingredient appears before any formulations in the combined clique.
</ol>
You can read <a href="https://github.com/NCATSTranslator/Babel/blob/master/docs/Conflation.md">more about conflation</a> or
<a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md#get_allowed_conflations">more about this endpoint</a>.'
responses:
'200':
content:
Expand All @@ -182,3 +224,32 @@ paths:
summary: Return a list of named conflations.
tags:
- Interfaces
/get_setid:
get:
description: 'Returns the set ID for a given set of CURIEs. A set-id is an identifier that can be used to identify
this set of CURIEs going forward. It is currently impossible to recreate a set of CURIEs from a set-id, but the
same set of CURIEs given to the same version of Node Normalization will always return the same set-id.
You can read more about this endpoint in the
<a href="https://github.com/NCATSTranslator/NodeNormalization/blob/master/documentation/API.md#get_setid">NodeNorm API documentation</a>.'
responses:
'200':
description: Successful result
content:
application/json:
schema:
example:
curies:
- MESH:D014867
- NCIT:C34373
- UNII:63M8RYN44N
- RUBBISH:1234
conflations:
- GeneProtein
- DrugChemical
error: null
normalized_curies:
- CHEBI:15377
- MONDO:0004976
- RUBBISH:1234
normalized_string: "CHEBI:15377||MONDO:0004976||RUBBISH:1234"
setid: "uuid:771d3c09-9a8c-5c46-8b85-97f481a90d40"