vanda-api 1.1.0__tar.gz → 1.1.2__tar.gz
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.
- {vanda_api-1.1.0 → vanda_api-1.1.2}/CHANGELOG.md +22 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/PKG-INFO +25 -6
- {vanda_api-1.1.0 → vanda_api-1.1.2}/README.md +24 -5
- {vanda_api-1.1.0 → vanda_api-1.1.2}/pyproject.toml +1 -1
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/__init__.py +1 -1
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/models.py +9 -3
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_flow.py +92 -13
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_positioning.py +43 -23
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/flow.py +92 -13
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/positioning.py +43 -23
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_flow_client.py +146 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_positioning_client.py +82 -1
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_flow_client.py +168 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_positioning_client.py +74 -1
- {vanda_api-1.1.0 → vanda_api-1.1.2}/.gitignore +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/LICENSE +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/_base/__init__.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/_base/async_base_client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/_base/base_client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/async_auth.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/async_client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/auth.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/errors.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/retry.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/__init__.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/aggregates.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_aggregates.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/async_series.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/services/series.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/__init__.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/dates.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/deprecation.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/io.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/normalize.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/src/vanda/utils/params.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/__init__.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_aggregates_client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_aggregates_client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_async_series_client.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_auth.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_dates.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_normalize.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_retry.py +0 -0
- {vanda_api-1.1.0 → vanda_api-1.1.2}/tests/test_series_client.py +0 -0
|
@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.1.2] - 2026-11-13
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
- `version` and `revision` on `flow.get_timeseries()`, `flow.get_latest()` and `flow.export_timeseries()`, sent only when set. `revision` takes `"prefer_restated"` (the service default), `"restated"` or `"point_in_time"`; the strict values leave out series without that revision, and none having it raises `NotFoundError`. An unknown `version` also raises `NotFoundError`
|
|
12
|
+
- Flow responses keep the envelope's `revision`, `requested_revision` and `missing_revision`
|
|
13
|
+
- `FlowRevision` and `PositioningMetric` types
|
|
14
|
+
- Windows `"2"`, `"3"`, `"4"`, `"6"`, `"12"`, `"13"`, `"26"` and `"52"`, for weekly, bi-weekly and monthly series
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- `metric` on positioning's `get_timeseries()`, `get_latest()` and `export_timeseries()` is optional and no longer sent by default, so the service serves each series' headline metric. Pass it to pin one; an unknown metric raises `VandaError` (HTTP 400) naming the valid ones
|
|
18
|
+
- Positioning docs follow the service's raw default: omit `normalisation` for stored values (`"none"` means the same), `normalisation` alone runs over `"All"`, and `normalisation_period` alone means `"zscore"`
|
|
19
|
+
- Docs: windows count observations, not days; positioning `revision` is strict; flow `list_catalog()` describes `versions`, `revisions`, `lag` and `update_time`
|
|
20
|
+
|
|
21
|
+
## [1.1.1] - 2026-10-02
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
- `scenarios` on `flow.get_forecast()` - several branches of the cube in one call, as a sequence, a comma-separated string, or `"*"` for every one published. Mutually exclusive with `scenario`, which the SDK refuses before the round trip
|
|
25
|
+
- The response's `scenarios` list is preserved; with several branches the top-level `scenario` is `None` and each group carries its own
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
- `dimensions` on `flow.get_timeseries()` now documents the service's history-only rule: a forecast series' history is its neutral cell (`{"projection": 0, "zscore": "All"}`), and any other cell is refused with a 400. Read the cube with `get_forecast()`
|
|
29
|
+
|
|
8
30
|
## [1.1.0] - 2026-09-23
|
|
9
31
|
|
|
10
32
|
### Added
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: vanda-api
|
|
3
|
-
Version: 1.1.
|
|
3
|
+
Version: 1.1.2
|
|
4
4
|
Summary: Official Python SDK for Vanda Analytics Data API
|
|
5
5
|
Project-URL: Homepage, https://gitlab.com/yourusername/vanda-api
|
|
6
6
|
Project-URL: Documentation, https://gitlab.com/yourusername/vanda-api#readme
|
|
@@ -408,17 +408,20 @@ complete. That holds as long as *something* resolved - a request where no
|
|
|
408
408
|
identifier matches is a 404 and raises `NotFoundError`.
|
|
409
409
|
|
|
410
410
|
Some flow datasets are published as a cube rather than a flat series, with a
|
|
411
|
-
value per combination of dimensions.
|
|
411
|
+
value per combination of dimensions. `get_timeseries()` serves **history only**,
|
|
412
|
+
and a forecast series' history is its neutral cell, so that is the one cell
|
|
413
|
+
`dimensions` will pin here:
|
|
412
414
|
|
|
413
415
|
```python
|
|
414
416
|
data = client.flow.get_timeseries(
|
|
415
|
-
series_ids=slug, dimensions={"projection":
|
|
417
|
+
series_ids=slug, dimensions={"projection": 0, "zscore": "All"}
|
|
416
418
|
)
|
|
417
419
|
```
|
|
418
420
|
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
421
|
+
Any other cell is refused with a 400 - read the cube with `get_forecast()`
|
|
422
|
+
instead. It is sent as JSON because the types decide what matches:
|
|
423
|
+
`projection` is stored as a number and `zscore` as a string, so
|
|
424
|
+
`{"projection": "0"}` matches nothing at all.
|
|
422
425
|
|
|
423
426
|
Intraday series (FX options) are capped at 31 days per request. A request with
|
|
424
427
|
no dates returns the most recent 31 days rather than the full history, a longer
|
|
@@ -453,6 +456,22 @@ with VandaClient(token="YOUR_TOKEN_HERE") as client:
|
|
|
453
456
|
print(group["horizon"], group["component"], group["metrics"])
|
|
454
457
|
```
|
|
455
458
|
|
|
459
|
+
Ask for several branches at once with `scenarios` - a sequence, a
|
|
460
|
+
comma-separated string, or `"*"` for every one published:
|
|
461
|
+
|
|
462
|
+
```python
|
|
463
|
+
whole_run = client.flow.get_forecast(
|
|
464
|
+
series_ids="AUFXFUTUAUDMIXINSSPECTA", scenarios="*", horizons=[5], metrics="px"
|
|
465
|
+
)
|
|
466
|
+
print(whole_run["scenarios"]) # every branch served, in axis order
|
|
467
|
+
print(whole_run["data"][0]["scenario"]) # the branch is now part of the grain
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
`scenario` and `scenarios` are mutually exclusive. With `scenarios` the
|
|
471
|
+
top-level `scenario` is `None` and each group carries its own instead. A cta run
|
|
472
|
+
is 64 scenarios x 16 horizons, so narrow with `metrics` or `horizons` unless you
|
|
473
|
+
really want the lot.
|
|
474
|
+
|
|
456
475
|
Rows come back as one group per (series, component, horizon), with every metric
|
|
457
476
|
nested inside - a forecast is read as a point on a path. Horizon 0 is the run
|
|
458
477
|
date itself, so on the z-score axis it exists only for the unconditional
|
|
@@ -370,17 +370,20 @@ complete. That holds as long as *something* resolved - a request where no
|
|
|
370
370
|
identifier matches is a 404 and raises `NotFoundError`.
|
|
371
371
|
|
|
372
372
|
Some flow datasets are published as a cube rather than a flat series, with a
|
|
373
|
-
value per combination of dimensions.
|
|
373
|
+
value per combination of dimensions. `get_timeseries()` serves **history only**,
|
|
374
|
+
and a forecast series' history is its neutral cell, so that is the one cell
|
|
375
|
+
`dimensions` will pin here:
|
|
374
376
|
|
|
375
377
|
```python
|
|
376
378
|
data = client.flow.get_timeseries(
|
|
377
|
-
series_ids=slug, dimensions={"projection":
|
|
379
|
+
series_ids=slug, dimensions={"projection": 0, "zscore": "All"}
|
|
378
380
|
)
|
|
379
381
|
```
|
|
380
382
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
383
|
+
Any other cell is refused with a 400 - read the cube with `get_forecast()`
|
|
384
|
+
instead. It is sent as JSON because the types decide what matches:
|
|
385
|
+
`projection` is stored as a number and `zscore` as a string, so
|
|
386
|
+
`{"projection": "0"}` matches nothing at all.
|
|
384
387
|
|
|
385
388
|
Intraday series (FX options) are capped at 31 days per request. A request with
|
|
386
389
|
no dates returns the most recent 31 days rather than the full history, a longer
|
|
@@ -415,6 +418,22 @@ with VandaClient(token="YOUR_TOKEN_HERE") as client:
|
|
|
415
418
|
print(group["horizon"], group["component"], group["metrics"])
|
|
416
419
|
```
|
|
417
420
|
|
|
421
|
+
Ask for several branches at once with `scenarios` - a sequence, a
|
|
422
|
+
comma-separated string, or `"*"` for every one published:
|
|
423
|
+
|
|
424
|
+
```python
|
|
425
|
+
whole_run = client.flow.get_forecast(
|
|
426
|
+
series_ids="AUFXFUTUAUDMIXINSSPECTA", scenarios="*", horizons=[5], metrics="px"
|
|
427
|
+
)
|
|
428
|
+
print(whole_run["scenarios"]) # every branch served, in axis order
|
|
429
|
+
print(whole_run["data"][0]["scenario"]) # the branch is now part of the grain
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
`scenario` and `scenarios` are mutually exclusive. With `scenarios` the
|
|
433
|
+
top-level `scenario` is `None` and each group carries its own instead. A cta run
|
|
434
|
+
is 64 scenarios x 16 horizons, so narrow with `metrics` or `horizons` unless you
|
|
435
|
+
really want the lot.
|
|
436
|
+
|
|
418
437
|
Rows come back as one group per (series, component, horizon), with every metric
|
|
419
438
|
nested inside - a forecast is read as a point on a path. Horizon 0 is the run
|
|
420
439
|
date itself, so on the z-score axis it exists only for the unconditional
|
|
@@ -52,11 +52,17 @@ CompressionType = Literal["none", "gzip", "zip"]
|
|
|
52
52
|
StreamFormat = Literal["ndjson", "csv"]
|
|
53
53
|
|
|
54
54
|
Revision = Literal["restated", "point_in_time"]
|
|
55
|
-
|
|
55
|
+
# Flow alone has a default that picks per series: restated where it exists, else point in time.
|
|
56
|
+
FlowRevision = Literal["prefer_restated", "restated", "point_in_time"]
|
|
57
|
+
# Catalog-driven: /positioning/catalog/facets?dimensions=metric lists the valid values.
|
|
58
|
+
PositioningMetric = str
|
|
56
59
|
SortOrder = Literal["asc", "desc"]
|
|
57
60
|
Transformation = Literal["rolling_sum", "moving_avg"]
|
|
58
|
-
|
|
61
|
+
# In observations, not days: the trailing values suit weekly, bi-weekly and monthly series.
|
|
62
|
+
Window = Literal[
|
|
63
|
+
"5", "20", "30", "60", "90", "120", "252", "2", "3", "4", "6", "12", "13", "26", "52"
|
|
64
|
+
]
|
|
59
65
|
Normalisation = Literal["zscore", "percentile_rank"]
|
|
60
|
-
# Positioning
|
|
66
|
+
# Positioning still accepts "none", now the same as omitting normalisation.
|
|
61
67
|
PositioningNormalisation = Literal["zscore", "percentile_rank", "none"]
|
|
62
68
|
NormalisationPeriod = Literal["3m", "6m", "1y", "2y", "5y", "Expanding", "All"]
|
|
@@ -8,6 +8,7 @@ from vanda.errors import ValidationError, VandaError
|
|
|
8
8
|
from vanda.models import (
|
|
9
9
|
CompressionType,
|
|
10
10
|
ExportFormat,
|
|
11
|
+
FlowRevision,
|
|
11
12
|
Normalisation,
|
|
12
13
|
NormalisationPeriod,
|
|
13
14
|
SortOrder,
|
|
@@ -29,14 +30,27 @@ _TIMESERIES_KEYS = (
|
|
|
29
30
|
"frequencies",
|
|
30
31
|
"unresolved",
|
|
31
32
|
"pagination",
|
|
33
|
+
"revision",
|
|
34
|
+
"requested_revision",
|
|
35
|
+
"missing_revision",
|
|
36
|
+
)
|
|
37
|
+
_LATEST_KEYS = (
|
|
38
|
+
"count",
|
|
39
|
+
"series_ids",
|
|
40
|
+
"metrics",
|
|
41
|
+
"frequencies",
|
|
42
|
+
"unresolved",
|
|
43
|
+
"revision",
|
|
44
|
+
"requested_revision",
|
|
45
|
+
"missing_revision",
|
|
32
46
|
)
|
|
33
|
-
_LATEST_KEYS = ("count", "series_ids", "metrics", "frequencies", "unresolved")
|
|
34
47
|
_CATALOG_KEYS = ("count", "pagination")
|
|
35
48
|
_FORECAST_RUNS_KEYS = ("count", "unresolved", "pagination")
|
|
36
49
|
_FORECAST_KEYS = (
|
|
37
50
|
"count",
|
|
38
51
|
"run_date",
|
|
39
52
|
"scenario",
|
|
53
|
+
"scenarios",
|
|
40
54
|
"series_labels",
|
|
41
55
|
"metrics",
|
|
42
56
|
"unresolved",
|
|
@@ -64,6 +78,8 @@ class AsyncFlowAPI:
|
|
|
64
78
|
normalisation: Optional[Normalisation] = None,
|
|
65
79
|
normalisation_period: Optional[NormalisationPeriod] = None,
|
|
66
80
|
dimensions: Optional[Union[dict[str, Any], str]] = None,
|
|
81
|
+
version: Optional[str] = None,
|
|
82
|
+
revision: Optional[FlowRevision] = None,
|
|
67
83
|
) -> dict[str, Any]:
|
|
68
84
|
"""
|
|
69
85
|
Get flow timeseries data.
|
|
@@ -85,21 +101,39 @@ class AsyncFlowAPI:
|
|
|
85
101
|
normalisation: "zscore" or "percentile_rank". Requires
|
|
86
102
|
normalisation_period.
|
|
87
103
|
normalisation_period: Lookback for the normalisation.
|
|
88
|
-
dimensions:
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
104
|
+
dimensions: Pin one cell of a dimensioned dataset, as a dict. Sent
|
|
105
|
+
as JSON because the types matter: projection is stored as a
|
|
106
|
+
number and zscore as a string. This endpoint serves history
|
|
107
|
+
only, and a forecast series' history is its neutral cell, so
|
|
108
|
+
{"projection": 0, "zscore": "All"} (or "ret": 0 for gamma) is
|
|
109
|
+
accepted and changes nothing while any other cell is a 400 -
|
|
110
|
+
read the cube with get_forecast(). A dataset that publishes no
|
|
111
|
+
dimensions matches nothing.
|
|
112
|
+
version: Model version, e.g. "V2" ("2" and "v2" also work). Selects
|
|
113
|
+
series, not rows. Omit it and each label serves the newest
|
|
114
|
+
version of every metric it publishes.
|
|
115
|
+
revision: "prefer_restated" (the service default when omitted),
|
|
116
|
+
"restated" or "point_in_time". The default serves each series
|
|
117
|
+
restated where it has restated rows, else point in time. The
|
|
118
|
+
other two are strict: a series without that revision is left
|
|
119
|
+
out and listed in "missing_revision". Point in time never falls
|
|
120
|
+
back to restated, so a backtest cannot see later revisions.
|
|
92
121
|
|
|
93
122
|
Returns:
|
|
94
123
|
Records under "data", plus count, series, series_ids, metrics,
|
|
95
|
-
frequencies, unresolved
|
|
96
|
-
|
|
124
|
+
frequencies, unresolved, pagination, revision, requested_revision
|
|
125
|
+
and missing_revision. Each record carries its own "revision"; the
|
|
126
|
+
top-level "revision" is None when the series served differ.
|
|
127
|
+
Identifiers that matched nothing are listed in "unresolved" rather
|
|
128
|
+
than failing the request.
|
|
97
129
|
If the transformation service fails, the untransformed rows are
|
|
98
130
|
returned with "transformation" reporting status "Failure" rather
|
|
99
131
|
than raising.
|
|
100
132
|
|
|
101
133
|
Raises:
|
|
102
134
|
ValidationError: If parameters are invalid.
|
|
135
|
+
NotFoundError: If a metric or version matches no series, or a
|
|
136
|
+
strict revision leaves nothing to serve.
|
|
103
137
|
"""
|
|
104
138
|
params: dict[str, Any] = {
|
|
105
139
|
"series_ids": csv_param(series_ids),
|
|
@@ -116,6 +150,10 @@ class AsyncFlowAPI:
|
|
|
116
150
|
params["dimensions"] = (
|
|
117
151
|
dimensions if isinstance(dimensions, str) else json.dumps(dimensions)
|
|
118
152
|
)
|
|
153
|
+
if version:
|
|
154
|
+
params["version"] = version
|
|
155
|
+
if revision:
|
|
156
|
+
params["revision"] = revision
|
|
119
157
|
|
|
120
158
|
if start_date:
|
|
121
159
|
params["start_date"] = format_date(start_date)
|
|
@@ -164,6 +202,8 @@ class AsyncFlowAPI:
|
|
|
164
202
|
metrics: Optional[Union[str, Sequence[str]]] = None,
|
|
165
203
|
frequency: Optional[Union[str, Sequence[str]]] = None,
|
|
166
204
|
as_of: Optional[Union[str, date, datetime]] = None,
|
|
205
|
+
version: Optional[str] = None,
|
|
206
|
+
revision: Optional[FlowRevision] = None,
|
|
167
207
|
) -> dict[str, Any]:
|
|
168
208
|
"""
|
|
169
209
|
Get the latest observation for each series.
|
|
@@ -174,10 +214,13 @@ class AsyncFlowAPI:
|
|
|
174
214
|
metrics: Metrics to select; omit for all.
|
|
175
215
|
frequency: Cadences to select; omit for all.
|
|
176
216
|
as_of: Return the latest observation on or before this date.
|
|
217
|
+
version: Model version, as for get_timeseries().
|
|
218
|
+
revision: "prefer_restated" (default), "restated" or
|
|
219
|
+
"point_in_time", as for get_timeseries().
|
|
177
220
|
|
|
178
221
|
Returns:
|
|
179
|
-
Records under "data", plus count, series_ids, metrics, frequencies
|
|
180
|
-
and
|
|
222
|
+
Records under "data", plus count, series_ids, metrics, frequencies,
|
|
223
|
+
unresolved, revision, requested_revision and missing_revision.
|
|
181
224
|
"""
|
|
182
225
|
params: dict[str, Any] = {"series_ids": csv_param(series_ids)}
|
|
183
226
|
|
|
@@ -187,6 +230,10 @@ class AsyncFlowAPI:
|
|
|
187
230
|
params["frequency"] = csv_param(frequency)
|
|
188
231
|
if as_of:
|
|
189
232
|
params["as_of"] = format_date(as_of)
|
|
233
|
+
if version:
|
|
234
|
+
params["version"] = version
|
|
235
|
+
if revision:
|
|
236
|
+
params["revision"] = revision
|
|
190
237
|
|
|
191
238
|
data = await self._client._request("GET", "/flow/latest", params=params)
|
|
192
239
|
|
|
@@ -202,6 +249,8 @@ class AsyncFlowAPI:
|
|
|
202
249
|
end_date: Optional[Union[str, date, datetime]] = None,
|
|
203
250
|
export_format: ExportFormat = "csv",
|
|
204
251
|
compression: CompressionType = "none",
|
|
252
|
+
version: Optional[str] = None,
|
|
253
|
+
revision: Optional[FlowRevision] = None,
|
|
205
254
|
) -> None:
|
|
206
255
|
"""
|
|
207
256
|
Export flow timeseries to a file.
|
|
@@ -216,6 +265,9 @@ class AsyncFlowAPI:
|
|
|
216
265
|
end_date: End date (optional).
|
|
217
266
|
export_format: "csv" or "json".
|
|
218
267
|
compression: "none", "gzip", or "zip".
|
|
268
|
+
version: Model version, as for get_timeseries().
|
|
269
|
+
revision: "prefer_restated" (default), "restated" or
|
|
270
|
+
"point_in_time", as for get_timeseries().
|
|
219
271
|
|
|
220
272
|
Raises:
|
|
221
273
|
ValidationError: If parameters are invalid.
|
|
@@ -226,6 +278,10 @@ class AsyncFlowAPI:
|
|
|
226
278
|
"compression": compression,
|
|
227
279
|
}
|
|
228
280
|
|
|
281
|
+
if version:
|
|
282
|
+
params["version"] = version
|
|
283
|
+
if revision:
|
|
284
|
+
params["revision"] = revision
|
|
229
285
|
if metrics:
|
|
230
286
|
params["metrics"] = csv_param(metrics)
|
|
231
287
|
if frequency:
|
|
@@ -254,8 +310,11 @@ class AsyncFlowAPI:
|
|
|
254
310
|
Search the flow catalog.
|
|
255
311
|
|
|
256
312
|
Entries are keyed by series_label, not by series: each one carries a
|
|
257
|
-
"series" list holding the per-series slug, metric, unit and
|
|
258
|
-
Address series by "slug" — series_id changes when the pipeline
|
|
313
|
+
"series" list holding the per-series slug, metric, unit, frequency and
|
|
314
|
+
version. Address series by "slug" — series_id changes when the pipeline
|
|
315
|
+
reloads. Each entry's identity lists its "versions" and the "revisions"
|
|
316
|
+
it publishes, plus "lag" (days) and "update_time" (time of day) from the
|
|
317
|
+
series library.
|
|
259
318
|
|
|
260
319
|
Args:
|
|
261
320
|
q: Free text search.
|
|
@@ -294,7 +353,8 @@ class AsyncFlowAPI:
|
|
|
294
353
|
A forecast dataset publishes a cube: every combination of a horizon and
|
|
295
354
|
a scenario, for each run date. This reports the run dates, horizons,
|
|
296
355
|
components and scenario tokens, so `get_forecast()` can be called with
|
|
297
|
-
values the series actually publishes.
|
|
356
|
+
values the series actually publishes. Horizons, components and scenarios
|
|
357
|
+
come from each series' newest run; run_dates lists every run.
|
|
298
358
|
|
|
299
359
|
Args:
|
|
300
360
|
series_ids: Slugs (preferred), series labels, entities or series ids,
|
|
@@ -325,6 +385,7 @@ class AsyncFlowAPI:
|
|
|
325
385
|
run_date: Optional[Union[str, date, datetime]] = None,
|
|
326
386
|
horizons: Optional[Union[int, str, Sequence[Union[int, str]]]] = None,
|
|
327
387
|
scenario: Optional[Union[str, int, float]] = None,
|
|
388
|
+
scenarios: Optional[Union[str, Sequence[Union[str, int, float]]]] = None,
|
|
328
389
|
components: Optional[Union[str, Sequence[str]]] = None,
|
|
329
390
|
records_per_page: int = 2000,
|
|
330
391
|
page_number: int = 1,
|
|
@@ -344,6 +405,10 @@ class AsyncFlowAPI:
|
|
|
344
405
|
component - "zscore" for cta, rp and vt, "ret" for gamma - so
|
|
345
406
|
read scenario_key from get_forecast_runs() first. On the z-score
|
|
346
407
|
axis the domain mixes "All", "<0" and ">0" with numbers.
|
|
408
|
+
scenarios: Several branches at once, as a sequence or a
|
|
409
|
+
comma-separated string, or "*" for every one published - a whole
|
|
410
|
+
run in one call. Mutually exclusive with scenario. A cta run is
|
|
411
|
+
64 scenarios x 16 horizons, so narrow with metrics or horizons.
|
|
347
412
|
components: Systematic strategies to select, e.g. "cta,vt"; omit for
|
|
348
413
|
all. Each publishes its own metrics, so a group never mixes them.
|
|
349
414
|
records_per_page: Records per page (1-10000).
|
|
@@ -352,7 +417,13 @@ class AsyncFlowAPI:
|
|
|
352
417
|
Returns:
|
|
353
418
|
One group per (series, component, horizon) under "data", each
|
|
354
419
|
holding every metric for that point, plus run_date, scenario,
|
|
355
|
-
series_labels, metrics, unresolved, count and pagination.
|
|
420
|
+
scenarios, series_labels, metrics, unresolved, count and pagination.
|
|
421
|
+
With scenarios, the branch is part of the grain: every group carries
|
|
422
|
+
its own "scenario", the top-level "scenario" is None, and
|
|
423
|
+
"scenarios" lists what was served.
|
|
424
|
+
|
|
425
|
+
Raises:
|
|
426
|
+
ValidationError: If both scenario and scenarios are given.
|
|
356
427
|
|
|
357
428
|
Note:
|
|
358
429
|
Horizon 0 is the run date itself, so on the z-score axis it exists
|
|
@@ -373,12 +444,20 @@ class AsyncFlowAPI:
|
|
|
373
444
|
if run_date:
|
|
374
445
|
params["run_date"] = format_date(run_date)
|
|
375
446
|
|
|
447
|
+
if scenario is not None and scenarios is not None:
|
|
448
|
+
raise ValidationError("pass either scenario or scenarios, not both")
|
|
449
|
+
|
|
376
450
|
# Horizon 0 and scenario 0 are real values, so test against None.
|
|
377
451
|
if horizons is not None:
|
|
378
452
|
values = horizons if isinstance(horizons, (str, Sequence)) else [horizons]
|
|
379
453
|
params["horizons"] = csv_param(values)
|
|
380
454
|
if scenario is not None:
|
|
381
455
|
params["scenario"] = str(scenario)
|
|
456
|
+
if scenarios is not None:
|
|
457
|
+
# csv_param stringifies a sequence but passes a string through; mapping
|
|
458
|
+
# str() ourselves would iterate a string one character at a time.
|
|
459
|
+
branches = scenarios if isinstance(scenarios, (str, Sequence)) else [scenarios]
|
|
460
|
+
params["scenarios"] = csv_param(branches)
|
|
382
461
|
|
|
383
462
|
data = await self._client._request("GET", "/flow/forecast", params=params)
|
|
384
463
|
|
|
@@ -38,7 +38,7 @@ class AsyncPositioningAPI:
|
|
|
38
38
|
start_date: Optional[Union[str, date, datetime]] = None,
|
|
39
39
|
end_date: Optional[Union[str, date, datetime]] = None,
|
|
40
40
|
revision: Revision = "restated",
|
|
41
|
-
metric: PositioningMetric =
|
|
41
|
+
metric: Optional[PositioningMetric] = None,
|
|
42
42
|
version: Optional[str] = None,
|
|
43
43
|
order: SortOrder = "desc",
|
|
44
44
|
records_per_page: int = 2000,
|
|
@@ -55,23 +55,31 @@ class AsyncPositioningAPI:
|
|
|
55
55
|
series_ids: Series identifiers or labels, comma separated or as a sequence.
|
|
56
56
|
start_date: Start date (YYYY-MM-DD or date object).
|
|
57
57
|
end_date: End date (YYYY-MM-DD or date object).
|
|
58
|
-
revision: "restated" or "point_in_time".
|
|
59
|
-
|
|
60
|
-
|
|
58
|
+
revision: "restated" or "point_in_time". Strict: a series with no
|
|
59
|
+
rows of that revision raises NotFoundError.
|
|
60
|
+
metric: Measure to return; valid values are listed by
|
|
61
|
+
list_catalog() and the service's metric facet. Omit for each
|
|
62
|
+
series' headline: its version's "combined_positioning", or
|
|
63
|
+
"combined_score_published" where that version has none (rates V2).
|
|
64
|
+
An unknown metric raises VandaError (HTTP 400) naming the valid ones.
|
|
65
|
+
version: Model version, e.g. "V1". Omit for the latest.
|
|
61
66
|
order: "asc" or "desc" by timestamp.
|
|
62
67
|
records_per_page: Records per page (1-10000).
|
|
63
68
|
page_number: Page number, 1-indexed.
|
|
64
69
|
transformation: "rolling_sum" or "moving_avg". Requires window.
|
|
65
|
-
window: Transformation window in observations
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
+
window: Transformation window in observations, not days - "20" is
|
|
71
|
+
20 weeks on a weekly series.
|
|
72
|
+
normalisation: "zscore" or "percentile_rank"; omit for raw values.
|
|
73
|
+
"none" is still accepted and means the same as omitting it.
|
|
74
|
+
Sent alone, normalisation runs over "All" history.
|
|
75
|
+
normalisation_period: Calendar lookback for the normalisation. Sent
|
|
76
|
+
alone, it normalises with "zscore".
|
|
70
77
|
|
|
71
78
|
Returns:
|
|
72
79
|
Records under "data", plus count, metric, revision, series_ids,
|
|
73
80
|
version and pagination. Transformed and normalised values arrive
|
|
74
|
-
under "transformation"
|
|
81
|
+
under "transformation", present only when one was asked for; "data"
|
|
82
|
+
is always the raw stored series.
|
|
75
83
|
If the transformation service fails, the untransformed rows are
|
|
76
84
|
returned with "transformation" reporting status "Failure" rather
|
|
77
85
|
than raising. Asking for more than one series skips the
|
|
@@ -83,7 +91,6 @@ class AsyncPositioningAPI:
|
|
|
83
91
|
params: dict[str, Any] = {
|
|
84
92
|
"series_ids": csv_param(series_ids),
|
|
85
93
|
"revision": revision,
|
|
86
|
-
"metric": metric,
|
|
87
94
|
"order": order,
|
|
88
95
|
"records_per_page": records_per_page,
|
|
89
96
|
"page_number": page_number,
|
|
@@ -96,6 +103,8 @@ class AsyncPositioningAPI:
|
|
|
96
103
|
if start_date and end_date:
|
|
97
104
|
validate_date_range(params["start_date"], params["end_date"])
|
|
98
105
|
|
|
106
|
+
if metric:
|
|
107
|
+
params["metric"] = metric
|
|
99
108
|
if version:
|
|
100
109
|
params["version"] = version
|
|
101
110
|
|
|
@@ -107,8 +116,7 @@ class AsyncPositioningAPI:
|
|
|
107
116
|
if transformation:
|
|
108
117
|
params.update({"transformation": transformation, "window": window})
|
|
109
118
|
|
|
110
|
-
# Positioning
|
|
111
|
-
# flow either one may be sent alone.
|
|
119
|
+
# Positioning pairs these itself, so unlike flow either one may be sent alone.
|
|
112
120
|
if normalisation:
|
|
113
121
|
params["normalisation"] = normalisation
|
|
114
122
|
if normalisation_period:
|
|
@@ -133,7 +141,7 @@ class AsyncPositioningAPI:
|
|
|
133
141
|
self,
|
|
134
142
|
series_ids: Union[str, Sequence[str]],
|
|
135
143
|
revision: Revision = "restated",
|
|
136
|
-
metric: PositioningMetric =
|
|
144
|
+
metric: Optional[PositioningMetric] = None,
|
|
137
145
|
version: Optional[str] = None,
|
|
138
146
|
as_of: Optional[Union[str, date, datetime]] = None,
|
|
139
147
|
) -> dict[str, Any]:
|
|
@@ -142,9 +150,14 @@ class AsyncPositioningAPI:
|
|
|
142
150
|
|
|
143
151
|
Args:
|
|
144
152
|
series_ids: Series identifiers or labels, comma separated or as a sequence.
|
|
145
|
-
revision: "restated" or "point_in_time".
|
|
146
|
-
|
|
147
|
-
|
|
153
|
+
revision: "restated" or "point_in_time". Strict: a series with no
|
|
154
|
+
rows of that revision raises NotFoundError.
|
|
155
|
+
metric: Measure to return; valid values are listed by
|
|
156
|
+
list_catalog() and the service's metric facet. Omit for each
|
|
157
|
+
series' headline: its version's "combined_positioning", or
|
|
158
|
+
"combined_score_published" where that version has none (rates V2).
|
|
159
|
+
An unknown metric raises VandaError (HTTP 400) naming the valid ones.
|
|
160
|
+
version: Model version, e.g. "V1". Omit for the latest.
|
|
148
161
|
as_of: Return the latest reading on or before this date.
|
|
149
162
|
|
|
150
163
|
Returns:
|
|
@@ -153,9 +166,10 @@ class AsyncPositioningAPI:
|
|
|
153
166
|
params: dict[str, Any] = {
|
|
154
167
|
"series_ids": csv_param(series_ids),
|
|
155
168
|
"revision": revision,
|
|
156
|
-
"metric": metric,
|
|
157
169
|
}
|
|
158
170
|
|
|
171
|
+
if metric:
|
|
172
|
+
params["metric"] = metric
|
|
159
173
|
if version:
|
|
160
174
|
params["version"] = version
|
|
161
175
|
if as_of:
|
|
@@ -172,7 +186,7 @@ class AsyncPositioningAPI:
|
|
|
172
186
|
start_date: Optional[Union[str, date, datetime]] = None,
|
|
173
187
|
end_date: Optional[Union[str, date, datetime]] = None,
|
|
174
188
|
revision: Revision = "restated",
|
|
175
|
-
metric: PositioningMetric =
|
|
189
|
+
metric: Optional[PositioningMetric] = None,
|
|
176
190
|
version: Optional[str] = None,
|
|
177
191
|
export_format: ExportFormat = "csv",
|
|
178
192
|
compression: CompressionType = "none",
|
|
@@ -185,9 +199,14 @@ class AsyncPositioningAPI:
|
|
|
185
199
|
output_path: Output file path.
|
|
186
200
|
start_date: Start date (optional).
|
|
187
201
|
end_date: End date (optional).
|
|
188
|
-
revision: "restated" or "point_in_time".
|
|
189
|
-
|
|
190
|
-
|
|
202
|
+
revision: "restated" or "point_in_time". Strict: a series with no
|
|
203
|
+
rows of that revision raises NotFoundError.
|
|
204
|
+
metric: Measure to return; valid values are listed by
|
|
205
|
+
list_catalog() and the service's metric facet. Omit for each
|
|
206
|
+
series' headline: its version's "combined_positioning", or
|
|
207
|
+
"combined_score_published" where that version has none (rates V2).
|
|
208
|
+
An unknown metric raises VandaError (HTTP 400) naming the valid ones.
|
|
209
|
+
version: Model version, e.g. "V1". Omit for the latest.
|
|
191
210
|
export_format: "csv" or "json".
|
|
192
211
|
compression: "none", "gzip", or "zip".
|
|
193
212
|
|
|
@@ -197,7 +216,6 @@ class AsyncPositioningAPI:
|
|
|
197
216
|
params: dict[str, Any] = {
|
|
198
217
|
"series_ids": csv_param(series_ids),
|
|
199
218
|
"revision": revision,
|
|
200
|
-
"metric": metric,
|
|
201
219
|
"export_format": export_format,
|
|
202
220
|
"compression": compression,
|
|
203
221
|
}
|
|
@@ -209,6 +227,8 @@ class AsyncPositioningAPI:
|
|
|
209
227
|
if start_date and end_date:
|
|
210
228
|
validate_date_range(params["start_date"], params["end_date"])
|
|
211
229
|
|
|
230
|
+
if metric:
|
|
231
|
+
params["metric"] = metric
|
|
212
232
|
if version:
|
|
213
233
|
params["version"] = version
|
|
214
234
|
|