hdp-hmm-te

Disentangled Sticky Hierarchical Dirichlet Process Hidden Markov Model with Topological Emissions (developed in VS Code using Julia)

The model detects changes in time series data by capturing key topological features of the data's overall “shape.”

This is accomplished by computing vectorized persistence diagrams from sliding windows of the data. These topological summaries are then used as the emission features in a Hidden Markov Model (HMM).

To allow the number of hidden states to be determined automatically, the model places a Hierarchical Dirichlet Process (HDP) prior on the Markov transition process.

The primary code is found in the Source_Code folder. Once Julia is installed, the following packages must also be available.

Clustering, CSV, DataFrames, DelimitedFiles, Distributions, Hungarian, LinearAlgebra, PersistenceDiagrams, PlotlyJS, Printf, ProgressBars, Random, Ripserer, Serialization, SpecialFunctions, StatsBase,

Disentangled Sticky Hierarchical Dirichlet Process Hidden Markov Model with Topological Emissions (ds-HDP-HMM-TE).

This repository contains:

• Julia source code for training and evaluating the model
• utilities for topological data analysis (TDA)-based emissions
• sample datasets used by the provided scripts

• Source_Code/ — core Julia implementation and usage notes
  • ds_HDP_HMM_w_TDA_weak_limit.jl — main model implementation
  • ds_HDP_HMM_AUX.jl — helper routines used by the model
  • TDA_Tools.jl — TDA feature/persistence-diagram tooling
  • README.md — script-level usage details
• Sample_Data/ — CSV sample datasets and data preparation notes
  • README.md — how to transform CSV data into serialized persistence-image inputs expected by the model

• Julia (version compatible with the scripts in Source_Code/)
• The following Julia packages:

Clustering
CSV
DataFrames
DelimitedFiles
Distributions
Hungarian
LinearAlgebra
PersistenceDiagrams
PlotlyJS
Printf
ProgressBars
Random
Ripserer
Serialization
SpecialFunctions
StatsBase
Tables

1. Install Julia.
2. Ensure all required packages are available in your Julia environment.
3. Prepare the data:
   • Start from files in Sample_Data/ (or your own equivalent data).
   • Convert the CSV inputs into vectorized persistence images.
   • Save those persistence-image outputs as Julia Serialization objects.
   • Follow Sample_Data/README.md for the expected preparation workflow.

1. Open the scripts in Source_Code/.
2. Follow the execution instructions in Source_Code/README.md.
3. Point script configuration to your prepared serialized input data.

The included sample data are intended as reference/test inputs for the repository workflow. File naming in Sample_Data/ reflects train/test splits and state/change-point variants used by the example pipeline.

• For dataset preparation specifics: Sample_Data/README.md
• For script-level execution details and parameters: Source_Code/README.md

See README in Source_Code for details. If you use this project in research, consider documenting the exact Julia/package versions used in your environment to improve reproducibility.

The model implemented here draws on the following works.

1. Fox, E., Sudderth, E., Jordan, M., & Willsky, A. (2009).
   The Sticky HDP–HMM: Bayesian Nonparametric Hidden Markov Models with Persistent States.
   MIT Laboratory for Information and Decision Systems Technical Report.

2. Teh, Y. W., Jordan, M. I., Beal, M. J., & Blei, D. M. (2006).
   Hierarchical Dirichlet Processes.
   Journal of the American Statistical Association, 101(476), 1566–1581.

3. Zheng, X., Mak, S., Xie, L., & Xie, Y. (2023).
   PERCEPT: A New Online Change-Point Detection Method Using Topological Data Analysis.
   Technometrics, 65(2), 162–178.

4. Zhou, D., Gao, Y., & Paninski, L. (2020).
   Disentangled Sticky Hierarchical Dirichlet Process Hidden Markov Model.
   In Machine Learning and Knowledge Discovery in Databases (ECML PKDD). Springer.