mrv.models – Regime model fitting

mrv.models – Regime model registry.

Built-in: gmm, hmm. Add custom: register_model("name", fn).

Model function signature: (features: DataFrame, K: int, **kwargs) -> ndarray | None

mrv.models.fit(features, model='gmm', n_states=3, **kwargs)

Fit a regime model and return hard labels (or None on failure).

n_states is the number of regime states (also accepted as K via kwargs). The value is forwarded to the model function as K.

Return type:

Optional[ndarray]

mrv.models.register_model(name, fn)

Register a model function.

Return type:

None

Sub-modules

GMM fitting

mrv.models.gmm – Gaussian Mixture Model.

mrv.models.gmm.fit_gmm(features, K=3, **kwargs)

Fit a Gaussian Mixture Model and return hard regime labels.

Parameters:

• features (DataFrame) – Normalised feature matrix. Rows with NaN are dropped before fitting.

• K (int) – Number of mixture components (regime states).

• **kwargs – random_state (default 1) and n_init (default 10) are forwarded to sklearn.mixture.GaussianMixture.

Returns:

Integer label array of shape (n_obs,) where n_obs = len(features.dropna()), or None when the input is too short to fit (fewer than max(K * 5, 20) rows after NaN removal).

Return type:

Optional[ndarray]

HMM fitting

mrv.models.hmm – Gaussian Hidden Markov Model.

mrv.models.hmm.fit_hmm(features, K=3, **kwargs)

Fit a Gaussian Hidden Markov Model and return Viterbi-decoded regime labels.

Parameters:

• features (DataFrame) – Normalised feature matrix. Rows with NaN are dropped before fitting.

• K (int) – Number of hidden states (regime states).

• **kwargs – covariance_type (default "full"), n_iter (default 200), and random_state (default 1) are forwarded to hmmlearn.hmm.GaussianHMM.

Returns:

Integer label array of shape (n_obs,) where n_obs = len(features.dropna()), or None when the input is too short to fit (fewer than max(K * 5, 20) rows after NaN removal).

Return type:

Optional[ndarray]

Raises:

ImportError – If hmmlearn is not installed (pip install hmmlearn).