hfvol 0.1.0__tar.gz

hfvol-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+.coverage

hfvol-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-11-15
+
+First release. Carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab)
+(`lib/math/volatility_models.py` and `lib/math/hawkes_process.py`) at commit
+`8cbfcb0` (MIT). See `docs/provenance.md`.
+
+### Added
+- sktime transformers `RealizedVariance`, `BipowerVariation`, `JumpVariation`
+  (`freq` as bars per period or a calendar alias such as `"D"`; multivariate;
+  Panel and hierarchical data through sktime's vectorization) and
+  `HawkesIntensity` (fixed parameters or `method="mle"`, causal intensity by
+  default, `time_unit` for DatetimeIndex data).
+- sktime forecaster `HARForecaster` (Corsi 2009) with `update`.
+- All five pass `sktime.utils.estimator_checks.check_estimator` on sktime 1.0.0
+  and 1.3.0.
+- numpy functions `bipower_variation_series`, `jump_variation_series`,
+  `har_forecast_path`, `hawkes_compensator`.
+- Tests: hand-computed values, Barndorff-Nielsen and Shephard consistency and
+  jump-robustness checks, HAR OLS against the normal equations and coefficient
+  recovery, closed-form and brute-force Hawkes likelihood, intensity and
+  compensator checks, MLE recovery and time-rescaling residuals. srfm-lab had no
+  dedicated tests for either module.
+
+### Changed (relative to srfm-lab)
+- `annualize` defaults to `False` in every realized-measure function.
+- The Hawkes log-likelihood, intensity path, simulation and residuals run in
+  O(n) through the exponential-kernel recursion (srfm-lab was O(n^2) in three
+  of them).
+- `fit_hawkes_mle` optimises over `(log mu, log beta, logit n)` so every
+  candidate is stationary, scales its starts to the observed event rate and
+  takes a seed (`rng`).
+- `hawkes_intensity_path` takes `include_current` (default `True`, the srfm-lab
+  behaviour); `False` gives the predictable intensity.
+- `hawkes_residual_analysis` includes the first compensator increment
+  `Lambda(t_1)`.
+- `HARParams` and `HawkesParams` are frozen dataclasses; `har_features` is
+  vectorised.
+- Multivariate Hawkes, GARCH, EWMA, VIX, surface and rough-volatility code from
+  the source files is not included.
+
+### Fixed (relative to srfm-lab)
+- Events sharing a time stamp excited each other in the likelihood
+  (`exp(0) = 1`), which makes it unbounded on binned data: the MLE ran off to
+  `alpha, beta -> inf`. Only strictly earlier events now count, and
+  `hawkes_intensity_path` / `hawkes_compensator` count every tied event.
+- `fit_hawkes_mle` returned the default `HawkesParams()` with log-likelihood
+  `-inf` whenever no Nelder-Mead run reported `success`, even when the runs had
+  found good parameters. The best finite result is now kept.
+- `fit_hawkes_mle` and `branching_ratio` were not reproducible (unseeded
+  generator with no way to pass one).
+- `hawkes_simulate` used `assert` for the stationarity check, which is skipped
+  under `python -O`; it now raises `ValueError`.

hfvol-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Busel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hfvol-0.1.0/NOTICE

@@ -0,0 +1,12 @@
+hfvol
+Copyright (c) 2026 Matthew Busel
+
+This package was carved out of srfm-lab (https://github.com/Mattbusel/srfm-lab)
+at commit 8cbfcb0551d44e3ed1c20bdae9dc805d61521c62. srfm-lab is released under
+the MIT License, copyright (c) 2026 Matthew Busel.
+
+src/hfvol/realized.py and src/hfvol/har.py are derived from
+lib/math/volatility_models.py; src/hfvol/hawkes.py is derived from
+lib/math/hawkes_process.py. docs/provenance.md maps every function to its
+origin and lists what changed. The sktime estimators (transformers.py,
+forecasting.py) and the tests are new.

hfvol-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.5
+Name: hfvol
+Version: 0.1.0
+Summary: sktime-compatible realized variance, bipower and jump variation, Hawkes intensity transformers and a HAR-RV forecaster, on plain numpy functions. Carved out of srfm-lab.
+Project-URL: Homepage, https://github.com/Mattbusel/hfvol
+Project-URL: Repository, https://github.com/Mattbusel/hfvol
+Project-URL: Documentation, https://github.com/Mattbusel/hfvol/tree/main/docs
+Project-URL: Changelog, https://github.com/Mattbusel/hfvol/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Mattbusel/hfvol/issues
+Project-URL: Upstream (srfm-lab), https://github.com/Mattbusel/srfm-lab
+Author: Matthew Busel
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: bipower-variation,har-rv,hawkes-process,high-frequency,jump-variation,market-microstructure,quantitative-finance,realized-variance,realized-volatility,sktime,time-series,volatility-forecasting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.22
+Provides-Extra: scipy
+Requires-Dist: scipy>=1.8; extra == 'scipy'
+Provides-Extra: sktime
+Requires-Dist: scipy>=1.8; extra == 'sktime'
+Requires-Dist: sktime>=1.0; extra == 'sktime'
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: scipy>=1.8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# hfvol
+
+Realized variance, bipower variation, jump variation, Hawkes intensity and the
+HAR-RV forecaster, as sktime estimators on top of plain numpy functions.
+
+```
+pip install hfvol            # numpy functions only
+pip install "hfvol[sktime]"  # plus the sktime transformers and forecaster
+```
+
+## Why
+
+sktime has a Hurst-exponent transformer but no realized measures and no Hawkes
+process. The main Python Hawkes library (`tick`) needs a C++ build. hfvol fills
+both gaps with small numpy code that passes sktime's own
+`check_estimator` suite.
+
+## sktime
+
+```python
+import numpy as np, pandas as pd
+from hfvol import RealizedVariance, BipowerVariation, JumpVariation, HARForecaster
+
+# 5-minute returns, 78 bars per session, DatetimeIndex
+idx = pd.date_range("2024-01-02 09:35", periods=78 * 250, freq="5min")
+r = pd.Series(np.random.default_rng(0).normal(0, 1e-3, len(idx)), index=idx)
+
+rv = RealizedVariance(freq=78).fit_transform(r)  # one value per session
+bv = BipowerVariation(freq=78).fit_transform(r)  # jump-robust
+jv = JumpVariation(freq=78).fit_transform(r)  # max(RV - BV, 0)
+
+f = HARForecaster().fit(rv.reset_index(drop=True))
+f.predict(fh=[1, 5, 22])
+```
+
+`freq` is either an integer number of bars per period or a pandas offset alias
+(`"D"`, `"W"`, ...) that groups a DatetimeIndex by calendar period. Multivariate
+frames give one column per asset; Panel and hierarchical data work through
+sktime's usual vectorization.
+
+```python
+from hfvol import HawkesIntensity
+
+# trade counts per second; the intensity at each second uses only earlier trades
+lam = HawkesIntensity(method="mle", time_unit="1s", random_state=0).fit_transform(counts)
+```
+
+## numpy
+
+```python
+from hfvol import (
+    realized_variance,
+    bipower_variation,
+    jump_variation,
+    fit_har,
+    har_forecast,
+    HawkesParams,
+    hawkes_simulate,
+    fit_hawkes_mle,
+    hawkes_residual_analysis,
+)
+
+events = hawkes_simulate(HawkesParams(mu=0.5, alpha=0.8, beta=1.6), T=5000, rng=1)
+params, ll = fit_hawkes_mle(events, T=5000, rng=0)
+params.branching_ratio  # about 0.5
+hawkes_residual_analysis(events, 5000, params)["well_fit"]
+```
+
+## More
+
+- [API reference](api.md)
+- [Formulas and references](methods.md)
+- [Where this came from](provenance.md)
+- [Ecosystem plan (sktime, OpenBB)](ecosystem.md)
+- Examples: `examples/`
+
+MIT licensed. Carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab).

hfvol-0.1.0/docs/api.md

@@ -0,0 +1,87 @@
+# API reference
+
+## sktime estimators (`pip install "hfvol[sktime]"`)
+
+All five pass `sktime.utils.estimator_checks.check_estimator` (tested on sktime
+1.0.0 and 1.3.0; `tests/test_sktime.py` runs it in CI).
+
+| Estimator | sktime type | Input | Output |
+|---|---|---|---|
+| `RealizedVariance(freq="D", annualize=False, trading_days=252)` | transformer, Series to Series | intraday returns | one row per period: `sum r^2` |
+| `BipowerVariation(freq="D", annualize=False, trading_days=252)` | transformer, Series to Series | intraday returns | `(pi/2) sum abs(r_i) abs(r_{i-1})` |
+| `JumpVariation(freq="D", annualize=False, trading_days=252, relative=False)` | transformer, Series to Series | intraday returns | `max(RV - BV, 0)`, or that divided by RV if `relative` |
+| `HawkesIntensity(mu=0.5, alpha=0.6, beta=1.0, method="fixed", n_restarts=10, time_unit=None, causal=True, random_state=None)` | transformer, Series to Series (same index) | event counts | conditional intensity |
+| `HARForecaster(window_w=5, window_m=22)` | forecaster, univariate | per-period realized measure | forecasts at `fh` (out of sample) |
+
+### Realized measures
+
+- `freq` int: bars per period. Rows are labelled by the last bar of each period.
+  A trailing incomplete period is dropped.
+- `freq` str: pandas offset alias. Needs a DatetimeIndex (rows labelled by the
+  period start timestamp; time zones are dropped and wall-clock dates kept) or a
+  PeriodIndex (rows labelled by the period).
+- Multivariate input: one output column per input column.
+- No missing values (`capability:missing_values = False`). Drop or fill first.
+
+### HawkesIntensity
+
+- Input values are event counts per time stamp, rounded to the nearest integer,
+  negatives counted as zero.
+- Clock: DatetimeIndex in seconds unless `time_unit` is given ("1min", "1D", ...);
+  PeriodIndex in periods; integer or float index in its own values. Time starts
+  at 0 at the first label.
+- Events in the same time stamp count as simultaneous and do not excite each
+  other, so a clock coarser than `1 / beta` hides the fastest clustering. Pick
+  bins well below the decay time you expect.
+- `method="mle"` fits each series separately in `fit`. Fewer than 3 events
+  falls back to a Poisson rate (`alpha_ = 0`).
+- Fitted attributes: `mu_`, `alpha_`, `beta_`, `branching_ratio_`,
+  `log_likelihood_`, `n_events_`.
+- `transform` uses the events of the series it is given (not those seen in
+  `fit`) with the fitted parameters.
+- `causal=True` (default) excludes events at the current stamp, so the output is
+  usable as a feature without look-ahead. `causal=False` includes them.
+
+The original plan named the switch `fit="mle"`. An sktime estimator cannot have
+a parameter called `fit` (it would hide the `fit` method), so it is `method`.
+
+### HARForecaster
+
+- Needs at least `window_m + 4` observations.
+- `fit` stores the series; `update` appends and refits (`update_params=True`).
+- Fitted attributes: `params_` (`HARParams`), `coef_` (`const`, `rv_d`, `rv_w`, `rv_m`).
+- No prediction intervals and no in-sample predictions in 0.1.0.
+
+## numpy functions (`pip install hfvol`)
+
+### `hfvol.realized`
+
+| Function | Returns |
+|---|---|
+| `realized_variance(r, annualize=False, trading_days=252)` | float |
+| `realized_variance_series(r, freq=78, ...)` | array, one value per `freq` bars |
+| `bipower_variation(r, ...)` / `bipower_variation_series(r, freq=78, ...)` | float / array |
+| `jump_variation(r, ...)` | `(continuous, jump)` |
+| `jump_variation_series(r, freq=78, ...)` | array `(n_periods, 2)` |
+
+### `hfvol.har`
+
+| Function | Returns |
+|---|---|
+| `har_features(rv, window_w=5, window_m=22)` | design matrix `(n - window_m, 4)` |
+| `fit_har(rv, window_w=5, window_m=22)` | `HARParams(mu, beta_d, beta_w, beta_m)` |
+| `har_forecast_path(params, rv, horizon, ...)` | array of forecasts for steps 1..horizon |
+| `har_forecast(params, rv, horizon=1, ...)` | float, the `horizon`-step forecast |
+
+### `hfvol.hawkes` (fitting and residuals need scipy)
+
+| Function | Returns |
+|---|---|
+| `HawkesParams(mu, alpha, beta)` | `.branching_ratio`, `.is_stationary`, `.unconditional_intensity` |
+| `hawkes_simulate(params, T, rng=None)` | event times on `[0, T]` (Ogata thinning) |
+| `hawkes_intensity_path(events, params, times, include_current=True)` | intensity on a grid |
+| `hawkes_compensator(events, params, times)` | integrated intensity on a grid |
+| `hawkes_log_likelihood(events, T, params)` | float |
+| `fit_hawkes_mle(events, T, n_restarts=10, rng=None)` | `(HawkesParams, log_likelihood)` |
+| `branching_ratio(events, T, n_restarts=10, rng=None)` | float in `[0, 1]` |
+| `hawkes_residual_analysis(events, T, params)` | dict: `ks_statistic`, `ks_pvalue`, `mean_residual`, `std_residual`, `well_fit` |

hfvol-0.1.0/docs/ecosystem.md

@@ -0,0 +1,31 @@
+# Ecosystem plan
+
+hfvol exists so these pieces can be merged where people already look for them.
+
+## 1. sktime: realized-measure transformers (one estimator per PR)
+
+sktime has `sktime/transformations/hurst.py` but no realized measures. Planned
+PRs, each one file under `sktime/transformations/` and each passing
+`check_estimator`:
+
+1. `RealizedVariance`
+2. `BipowerVariation`
+3. `JumpVariation`
+
+The classes in `src/hfvol/transformers.py` follow sktime's transformer extension
+template and need only numpy and pandas, so each PR is one class plus its
+private helpers. Hurst is already in sktime and is not part of this.
+
+## 2. sktime: `HawkesIntensity`
+
+Either a PR (its only extra dependency is scipy, which sktime already requires)
+or a third-party estimator listing that points at hfvol. The usual alternative,
+`tick`, needs a C++ build.
+
+## 3. OpenBB (after hfvol is on PyPI)
+
+An OpenBB core-extension package that registers a router through the
+`openbb_core_extension` entry point and calls hfvol. Its name must not lead with
+the OpenBB trademark (for example `hfvol-router`, not `openbb-hfvol`).
+
+Status at 0.1.0: none of these has been submitted.

hfvol-0.1.0/docs/index.md

@@ -0,0 +1,77 @@
+# hfvol
+
+Realized variance, bipower variation, jump variation, Hawkes intensity and the
+HAR-RV forecaster, as sktime estimators on top of plain numpy functions.
+
+```
+pip install hfvol            # numpy functions only
+pip install "hfvol[sktime]"  # plus the sktime transformers and forecaster
+```
+
+## Why
+
+sktime has a Hurst-exponent transformer but no realized measures and no Hawkes
+process. The main Python Hawkes library (`tick`) needs a C++ build. hfvol fills
+both gaps with small numpy code that passes sktime's own
+`check_estimator` suite.
+
+## sktime
+
+```python
+import numpy as np, pandas as pd
+from hfvol import RealizedVariance, BipowerVariation, JumpVariation, HARForecaster
+
+# 5-minute returns, 78 bars per session, DatetimeIndex
+idx = pd.date_range("2024-01-02 09:35", periods=78 * 250, freq="5min")
+r = pd.Series(np.random.default_rng(0).normal(0, 1e-3, len(idx)), index=idx)
+
+rv = RealizedVariance(freq=78).fit_transform(r)  # one value per session
+bv = BipowerVariation(freq=78).fit_transform(r)  # jump-robust
+jv = JumpVariation(freq=78).fit_transform(r)  # max(RV - BV, 0)
+
+f = HARForecaster().fit(rv.reset_index(drop=True))
+f.predict(fh=[1, 5, 22])
+```
+
+`freq` is either an integer number of bars per period or a pandas offset alias
+(`"D"`, `"W"`, ...) that groups a DatetimeIndex by calendar period. Multivariate
+frames give one column per asset; Panel and hierarchical data work through
+sktime's usual vectorization.
+
+```python
+from hfvol import HawkesIntensity
+
+# trade counts per second; the intensity at each second uses only earlier trades
+lam = HawkesIntensity(method="mle", time_unit="1s", random_state=0).fit_transform(counts)
+```
+
+## numpy
+
+```python
+from hfvol import (
+    realized_variance,
+    bipower_variation,
+    jump_variation,
+    fit_har,
+    har_forecast,
+    HawkesParams,
+    hawkes_simulate,
+    fit_hawkes_mle,
+    hawkes_residual_analysis,
+)
+
+events = hawkes_simulate(HawkesParams(mu=0.5, alpha=0.8, beta=1.6), T=5000, rng=1)
+params, ll = fit_hawkes_mle(events, T=5000, rng=0)
+params.branching_ratio  # about 0.5
+hawkes_residual_analysis(events, 5000, params)["well_fit"]
+```
+
+## More
+
+- [API reference](api.md)
+- [Formulas and references](methods.md)
+- [Where this came from](provenance.md)
+- [Ecosystem plan (sktime, OpenBB)](ecosystem.md)
+- Examples: `examples/`
+
+MIT licensed. Carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab).

hfvol-0.1.0/docs/methods.md

@@ -0,0 +1,59 @@
+# Formulas and references
+
+## Realized measures
+
+For intraday returns `r_1, ..., r_n` of one period:
+
+- Realized variance: `RV = sum_i r_i^2` (Andersen and Bollerslev 1998).
+- Bipower variation: `BV = mu1^-2 sum_{i=2..n} |r_i| |r_{i-1}|`, with `mu1 = E|Z| = sqrt(2/pi)`
+  (Barndorff-Nielsen and Shephard 2004). No `n/(n-1)` small-sample factor.
+- Jump variation: `JV = max(RV - BV, 0)`; relative jump `JV / RV`
+  (Barndorff-Nielsen and Shephard 2006).
+
+As sampling gets finer, RV converges to integrated variance plus the sum of
+squared jumps, and BV to integrated variance alone. The tests check both on
+simulated data: with `r_i ~ N(0, s2/n)`, mean RV is `s2` and mean BV is
+`s2 (n-1)/n`; adding one jump `J` per day moves RV by `J^2` and BV only by about
+`pi mu1 sqrt(s2/n) J`.
+
+## HAR-RV
+
+Corsi (2009):
+
+    RV_{t+1} = c + b_d RV_t + b_w RV_t^(w) + b_m RV_t^(m) + e_{t+1}
+
+with `RV^(w)` and `RV^(m)` the means over the last 5 and 22 periods, estimated
+by OLS. Multi-step forecasts iterate the equation. The tests compare the OLS
+coefficients with the normal equations and recover known coefficients from a
+simulated HAR process.
+
+## Hawkes process (exponential kernel)
+
+    lambda(t) = mu + sum_{t_i < t} alpha exp(-beta (t - t_i))
+
+Branching ratio `n = alpha / beta`; stationary mean rate `mu / (1 - n)`.
+
+Log-likelihood on `[0, T]` (Ozaki 1979):
+
+    LL = sum_i log(mu + alpha R_i) - mu T - (alpha/beta) sum_i (1 - exp(-beta (T - t_i)))
+    R_1 = 0,  R_i = exp(-beta (t_i - t_{i-1})) (1 + R_{i-1})
+
+Compensator: `Lambda(t) = mu t + (alpha/beta) sum_{t_i <= t} (1 - exp(-beta (t - t_i)))`.
+Under the true model the increments `Lambda(t_i) - Lambda(t_{i-1})` are iid
+Exp(1) (time-rescaling theorem); `hawkes_residual_analysis` tests that with a
+Kolmogorov-Smirnov test. Simulation uses Ogata (1981) thinning.
+
+The tests check the likelihood against a closed form for two events and a
+brute-force O(n^2) sum, the compensator against numerical integration of the
+intensity, the simulated mean rate against `mu / (1 - n)`, and MLE recovery of
+`(mu, alpha, beta)`.
+
+## References
+
+- Andersen, T. G. and Bollerslev, T. (1998). Answering the skeptics: yes, standard volatility models do provide accurate forecasts. International Economic Review 39(4), 885-905.
+- Barndorff-Nielsen, O. E. and Shephard, N. (2004). Power and bipower variation with stochastic volatility and jumps. Journal of Financial Econometrics 2(1), 1-37.
+- Barndorff-Nielsen, O. E. and Shephard, N. (2006). Econometrics of testing for jumps in financial economics using bipower variation. Journal of Financial Econometrics 4(1), 1-30.
+- Corsi, F. (2009). A simple approximate long-memory model of realized volatility. Journal of Financial Econometrics 7(2), 174-196.
+- Hawkes, A. G. (1971). Spectra of some self-exciting and mutually exciting point processes. Biometrika 58(1), 83-90.
+- Ogata, Y. (1981). On Lewis' simulation method for point processes. IEEE Transactions on Information Theory 27(1), 23-31.
+- Ozaki, T. (1979). Maximum likelihood estimation of Hawkes' self-exciting point processes. Annals of the Institute of Statistical Mathematics 31, 145-155.

hfvol-0.1.0/docs/provenance.md

@@ -0,0 +1,30 @@
+# Provenance
+
+hfvol was carved out of [srfm-lab](https://github.com/Mattbusel/srfm-lab)
+(MIT, copyright 2026 Matthew Busel) at commit
+`8cbfcb0551d44e3ed1c20bdae9dc805d61521c62`.
+
+| hfvol | srfm-lab origin | Changes |
+|---|---|---|
+| `realized.realized_variance` | `lib/math/volatility_models.py` `realized_variance` (L130) | `annualize` default `False`; input validation |
+| `realized.realized_variance_series` | `realized_variance_series` (L145) | vectorised reshape instead of a Python loop |
+| `realized.bipower_variation` (+ `_series`) | `bipower_variation` (L169) | `annualize` default `False`; `_series` variant is new |
+| `realized.jump_variation` (+ `_series`) | `jump_variation` (L189) | `_series` variant is new |
+| `har.HARParams` | `HARParams` dataclass | frozen; `as_array()` |
+| `har.har_features` | `har_features` (L206) | vectorised with a cumulative sum; same values |
+| `har.fit_har` | `fit_har` (L226) | clear error when the series is too short |
+| `har.har_forecast`, `har.har_forecast_path` | `har_forecast` (L244) | same recursion; the path variant returns every step |
+| `hawkes.HawkesParams` | `lib/math/hawkes_process.py` `HawkesParams` | frozen; `_validate()` |
+| `hawkes.hawkes_simulate` | `hawkes_simulate` | O(n) excitation state instead of re-summing all past events; seedable; `ValueError` instead of `assert` |
+| `hawkes.hawkes_intensity_path` | `hawkes_intensity_path` | O(n + m) via `searchsorted` and the recursion; `include_current` switch |
+| `hawkes.hawkes_compensator` | new (was inline in `hawkes_residual_analysis`) | O(n + m) |
+| `hawkes.hawkes_log_likelihood` | `hawkes_log_likelihood` | same formula; checks event order |
+| `hawkes.fit_hawkes_mle` | `fit_hawkes_mle` | reparametrised, rate-scaled starts, seeded, keeps the best finite run (see CHANGELOG, Fixed) |
+| `hawkes.branching_ratio` | `branching_ratio` | seeded; unused local removed |
+| `hawkes.hawkes_residual_analysis` | `hawkes_residual_analysis` | O(n); includes the first increment |
+| `transformers.*`, `forecasting.*` | new | sktime wrappers built from sktime's extension templates |
+| `tests/*` | new | srfm-lab has no tests for these modules |
+
+Left behind: EWMA, GARCH and realized GARCH, VIX and variance risk premium,
+volatility surface, rough volatility (sktime already ships a Hurst
+transformer), and the multivariate Hawkes simulator.

hfvol-0.1.0/examples/hawkes_trade_intensity.py

@@ -0,0 +1,26 @@
+"""Hawkes intensity of trade arrivals as a look-ahead-free feature (pip install hfvol[sktime])."""
+
+import numpy as np
+import pandas as pd
+
+from hfvol import HawkesIntensity, HawkesParams, hawkes_simulate
+
+# Simulated trade times over one hour, in seconds. Excitation decays over ~20 s,
+# well above the 1 s bins used below. Trades in the same bin count as
+# simultaneous and do not excite each other, so pick bins finer than 1 / beta.
+true = HawkesParams(mu=0.05, alpha=0.04, beta=0.05)
+events = hawkes_simulate(true, T=3600.0, rng=7)
+
+# Trades per second on a DatetimeIndex.
+start = pd.Timestamp("2024-06-03 14:00:00")
+seconds = pd.date_range(start, periods=3600, freq="1s")
+counts = pd.Series(np.bincount(events.astype(int), minlength=3600)[:3600], index=seconds)
+
+tr = HawkesIntensity(method="mle", time_unit="1s", random_state=0)
+intensity = tr.fit_transform(counts)
+
+print(f"{int(counts.sum())} trades; true {true}, branching ratio {true.branching_ratio:.2f}")
+print(f"fitted mu={tr.mu_:.3f}/s alpha={tr.alpha_:.3f} beta={tr.beta_:.3f}/s")
+print(f"fitted branching ratio {tr.branching_ratio_:.2f}")
+print("busiest seconds by predicted intensity:")
+print(intensity.nlargest(5))

hfvol-0.1.0/examples/numpy_quickstart.py

@@ -0,0 +1,42 @@
+"""Realized measures, HAR-RV and Hawkes with numpy only (pip install hfvol[scipy])."""
+
+import numpy as np
+
+from hfvol import (
+    HawkesParams,
+    bipower_variation_series,
+    fit_har,
+    fit_hawkes_mle,
+    har_forecast_path,
+    hawkes_residual_analysis,
+    hawkes_simulate,
+    jump_variation_series,
+    realized_variance_series,
+)
+
+rng = np.random.default_rng(0)
+bars, days = 78, 300
+
+# Simulated 5-minute returns with slowly moving daily volatility and occasional jumps.
+daily_vol = 0.01 * np.exp(np.cumsum(rng.normal(0, 0.05, days)))
+r = rng.normal(0, 1, (days, bars)) * (daily_vol[:, None] / np.sqrt(bars))
+jump_days = rng.random(days) < 0.05
+r[jump_days, bars // 2] += 0.02
+r = r.ravel()
+
+rv = realized_variance_series(r, freq=bars)
+bv = bipower_variation_series(r, freq=bars)
+jv = jump_variation_series(r, freq=bars)[:, 1]
+print(f"mean RV {rv.mean():.3e}  mean BV {bv.mean():.3e}")
+print(f"mean jump variation on jump days {jv[jump_days].mean():.3e}")
+print(f"mean jump variation on other days {jv[~jump_days].mean():.3e}")
+
+params = fit_har(bv)
+print("HAR coefficients:", params)
+print("next 5 days:", np.round(har_forecast_path(params, bv, horizon=5), 7))
+
+true = HawkesParams(mu=0.5, alpha=0.8, beta=1.6)
+events = hawkes_simulate(true, T=5000.0, rng=1)
+est, ll = fit_hawkes_mle(events, T=5000.0, rng=0)
+print(f"{len(events)} events; fitted {est}, branching ratio {est.branching_ratio:.3f}")
+print("time-rescaling check:", hawkes_residual_analysis(events, 5000.0, est))

hfvol-0.1.0/examples/sktime_pipeline.py

@@ -0,0 +1,44 @@
+"""Daily realized measures from intraday returns, then a HAR forecast.
+
+Needs pip install "hfvol[sktime]".
+"""
+
+import numpy as np
+import pandas as pd
+from sktime.forecasting.model_evaluation import evaluate
+from sktime.split import ExpandingWindowSplitter
+
+from hfvol import BipowerVariation, HARForecaster, JumpVariation, RealizedVariance
+
+rng = np.random.default_rng(0)
+bars = 78
+sessions = pd.bdate_range("2024-01-02", periods=250)
+index = pd.DatetimeIndex(
+    np.concatenate(
+        [pd.date_range(d + pd.Timedelta("9h35min"), periods=bars, freq="5min") for d in sessions]
+    )
+)
+vol = np.repeat(0.01 * np.exp(np.cumsum(rng.normal(0, 0.05, len(sessions)))), bars)
+returns = pd.DataFrame(
+    {
+        "SPY": rng.normal(0, 1, len(index)) * vol / np.sqrt(bars),
+        "QQQ": rng.normal(0, 1, len(index)) * 1.3 * vol / np.sqrt(bars),
+    },
+    index=index,
+)
+
+# One row per calendar day, one column per asset.
+rv = RealizedVariance(freq="D").fit_transform(returns)
+bv = BipowerVariation(freq="D").fit_transform(returns)
+jv = JumpVariation(freq="D", relative=True).fit_transform(returns)
+print(rv.tail(3), bv.tail(3), jv.tail(3), sep="\n\n")
+
+# HAR on SPY's daily realized variance, evaluated with an expanding window.
+y = rv["SPY"].reset_index(drop=True)
+cv = ExpandingWindowSplitter(initial_window=150, step_length=10, fh=[1, 5])
+results = evaluate(HARForecaster(), cv=cv, y=y)
+print(results[["test_MeanAbsolutePercentageError", "cutoff"]].tail())
+
+forecaster = HARForecaster().fit(y)
+print("coefficients:\n", forecaster.coef_)
+print("next 5 days:\n", forecaster.predict(fh=[1, 2, 3, 4, 5]))