detect_regimes¶
Defined in fynance.features.regime
- detect_regimes(X, n_regimes=3, w=21, period=252, seed=0)[source]
Label market regimes by k-means on rolling vol / return features.
Builds two features per date — trailing realized volatility and trailing mean return — standardizes them, and clusters with k-means into
n_regimesgroups. Labels are ordered by mean volatility (0 = calmest,n_regimes - 1= most volatile) so they are comparable across runs.Note
The clustering is fit in-sample (it sees the whole series), so the labels are appropriate for analysis and for studying regime conditioning — not as a strictly-causal online feature. A causal online assignment (fit on the past only) is a separate extension.
- Parameters:
- Xnp.ndarray
One-dimensional price/level series.
- n_regimesint, optional
Number of regimes (clusters). Default 3.
- wint, optional
Rolling window for the features. Default 21.
- periodint, optional
Annualization factor for the volatility feature. Default 252.
- seedint, optional
Seed for the k-means initialization. Default 0.
- Returns:
- np.ndarray
Integer regime label per observation, shape
(len(X),), in[0, n_regimes)and ordered by increasing average volatility.