protocolith 0.6.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.
- protocolith/__init__.py +38 -0
- protocolith/baseline_groups.py +294 -0
- protocolith/baselines.py +288 -0
- protocolith/card_svg_render.py +281 -0
- protocolith/card_svg_styles.py +178 -0
- protocolith/cli.py +796 -0
- protocolith/core/__init__.py +63 -0
- protocolith/core/_lock_posix.py +29 -0
- protocolith/core/_lock_windows.py +29 -0
- protocolith/core/atlas.py +406 -0
- protocolith/core/atlas_assets/atlas.css +86 -0
- protocolith/core/atlas_assets/atlas.html +84 -0
- protocolith/core/atlas_assets/atlas.js +370 -0
- protocolith/core/atlas_i18n/en.json +61 -0
- protocolith/core/canonical.py +124 -0
- protocolith/core/capture.py +68 -0
- protocolith/core/clock.py +25 -0
- protocolith/core/commands.py +356 -0
- protocolith/core/errors.py +116 -0
- protocolith/core/issue.py +98 -0
- protocolith/core/ledger.py +75 -0
- protocolith/core/mcp.py +371 -0
- protocolith/core/ops.py +183 -0
- protocolith/core/rules.py +352 -0
- protocolith/core/schema.py +137 -0
- protocolith/core/store.py +101 -0
- protocolith/core/views.py +136 -0
- protocolith/doctor.py +135 -0
- protocolith/evidence_card.py +354 -0
- protocolith/family_ledger.py +489 -0
- protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
- protocolith/inspect.py +48 -0
- protocolith/nasa_power.py +266 -0
- protocolith/nasa_power_fetch.py +64 -0
- protocolith/nasa_power_parser.py +133 -0
- protocolith/nasa_power_prereg_runner.py +383 -0
- protocolith/noaa_coops_fetch.py +188 -0
- protocolith/noaa_coops_parser.py +120 -0
- protocolith/noaa_coops_prereg_runner.py +341 -0
- protocolith/public_ai_protocol.py +176 -0
- protocolith/py.typed +0 -0
- protocolith/registry.py +139 -0
- protocolith/registry_view.py +302 -0
- protocolith/rerun_report.py +111 -0
- protocolith/run_root.py +243 -0
- protocolith/scaffold.py +565 -0
- protocolith/source_probe.py +230 -0
- protocolith/svg_a11y.py +100 -0
- protocolith/tree_overlay.py +343 -0
- protocolith/verify_packs.py +251 -0
- protocolith/workflows.py +233 -0
- protocolith-0.6.0.dist-info/METADATA +283 -0
- protocolith-0.6.0.dist-info/RECORD +57 -0
- protocolith-0.6.0.dist-info/WHEEL +4 -0
- protocolith-0.6.0.dist-info/entry_points.txt +3 -0
- protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
- protocolith-0.6.0.dist-info/licenses/NOTICE +13 -0
protocolith/__init__.py
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Protocolith: records, verifies and issues trial records.
|
|
3
|
+
|
|
4
|
+
The core modules use only the standard library. The NASA POWER runner names below are kept
|
|
5
|
+
for compatibility and load on first access, because that runner needs the optional
|
|
6
|
+
``runners`` extra (numpy).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
from typing import TYPE_CHECKING, Any
|
|
12
|
+
|
|
13
|
+
if TYPE_CHECKING: # pragma: no cover
|
|
14
|
+
from protocolith.nasa_power_prereg_runner import (
|
|
15
|
+
NASA_POWER_PREREG_REPORT_SCHEMA,
|
|
16
|
+
NasaPowerPreregConfig,
|
|
17
|
+
evaluate_nasa_power_prereg,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
_LAZY = {
|
|
21
|
+
"NASA_POWER_PREREG_REPORT_SCHEMA",
|
|
22
|
+
"NasaPowerPreregConfig",
|
|
23
|
+
"evaluate_nasa_power_prereg",
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"NASA_POWER_PREREG_REPORT_SCHEMA",
|
|
28
|
+
"NasaPowerPreregConfig",
|
|
29
|
+
"evaluate_nasa_power_prereg",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def __getattr__(name: str) -> Any:
|
|
34
|
+
if name in _LAZY:
|
|
35
|
+
from protocolith import nasa_power_prereg_runner
|
|
36
|
+
|
|
37
|
+
return getattr(nasa_power_prereg_runner, name)
|
|
38
|
+
raise AttributeError(f"module 'protocolith' has no attribute {name!r}")
|
|
@@ -0,0 +1,294 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
"""Baseline groups and doc-11 paired acceptance evaluator.
|
|
4
|
+
|
|
5
|
+
This module exposes the three baseline groups required by doc 11:
|
|
6
|
+
|
|
7
|
+
* ``stat_baselines_only`` — zscore_rolling, ewma_residual, stl_residual,
|
|
8
|
+
persistence_residual;
|
|
9
|
+
* ``ml_anomaly_baselines_only`` — knn_lof, isolation_tree;
|
|
10
|
+
* ``all_baselines`` — union of the two groups above.
|
|
11
|
+
|
|
12
|
+
It also provides :func:`evaluate_group_vs_baseline_pool`, a deterministic
|
|
13
|
+
paired acceptance evaluator which — for a given candidate group score and a
|
|
14
|
+
pool of baseline scores across ``>=3`` independent windows — computes:
|
|
15
|
+
|
|
16
|
+
* per-window precision-at-top-rate of each scorer;
|
|
17
|
+
* paired ``positive_rate`` of candidate over every baseline;
|
|
18
|
+
* bootstrap percentile CI of the mean candidate-minus-baseline delta;
|
|
19
|
+
* overall go/no-go vs the combined pool (must beat every baseline).
|
|
20
|
+
|
|
21
|
+
The acceptance gates match doc 53: ``positive_rate >= 0.70``,
|
|
22
|
+
``mean_delta > 0``, bootstrap CI excludes zero uplift, ``>= 3`` independent
|
|
23
|
+
windows, ``beats all baselines``.
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
from __future__ import annotations
|
|
27
|
+
|
|
28
|
+
from dataclasses import dataclass, field
|
|
29
|
+
from collections.abc import Mapping, Sequence
|
|
30
|
+
|
|
31
|
+
import numpy as np
|
|
32
|
+
from numpy.typing import NDArray
|
|
33
|
+
|
|
34
|
+
from protocolith.baselines import (
|
|
35
|
+
DOC11_BASELINE_NAMES,
|
|
36
|
+
BaselinePoolConfig,
|
|
37
|
+
compute_baseline_scores,
|
|
38
|
+
normalize_baseline_score,
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
STAT_BASELINE_NAMES: tuple[str, ...] = (
|
|
42
|
+
"zscore_rolling",
|
|
43
|
+
"ewma_residual",
|
|
44
|
+
"stl_residual",
|
|
45
|
+
"persistence_residual",
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
ML_ANOMALY_BASELINE_NAMES: tuple[str, ...] = (
|
|
49
|
+
"knn_lof",
|
|
50
|
+
"isolation_tree",
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
DOC11_BASELINE_GROUPS: dict[str, tuple[str, ...]] = {
|
|
54
|
+
"stat_baselines_only": STAT_BASELINE_NAMES,
|
|
55
|
+
"ml_anomaly_baselines_only": ML_ANOMALY_BASELINE_NAMES,
|
|
56
|
+
"all_baselines": DOC11_BASELINE_NAMES,
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
@dataclass(frozen=True)
|
|
61
|
+
class Doc11AcceptanceConfig:
|
|
62
|
+
"""Acceptance-gate configuration (doc 53 defaults)."""
|
|
63
|
+
|
|
64
|
+
top_rate: float = 0.2
|
|
65
|
+
min_windows: int = 3
|
|
66
|
+
min_positive_rate: float = 0.70
|
|
67
|
+
min_event_rate: float = 0.03
|
|
68
|
+
max_event_rate: float = 0.40
|
|
69
|
+
bootstrap_samples: int = 2000
|
|
70
|
+
bootstrap_ci: float = 0.95
|
|
71
|
+
rng_seed: int = 4242
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
@dataclass(frozen=True)
|
|
75
|
+
class BaselinePoolScores:
|
|
76
|
+
"""Container for a precomputed baseline pool at a given rowset."""
|
|
77
|
+
|
|
78
|
+
raw: dict[str, NDArray[np.float64]]
|
|
79
|
+
config: BaselinePoolConfig = field(default_factory=BaselinePoolConfig)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def build_baseline_pool_scores(
|
|
83
|
+
prices: NDArray[np.float64],
|
|
84
|
+
*,
|
|
85
|
+
config: BaselinePoolConfig | None = None,
|
|
86
|
+
) -> BaselinePoolScores:
|
|
87
|
+
"""Compute the full doc-11 baseline pool aligned with ``prices``."""
|
|
88
|
+
|
|
89
|
+
cfg = config or BaselinePoolConfig()
|
|
90
|
+
raw = compute_baseline_scores(prices, config=cfg)
|
|
91
|
+
return BaselinePoolScores(raw=raw, config=cfg)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def normalized_baseline_scores_for_split(
|
|
95
|
+
pool: BaselinePoolScores,
|
|
96
|
+
*,
|
|
97
|
+
train_idx: NDArray[np.int64],
|
|
98
|
+
test_idx: NDArray[np.int64],
|
|
99
|
+
group: str = "all_baselines",
|
|
100
|
+
) -> dict[str, NDArray[np.float64]]:
|
|
101
|
+
"""Train-only-normalized scores for a split, filtered by baseline group."""
|
|
102
|
+
|
|
103
|
+
if group not in DOC11_BASELINE_GROUPS:
|
|
104
|
+
raise KeyError(f"Unknown baseline group: {group!r}")
|
|
105
|
+
names = DOC11_BASELINE_GROUPS[group]
|
|
106
|
+
out: dict[str, NDArray[np.float64]] = {}
|
|
107
|
+
for name in names:
|
|
108
|
+
values = pool.raw[name]
|
|
109
|
+
out[name] = normalize_baseline_score(values, train_idx, test_idx)
|
|
110
|
+
return out
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def _precision_at_top(
|
|
114
|
+
scores: NDArray[np.float64],
|
|
115
|
+
events: NDArray[np.bool_],
|
|
116
|
+
top_rate: float,
|
|
117
|
+
) -> float | None:
|
|
118
|
+
scores_arr = np.asarray(scores, dtype=np.float64)
|
|
119
|
+
events_arr = np.asarray(events, dtype=bool)
|
|
120
|
+
if len(scores_arr) == 0 or len(events_arr) == 0:
|
|
121
|
+
return None
|
|
122
|
+
count = max(1, int(np.ceil(len(scores_arr) * top_rate)))
|
|
123
|
+
order = np.argsort(-scores_arr)
|
|
124
|
+
selected = order[:count]
|
|
125
|
+
return float(np.mean(events_arr[selected]))
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def _bootstrap_mean_ci(
|
|
129
|
+
values: Sequence[float],
|
|
130
|
+
*,
|
|
131
|
+
samples: int,
|
|
132
|
+
ci: float,
|
|
133
|
+
rng_seed: int,
|
|
134
|
+
) -> tuple[float | None, float | None, float | None]:
|
|
135
|
+
arr = np.asarray(values, dtype=np.float64)
|
|
136
|
+
if len(arr) == 0:
|
|
137
|
+
return (None, None, None)
|
|
138
|
+
if len(arr) == 1:
|
|
139
|
+
return (float(arr[0]), float(arr[0]), float(arr[0]))
|
|
140
|
+
rng = np.random.default_rng(rng_seed)
|
|
141
|
+
boot = np.empty(samples, dtype=np.float64)
|
|
142
|
+
n = len(arr)
|
|
143
|
+
for s in range(samples):
|
|
144
|
+
draw = rng.integers(0, n, size=n)
|
|
145
|
+
boot[s] = float(np.mean(arr[draw]))
|
|
146
|
+
alpha = (1.0 - ci) / 2.0
|
|
147
|
+
low = float(np.quantile(boot, alpha))
|
|
148
|
+
high = float(np.quantile(boot, 1.0 - alpha))
|
|
149
|
+
return (float(np.mean(arr)), low, high)
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
@dataclass(frozen=True)
|
|
153
|
+
class WindowObservation:
|
|
154
|
+
"""Per-window inputs to the acceptance evaluator."""
|
|
155
|
+
|
|
156
|
+
candidate_scores: NDArray[np.float64]
|
|
157
|
+
baseline_scores: Mapping[str, NDArray[np.float64]]
|
|
158
|
+
events: NDArray[np.bool_]
|
|
159
|
+
window_id: int
|
|
160
|
+
|
|
161
|
+
|
|
162
|
+
def _per_window_precisions(
|
|
163
|
+
obs: WindowObservation,
|
|
164
|
+
*,
|
|
165
|
+
top_rate: float,
|
|
166
|
+
) -> dict[str, float | None]:
|
|
167
|
+
out: dict[str, float | None] = {"candidate": _precision_at_top(obs.candidate_scores, obs.events, top_rate)}
|
|
168
|
+
for name, scores in obs.baseline_scores.items():
|
|
169
|
+
out[name] = _precision_at_top(scores, obs.events, top_rate)
|
|
170
|
+
return out
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def _event_rate(events: NDArray[np.bool_]) -> float | None:
|
|
174
|
+
events_arr = np.asarray(events, dtype=bool)
|
|
175
|
+
return float(np.mean(events_arr)) if len(events_arr) else None
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
def _positive_rate(values: Sequence[float]) -> float | None:
|
|
179
|
+
if not values:
|
|
180
|
+
return None
|
|
181
|
+
return float(sum(1 for value in values if value > 0.0) / len(values))
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def _mean(values: Sequence[float]) -> float | None:
|
|
185
|
+
if not values:
|
|
186
|
+
return None
|
|
187
|
+
return float(np.mean(np.asarray(values, dtype=np.float64)))
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def evaluate_group_vs_baseline_pool(
|
|
191
|
+
observations: Sequence[WindowObservation],
|
|
192
|
+
*,
|
|
193
|
+
config: Doc11AcceptanceConfig | None = None,
|
|
194
|
+
) -> dict[str, object]:
|
|
195
|
+
"""Paired doc-11/doc-53 acceptance evaluator over ``>=min_windows`` windows.
|
|
196
|
+
|
|
197
|
+
For each window computes precision-at-top of candidate and every baseline
|
|
198
|
+
and per-baseline delta; aggregates across windows with bootstrap CIs and
|
|
199
|
+
emits an overall go/no-go that is ``True`` only if **every** baseline is
|
|
200
|
+
beaten by all gate criteria simultaneously.
|
|
201
|
+
"""
|
|
202
|
+
|
|
203
|
+
cfg = config or Doc11AcceptanceConfig()
|
|
204
|
+
window_records: list[dict[str, object]] = []
|
|
205
|
+
baseline_names: tuple[str, ...] = ()
|
|
206
|
+
for obs in observations:
|
|
207
|
+
baseline_names = tuple(obs.baseline_scores.keys())
|
|
208
|
+
per_precision = _per_window_precisions(obs, top_rate=cfg.top_rate)
|
|
209
|
+
rate = _event_rate(obs.events)
|
|
210
|
+
window_records.append(
|
|
211
|
+
{
|
|
212
|
+
"window_id": int(obs.window_id),
|
|
213
|
+
"event_rate": rate,
|
|
214
|
+
"evaluated": int(len(obs.events)),
|
|
215
|
+
"events": int(np.sum(np.asarray(obs.events, dtype=bool))),
|
|
216
|
+
"precision": per_precision,
|
|
217
|
+
"event_rate_in_range": (
|
|
218
|
+
None
|
|
219
|
+
if rate is None
|
|
220
|
+
else bool(cfg.min_event_rate <= rate <= cfg.max_event_rate)
|
|
221
|
+
),
|
|
222
|
+
}
|
|
223
|
+
)
|
|
224
|
+
|
|
225
|
+
baseline_acceptance: dict[str, dict[str, object]] = {}
|
|
226
|
+
for name in baseline_names:
|
|
227
|
+
deltas: list[float] = []
|
|
228
|
+
for record in window_records:
|
|
229
|
+
precision = record["precision"]
|
|
230
|
+
assert isinstance(precision, dict)
|
|
231
|
+
candidate = precision.get("candidate")
|
|
232
|
+
baseline = precision.get(name)
|
|
233
|
+
if candidate is None or baseline is None:
|
|
234
|
+
continue
|
|
235
|
+
deltas.append(float(candidate) - float(baseline))
|
|
236
|
+
positive = _positive_rate(deltas)
|
|
237
|
+
mean_delta = _mean(deltas)
|
|
238
|
+
mean_boot, ci_low, ci_high = _bootstrap_mean_ci(
|
|
239
|
+
deltas,
|
|
240
|
+
samples=cfg.bootstrap_samples,
|
|
241
|
+
ci=cfg.bootstrap_ci,
|
|
242
|
+
rng_seed=cfg.rng_seed,
|
|
243
|
+
)
|
|
244
|
+
ci_excludes_zero = (
|
|
245
|
+
ci_low is not None and ci_high is not None and ci_low > 0.0
|
|
246
|
+
)
|
|
247
|
+
meets = (
|
|
248
|
+
len(deltas) >= cfg.min_windows
|
|
249
|
+
and positive is not None
|
|
250
|
+
and positive >= cfg.min_positive_rate
|
|
251
|
+
and mean_delta is not None
|
|
252
|
+
and mean_delta > 0.0
|
|
253
|
+
and ci_excludes_zero
|
|
254
|
+
)
|
|
255
|
+
baseline_acceptance[name] = {
|
|
256
|
+
"windows": len(deltas),
|
|
257
|
+
"positive_rate": positive,
|
|
258
|
+
"mean_delta": mean_delta,
|
|
259
|
+
"bootstrap_mean": mean_boot,
|
|
260
|
+
"bootstrap_ci_low": ci_low,
|
|
261
|
+
"bootstrap_ci_high": ci_high,
|
|
262
|
+
"bootstrap_ci_excludes_zero": bool(ci_excludes_zero),
|
|
263
|
+
"meets_paired_gate": bool(meets),
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
event_rate_ok = all(
|
|
267
|
+
record.get("event_rate_in_range") is True for record in window_records
|
|
268
|
+
)
|
|
269
|
+
overall_go = (
|
|
270
|
+
len(window_records) >= cfg.min_windows
|
|
271
|
+
and event_rate_ok
|
|
272
|
+
and bool(baseline_acceptance)
|
|
273
|
+
and all(payload.get("meets_paired_gate") for payload in baseline_acceptance.values())
|
|
274
|
+
)
|
|
275
|
+
return {
|
|
276
|
+
"config": {
|
|
277
|
+
"top_rate": cfg.top_rate,
|
|
278
|
+
"min_windows": cfg.min_windows,
|
|
279
|
+
"min_positive_rate": cfg.min_positive_rate,
|
|
280
|
+
"min_event_rate": cfg.min_event_rate,
|
|
281
|
+
"max_event_rate": cfg.max_event_rate,
|
|
282
|
+
"bootstrap_samples": cfg.bootstrap_samples,
|
|
283
|
+
"bootstrap_ci": cfg.bootstrap_ci,
|
|
284
|
+
"rng_seed": cfg.rng_seed,
|
|
285
|
+
},
|
|
286
|
+
"baseline_names": list(baseline_names),
|
|
287
|
+
"windows": window_records,
|
|
288
|
+
"baseline_acceptance": baseline_acceptance,
|
|
289
|
+
"overall_go_no_go": bool(overall_go),
|
|
290
|
+
"claim_boundary": (
|
|
291
|
+
"paired doc-11 acceptance on precision@top_rate; "
|
|
292
|
+
"positive claim requires beating every baseline in the pool"
|
|
293
|
+
),
|
|
294
|
+
}
|
protocolith/baselines.py
ADDED
|
@@ -0,0 +1,288 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
"""Pure-numpy doc-11 baseline pool for Protocolith non-PnL anomaly/regime evaluation.
|
|
4
|
+
|
|
5
|
+
Each baseline produces a causal, train-only-normalized outlier score over a
|
|
6
|
+
closing-price series. Higher score = more anomalous. Outputs are aligned
|
|
7
|
+
with the input series and ready to be compared against Protocolith feature-group
|
|
8
|
+
scores under paired acceptance gates (doc 11 / doc 53).
|
|
9
|
+
|
|
10
|
+
Six reference baselines, all deterministic, NumPy-only, no lookahead:
|
|
11
|
+
``zscore_rolling``, ``ewma_residual``, ``stl_residual``,
|
|
12
|
+
``persistence_residual``, ``knn_lof``, ``isolation_tree``.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
from dataclasses import dataclass
|
|
18
|
+
|
|
19
|
+
import numpy as np
|
|
20
|
+
from numpy.typing import NDArray
|
|
21
|
+
|
|
22
|
+
DOC11_BASELINE_NAMES: tuple[str, ...] = (
|
|
23
|
+
"zscore_rolling",
|
|
24
|
+
"ewma_residual",
|
|
25
|
+
"stl_residual",
|
|
26
|
+
"persistence_residual",
|
|
27
|
+
"knn_lof",
|
|
28
|
+
"isolation_tree",
|
|
29
|
+
)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class BaselinePoolConfig:
|
|
34
|
+
"""Deterministic configuration for the doc-11 baseline pool.
|
|
35
|
+
|
|
36
|
+
All defaults are chosen to be reasonable without peeking at test data.
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
zscore_lookback: int = 50
|
|
40
|
+
ewma_alpha: float = 0.1
|
|
41
|
+
stl_period: int = 7
|
|
42
|
+
stl_trend_window: int = 25
|
|
43
|
+
knn_window: int = 50
|
|
44
|
+
knn_k: int = 5
|
|
45
|
+
isolation_window: int = 50
|
|
46
|
+
isolation_trees: int = 32
|
|
47
|
+
isolation_max_depth: int = 8
|
|
48
|
+
rng_seed: int = 1337
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _log_returns(prices: NDArray[np.float64]) -> NDArray[np.float64]:
|
|
52
|
+
values = np.asarray(prices, dtype=np.float64)
|
|
53
|
+
log_p = np.log(np.where(values > 0.0, values, np.nan))
|
|
54
|
+
out = np.zeros(len(values), dtype=np.float64)
|
|
55
|
+
if len(values) < 2:
|
|
56
|
+
return out
|
|
57
|
+
out[1:] = log_p[1:] - log_p[:-1]
|
|
58
|
+
return np.nan_to_num(out, nan=0.0, posinf=0.0, neginf=0.0)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def zscore_rolling_score(
|
|
62
|
+
prices: NDArray[np.float64],
|
|
63
|
+
*,
|
|
64
|
+
lookback: int,
|
|
65
|
+
) -> NDArray[np.float64]:
|
|
66
|
+
"""Rolling absolute zscore of log-returns (causal, no lookahead)."""
|
|
67
|
+
|
|
68
|
+
ret = _log_returns(prices)
|
|
69
|
+
out = np.zeros_like(ret)
|
|
70
|
+
if lookback <= 1 or len(ret) == 0:
|
|
71
|
+
return out
|
|
72
|
+
for i in range(len(ret)):
|
|
73
|
+
start = max(0, i - lookback + 1)
|
|
74
|
+
window = ret[start : i + 1]
|
|
75
|
+
if len(window) < 2:
|
|
76
|
+
continue
|
|
77
|
+
mu = float(np.mean(window[:-1])) if len(window) >= 2 else 0.0
|
|
78
|
+
sigma = float(np.std(window[:-1])) if len(window) >= 2 else 0.0
|
|
79
|
+
if sigma <= 1.0e-12:
|
|
80
|
+
sigma = 1.0
|
|
81
|
+
out[i] = abs(ret[i] - mu) / sigma
|
|
82
|
+
return out
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def ewma_residual_score(
|
|
86
|
+
prices: NDArray[np.float64],
|
|
87
|
+
*,
|
|
88
|
+
alpha: float,
|
|
89
|
+
) -> NDArray[np.float64]:
|
|
90
|
+
"""Absolute residual against a one-sided EWMA of log-returns."""
|
|
91
|
+
|
|
92
|
+
ret = _log_returns(prices)
|
|
93
|
+
out = np.zeros_like(ret)
|
|
94
|
+
if len(ret) == 0:
|
|
95
|
+
return out
|
|
96
|
+
ewma = 0.0
|
|
97
|
+
for i in range(len(ret)):
|
|
98
|
+
out[i] = abs(ret[i] - ewma)
|
|
99
|
+
ewma = (1.0 - alpha) * ewma + alpha * ret[i]
|
|
100
|
+
return out
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def stl_residual_score(
|
|
104
|
+
prices: NDArray[np.float64],
|
|
105
|
+
*,
|
|
106
|
+
period: int,
|
|
107
|
+
trend_window: int,
|
|
108
|
+
) -> NDArray[np.float64]:
|
|
109
|
+
"""Simplified additive trend/seasonal/residual decomposition.
|
|
110
|
+
|
|
111
|
+
Trend is a causal centered-aware moving average over ``trend_window``;
|
|
112
|
+
seasonal component is the mean residual-from-trend at the same phase of
|
|
113
|
+
``period`` over the in-window history preceding bar ``i``. The score is
|
|
114
|
+
the absolute residual after removing trend and seasonal estimates.
|
|
115
|
+
"""
|
|
116
|
+
|
|
117
|
+
ret = _log_returns(prices)
|
|
118
|
+
out = np.zeros_like(ret)
|
|
119
|
+
if period <= 1 or trend_window <= 1 or len(ret) == 0:
|
|
120
|
+
return np.abs(ret)
|
|
121
|
+
trend = np.zeros_like(ret)
|
|
122
|
+
for i in range(len(ret)):
|
|
123
|
+
start = max(0, i - trend_window + 1)
|
|
124
|
+
window = ret[start : i + 1]
|
|
125
|
+
trend[i] = float(np.mean(window)) if len(window) else 0.0
|
|
126
|
+
detrended = ret - trend
|
|
127
|
+
seasonal = np.zeros_like(ret)
|
|
128
|
+
for i in range(len(ret)):
|
|
129
|
+
phase = i % period
|
|
130
|
+
history_end = i
|
|
131
|
+
idx = np.arange(phase, history_end, period, dtype=np.int64)
|
|
132
|
+
if len(idx) == 0:
|
|
133
|
+
continue
|
|
134
|
+
seasonal[i] = float(np.mean(detrended[idx]))
|
|
135
|
+
residual = ret - trend - seasonal
|
|
136
|
+
out = np.abs(residual)
|
|
137
|
+
return out
|
|
138
|
+
|
|
139
|
+
|
|
140
|
+
def persistence_residual_score(prices: NDArray[np.float64]) -> NDArray[np.float64]:
|
|
141
|
+
"""Absolute one-step log-return (the canonical persistence/random-walk residual)."""
|
|
142
|
+
|
|
143
|
+
return np.abs(_log_returns(prices))
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def knn_lof_score(
|
|
147
|
+
prices: NDArray[np.float64],
|
|
148
|
+
*,
|
|
149
|
+
window: int,
|
|
150
|
+
k: int,
|
|
151
|
+
) -> NDArray[np.float64]:
|
|
152
|
+
"""Local-Outlier-Factor approximation on sliding windows of log-returns.
|
|
153
|
+
|
|
154
|
+
For bar ``i`` the method takes the preceding ``window`` log-returns (open
|
|
155
|
+
interval ending before ``i``) as points in a 1-D feature space together
|
|
156
|
+
with the target value ``ret[i]``, then computes the ratio of the target
|
|
157
|
+
point's k-NN mean distance to the median k-NN mean distance of the
|
|
158
|
+
reference points. The ratio is monotonically increasing in how far the
|
|
159
|
+
target sits from the local density — a deterministic LOF-style proxy.
|
|
160
|
+
"""
|
|
161
|
+
|
|
162
|
+
ret = _log_returns(prices)
|
|
163
|
+
out = np.zeros_like(ret)
|
|
164
|
+
if window <= k + 1 or len(ret) == 0:
|
|
165
|
+
return out
|
|
166
|
+
for i in range(len(ret)):
|
|
167
|
+
start = max(0, i - window)
|
|
168
|
+
ref = ret[start:i]
|
|
169
|
+
if len(ref) <= k:
|
|
170
|
+
continue
|
|
171
|
+
target = ret[i]
|
|
172
|
+
target_dists = np.sort(np.abs(ref - target))
|
|
173
|
+
target_kmean = float(np.mean(target_dists[:k]))
|
|
174
|
+
ref_kmeans = np.empty(len(ref), dtype=np.float64)
|
|
175
|
+
for j in range(len(ref)):
|
|
176
|
+
others = np.delete(ref, j)
|
|
177
|
+
if len(others) < k:
|
|
178
|
+
ref_kmeans[j] = 0.0
|
|
179
|
+
continue
|
|
180
|
+
od = np.sort(np.abs(others - ref[j]))
|
|
181
|
+
ref_kmeans[j] = float(np.mean(od[:k]))
|
|
182
|
+
median_ref = float(np.median(ref_kmeans)) if len(ref_kmeans) else 0.0
|
|
183
|
+
if median_ref <= 1.0e-12:
|
|
184
|
+
median_ref = 1.0
|
|
185
|
+
out[i] = target_kmean / median_ref
|
|
186
|
+
return np.nan_to_num(out, nan=0.0, posinf=0.0, neginf=0.0)
|
|
187
|
+
|
|
188
|
+
|
|
189
|
+
def isolation_tree_score(
|
|
190
|
+
prices: NDArray[np.float64],
|
|
191
|
+
*,
|
|
192
|
+
window: int,
|
|
193
|
+
n_trees: int,
|
|
194
|
+
max_depth: int,
|
|
195
|
+
rng_seed: int,
|
|
196
|
+
) -> NDArray[np.float64]:
|
|
197
|
+
"""Deterministic isolation-forest-style isolation depth on log-returns.
|
|
198
|
+
|
|
199
|
+
For each bar ``i`` the method samples the preceding ``window`` log-returns
|
|
200
|
+
as a reference cloud and grows ``n_trees`` random axis-aligned binary
|
|
201
|
+
trees up to ``max_depth``. The target point's isolation depth averaged
|
|
202
|
+
across trees is returned and inverted so that lower depth (easier to
|
|
203
|
+
isolate, hence more anomalous) maps to a higher score.
|
|
204
|
+
"""
|
|
205
|
+
|
|
206
|
+
ret = _log_returns(prices)
|
|
207
|
+
out = np.zeros_like(ret)
|
|
208
|
+
if window <= 2 or n_trees <= 0 or max_depth <= 0 or len(ret) == 0:
|
|
209
|
+
return out
|
|
210
|
+
rng = np.random.default_rng(rng_seed)
|
|
211
|
+
for i in range(len(ret)):
|
|
212
|
+
start = max(0, i - window)
|
|
213
|
+
ref = ret[start:i]
|
|
214
|
+
if len(ref) < 2:
|
|
215
|
+
continue
|
|
216
|
+
target = ret[i]
|
|
217
|
+
depths = np.empty(n_trees, dtype=np.float64)
|
|
218
|
+
for t in range(n_trees):
|
|
219
|
+
lo = float(np.min(ref))
|
|
220
|
+
hi = float(np.max(ref))
|
|
221
|
+
active = ref.copy()
|
|
222
|
+
depth = 0.0
|
|
223
|
+
for _ in range(max_depth):
|
|
224
|
+
if hi - lo <= 1.0e-12 or len(active) <= 1:
|
|
225
|
+
break
|
|
226
|
+
split = rng.uniform(lo, hi)
|
|
227
|
+
if target < split:
|
|
228
|
+
active = active[active < split]
|
|
229
|
+
hi = split
|
|
230
|
+
else:
|
|
231
|
+
active = active[active >= split]
|
|
232
|
+
lo = split
|
|
233
|
+
depth += 1.0
|
|
234
|
+
if len(active) == 0:
|
|
235
|
+
break
|
|
236
|
+
depths[t] = depth
|
|
237
|
+
mean_depth = float(np.mean(depths))
|
|
238
|
+
out[i] = float(max_depth) - mean_depth
|
|
239
|
+
return out
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def compute_baseline_scores(
|
|
243
|
+
prices: NDArray[np.float64],
|
|
244
|
+
*,
|
|
245
|
+
config: BaselinePoolConfig,
|
|
246
|
+
) -> dict[str, NDArray[np.float64]]:
|
|
247
|
+
"""Compute all six doc-11 baseline score series (aligned with ``prices``)."""
|
|
248
|
+
|
|
249
|
+
prices_arr = np.asarray(prices, dtype=np.float64)
|
|
250
|
+
return {
|
|
251
|
+
"zscore_rolling": zscore_rolling_score(prices_arr, lookback=config.zscore_lookback),
|
|
252
|
+
"ewma_residual": ewma_residual_score(prices_arr, alpha=config.ewma_alpha),
|
|
253
|
+
"stl_residual": stl_residual_score(
|
|
254
|
+
prices_arr,
|
|
255
|
+
period=config.stl_period,
|
|
256
|
+
trend_window=config.stl_trend_window,
|
|
257
|
+
),
|
|
258
|
+
"persistence_residual": persistence_residual_score(prices_arr),
|
|
259
|
+
"knn_lof": knn_lof_score(
|
|
260
|
+
prices_arr,
|
|
261
|
+
window=config.knn_window,
|
|
262
|
+
k=config.knn_k,
|
|
263
|
+
),
|
|
264
|
+
"isolation_tree": isolation_tree_score(
|
|
265
|
+
prices_arr,
|
|
266
|
+
window=config.isolation_window,
|
|
267
|
+
n_trees=config.isolation_trees,
|
|
268
|
+
max_depth=config.isolation_max_depth,
|
|
269
|
+
rng_seed=config.rng_seed,
|
|
270
|
+
),
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
def normalize_baseline_score(
|
|
275
|
+
values: NDArray[np.float64],
|
|
276
|
+
train_idx: NDArray[np.int64],
|
|
277
|
+
test_idx: NDArray[np.int64],
|
|
278
|
+
) -> NDArray[np.float64]:
|
|
279
|
+
"""Zero-mean/unit-variance normalization using train-only statistics."""
|
|
280
|
+
|
|
281
|
+
arr = np.asarray(values, dtype=np.float64)
|
|
282
|
+
train = arr[train_idx]
|
|
283
|
+
mean = float(np.mean(train)) if len(train) else 0.0
|
|
284
|
+
std = float(np.std(train)) if len(train) else 0.0
|
|
285
|
+
if std <= 1.0e-12:
|
|
286
|
+
std = 1.0
|
|
287
|
+
scaled = (arr[test_idx] - mean) / std
|
|
288
|
+
return np.nan_to_num(scaled, nan=0.0, posinf=0.0, neginf=0.0)
|