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.
Files changed (57) hide show
  1. protocolith/__init__.py +38 -0
  2. protocolith/baseline_groups.py +294 -0
  3. protocolith/baselines.py +288 -0
  4. protocolith/card_svg_render.py +281 -0
  5. protocolith/card_svg_styles.py +178 -0
  6. protocolith/cli.py +796 -0
  7. protocolith/core/__init__.py +63 -0
  8. protocolith/core/_lock_posix.py +29 -0
  9. protocolith/core/_lock_windows.py +29 -0
  10. protocolith/core/atlas.py +406 -0
  11. protocolith/core/atlas_assets/atlas.css +86 -0
  12. protocolith/core/atlas_assets/atlas.html +84 -0
  13. protocolith/core/atlas_assets/atlas.js +370 -0
  14. protocolith/core/atlas_i18n/en.json +61 -0
  15. protocolith/core/canonical.py +124 -0
  16. protocolith/core/capture.py +68 -0
  17. protocolith/core/clock.py +25 -0
  18. protocolith/core/commands.py +356 -0
  19. protocolith/core/errors.py +116 -0
  20. protocolith/core/issue.py +98 -0
  21. protocolith/core/ledger.py +75 -0
  22. protocolith/core/mcp.py +371 -0
  23. protocolith/core/ops.py +183 -0
  24. protocolith/core/rules.py +352 -0
  25. protocolith/core/schema.py +137 -0
  26. protocolith/core/store.py +101 -0
  27. protocolith/core/views.py +136 -0
  28. protocolith/doctor.py +135 -0
  29. protocolith/evidence_card.py +354 -0
  30. protocolith/family_ledger.py +489 -0
  31. protocolith/generic_ohlcv_batch_pre_registration_meta.py +123 -0
  32. protocolith/inspect.py +48 -0
  33. protocolith/nasa_power.py +266 -0
  34. protocolith/nasa_power_fetch.py +64 -0
  35. protocolith/nasa_power_parser.py +133 -0
  36. protocolith/nasa_power_prereg_runner.py +383 -0
  37. protocolith/noaa_coops_fetch.py +188 -0
  38. protocolith/noaa_coops_parser.py +120 -0
  39. protocolith/noaa_coops_prereg_runner.py +341 -0
  40. protocolith/public_ai_protocol.py +176 -0
  41. protocolith/py.typed +0 -0
  42. protocolith/registry.py +139 -0
  43. protocolith/registry_view.py +302 -0
  44. protocolith/rerun_report.py +111 -0
  45. protocolith/run_root.py +243 -0
  46. protocolith/scaffold.py +565 -0
  47. protocolith/source_probe.py +230 -0
  48. protocolith/svg_a11y.py +100 -0
  49. protocolith/tree_overlay.py +343 -0
  50. protocolith/verify_packs.py +251 -0
  51. protocolith/workflows.py +233 -0
  52. protocolith-0.6.0.dist-info/METADATA +283 -0
  53. protocolith-0.6.0.dist-info/RECORD +57 -0
  54. protocolith-0.6.0.dist-info/WHEEL +4 -0
  55. protocolith-0.6.0.dist-info/entry_points.txt +3 -0
  56. protocolith-0.6.0.dist-info/licenses/LICENSE +201 -0
  57. protocolith-0.6.0.dist-info/licenses/NOTICE +13 -0
@@ -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
+ }
@@ -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)