regime

Documentation

Overview

Experimental — this package is not yet wired into the main framework.

Package regime provides Hidden Markov Model (HMM) based regime classification for time series data.

The primary entry point is the HMM type, which models observable sequences as being generated by transitions between hidden states (regimes). Typical regimes include trending, mean-reverting, volatile, and crash states.

Training uses the Baum-Welch algorithm (Expectation-Maximisation for HMMs):

1. Forward pass — compute forward probabilities α(t,i) = P(o₁…oₜ, sₜ=i).
2. Backward pass — compute backward probabilities β(t,i) = P(oₜ₊₁…oT | sₜ=i).
3. E-step — compute state occupation γ(t,i) and transition ξ(t,i,j) posteriors.
4. M-step — re-estimate initial, transition, and emission parameters.

Decoding uses the Viterbi algorithm to find the most likely hidden state sequence given an observation sequence.

Emissions are modelled as univariate Gaussians (one mean and variance per hidden state).

(Stability: alpha)

Index

• type Config
• type HMM
  • func NewHMM(cfg Config) (*HMM, error)
  • func (h *HMM) Fit(obs []float64, cfg Config) (logLikelihood float64, iterations int, err error)
  • func (h *HMM) LogLikelihood(obs []float64) (float64, error)
  • func (h *HMM) NStates() int
  • func (h *HMM) Predict(obs []float64) (state int, probs []float64, err error)
  • func (h *HMM) Viterbi(obs []float64) ([]int, error)

Types

type Config

type Config struct {
	// NStates is the number of hidden states (regimes). Must be >= 2.
	NStates int

	// MaxIterations is the maximum number of Baum-Welch EM iterations.
	// Default: 100.
	MaxIterations int

	// Tolerance is the log-likelihood convergence threshold. Training stops
	// when the absolute change in log-likelihood is below this value.
	// Default: 1e-6.
	Tolerance float64

	// Seed for random initialisation. A value of 0 uses a fixed default seed.
	Seed int64
}

Config controls HMM training behaviour.

type HMM

type HMM struct {

	// Initial state probabilities π[i] = P(s₁ = i).
	Initial []float64

	// Transition matrix A[i][j] = P(sₜ₊₁ = j | sₜ = i).
	Transition [][]float64

	// Emission parameters: Gaussian mean and variance per state.
	Means     []float64
	Variances []float64
	// contains filtered or unexported fields
}

HMM is a Hidden Markov Model with Gaussian emissions for regime classification. Hidden states represent distinct regimes (e.g. trending, mean-reverting, volatile, crash).

func NewHMM

func NewHMM(cfg Config) (*HMM, error)

NewHMM creates a new HMM with the given configuration. Parameters are initialised randomly.

func (*HMM) Fit

func (h *HMM) Fit(obs []float64, cfg Config) (logLikelihood float64, iterations int, err error)

Fit trains the HMM on the observation sequence using the Baum-Welch algorithm. It returns the final log-likelihood and number of iterations performed.

func (*HMM) LogLikelihood

func (h *HMM) LogLikelihood(obs []float64) (float64, error)

LogLikelihood computes the log-likelihood of the observation sequence under the current model parameters.

func (*HMM) NStates

func (h *HMM) NStates() int

NStates returns the number of hidden states.

func (*HMM) Predict

func (h *HMM) Predict(obs []float64) (state int, probs []float64, err error)

Predict returns the most likely regime (hidden state index) for the final observation in the sequence, along with the posterior probabilities for each state.

func (*HMM) Viterbi

func (h *HMM) Viterbi(obs []float64) ([]int, error)

Viterbi returns the most likely hidden state sequence for the given observations using the Viterbi algorithm.