overfitlab 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
overfitlab/__init__.py ADDED
@@ -0,0 +1,119 @@
1
+ """overfitlab: statistics that separate a real trading signal from a lucky one."""
2
+
3
+ from overfitlab._normal import EULER_GAMMA
4
+ from overfitlab.bootstrap import optimal_block_length, stationary_bootstrap_indices
5
+ from overfitlab.cv import CombinatorialPurgedCV, PurgedKFold, assemble_paths
6
+ from overfitlab.deflated import (
7
+ deflated_sharpe_ratio,
8
+ dsr_from_returns,
9
+ expected_max_sharpe,
10
+ min_backtest_length,
11
+ )
12
+ from overfitlab.factory import StrategySpec, run_strategies, strategy_grid
13
+ from overfitlab.haircut import haircut_sharpe, sharpe_to_tstat
14
+ from overfitlab.pbo import PBOResult, pbo_cscv
15
+ from overfitlab.results import DSRResult, HaircutResult, ReturnMoments
16
+ from overfitlab.sharpe import (
17
+ annualize_sharpe,
18
+ min_track_record_length,
19
+ probabilistic_sharpe_ratio,
20
+ psr_from_returns,
21
+ return_moments,
22
+ sharpe_ratio,
23
+ sharpe_std,
24
+ )
25
+ from overfitlab.snooping import (
26
+ SnoopResult,
27
+ SPAResult,
28
+ StepMResult,
29
+ reality_check,
30
+ romano_wolf_stepdown,
31
+ spa_test,
32
+ )
33
+ from overfitlab.synth import (
34
+ SynthResult,
35
+ block_bootstrap_returns,
36
+ gaussian_noise,
37
+ gbm_prices,
38
+ planted_signal_matrix,
39
+ planted_signal_prices,
40
+ student_t_noise,
41
+ )
42
+ from overfitlab.triallog import (
43
+ TRIAL_LOG_COLUMNS,
44
+ TRIAL_LOG_VERSION,
45
+ TrialLog,
46
+ TrialLogError,
47
+ TrialLogger,
48
+ TrialLogIssue,
49
+ TrialLogReport,
50
+ TrialSharpes,
51
+ add_manual_trial,
52
+ canonical_params_json,
53
+ evaluate_trial_log,
54
+ read_trial_log,
55
+ validate_trial_log,
56
+ )
57
+ from overfitlab.verdict import VerdictConfig, VerdictReport, evaluate
58
+
59
+ __version__ = "0.1.0"
60
+
61
+ __all__ = [
62
+ "EULER_GAMMA",
63
+ "CombinatorialPurgedCV",
64
+ "DSRResult",
65
+ "HaircutResult",
66
+ "PBOResult",
67
+ "PurgedKFold",
68
+ "ReturnMoments",
69
+ "SPAResult",
70
+ "SnoopResult",
71
+ "StepMResult",
72
+ "StrategySpec",
73
+ "SynthResult",
74
+ "TRIAL_LOG_COLUMNS",
75
+ "TRIAL_LOG_VERSION",
76
+ "TrialLog",
77
+ "TrialLogError",
78
+ "TrialLogIssue",
79
+ "TrialLogReport",
80
+ "TrialLogger",
81
+ "TrialSharpes",
82
+ "VerdictConfig",
83
+ "VerdictReport",
84
+ "__version__",
85
+ "add_manual_trial",
86
+ "annualize_sharpe",
87
+ "assemble_paths",
88
+ "block_bootstrap_returns",
89
+ "canonical_params_json",
90
+ "deflated_sharpe_ratio",
91
+ "dsr_from_returns",
92
+ "evaluate",
93
+ "evaluate_trial_log",
94
+ "expected_max_sharpe",
95
+ "gaussian_noise",
96
+ "gbm_prices",
97
+ "haircut_sharpe",
98
+ "min_backtest_length",
99
+ "min_track_record_length",
100
+ "optimal_block_length",
101
+ "pbo_cscv",
102
+ "planted_signal_matrix",
103
+ "planted_signal_prices",
104
+ "probabilistic_sharpe_ratio",
105
+ "psr_from_returns",
106
+ "read_trial_log",
107
+ "reality_check",
108
+ "return_moments",
109
+ "romano_wolf_stepdown",
110
+ "run_strategies",
111
+ "sharpe_ratio",
112
+ "sharpe_std",
113
+ "sharpe_to_tstat",
114
+ "spa_test",
115
+ "stationary_bootstrap_indices",
116
+ "strategy_grid",
117
+ "student_t_noise",
118
+ "validate_trial_log",
119
+ ]
overfitlab/_arrays.py ADDED
@@ -0,0 +1,124 @@
1
+ """Input coercion shared by every public function.
2
+
3
+ Array arguments accept NumPy arrays, nested lists and, when Polars is installed,
4
+ ``pl.Series`` and ``pl.DataFrame``. Polars is duck-typed through ``.to_numpy()`` so
5
+ it is never imported here.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ from typing import Any
11
+
12
+ import numpy as np
13
+ from numpy.typing import NDArray
14
+
15
+ F64 = NDArray[np.float64]
16
+
17
+
18
+ def as_float_array(x: Any, *, name: str = "x", allow_nan: bool = False) -> F64:
19
+ """Convert ``x`` to a ``float64`` array and reject non-finite values.
20
+
21
+ Parameters
22
+ ----------
23
+ x : array_like
24
+ NumPy array, nested list or an object with a ``to_numpy()`` method.
25
+ name : str, default "x"
26
+ Argument name used in error messages.
27
+ allow_nan : bool, default False
28
+ Keep NaN and inf. Only functions that document their NaN handling set this.
29
+
30
+ Returns
31
+ -------
32
+ numpy.ndarray
33
+ Array of dtype ``float64``.
34
+
35
+ Raises
36
+ ------
37
+ ValueError
38
+ If ``x`` holds NaN or inf and ``allow_nan`` is false.
39
+
40
+ Examples
41
+ --------
42
+ >>> as_float_array([1, 2, 3]).tolist()
43
+ [1.0, 2.0, 3.0]
44
+ """
45
+ if hasattr(x, "to_numpy"):
46
+ x = x.to_numpy()
47
+ arr = np.asarray(x, dtype=np.float64)
48
+ if not allow_nan and not np.isfinite(arr).all():
49
+ raise ValueError(f"{name} contains NaN or inf")
50
+ return arr
51
+
52
+
53
+ def as_vector(x: Any, *, name: str = "x", allow_nan: bool = False) -> F64:
54
+ """Convert ``x`` to a one-dimensional ``float64`` array.
55
+
56
+ A single-column matrix is flattened, so a one-column ``pl.DataFrame`` is accepted.
57
+
58
+ Parameters
59
+ ----------
60
+ x : array_like
61
+ Input values.
62
+ name : str, default "x"
63
+ Argument name used in error messages.
64
+ allow_nan : bool, default False
65
+ Keep NaN and inf.
66
+
67
+ Returns
68
+ -------
69
+ numpy.ndarray
70
+ One-dimensional array of dtype ``float64``.
71
+
72
+ Raises
73
+ ------
74
+ ValueError
75
+ If ``x`` is not one-dimensional or holds non-finite values.
76
+
77
+ Examples
78
+ --------
79
+ >>> as_vector([[1.0], [2.0]]).tolist()
80
+ [1.0, 2.0]
81
+ """
82
+ arr = as_float_array(x, name=name, allow_nan=allow_nan)
83
+ if arr.ndim == 2 and arr.shape[1] == 1:
84
+ arr = arr[:, 0]
85
+ if arr.ndim != 1:
86
+ raise ValueError(f"{name} must be one-dimensional, got shape {arr.shape}")
87
+ return arr
88
+
89
+
90
+ def as_matrix(x: Any, *, name: str = "returns", allow_nan: bool = False) -> F64:
91
+ """Convert ``x`` to a two-dimensional ``float64`` array of shape ``(T, N)``.
92
+
93
+ A one-dimensional input becomes a single column.
94
+
95
+ Parameters
96
+ ----------
97
+ x : array_like
98
+ Input values, rows are observations and columns are trials.
99
+ name : str, default "returns"
100
+ Argument name used in error messages.
101
+ allow_nan : bool, default False
102
+ Keep NaN and inf.
103
+
104
+ Returns
105
+ -------
106
+ numpy.ndarray
107
+ Two-dimensional array of dtype ``float64``.
108
+
109
+ Raises
110
+ ------
111
+ ValueError
112
+ If ``x`` has more than two dimensions or holds non-finite values.
113
+
114
+ Examples
115
+ --------
116
+ >>> as_matrix([1.0, 2.0]).shape
117
+ (2, 1)
118
+ """
119
+ arr = as_float_array(x, name=name, allow_nan=allow_nan)
120
+ if arr.ndim == 1:
121
+ arr = arr[:, np.newaxis]
122
+ if arr.ndim != 2:
123
+ raise ValueError(f"{name} must be two-dimensional, got shape {arr.shape}")
124
+ return arr
overfitlab/_normal.py ADDED
@@ -0,0 +1,92 @@
1
+ """Normal distribution helpers built on ``scipy.special``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import numpy as np
6
+ from scipy.special import log_ndtr, ndtr, ndtri
7
+
8
+ EULER_GAMMA: float = 0.5772156649015329
9
+
10
+
11
+ def norm_cdf(x: float) -> float:
12
+ """Return the standard normal CDF at ``x``.
13
+
14
+ Parameters
15
+ ----------
16
+ x : float
17
+ Point of evaluation.
18
+
19
+ Returns
20
+ -------
21
+ float
22
+ ``Phi(x)``.
23
+
24
+ Examples
25
+ --------
26
+ >>> round(norm_cdf(1.96), 3)
27
+ 0.975
28
+ """
29
+ return float(ndtr(x))
30
+
31
+
32
+ def norm_ppf(p: float) -> float:
33
+ """Return the standard normal quantile of ``p``.
34
+
35
+ Parameters
36
+ ----------
37
+ p : float
38
+ Probability in ``[0, 1]``.
39
+
40
+ Returns
41
+ -------
42
+ float
43
+ ``Phi^-1(p)``.
44
+
45
+ Examples
46
+ --------
47
+ >>> round(norm_ppf(0.975), 2)
48
+ 1.96
49
+ """
50
+ return float(ndtri(p))
51
+
52
+
53
+ def norm_sf(x: float) -> float:
54
+ """Return the upper tail ``1 - Phi(x)`` without losing precision far in the tail.
55
+
56
+ Parameters
57
+ ----------
58
+ x : float
59
+ Point of evaluation.
60
+
61
+ Returns
62
+ -------
63
+ float
64
+ ``1 - Phi(x)``, computed from the log lower tail of ``-x``.
65
+
66
+ Examples
67
+ --------
68
+ >>> norm_sf(10.0) < 1e-22
69
+ True
70
+ """
71
+ return float(np.exp(log_ndtr(-x)))
72
+
73
+
74
+ def upper_quantile(tail: float) -> float:
75
+ """Return ``Phi^-1(1 - tail)``, accurate when ``tail`` is tiny.
76
+
77
+ Parameters
78
+ ----------
79
+ tail : float
80
+ Upper-tail probability in ``(0, 1)``.
81
+
82
+ Returns
83
+ -------
84
+ float
85
+ Quantile with ``tail`` probability above it.
86
+
87
+ Examples
88
+ --------
89
+ >>> round(upper_quantile(0.05), 3)
90
+ 1.645
91
+ """
92
+ return -float(ndtri(tail))
@@ -0,0 +1,137 @@
1
+ """Stationary bootstrap indices and automatic block length.
2
+
3
+ Indices are generated with a NumPy ``Generator``, so results are the same on every OS, and
4
+ are passed into the tests as plain arrays.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import math
10
+
11
+ import numpy as np
12
+ from numpy.typing import ArrayLike, NDArray
13
+
14
+ from overfitlab._arrays import as_vector
15
+
16
+ F64 = NDArray[np.float64]
17
+ I64 = NDArray[np.int64]
18
+ RNGLike = np.random.Generator | int | None
19
+
20
+
21
+ def stationary_bootstrap_indices(
22
+ n_obs: int, n_boot: int, *, mean_block: float, rng: RNGLike = None
23
+ ) -> I64:
24
+ """Return indices of the stationary bootstrap of Politis and Romano (1994).
25
+
26
+ Each position starts a new block with probability ``1 / mean_block`` and otherwise
27
+ continues the previous block, wrapping around the end of the sample. Block lengths are
28
+ geometric with mean ``mean_block``.
29
+
30
+ Parameters
31
+ ----------
32
+ n_obs : int
33
+ Observations in the sample and in each resample.
34
+ n_boot : int
35
+ Number of resamples.
36
+ mean_block : float
37
+ Mean block length, at least 1.
38
+ rng : numpy.random.Generator or int or None, optional
39
+ Source of randomness.
40
+
41
+ Returns
42
+ -------
43
+ numpy.ndarray
44
+ Integer array of shape ``(n_boot, n_obs)``.
45
+
46
+ Raises
47
+ ------
48
+ ValueError
49
+ If an argument is out of range.
50
+
51
+ Examples
52
+ --------
53
+ >>> stationary_bootstrap_indices(5, 2, mean_block=2.0, rng=0).shape
54
+ (2, 5)
55
+ """
56
+ if n_obs < 1 or n_boot < 1:
57
+ raise ValueError("n_obs and n_boot must be at least 1")
58
+ if mean_block < 1.0:
59
+ raise ValueError("mean_block must be at least 1")
60
+ generator = np.random.default_rng(rng)
61
+ starts_block = generator.random((n_boot, n_obs)) < 1.0 / mean_block
62
+ starts_block[:, 0] = True
63
+ starts = generator.integers(0, n_obs, size=(n_boot, n_obs), dtype=np.int64)
64
+ positions = np.arange(n_obs, dtype=np.int64)
65
+ latest = np.maximum.accumulate(np.where(starts_block, positions, 0), axis=1)
66
+ origin = np.take_along_axis(starts, latest, axis=1)
67
+ return (origin + positions - latest) % n_obs
68
+
69
+
70
+ def optimal_block_length(x: ArrayLike) -> float:
71
+ r"""Return the stationary bootstrap block length of Politis and White (2004).
72
+
73
+ Uses the flat-top lag window and the correction of Patton, Politis and White (2009):
74
+ :math:`b = (2\hat{G}^2/\hat{D})^{1/3} n^{1/3}`, with
75
+ :math:`\hat{D} = 2\hat{\sigma}^4`. The result is capped at the sample's upper bound
76
+ :math:`\min(3\sqrt{n}, n/3)` and floored at 1.
77
+
78
+ Parameters
79
+ ----------
80
+ x : array_like
81
+ One-dimensional series.
82
+
83
+ Returns
84
+ -------
85
+ float
86
+ Mean block length.
87
+
88
+ Raises
89
+ ------
90
+ ValueError
91
+ If there are fewer than nine observations.
92
+
93
+ Examples
94
+ --------
95
+ >>> rng = np.random.default_rng(0)
96
+ >>> round(optimal_block_length(rng.standard_normal(1000)), 1) < 3.0
97
+ True
98
+ """
99
+ series = as_vector(x, name="x")
100
+ n_obs = series.size
101
+ if n_obs < 9:
102
+ raise ValueError("at least 9 observations are needed")
103
+ centred = series - series.mean()
104
+ variance = float(np.dot(centred, centred)) / n_obs
105
+ if variance <= 0.0:
106
+ return 1.0
107
+
108
+ significance_run = max(5, math.ceil(math.log10(n_obs)))
109
+ max_lag = math.ceil(math.sqrt(n_obs)) + significance_run
110
+ max_lag = min(max_lag, n_obs - 1)
111
+ autocov = np.array(
112
+ [float(np.dot(centred[:-k], centred[k:])) / n_obs for k in range(1, max_lag + 1)]
113
+ )
114
+ rho = np.abs(autocov) / variance
115
+
116
+ threshold = 2.0 * math.sqrt(math.log10(n_obs) / n_obs)
117
+ lag = 0
118
+ for k in range(rho.size - significance_run + 1):
119
+ if (rho[k : k + significance_run] < threshold).all():
120
+ lag = k
121
+ break
122
+ else:
123
+ significant = np.flatnonzero(rho > threshold)
124
+ lag = int(significant[-1]) + 1 if significant.size else 0
125
+ window_end = min(2 * max(lag, 1), max_lag)
126
+
127
+ lags = np.arange(1, window_end + 1, dtype=np.float64)
128
+ ratio = lags / window_end
129
+ flat_top = np.where(ratio <= 0.5, 1.0, 2.0 * (1.0 - ratio))
130
+ weighted = flat_top * autocov[:window_end]
131
+ g_hat = 2.0 * float(np.sum(weighted * lags))
132
+ long_run = variance + 2.0 * float(np.sum(weighted))
133
+ d_hat = 2.0 * long_run**2
134
+ if g_hat == 0.0 or d_hat == 0.0:
135
+ return 1.0
136
+ length = (2.0 * g_hat**2 / d_hat) ** (1.0 / 3.0) * n_obs ** (1.0 / 3.0)
137
+ return float(min(max(length, 1.0), 3.0 * math.sqrt(n_obs), n_obs / 3.0))