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.
- trialmap/__init__.py +79 -0
- trialmap/_http.py +210 -0
- trialmap/_version.py +24 -0
- trialmap/assets/__init__.py +43 -0
- trialmap/assets/base.py +75 -0
- trialmap/assets/cache.py +129 -0
- trialmap/assets/names.py +165 -0
- trialmap/assets/resolver.py +247 -0
- trialmap/assets/sources.py +260 -0
- trialmap/cli.py +387 -0
- trialmap/client.py +487 -0
- trialmap/companies.py +261 -0
- trialmap/enums.py +406 -0
- trialmap/exceptions.py +40 -0
- trialmap/frame.py +130 -0
- trialmap/models/__init__.py +46 -0
- trialmap/models/_raw.py +1140 -0
- trialmap/models/study.py +238 -0
- trialmap/pipeline.py +180 -0
- trialmap/py.typed +0 -0
- trialmap/query.py +236 -0
- trialmap/rwe/__init__.py +51 -0
- trialmap/rwe/base.py +86 -0
- trialmap/rwe/cache.py +115 -0
- trialmap/rwe/collector.py +182 -0
- trialmap/rwe/sources.py +480 -0
- trialmap-0.1.0.dist-info/METADATA +398 -0
- trialmap-0.1.0.dist-info/RECORD +32 -0
- trialmap-0.1.0.dist-info/WHEEL +4 -0
- trialmap-0.1.0.dist-info/entry_points.txt +2 -0
- trialmap-0.1.0.dist-info/licenses/LICENSE +202 -0
- trialmap-0.1.0.dist-info/licenses/NOTICE +8 -0
trialmap/assets/names.py
ADDED
|
@@ -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})"
|