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/client.py
ADDED
|
@@ -0,0 +1,487 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Client for the ClinicalTrials.gov v2 REST API (https://clinicaltrials.gov/data-api/api)."""
|
|
3
|
+
|
|
4
|
+
from __future__ import annotations
|
|
5
|
+
|
|
6
|
+
import logging
|
|
7
|
+
import warnings
|
|
8
|
+
from collections.abc import Iterator, Sequence
|
|
9
|
+
from typing import TYPE_CHECKING, Any, Literal, cast, overload
|
|
10
|
+
|
|
11
|
+
import httpx
|
|
12
|
+
|
|
13
|
+
from ._http import HttpClient
|
|
14
|
+
from .enums import FieldStatsType
|
|
15
|
+
from .models import (
|
|
16
|
+
EnumInfoDict,
|
|
17
|
+
FieldNodeDict,
|
|
18
|
+
FieldValuesStatsDict,
|
|
19
|
+
GzipStatsDict,
|
|
20
|
+
ListSizesDict,
|
|
21
|
+
PagedStudiesDict,
|
|
22
|
+
SearchDocumentDict,
|
|
23
|
+
StudiesPage,
|
|
24
|
+
Study,
|
|
25
|
+
StudyDict,
|
|
26
|
+
VersionDict,
|
|
27
|
+
)
|
|
28
|
+
from .query import StudyQuery, StudyQueryParams, _serialise
|
|
29
|
+
|
|
30
|
+
if TYPE_CHECKING:
|
|
31
|
+
from types import TracebackType
|
|
32
|
+
|
|
33
|
+
from typing_extensions import Self, Unpack
|
|
34
|
+
|
|
35
|
+
__all__ = ["BASE_URL", "MAX_PAGE_SIZE", "CTGovClient"]
|
|
36
|
+
|
|
37
|
+
log = logging.getLogger("trialmap.client")
|
|
38
|
+
|
|
39
|
+
BASE_URL = "https://clinicaltrials.gov/api/v2"
|
|
40
|
+
MAX_PAGE_SIZE = 1000
|
|
41
|
+
"""The API silently coerces larger ``pageSize`` values down to this."""
|
|
42
|
+
|
|
43
|
+
MarkupFormat = Literal["markdown", "legacy"]
|
|
44
|
+
SingleStudyFormat = Literal["json", "csv", "json.zip", "fhir.json", "ris"]
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
class CTGovClient:
|
|
48
|
+
"""ClinicalTrials.gov v2 API client.
|
|
49
|
+
|
|
50
|
+
>>> with CTGovClient() as ct: # doctest: +SKIP
|
|
51
|
+
... for study in ct.iter_studies(query_intr="methotrexate", max_studies=50):
|
|
52
|
+
... print(study.nct_id, study.overall_status, study.phases)
|
|
53
|
+
|
|
54
|
+
Args:
|
|
55
|
+
user_agent: optional; sent with every request. Defaults to ``trialmap/<version> ...``.
|
|
56
|
+
timeout: per-request timeout in seconds.
|
|
57
|
+
max_retries: retries on HTTP 429/5xx and network errors, with exponential backoff
|
|
58
|
+
(``Retry-After`` honoured).
|
|
59
|
+
backoff_factor: base of the exponential backoff, in seconds.
|
|
60
|
+
rate_limit: max requests per second (``None`` disables). The API's limit is not
|
|
61
|
+
published in machine-readable form; the conservative default avoids 429s.
|
|
62
|
+
base_url: override for testing/mirrors.
|
|
63
|
+
transport: custom httpx transport (e.g. ``httpx.MockTransport`` in tests).
|
|
64
|
+
"""
|
|
65
|
+
|
|
66
|
+
def __init__(
|
|
67
|
+
self,
|
|
68
|
+
*,
|
|
69
|
+
user_agent: str | None = None,
|
|
70
|
+
timeout: float = 60.0,
|
|
71
|
+
max_retries: int = 4,
|
|
72
|
+
backoff_factor: float = 1.0,
|
|
73
|
+
rate_limit: float | None = 2.0,
|
|
74
|
+
base_url: str = BASE_URL,
|
|
75
|
+
transport: httpx.BaseTransport | None = None,
|
|
76
|
+
) -> None:
|
|
77
|
+
self.http = HttpClient(
|
|
78
|
+
base_url=base_url.rstrip("/") + "/",
|
|
79
|
+
timeout=timeout,
|
|
80
|
+
max_retries=max_retries,
|
|
81
|
+
backoff_factor=backoff_factor,
|
|
82
|
+
rate_limit=rate_limit,
|
|
83
|
+
user_agent=user_agent,
|
|
84
|
+
transport=transport,
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
def close(self) -> None:
|
|
88
|
+
self.http.close()
|
|
89
|
+
|
|
90
|
+
def __enter__(self) -> Self:
|
|
91
|
+
return self
|
|
92
|
+
|
|
93
|
+
def __exit__(
|
|
94
|
+
self,
|
|
95
|
+
exc_type: type[BaseException] | None,
|
|
96
|
+
exc: BaseException | None,
|
|
97
|
+
tb: TracebackType | None,
|
|
98
|
+
) -> None:
|
|
99
|
+
self.close()
|
|
100
|
+
|
|
101
|
+
# ================================================================== /studies
|
|
102
|
+
|
|
103
|
+
@staticmethod
|
|
104
|
+
def _build_query(query: StudyQuery | None, kwargs: StudyQueryParams) -> StudyQuery:
|
|
105
|
+
q = query or StudyQuery()
|
|
106
|
+
if kwargs:
|
|
107
|
+
q = q.replace(**kwargs)
|
|
108
|
+
if q.nct_only_query and q.has_filters:
|
|
109
|
+
warnings.warn(
|
|
110
|
+
"a query.* parameter contains only NCT IDs, so the API ignores all filter.*, "
|
|
111
|
+
"postFilter.* and aggFilters parameters",
|
|
112
|
+
UserWarning,
|
|
113
|
+
stacklevel=3,
|
|
114
|
+
)
|
|
115
|
+
return q
|
|
116
|
+
|
|
117
|
+
@staticmethod
|
|
118
|
+
def _paging_params(
|
|
119
|
+
*,
|
|
120
|
+
page_size: int | None,
|
|
121
|
+
page_token: str | None,
|
|
122
|
+
count_total: bool,
|
|
123
|
+
markup_format: MarkupFormat | None,
|
|
124
|
+
fmt: str,
|
|
125
|
+
) -> dict[str, str]:
|
|
126
|
+
params = {"format": fmt}
|
|
127
|
+
if page_size is not None:
|
|
128
|
+
if page_size < 0:
|
|
129
|
+
raise ValueError("page_size must be >= 0")
|
|
130
|
+
params["pageSize"] = str(page_size)
|
|
131
|
+
if page_token:
|
|
132
|
+
params["pageToken"] = page_token
|
|
133
|
+
if count_total:
|
|
134
|
+
params["countTotal"] = "true"
|
|
135
|
+
if markup_format:
|
|
136
|
+
params["markupFormat"] = markup_format
|
|
137
|
+
return params
|
|
138
|
+
|
|
139
|
+
@overload
|
|
140
|
+
def search_studies_raw(
|
|
141
|
+
self,
|
|
142
|
+
query: StudyQuery | None = None,
|
|
143
|
+
*,
|
|
144
|
+
format: Literal["json"] = "json",
|
|
145
|
+
page_size: int | None = None,
|
|
146
|
+
page_token: str | None = None,
|
|
147
|
+
count_total: bool = False,
|
|
148
|
+
markup_format: MarkupFormat | None = None,
|
|
149
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
150
|
+
) -> PagedStudiesDict: ...
|
|
151
|
+
|
|
152
|
+
@overload
|
|
153
|
+
def search_studies_raw(
|
|
154
|
+
self,
|
|
155
|
+
query: StudyQuery | None = None,
|
|
156
|
+
*,
|
|
157
|
+
format: Literal["csv"],
|
|
158
|
+
page_size: int | None = None,
|
|
159
|
+
page_token: str | None = None,
|
|
160
|
+
count_total: bool = False,
|
|
161
|
+
markup_format: MarkupFormat | None = None,
|
|
162
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
163
|
+
) -> str: ...
|
|
164
|
+
|
|
165
|
+
def search_studies_raw(
|
|
166
|
+
self,
|
|
167
|
+
query: StudyQuery | None = None,
|
|
168
|
+
*,
|
|
169
|
+
format: Literal["json", "csv"] = "json",
|
|
170
|
+
page_size: int | None = None,
|
|
171
|
+
page_token: str | None = None,
|
|
172
|
+
count_total: bool = False,
|
|
173
|
+
markup_format: MarkupFormat | None = None,
|
|
174
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
175
|
+
) -> PagedStudiesDict | str:
|
|
176
|
+
"""One page of ``GET /studies`` as the API returns it.
|
|
177
|
+
|
|
178
|
+
``format="json"`` returns the parsed ``{"studies": [...], "nextPageToken": ...}``
|
|
179
|
+
dict; ``format="csv"`` returns CSV text (the total count, if requested, is in the
|
|
180
|
+
``x-total-count`` header and therefore not available here — use :meth:`count_studies`).
|
|
181
|
+
"""
|
|
182
|
+
response = self._fetch_page(
|
|
183
|
+
self._build_query(query, kwargs),
|
|
184
|
+
fmt=format,
|
|
185
|
+
page_size=page_size,
|
|
186
|
+
page_token=page_token,
|
|
187
|
+
count_total=count_total,
|
|
188
|
+
markup_format=markup_format,
|
|
189
|
+
)
|
|
190
|
+
if format == "csv":
|
|
191
|
+
return response.text
|
|
192
|
+
return cast("PagedStudiesDict", response.json())
|
|
193
|
+
|
|
194
|
+
def _fetch_page(
|
|
195
|
+
self,
|
|
196
|
+
q: StudyQuery,
|
|
197
|
+
*,
|
|
198
|
+
fmt: str,
|
|
199
|
+
page_size: int | None,
|
|
200
|
+
page_token: str | None,
|
|
201
|
+
count_total: bool,
|
|
202
|
+
markup_format: MarkupFormat | None,
|
|
203
|
+
) -> httpx.Response:
|
|
204
|
+
params = {
|
|
205
|
+
**q.to_params(),
|
|
206
|
+
**self._paging_params(
|
|
207
|
+
page_size=page_size,
|
|
208
|
+
page_token=page_token,
|
|
209
|
+
count_total=count_total,
|
|
210
|
+
markup_format=markup_format,
|
|
211
|
+
fmt=fmt,
|
|
212
|
+
),
|
|
213
|
+
}
|
|
214
|
+
return self.http.get("studies", params=params)
|
|
215
|
+
|
|
216
|
+
def search_studies(
|
|
217
|
+
self,
|
|
218
|
+
query: StudyQuery | None = None,
|
|
219
|
+
*,
|
|
220
|
+
page_size: int | None = None,
|
|
221
|
+
page_token: str | None = None,
|
|
222
|
+
count_total: bool = False,
|
|
223
|
+
markup_format: MarkupFormat | None = None,
|
|
224
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
225
|
+
) -> StudiesPage:
|
|
226
|
+
"""One page of ``GET /studies`` as typed :class:`~trialmap.models.Study` objects.
|
|
227
|
+
|
|
228
|
+
Pass the returned ``next_page_token`` back as ``page_token`` together with the *same*
|
|
229
|
+
search parameters to get the next page — or just use :meth:`iter_studies`.
|
|
230
|
+
"""
|
|
231
|
+
data = self.search_studies_raw(
|
|
232
|
+
query,
|
|
233
|
+
page_size=page_size,
|
|
234
|
+
page_token=page_token,
|
|
235
|
+
count_total=count_total,
|
|
236
|
+
markup_format=markup_format,
|
|
237
|
+
**kwargs,
|
|
238
|
+
)
|
|
239
|
+
return StudiesPage(
|
|
240
|
+
studies=tuple(Study.from_raw(s) for s in data.get("studies", [])),
|
|
241
|
+
next_page_token=data.get("nextPageToken"),
|
|
242
|
+
total_count=data.get("totalCount"),
|
|
243
|
+
)
|
|
244
|
+
|
|
245
|
+
def iter_pages(
|
|
246
|
+
self,
|
|
247
|
+
query: StudyQuery | None = None,
|
|
248
|
+
*,
|
|
249
|
+
page_size: int = MAX_PAGE_SIZE,
|
|
250
|
+
max_studies: int | None = None,
|
|
251
|
+
count_total: bool = False,
|
|
252
|
+
markup_format: MarkupFormat | None = None,
|
|
253
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
254
|
+
) -> Iterator[PagedStudiesDict]:
|
|
255
|
+
"""Yield raw result pages, following ``nextPageToken`` until the last page.
|
|
256
|
+
|
|
257
|
+
``max_studies`` stops after that many studies in total (the last page is requested
|
|
258
|
+
with a smaller ``pageSize`` so no data is fetched and thrown away).
|
|
259
|
+
"""
|
|
260
|
+
if max_studies is not None and max_studies <= 0:
|
|
261
|
+
return
|
|
262
|
+
q = self._build_query(query, kwargs)
|
|
263
|
+
page_size = min(max(page_size, 1), MAX_PAGE_SIZE)
|
|
264
|
+
token: str | None = None
|
|
265
|
+
seen = 0
|
|
266
|
+
while True:
|
|
267
|
+
size = page_size if max_studies is None else min(page_size, max_studies - seen)
|
|
268
|
+
page = cast(
|
|
269
|
+
"PagedStudiesDict",
|
|
270
|
+
self._fetch_page(
|
|
271
|
+
q,
|
|
272
|
+
fmt="json",
|
|
273
|
+
page_size=size,
|
|
274
|
+
page_token=token,
|
|
275
|
+
count_total=count_total and token is None,
|
|
276
|
+
markup_format=markup_format,
|
|
277
|
+
).json(),
|
|
278
|
+
)
|
|
279
|
+
studies = page.get("studies", [])
|
|
280
|
+
if max_studies is not None and seen + len(studies) > max_studies:
|
|
281
|
+
page = {**page, "studies": studies[: max_studies - seen]}
|
|
282
|
+
seen += len(page.get("studies", []))
|
|
283
|
+
log.debug("page: %d studies (total so far %d)", len(studies), seen)
|
|
284
|
+
yield page
|
|
285
|
+
token = page.get("nextPageToken")
|
|
286
|
+
# A page may legitimately be empty; only a missing token marks the end.
|
|
287
|
+
if not token or (max_studies is not None and seen >= max_studies):
|
|
288
|
+
return
|
|
289
|
+
|
|
290
|
+
@overload
|
|
291
|
+
def iter_studies(
|
|
292
|
+
self,
|
|
293
|
+
query: StudyQuery | None = None,
|
|
294
|
+
*,
|
|
295
|
+
raw: Literal[False] = False,
|
|
296
|
+
page_size: int = MAX_PAGE_SIZE,
|
|
297
|
+
max_studies: int | None = None,
|
|
298
|
+
markup_format: MarkupFormat | None = None,
|
|
299
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
300
|
+
) -> Iterator[Study]: ...
|
|
301
|
+
|
|
302
|
+
@overload
|
|
303
|
+
def iter_studies(
|
|
304
|
+
self,
|
|
305
|
+
query: StudyQuery | None = None,
|
|
306
|
+
*,
|
|
307
|
+
raw: Literal[True],
|
|
308
|
+
page_size: int = MAX_PAGE_SIZE,
|
|
309
|
+
max_studies: int | None = None,
|
|
310
|
+
markup_format: MarkupFormat | None = None,
|
|
311
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
312
|
+
) -> Iterator[StudyDict]: ...
|
|
313
|
+
|
|
314
|
+
def iter_studies(
|
|
315
|
+
self,
|
|
316
|
+
query: StudyQuery | None = None,
|
|
317
|
+
*,
|
|
318
|
+
raw: bool = False,
|
|
319
|
+
page_size: int = MAX_PAGE_SIZE,
|
|
320
|
+
max_studies: int | None = None,
|
|
321
|
+
markup_format: MarkupFormat | None = None,
|
|
322
|
+
**kwargs: Unpack[StudyQueryParams],
|
|
323
|
+
) -> Iterator[Study] | Iterator[StudyDict]:
|
|
324
|
+
"""Yield every matching study across all pages.
|
|
325
|
+
|
|
326
|
+
>>> for s in ct.iter_studies(query_spons='"National Cancer Institute"', # doctest: +SKIP
|
|
327
|
+
... filter_overall_status=[Status.RECRUITING]):
|
|
328
|
+
... ...
|
|
329
|
+
|
|
330
|
+
Args:
|
|
331
|
+
raw: yield the JSON dicts instead of :class:`~trialmap.models.Study` objects.
|
|
332
|
+
page_size: studies per request (max 1000).
|
|
333
|
+
max_studies: stop after this many studies.
|
|
334
|
+
"""
|
|
335
|
+
pages = self.iter_pages(
|
|
336
|
+
query,
|
|
337
|
+
page_size=page_size,
|
|
338
|
+
max_studies=max_studies,
|
|
339
|
+
markup_format=markup_format,
|
|
340
|
+
**kwargs,
|
|
341
|
+
)
|
|
342
|
+
if raw:
|
|
343
|
+
return (s for page in pages for s in page.get("studies", []))
|
|
344
|
+
return (Study.from_raw(s) for page in pages for s in page.get("studies", []))
|
|
345
|
+
|
|
346
|
+
def count_studies(
|
|
347
|
+
self, query: StudyQuery | None = None, **kwargs: Unpack[StudyQueryParams]
|
|
348
|
+
) -> int:
|
|
349
|
+
"""Number of studies matching a search (one small request)."""
|
|
350
|
+
q = self._build_query(query, kwargs).replace(fields=["NCTId"])
|
|
351
|
+
response = self._fetch_page(
|
|
352
|
+
q, fmt="json", page_size=1, page_token=None, count_total=True, markup_format=None
|
|
353
|
+
)
|
|
354
|
+
return int(response.json().get("totalCount", 0))
|
|
355
|
+
|
|
356
|
+
# ================================================================== /studies/{nctId}
|
|
357
|
+
|
|
358
|
+
@overload
|
|
359
|
+
def get_study_raw(
|
|
360
|
+
self,
|
|
361
|
+
nct_id: str,
|
|
362
|
+
*,
|
|
363
|
+
format: Literal["json"] = "json",
|
|
364
|
+
fields: str | Sequence[str] | None = None,
|
|
365
|
+
markup_format: MarkupFormat | None = None,
|
|
366
|
+
) -> StudyDict: ...
|
|
367
|
+
|
|
368
|
+
@overload
|
|
369
|
+
def get_study_raw(
|
|
370
|
+
self,
|
|
371
|
+
nct_id: str,
|
|
372
|
+
*,
|
|
373
|
+
format: Literal["fhir.json"],
|
|
374
|
+
fields: str | Sequence[str] | None = None,
|
|
375
|
+
markup_format: MarkupFormat | None = None,
|
|
376
|
+
) -> dict[str, Any]: ...
|
|
377
|
+
|
|
378
|
+
@overload
|
|
379
|
+
def get_study_raw(
|
|
380
|
+
self,
|
|
381
|
+
nct_id: str,
|
|
382
|
+
*,
|
|
383
|
+
format: Literal["csv", "ris"],
|
|
384
|
+
fields: str | Sequence[str] | None = None,
|
|
385
|
+
markup_format: MarkupFormat | None = None,
|
|
386
|
+
) -> str: ...
|
|
387
|
+
|
|
388
|
+
@overload
|
|
389
|
+
def get_study_raw(
|
|
390
|
+
self,
|
|
391
|
+
nct_id: str,
|
|
392
|
+
*,
|
|
393
|
+
format: Literal["json.zip"],
|
|
394
|
+
fields: str | Sequence[str] | None = None,
|
|
395
|
+
markup_format: MarkupFormat | None = None,
|
|
396
|
+
) -> bytes: ...
|
|
397
|
+
|
|
398
|
+
def get_study_raw(
|
|
399
|
+
self,
|
|
400
|
+
nct_id: str,
|
|
401
|
+
*,
|
|
402
|
+
format: SingleStudyFormat = "json",
|
|
403
|
+
fields: str | Sequence[str] | None = None,
|
|
404
|
+
markup_format: MarkupFormat | None = None,
|
|
405
|
+
) -> StudyDict | dict[str, Any] | str | bytes:
|
|
406
|
+
"""``GET /studies/{nctId}`` in any supported format.
|
|
407
|
+
|
|
408
|
+
Alias NCT IDs are redirected (HTTP 301) to the current record automatically.
|
|
409
|
+
Raises :class:`~trialmap.exceptions.NotFoundError` for unknown IDs.
|
|
410
|
+
"""
|
|
411
|
+
params: dict[str, str] = {"format": format}
|
|
412
|
+
if fields:
|
|
413
|
+
params["fields"] = _serialise(fields)
|
|
414
|
+
if markup_format:
|
|
415
|
+
params["markupFormat"] = markup_format
|
|
416
|
+
response = self.http.get(f"studies/{nct_id.strip().upper()}", params=params)
|
|
417
|
+
if format in ("json", "fhir.json"):
|
|
418
|
+
return cast("dict[str, Any]", response.json())
|
|
419
|
+
if format == "json.zip":
|
|
420
|
+
return response.content
|
|
421
|
+
return response.text
|
|
422
|
+
|
|
423
|
+
def get_study(
|
|
424
|
+
self,
|
|
425
|
+
nct_id: str,
|
|
426
|
+
*,
|
|
427
|
+
fields: str | Sequence[str] | None = None,
|
|
428
|
+
markup_format: MarkupFormat | None = None,
|
|
429
|
+
) -> Study:
|
|
430
|
+
"""``GET /studies/{nctId}`` as a typed :class:`~trialmap.models.Study`."""
|
|
431
|
+
return Study.from_raw(
|
|
432
|
+
self.get_study_raw(nct_id, fields=fields, markup_format=markup_format)
|
|
433
|
+
)
|
|
434
|
+
|
|
435
|
+
# ================================================================== metadata
|
|
436
|
+
|
|
437
|
+
def metadata(
|
|
438
|
+
self, *, include_indexed_only: bool = False, include_historic_only: bool = False
|
|
439
|
+
) -> list[FieldNodeDict]:
|
|
440
|
+
"""``GET /studies/metadata``: the tree of every field in the study data structure."""
|
|
441
|
+
params = {}
|
|
442
|
+
if include_indexed_only:
|
|
443
|
+
params["includeIndexedOnly"] = "true"
|
|
444
|
+
if include_historic_only:
|
|
445
|
+
params["includeHistoricOnly"] = "true"
|
|
446
|
+
return cast("list[FieldNodeDict]", self.http.get("studies/metadata", params=params).json())
|
|
447
|
+
|
|
448
|
+
def search_areas(self) -> list[SearchDocumentDict]:
|
|
449
|
+
"""``GET /studies/search-areas``: which fields each ``query.*`` parameter searches."""
|
|
450
|
+
return cast("list[SearchDocumentDict]", self.http.get("studies/search-areas").json())
|
|
451
|
+
|
|
452
|
+
def enums(self) -> list[EnumInfoDict]:
|
|
453
|
+
"""``GET /studies/enums``: every enum type, its values and the fields that use it."""
|
|
454
|
+
return cast("list[EnumInfoDict]", self.http.get("studies/enums").json())
|
|
455
|
+
|
|
456
|
+
# ================================================================== /stats
|
|
457
|
+
|
|
458
|
+
def size_stats(self) -> GzipStatsDict:
|
|
459
|
+
"""``GET /stats/size``: distribution of gzipped study record sizes."""
|
|
460
|
+
return cast("GzipStatsDict", self.http.get("stats/size").json())
|
|
461
|
+
|
|
462
|
+
def field_values(
|
|
463
|
+
self,
|
|
464
|
+
fields: str | Sequence[str] | None = None,
|
|
465
|
+
*,
|
|
466
|
+
types: FieldStatsType | str | Sequence[FieldStatsType | str] | None = None,
|
|
467
|
+
) -> list[FieldValuesStatsDict]:
|
|
468
|
+
"""``GET /stats/field/values``: value statistics (top values, counts) per leaf field."""
|
|
469
|
+
params = {}
|
|
470
|
+
if fields:
|
|
471
|
+
params["fields"] = _serialise(fields)
|
|
472
|
+
if types:
|
|
473
|
+
params["types"] = _serialise(types)
|
|
474
|
+
return cast(
|
|
475
|
+
"list[FieldValuesStatsDict]", self.http.get("stats/field/values", params=params).json()
|
|
476
|
+
)
|
|
477
|
+
|
|
478
|
+
def field_sizes(self, fields: str | Sequence[str] | None = None) -> list[ListSizesDict]:
|
|
479
|
+
"""``GET /stats/field/sizes``: size statistics for list/array fields."""
|
|
480
|
+
params = {"fields": _serialise(fields)} if fields else {}
|
|
481
|
+
return cast("list[ListSizesDict]", self.http.get("stats/field/sizes", params=params).json())
|
|
482
|
+
|
|
483
|
+
# ================================================================== /version
|
|
484
|
+
|
|
485
|
+
def version(self) -> VersionDict:
|
|
486
|
+
"""``GET /version``: API version and data timestamp."""
|
|
487
|
+
return cast("VersionDict", self.http.get("version").json())
|