Article-22745-Categorical-Hidden-Markov-Model-MQL5/README.md

Article-22745-Categorical-Hidden-Markov-Model-MQL5

This repository is an article-derived reference project based on the original MQL5 article. It does not claim to reproduce the full original source code unless files are explicitly attached.

## Overview

Reference repository for an MQL5 implementation of a categorical Hidden Markov Model (HMM) as a discrete-state, discrete-observation state space model. The article describes a `CCategoricalHMM` class and example scripts covering posterior inference, Baum-Welch training, synthetic sampling, model selection via AIC/BIC, and online filtering.

## Original Article

- Article ID: 22745
- Author: Evgeniy Chernish
- Publication date: 2026.06.01 00:41
- Category: Library
- URL: https://www.mql5.com/ru/articles/22745

## Repository Purpose

This repository is intended as a technical reference/reconstruction of the article’s MQL5 material on categorical HMMs.

Its purpose is to preserve the described class interface, workflow, and example scenarios:

- hidden state inference with Forward-Backward
- parameter estimation with EM / Baum-Welch
- synthetic sequence generation
- hidden-state-count selection using AIC/BIC
- real-time recursive filtering

## Key Concepts

- State Space Models (SSM)
- Hidden Markov Models (HMM)
- Discrete latent states
- Categorical emissions
- Transition matrix `TR`
- Emission matrix `E`
- Forward-Backward inference
- Filtering vs smoothing
- EM / Baum-Welch training
- Dirichlet-based random initialization
- Bayesian regularization with pseudo-counts
- AIC / BIC model selection
- Online Bayesian filtering

## Algorithm / Architecture Summary

The article presents a class `CCategoricalHMM` with the following documented members and methods:

- Core parameters:
- `m_numStates`
- `m_numEmissions`
- `m_TR`
- `m_E`
- Priors / regularization:
- `m_pTR`
- `m_pE`
- Training history:
- `m_logliks`

Main methods described in the article:

- `Fit(...)`
- Trains transition and emission matrices with the Baum-Welch EM algorithm.
- Uses scaled inference internally.
- Supports tolerance-based convergence checks.
- Can use pseudo-count priors to avoid zero-probability degeneration.

- `Inference(...)`
- Implements scaled Forward-Backward inference.
- Produces:
- smoothing distribution
- filtering distribution
- backward conditional likelihood terms
- log-likelihood
- scaling coefficients

- `Sample(...)`
- Generates hidden-state and observation sequences from supplied `TR` and `E`.
- Uses cumulative distributions for categorical sampling.

- `Filter(...)`
- Performs one-step online Bayesian update from previous state probabilities and a new observation.

- `AIC(...)`, `BIC(...)`, `GetParams()`
- Support model selection by balancing fit quality and model complexity.

The article also discusses random row initialization with Dirichlet distributions through helper methods:
- `RandomDirichlet(...)`
- `RandomizeMatrix(...)`

## Mentioned or Attached Files

### Explicitly attached files

No attached source files were available in the processed input.

### Files mentioned in the article text

- `CategoricalHMM.mqh` — class declaration and implementation outline for `CCategoricalHMM`
- `Inference.mq5` — inference and synthetic sampling example
- `Learning.mq5` — Baum-Welch training example
- `ModelSelection.mq5` — hidden-state-count selection with AIC/BIC
- `Filter.mq5` — online filtering example
- `MQL5.zip` — archive said to contain the article files

## Statistics

- Language: MQL5
- Main model type: categorical Hidden Markov Model
- Hidden states in examples: 2 and 3
- Emission symbols in examples: 6
- Example inference sample size: 300
- Example model-selection sample size: 5000
- Multi-start fits in model selection example: 10
- Training iterations shown:
- up to 100 in `Learning.mq5`
- 20 in `ModelSelection.mq5`

## Tags

`mql5`, `hmm`, `hidden-markov-model`, `state-space-model`, `categorical-distribution`, `baum-welch`, `forward-backward`, `bayesian-filtering`, `aic`, `bic`

## Difficulty

Intermediate to Advanced

## Limitations

- The full original repository content was not attached in the processed input.
- Article metadata is incomplete: article ID, publication date, category, and URL were not provided.
- This README is based on the article text and code excerpts only.
- Some implementation details may remain unavailable outside the quoted snippets.
- No claim is made that this repository exactly matches the author’s original archive unless the referenced files are explicitly added.

## Reference

Based on the original MQL5 article by Evgeniy Chernish describing the `CCategoricalHMM` class, its mathematical background, and example scripts for inference, training, model selection, and online filtering.