Name `contains` matches winning over (exact_)synonym `equals` matches

オープン
#276 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
4/5
見積もり時間
3〜5日
初心者へのやさしさ
45/100
issue の種類
バグ
明瞭さ
おおむね明確
活発さ
静か
技術スタック
python
領域
search

調査の方向性

Start by reading the /lookup ranking implementation and its tests in the NameResolution repository; the issue does not name specific files. Reproduce the reported queries, such as seizures and fungal infections, and trace how exact synonym matches compare with label substring matches. Done means exact label or exact_synonym matches rank above more specific concepts that only contain the query as a substring, with tests covering the reported cases.

索引モデルが issue の本文から書いたものです。

説明

Hi @gaurav,

I've noticed that NameRes could use a little bit of a ranking tweak on how names vs synonyms are ranked, and if you happen to be able to keep exact_synonym separately, that would allow for even more of an improvement. I'll paste in my agent generated issue report below for what I just tracked down relating to MeDIC. Separately, @RichardBruskiewich was trying to get "kidney disease" to resolve to MONDO:0005240 recently, which wasn't succeeding with NameRes or OLS. I made a monarchinitiative.org PR to expose the grounding function we use in our text annotator (which was also previously failing with kidney disease!), and I updated the ranking behavior there to boost a full string match on exact_synonym just below a full string match on name, and in both cases those are implemented as function query multipliers.

@ao33 on our team ran into something similar with chemical matches a little while ago, and might be able to chime in with the examples to build our more test cases for you.

I love working on text match ranking problems, so if it would be helpful for me to make a PR, I'd be happy to.

-- detailed robo report below

Generic disease queries return a hyperspecific concept as top-1 (the matching general concept is present but ranked below anatomically/clinically qualified terms)

Service: Name Resolution (https://name-resolution-sri.renci.org)
Endpoint: GET /lookup
Repo: TranslatorSRI/NameResolution

Summary

For common, generic disease terms, /lookup returns a far more specific concept as the
top-ranked hit, even when the correct general concept is indexed and retrievable. The general
concept is typically present somewhere in the result list (rank ~5–8), but it is ranked below
concepts that contain the query string as a literal substring (e.g. "... fungal infections",
"Central Nervous System Fungal Infections").

Any consumer that takes result[0] (the documented and common usage for autocomplete/normalization)
therefore gets a wrong, over-specified mapping.

This is not hypothetical: it produced a false edge in a published knowledge graph — see Impact.

Reproduction

# "fungal infections" -> top-1 is a CNS-specific concept
curl -s 'https://name-resolution-sri.renci.org/lookup?string=fungal%20infections&autocomplete=true&offset=0&limit=5&biolink_type=DiseaseOrPhenotypicFeature' | jq '.[].label'

Observed top-5:

"Central Nervous System Fungal Infections"   (UMLS:C0729544)   <- returned as top-1
"Recurrent fungal infections"                (HP:0002841)
"Endocardial fungal infections"              (UMLS:C0949014)
"Fungal infections NEC"                      (UMLS:C0947852)
"Meningeal fungal infections"                (UMLS:C0949020)

The correct general concept MONDO:0002041 (MONDO label fungal infectious disease; NameRes
preferred name Mycoses; exact synonyms Fungi infection, mycosis) does exist and is retrievable,
but ranks #7 for fungal infections and #4 for fungal infection.
autocomplete=false gives the same top-1.

More examples (same pattern)

All queried with biolink_type=DiseaseOrPhenotypicFeature, autocomplete=true, limit=30.

query top-1 returned (wrong) a reasonable expected concept
fungal infections UMLS:C0729544 — Central Nervous System Fungal Infections MONDO:0002041 fungal infectious disease (present, ranked #7)
fungal infection MONDO:0020944 — fungal infection of eye MONDO:0002041 fungal infectious disease (present, ranked #4)
viral infections MONDO:0030970 — immunodeficiency 106, susceptibility to viral infections a generic viral-infection concept
parasitic infections UMLS:C0752181 — Central Nervous System Parasitic Infections MONDO:0005135 parasitic infectious disease (present, lower)
bacterial infections MONDO:0021679 — gram-positive bacterial infections MONDO:0005113 bacterial infectious disease
seizures MONDO:0007365 — seizures, benign familial neonatal, 1 a generic seizure/HP:0001250 concept
allergic reactions MONDO:0005271 — Allergy (acceptable) —
diarrhea MONDO:0001673 — diarrhea (correct) — (works because the generic label is an exact string match)

diarrhea is the control: when the generic concept's label is itself an exact string match to
the query, it ranks #1 correctly. The failures occur when the matching general concept is reachable
only via a synonym (e.g. MONDO:0002041 is labeled Mycoses, matched by synonym fungal disease),
while other concepts contain the query phrase verbatim in their primary label.

Singular vs plural makes it worse
singular query → top-1 plural query → top-1
fungal infection → fungal infection of eye fungal infections → Central Nervous System Fungal Infections
viral infection → viral infection of central nervous system viral infections → immunodeficiency 106, susceptibility to viral infections
parasitic infection → parasitic infectious disease (ok) parasitic infections → Central Nervous System Parasitic Infections
seizure → Seizure cluster seizures → seizures, benign familial neonatal, 1

Likely cause (hypothesis)

Ranking favors concepts whose primary label contains the full query string as a contiguous
substring
over concepts where the query is an exact synonym (oboInOwl:hasExactSynonym) but
not a label substring. So a query that is literally an exact synonym of the correct general concept
loses to longer, anatomically/clinically qualified labels that merely embed the query phrase.

Actionable fix: boost exact_synonym matches

MONDO (and HP) tag synonyms with a scope — hasExactSynonym, hasRelatedSynonym, hasBroadSynonym,
hasNarrowSynonym. In every failing case below, the query is an exact synonym (or the label) of the
correct general concept
, yet NameRes ranks it below specific concepts that contain the query as a
substring. Weighting an exact-synonym (or label) hit above a substring-containment hit would fix all of
these. (Monarch's text-grounding API recently added exact-synonym boosting for this same purpose, and it
resolves these cases.)

Evidence (biolink_type=DiseaseOrPhenotypicFeature, autocomplete=true, limit=30):

query correct general concept query is an exact_synonym? NameRes rank of correct concept NameRes top-1 (wrong)
seizures HP:0001250 Seizure yes — exact_synonym Seizures (also the label) not in top 30 seizures, benign familial neonatal, 1
viral infections MONDO:0005108 viral infectious disease yes — exact_synonym viral infection #18 immunodeficiency 106, susceptibility to viral infections
bacterial infections MONDO:0005113 bacterial infectious disease yes — exact_synonym bacterial infection #5 gram-positive bacterial infections
parasitic infections MONDO:0005135 parasitic infectious disease yes — exact_synonym parasitic infection #2 Central Nervous System Parasitic Infections
fungal infections MONDO:0002041 fungal infectious disease via label + exact_synonyms Fungi infection / mycosis (no verbatim fungal infection exact synonym) #7 Central Nervous System Fungal Infections

The seizures row is the clearest: the query is verbatim an exact_synonym of HP:0001250, and the
concept is not even returned in the top 30.

Expected behavior

A query that exactly matches a concept's label or exact_synonym (modulo case and singular/plural
normalization) should rank at or near the top — above concepts that contain the query only as a
substring of a more specific phrase. Concretely, seizures → HP:0001250 Seizure, viral infections
→ MONDO:0005108 viral infectious disease, etc.

Impact

Downstream tools that take the top-1 hit get a wrong, over-specified normalization. Concretely, in the
MeDIC drug-indication knowledge graph, the indication term FUNGAL INFECTIONS was normalized via this
endpoint to UMLS:C0729544 "Central Nervous System Fungal Infections", producing the false published
edge:

Loratadine (CHEBI:6538) biolink:treats Central Nervous System Fungal Infections (UMLS:C0729544)

The same mechanism produced loratadine treats immunodeficiency 65, susceptibility to viral infections,
treats gram-positive bacterial infections, treats benign neonatal seizures, etc.

Environment

  • Date observed: 2026-06-18
  • All queries: biolink_type=DiseaseOrPhenotypicFeature, autocomplete ∈ {true, false}, offset=0.
  • Behavior identical for autocomplete=true and autocomplete=false.
主要言語
Python
スター
5
フォーク
4
PR マージ指標
30日以内にマージされた PR はありません

環境構築

  • Dockerfile または Docker Compose ファイルあり
  • プルリクエストのテンプレートなし
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

NCATSTranslator/NameResolution のほかの issue

NCATSTranslator/NameResolution の issue をすべて見る

似ている issue

Python の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。