trialmap 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,165 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Cleaning intervention names into lookup candidates.
3
+
4
+ Registry intervention names mix the drug with dose, route, formulation and arm labels:
5
+ ``"Open-label ABC-123456 100 mg oral tablet Q4W"``. :func:`clean_name` strips those parts so
6
+ the code can be looked up; :func:`candidate_names` produces every name worth trying for one
7
+ intervention (its name, its ``otherNames``, and anything in parentheses).
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import re
13
+ from collections.abc import Iterable, Sequence
14
+
15
+ __all__ = [
16
+ "DRUG_INTERVENTION_TYPES",
17
+ "candidate_names",
18
+ "clean_name",
19
+ "is_drug_intervention",
20
+ "is_non_asset",
21
+ "lookup_key",
22
+ "normalize_key",
23
+ "split_combination",
24
+ ]
25
+
26
+ DRUG_INTERVENTION_TYPES = frozenset({"DRUG", "BIOLOGICAL", "GENETIC", "COMBINATION_PRODUCT"})
27
+ """Intervention types that can be a pipeline asset."""
28
+
29
+ _NON_ASSET = re.compile(
30
+ r"\b(placebos?|vehicle|standard[- ]of[- ]care|usual care|saline|sham|best supportive|"
31
+ r"no (treatment|intervention)|active (drug|comparator)|study (drug|medication)|"
32
+ r"investigational (product|drug|medicinal product)|comparator)\b",
33
+ re.IGNORECASE,
34
+ )
35
+
36
+ _UNIT = (
37
+ r"(?:mg/kg|mg/m2|mg/m²|mg/ml|mcg/kg|µg/kg|μg/kg|ug/kg|mg|mcg|µg|μg|ug|ng|kg|g|ml|l|iu|"
38
+ r"units?|mmol|vp|viral particles|cfu|pfu|gc|vg|copies|cells|%)"
39
+ )
40
+ # "100 mg", "0.5%", "1*10^11 vp", "5x10e10 vp", and placeholder doses such as "A mg/kg".
41
+ _DOSE = re.compile(
42
+ rf"(?<![\w-])(?:\d+(?:[.,]\d+)?(?:\s*[x×*]\s*10\s*(?:\^|e)\s*\d+)?|[a-z])\s*{_UNIT}(?!\w)"
43
+ r"(?:\s*w/[wv])?|#\d+",
44
+ re.IGNORECASE,
45
+ )
46
+ # "Dose Level 3", "Dose 1", "Cohort 2", "Part A", "Arm B"
47
+ _ARM_LABEL = re.compile(
48
+ r"(?<![\w-])(?:dose(?:\s+level)?|level|cohort|part|arm|group|regimen)\s+(?:\d+|[a-z])(?![\w-])",
49
+ re.IGNORECASE,
50
+ )
51
+ _EDGE_WORDS = re.compile(
52
+ r"^(?:(?:mixture|combination) of|of|for|with|and|in|to|the|a)\s+|"
53
+ r"\s+(?:of|for|with|and|in|to|the|a)$",
54
+ re.IGNORECASE,
55
+ )
56
+ # (?<![\w-]) / (?![\w-]) instead of \b, so codes such as "PEN-866" or "SC-123" stay intact.
57
+ _REGIMEN = re.compile(
58
+ r"(?<![\w-])(q\d+(w|wk|wks|d|h|m)|qd|bid|tid|qid|qw|qod|qam|qpm|"
59
+ r"(once|twice|three times) (a )?(daily|weekly|day|week)|"
60
+ r"every \d+ (days?|weeks?|months?)|daily|weekly|monthly)(?![\w-])",
61
+ re.IGNORECASE,
62
+ )
63
+ _FORMULATION = re.compile(
64
+ r"(?<![\w-])(open[- ]label|treatment with|(low|medium|mid|high)[- ]doses?|doses?|"
65
+ r"oral(ly)?|i\.?v\.?|s\.?c\.?|subcutaneous(ly)?|intravenous(ly)?|intramuscular(ly)?|"
66
+ r"topical|inhaled|intranasal|"
67
+ r"tablets?|capsules?|solution|suspension|injections?|infusions?|cream|ointment|gel|"
68
+ r"spray|foam|lotion|patch|film[- ]coated|extended[- ]release|"
69
+ r"pre-?filled syringes?|auto-?injectors?|pens?|vials?|powder|formulation|implants?|"
70
+ r"immediate[- ]release|long[- ]acting|ER|XR|SR|"
71
+ r"study drug|investigational product)(?![\w-])",
72
+ re.IGNORECASE,
73
+ )
74
+ _PAREN = re.compile(r"[(\[]([^)\]]*)[)\]]?")
75
+ _TRADEMARK = re.compile(r"[®™©]")
76
+ _COMBINATION = re.compile(r"\s+(?:\+|plus|or|/)\s+|\s*[;,]\s*", re.IGNORECASE)
77
+ _STRIP = " ,;.:-/()+&"
78
+
79
+
80
+ def is_drug_intervention(intervention_type: str | None) -> bool:
81
+ return (intervention_type or "").upper() in DRUG_INTERVENTION_TYPES
82
+
83
+
84
+ def is_non_asset(name: str) -> bool:
85
+ """Placebo, vehicle, standard of care, sham, saline... — never an asset."""
86
+ return bool(_NON_ASSET.search(name))
87
+
88
+
89
+ def clean_name(name: str) -> str:
90
+ """Strip arm labels, parentheses, dose, regimen and formulation words.
91
+
92
+ >>> clean_name("Open-label ABC-123456 100 mg oral tablet Q4W")
93
+ 'ABC-123456'
94
+ >>> clean_name("XYZ-21235,")
95
+ 'XYZ-21235'
96
+ >>> clean_name("Core Treatment Active Experimental: XYZ0302")
97
+ 'XYZ0302'
98
+ """
99
+ name = _TRADEMARK.sub("", name)
100
+ name = name.rsplit(":", 1)[-1] # arm labels: "Core Treatment Active Experimental: XYZ0302"
101
+ name = _PAREN.sub(" ", name)
102
+ name = _DOSE.sub(" ", name)
103
+ name = _ARM_LABEL.sub(" ", name)
104
+ name = _REGIMEN.sub(" ", name)
105
+ name = _FORMULATION.sub(" ", name)
106
+ name = re.sub(r"\s+", " ", name).strip(_STRIP)
107
+ while (trimmed := _EDGE_WORDS.sub("", name).strip(_STRIP)) != name:
108
+ name = trimmed
109
+ # A leftover lone number or single character is noise, not a name.
110
+ if len(name) < 2 or name.replace(".", "").isdigit():
111
+ return ""
112
+ return name
113
+
114
+
115
+ def split_combination(name: str) -> list[str]:
116
+ """Split an intervention name that lists several products.
117
+
118
+ ``"VRC01 + 10-1074"`` → ``["VRC01", "10-1074"]``;
119
+ ``"NSC 740; Placebo"`` → ``["NSC 740", "Placebo"]``. Splits on ``+``, ``plus``, ``or``,
120
+ ``;``, ``,`` and a *spaced* `` / ``. A bare ``/`` (``ABC/3TC/DTG``) and ``and`` are kept:
121
+ they are too often part of one product's name.
122
+ """
123
+ parts, start = [], 0
124
+ for m in _COMBINATION.finditer(name):
125
+ before = name[: m.start()]
126
+ depth = before.count("(") + before.count("[") - before.count(")") - before.count("]")
127
+ if depth > 0: # separator inside brackets: "Drug X (10 mg, oral)"
128
+ continue
129
+ parts.append(name[start : m.start()])
130
+ start = m.end()
131
+ parts.append(name[start:])
132
+ return [part.strip() for part in parts if part.strip()]
133
+
134
+
135
+ def candidate_names(name: str, other_names: Sequence[str] = ()) -> list[str]:
136
+ """Cleaned, de-duplicated names to look up, best first.
137
+
138
+ Order: the intervention name, then each of ``other_names``, then text found in
139
+ parentheses (``"Amethopterin (methotrexate) 1%"`` also tries ``methotrexate``).
140
+ """
141
+ raw = [name, *other_names]
142
+ raw += [inner for n in raw for inner in _PAREN.findall(n)]
143
+ return _dedupe(c for c in map(clean_name, raw) if c and not is_non_asset(c))
144
+
145
+
146
+ def _dedupe(names: Iterable[str]) -> list[str]:
147
+ seen: set[str] = set()
148
+ out: list[str] = []
149
+ for n in names:
150
+ key = lookup_key(n)
151
+ if key not in seen:
152
+ seen.add(key)
153
+ out.append(n)
154
+ return out
155
+
156
+
157
+ def lookup_key(name: str) -> str:
158
+ """Case- and whitespace-insensitive key used for caching lookups."""
159
+ return " ".join(name.casefold().split())
160
+
161
+
162
+ def normalize_key(name: str) -> str:
163
+ """Punctuation-insensitive key used to merge assets and match codes:
164
+ ``"ABC-123456"``, ``"ABC 123456"`` and ``"abc123456"`` are the same."""
165
+ return re.sub(r"[\W_]+", "", name.casefold())
@@ -0,0 +1,247 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Chain resolvers, cache their answers, and map interventions to assets."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import dataclasses
7
+ import logging
8
+ from collections.abc import Mapping, Sequence
9
+ from dataclasses import dataclass
10
+ from typing import TYPE_CHECKING, Any
11
+
12
+ import httpx
13
+
14
+ from ..exceptions import APIError, ResolverError
15
+ from ..models import Intervention
16
+ from .base import Resolution, Resolver
17
+ from .cache import MemoryCache, ResolutionCache, SQLiteCache
18
+ from .names import (
19
+ candidate_names,
20
+ clean_name,
21
+ is_drug_intervention,
22
+ is_non_asset,
23
+ lookup_key,
24
+ normalize_key,
25
+ split_combination,
26
+ )
27
+
28
+ if TYPE_CHECKING:
29
+ from types import TracebackType
30
+
31
+ from typing_extensions import Self
32
+
33
+ __all__ = ["AssetResolver", "DrugMatch", "drug_parts", "unresolved_match"]
34
+
35
+ log = logging.getLogger("trialmap.assets")
36
+
37
+
38
+ @dataclass(frozen=True, slots=True)
39
+ class DrugMatch:
40
+ """The outcome of resolving one drug intervention.
41
+
42
+ Attributes:
43
+ intervention: the intervention name as registered.
44
+ code: the cleaned primary name (what an unresolved asset is called).
45
+ candidates: every name that was tried, in order.
46
+ resolution: the hit, or ``None``.
47
+ errors: resolvers that failed transiently for this drug (result may be incomplete).
48
+ """
49
+
50
+ intervention: str
51
+ code: str
52
+ candidates: tuple[str, ...]
53
+ resolution: Resolution | None
54
+ errors: tuple[str, ...] = ()
55
+
56
+ @property
57
+ def resolved(self) -> bool:
58
+ return self.resolution is not None
59
+
60
+ @property
61
+ def asset_name(self) -> str:
62
+ """Resolved name, or the cleaned code itself when unresolved."""
63
+ return self.resolution.asset_name if self.resolution else self.code
64
+
65
+ @property
66
+ def asset_key(self) -> str:
67
+ """Grouping key: punctuation/case-insensitive, so ``ABC-2113`` and ``ABC 2113`` merge."""
68
+ return normalize_key(self.asset_name)
69
+
70
+ @property
71
+ def needs_review(self) -> bool:
72
+ return self.resolution is None
73
+
74
+ def to_row(self, sep: str = "|") -> dict[str, Any]:
75
+ r = self.resolution
76
+ return {
77
+ "intervention": self.intervention,
78
+ "code": self.code,
79
+ "candidates": sep.join(self.candidates),
80
+ "asset": self.asset_name,
81
+ "resolved": self.resolved,
82
+ "source": r.source if r else "unresolved",
83
+ "source_id": r.source_id if r else None,
84
+ "url": r.url if r else None,
85
+ "matched_on": r.matched_on if r else None,
86
+ "molecule_type": r.molecule_type if r else None,
87
+ "max_phase": r.max_phase if r else None,
88
+ "synonyms": sep.join(r.synonyms) if r else None,
89
+ "errors": sep.join(self.errors),
90
+ }
91
+
92
+
93
+ class AssetResolver:
94
+ """Resolve drug codes to named assets by trying resolvers in order.
95
+
96
+ For each candidate name (intervention name first, then its ``otherNames``), every resolver
97
+ is tried in order; the first hit wins.
98
+
99
+ Args:
100
+ resolvers: the chain. Default: ``[ChemblResolver(), PubChemResolver()]``.
101
+ cache: ``True`` → persistent :class:`SQLiteCache` in the user cache dir;
102
+ ``False`` → in-memory only; or any :class:`ResolutionCache` instance.
103
+ user_agent: passed to the default resolvers.
104
+
105
+ >>> with AssetResolver() as r: # doctest: +SKIP
106
+ ... r.resolve("NSC 740").asset_name
107
+ 'methotrexate'
108
+ """
109
+
110
+ def __init__(
111
+ self,
112
+ resolvers: Sequence[Resolver] | None = None,
113
+ *,
114
+ cache: ResolutionCache | bool = True,
115
+ user_agent: str | None = None,
116
+ ) -> None:
117
+ if resolvers is None:
118
+ from .sources import ChemblResolver, PubChemResolver
119
+
120
+ resolvers = [
121
+ ChemblResolver(user_agent=user_agent),
122
+ PubChemResolver(user_agent=user_agent),
123
+ ]
124
+ if not resolvers:
125
+ raise ValueError("at least one resolver is required")
126
+ names = [r.name for r in resolvers]
127
+ if len(set(names)) != len(names):
128
+ raise ValueError(f"resolver names must be unique (they key the cache): {names}")
129
+ self.resolvers: list[Resolver] = list(resolvers)
130
+ if cache is True:
131
+ self.cache: ResolutionCache = SQLiteCache()
132
+ elif cache is False:
133
+ self.cache = MemoryCache()
134
+ else:
135
+ self.cache = cache
136
+ self._memo = MemoryCache()
137
+
138
+ # ------------------------------------------------------------------ lifecycle
139
+
140
+ def close(self) -> None:
141
+ for r in self.resolvers:
142
+ close = getattr(r, "close", None)
143
+ if callable(close):
144
+ close()
145
+ close_cache = getattr(self.cache, "close", None)
146
+ if callable(close_cache):
147
+ close_cache()
148
+
149
+ def __enter__(self) -> Self:
150
+ return self
151
+
152
+ def __exit__(
153
+ self,
154
+ exc_type: type[BaseException] | None,
155
+ exc: BaseException | None,
156
+ tb: TracebackType | None,
157
+ ) -> None:
158
+ self.close()
159
+
160
+ # ------------------------------------------------------------------ lookups
161
+
162
+ def _lookup_one(self, resolver: Resolver, name: str) -> Resolution | None:
163
+ """Cached lookup of one name in one resolver. Raises ResolverError on failure."""
164
+ key = lookup_key(name)
165
+ for cache in (self._memo, self.cache):
166
+ found, value = cache.get(resolver.name, key)
167
+ if found:
168
+ if cache is not self._memo:
169
+ self._memo.set(resolver.name, key, value)
170
+ return value
171
+ try:
172
+ value = resolver.lookup(name)
173
+ except (ResolverError, httpx.HTTPError, APIError) as exc:
174
+ raise ResolverError(str(exc)) from exc
175
+ self._memo.set(resolver.name, key, value)
176
+ self.cache.set(resolver.name, key, value)
177
+ return value
178
+
179
+ def resolve_candidates(
180
+ self, candidates: Sequence[str]
181
+ ) -> tuple[Resolution | None, tuple[str, ...]]:
182
+ """Try each candidate on each resolver. Returns ``(resolution, failed_resolvers)``."""
183
+ errors: list[str] = []
184
+ for cand in candidates:
185
+ for resolver in self.resolvers:
186
+ try:
187
+ hit = self._lookup_one(resolver, cand)
188
+ except ResolverError as exc:
189
+ log.warning("%s lookup of %r failed: %s", resolver.name, cand, exc)
190
+ if resolver.name not in errors:
191
+ errors.append(resolver.name)
192
+ continue
193
+ if hit is not None:
194
+ return dataclasses.replace(hit, matched_on=cand), tuple(errors)
195
+ return None, tuple(errors)
196
+
197
+ def resolve(self, name: str, other_names: Sequence[str] = ()) -> DrugMatch:
198
+ """Resolve one drug name (and optional synonyms/codes for the same drug).
199
+
200
+ >>> r.resolve("10-1074").asset_name # doctest: +SKIP
201
+ 'zinlirvimab'
202
+ """
203
+ candidates = candidate_names(name, other_names)
204
+ # No candidates means the name was only noise ("10 mg", "Placebo"): code stays empty.
205
+ code = candidates[0] if candidates else ""
206
+ resolution, errors = self.resolve_candidates(candidates)
207
+ return DrugMatch(
208
+ intervention=name,
209
+ code=code,
210
+ candidates=tuple(candidates),
211
+ resolution=resolution,
212
+ errors=errors,
213
+ )
214
+
215
+ def resolve_intervention(
216
+ self, intervention: Intervention | Mapping[str, Any]
217
+ ) -> list[DrugMatch]:
218
+ """Resolve a study intervention to zero or more assets (see :func:`drug_parts`)."""
219
+ matches = (self.resolve(name, others) for name, others in drug_parts(intervention))
220
+ return [m for m in matches if m.code]
221
+
222
+
223
+ def drug_parts(intervention: Intervention | Mapping[str, Any]) -> list[tuple[str, tuple[str, ...]]]:
224
+ """The drug name(s) in an intervention, each with the synonyms that apply to it.
225
+
226
+ Returns ``[]`` for non-drug types (devices, procedures, behavioural...) and for
227
+ placebo/vehicle/standard-of-care/sham. Multi-product names (``"A + B"``,
228
+ ``"NSC 740; Placebo"``) are split and placebo-like parts dropped; ``otherNames`` are only
229
+ kept when a single product remains, since otherwise it is unknown which one they belong to.
230
+ """
231
+ iv = (
232
+ intervention
233
+ if isinstance(intervention, Intervention)
234
+ else Intervention.from_raw(intervention)
235
+ )
236
+ if not is_drug_intervention(iv.type) or not iv.name:
237
+ return []
238
+ parts = [p for p in split_combination(iv.name) if clean_name(p) and not is_non_asset(p)]
239
+ if len(parts) == 1:
240
+ return [(parts[0], iv.other_names)]
241
+ return [(part, ()) for part in parts]
242
+
243
+
244
+ def unresolved_match(name: str, other_names: Sequence[str] = ()) -> DrugMatch:
245
+ """A :class:`DrugMatch` without any lookup: the asset is the cleaned code."""
246
+ candidates = candidate_names(name, other_names)
247
+ return DrugMatch(name, candidates[0] if candidates else "", tuple(candidates), None)
@@ -0,0 +1,260 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Built-in resolvers: ChEMBL, PubChem, NCI Thesaurus (EVS) and a user-supplied mapping.
3
+
4
+ Data-source terms (see README): ChEMBL is CC BY-SA 3.0 (attribution + share-alike when you
5
+ redistribute derived data); PubChem follows the NCBI usage policy (≤ 5 requests/second);
6
+ NCI Thesaurus is CC BY 4.0. Each :class:`Resolution` carries ``source``/``source_id``/``url``
7
+ so results can be attributed.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ import csv
13
+ import logging
14
+ import re
15
+ from collections.abc import Mapping
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ import httpx
20
+
21
+ from .._http import HttpClient
22
+ from ..exceptions import APIError, ResolverError
23
+ from .base import Resolution
24
+ from .names import normalize_key
25
+
26
+ __all__ = ["ChemblResolver", "MappingResolver", "NciEvsResolver", "PubChemResolver"]
27
+
28
+ log = logging.getLogger("trialmap.assets")
29
+
30
+
31
+ class _HttpResolver:
32
+ """Shared plumbing: owns an :class:`HttpClient` unless one is passed in."""
33
+
34
+ name: str = ""
35
+ base_url: str = ""
36
+ default_rate_limit: float = 5.0
37
+
38
+ def __init__(
39
+ self,
40
+ *,
41
+ http: HttpClient | None = None,
42
+ base_url: str | None = None,
43
+ rate_limit: float | None = None,
44
+ timeout: float = 30.0,
45
+ user_agent: str | None = None,
46
+ transport: httpx.BaseTransport | None = None,
47
+ ) -> None:
48
+ self._owns_http = http is None
49
+ self.http = http or HttpClient(
50
+ base_url=(base_url or self.base_url).rstrip("/") + "/",
51
+ timeout=timeout,
52
+ rate_limit=rate_limit if rate_limit is not None else self.default_rate_limit,
53
+ user_agent=user_agent,
54
+ transport=transport,
55
+ max_retries=3,
56
+ )
57
+
58
+ def lookup(self, name: str) -> Resolution | None: # pragma: no cover - abstract
59
+ raise NotImplementedError
60
+
61
+ def close(self) -> None:
62
+ if self._owns_http:
63
+ self.http.close()
64
+
65
+ def _call(self, method: str, url: str, **kw: Any) -> httpx.Response:
66
+ try:
67
+ return self.http.request(method, url, **kw)
68
+ except (httpx.HTTPError, APIError) as exc:
69
+ raise ResolverError(f"{self.name}: {exc}") from exc
70
+
71
+ def __repr__(self) -> str:
72
+ return f"{type(self).__name__}()"
73
+
74
+
75
+ class ChemblResolver(_HttpResolver):
76
+ """Exact (case-insensitive) synonym match in ChEMBL — reliable for antibodies and
77
+ research codes (``10-1074`` → zinlirvimab), and provides ``molecule_type``/``max_phase``.
78
+
79
+ Uses the ``molecule_synonyms__molecule_synonym__iexact`` filter, then ``pref_name__iexact``.
80
+ ChEMBL's free-text search is deliberately *not* used: it returns loose matches.
81
+ """
82
+
83
+ name = "chembl"
84
+ base_url = "https://www.ebi.ac.uk/chembl/api/data"
85
+ _ONLY = (
86
+ "molecule_chembl_id,pref_name,max_phase,molecule_type,molecule_hierarchy,molecule_synonyms"
87
+ )
88
+
89
+ def lookup(self, name: str) -> Resolution | None:
90
+ for field in ("molecule_synonyms__molecule_synonym__iexact", "pref_name__iexact"):
91
+ response = self._call(
92
+ "GET",
93
+ "molecule.json",
94
+ params={field: name, "limit": "5", "only": self._ONLY, "format": "json"},
95
+ )
96
+ molecules = [m for m in response.json().get("molecules", []) if m.get("pref_name")]
97
+ if molecules:
98
+ return self._to_resolution(_pick_parent(molecules))
99
+ return None
100
+
101
+ @staticmethod
102
+ def _to_resolution(m: Mapping[str, Any]) -> Resolution:
103
+ chembl_id = str(m["molecule_chembl_id"])
104
+ try:
105
+ max_phase = float(m["max_phase"]) if m.get("max_phase") is not None else None
106
+ except (TypeError, ValueError):
107
+ max_phase = None
108
+ synonyms = sorted(
109
+ {
110
+ str(s["molecule_synonym"])
111
+ for s in m.get("molecule_synonyms") or []
112
+ if s.get("molecule_synonym")
113
+ }
114
+ )
115
+ return Resolution(
116
+ asset_name=str(m["pref_name"]).lower(),
117
+ source="chembl",
118
+ source_id=chembl_id,
119
+ url=f"https://www.ebi.ac.uk/chembl/explore/compound/{chembl_id}",
120
+ molecule_type=m.get("molecule_type"),
121
+ max_phase=max_phase,
122
+ synonyms=tuple(synonyms),
123
+ )
124
+
125
+
126
+ def _pick_parent(molecules: list[Mapping[str, Any]]) -> Mapping[str, Any]:
127
+ """Prefer the parent compound over salts/forms when a synonym matches several records."""
128
+ for m in molecules:
129
+ hierarchy = m.get("molecule_hierarchy") or {}
130
+ if hierarchy.get("parent_chembl_id") in (None, m.get("molecule_chembl_id")):
131
+ return m
132
+ return molecules[0]
133
+
134
+
135
+ _INN_TAGS = ("INN", "INN-English", "USAN")
136
+ _TAGGED = re.compile(r"^(?P<name>.+?)\s*\[(?P<tag>[^\]]+)\]$")
137
+
138
+
139
+ class PubChemResolver(_HttpResolver):
140
+ """PubChem PUG REST name → synonyms. Good for small molecules and peptides
141
+ (``NSC 740`` → methotrexate); antibodies are usually absent (a miss, not an error).
142
+
143
+ The name is sent as a POST form field, which PubChem recommends for names containing
144
+ ``/`` or other special characters. Rate-limited to 5 requests/second by default.
145
+ """
146
+
147
+ name = "pubchem"
148
+ base_url = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
149
+ default_rate_limit = 5.0
150
+
151
+ def lookup(self, name: str) -> Resolution | None:
152
+ response = self._call(
153
+ "POST",
154
+ "compound/name/synonyms/JSON",
155
+ data={"name": name},
156
+ ok_statuses=frozenset({400, 404}),
157
+ )
158
+ if response.status_code in (400, 404):
159
+ return None
160
+ infos = response.json().get("InformationList", {}).get("Information", [])
161
+ info = next((i for i in infos if i.get("Synonym")), None)
162
+ if info is None:
163
+ return None
164
+ synonyms: list[str] = [str(s) for s in info["Synonym"]]
165
+ cid = info.get("CID")
166
+ return Resolution(
167
+ asset_name=preferred_synonym(synonyms).lower(),
168
+ source="pubchem",
169
+ source_id=f"CID{cid}" if cid else None,
170
+ url=f"https://pubchem.ncbi.nlm.nih.gov/compound/{cid}" if cid else None,
171
+ synonyms=tuple(synonyms[:25]),
172
+ )
173
+
174
+
175
+ def preferred_synonym(synonyms: list[str]) -> str:
176
+ """An ``[INN]``-tagged synonym if present (then INN-English, USAN), else PubChem's first
177
+ synonym, which is its preferred name."""
178
+ tagged: dict[str, str] = {}
179
+ for s in synonyms:
180
+ m = _TAGGED.match(s)
181
+ if m and m["tag"] in _INN_TAGS:
182
+ tagged.setdefault(m["tag"], m["name"].strip())
183
+ for tag in _INN_TAGS:
184
+ if tag in tagged:
185
+ return tagged[tag]
186
+ return synonyms[0]
187
+
188
+
189
+ class NciEvsResolver(_HttpResolver):
190
+ """NCI Thesaurus via the EVS REST API, exact match on concept names *and* synonyms
191
+ (``Triapine`` → triapine, C2242). Optional: not in the default chain.
192
+
193
+ Uses ``type=match``; the ``contains`` mode is too noisy for code resolution.
194
+ """
195
+
196
+ name = "nci_evs"
197
+ base_url = "https://api-evsrest.nci.nih.gov/api/v1"
198
+
199
+ def lookup(self, name: str) -> Resolution | None:
200
+ response = self._call(
201
+ "GET",
202
+ "concept/ncit/search",
203
+ params={"term": name, "type": "match", "include": "synonyms", "pageSize": "5"},
204
+ )
205
+ concepts = [c for c in response.json().get("concepts", []) if c.get("active", True)]
206
+ if not concepts:
207
+ return None
208
+ c = concepts[0]
209
+ code = str(c["code"])
210
+ synonyms = sorted({str(s["name"]) for s in c.get("synonyms") or [] if s.get("name")})
211
+ return Resolution(
212
+ asset_name=str(c["name"]).lower(),
213
+ source="nci_evs",
214
+ source_id=code,
215
+ url=f"https://evsexplore.semantics.cancer.gov/evsexplore/concept/ncit/{code}",
216
+ synonyms=tuple(synonyms),
217
+ )
218
+
219
+
220
+ class MappingResolver:
221
+ """Resolve from your own table, e.g. an internal pipeline list.
222
+
223
+ Keys are matched ignoring case and punctuation (``ABC 2113`` = ``abc-2113``).
224
+
225
+ >>> r = MappingResolver({"ABC-2113": "fooximab"})
226
+ >>> r.lookup("abc 2113").asset_name
227
+ 'fooximab'
228
+ """
229
+
230
+ def __init__(self, mapping: Mapping[str, str], *, name: str = "mapping") -> None:
231
+ self.name = name
232
+ self._map = {normalize_key(k): v for k, v in mapping.items() if k and v}
233
+
234
+ @classmethod
235
+ def from_csv(
236
+ cls,
237
+ path: str | Path,
238
+ *,
239
+ name_column: str = "name",
240
+ asset_column: str = "asset",
241
+ name: str = "mapping",
242
+ ) -> MappingResolver:
243
+ """Load a CSV with (at least) a code/name column and an asset column."""
244
+ with Path(path).open(newline="", encoding="utf-8-sig") as fh:
245
+ reader = csv.DictReader(fh)
246
+ missing = {name_column, asset_column} - set(reader.fieldnames or ())
247
+ if missing:
248
+ raise ValueError(f"{path}: missing column(s) {', '.join(sorted(missing))}")
249
+ rows = {
250
+ (r.get(name_column) or "").strip(): (r.get(asset_column) or "").strip()
251
+ for r in reader
252
+ }
253
+ return cls(rows, name=name)
254
+
255
+ def lookup(self, name: str) -> Resolution | None:
256
+ asset = self._map.get(normalize_key(name))
257
+ return Resolution(asset_name=asset, source=self.name, source_id=None) if asset else None
258
+
259
+ def __repr__(self) -> str:
260
+ return f"MappingResolver({len(self._map)} entries, name={self.name!r})"