GLM-HMM Comparison Tool

Cross-validated fitting and comparison of Generalized Linear Model Hidden Markov Models (GLM-HMMs) for behavioral neuroscience. Based on the framework from Ashwood et al. (2022).

What it does

Fits and compares two GLM-HMM architectures:

• Original (Sticky): All covariates in the observation model. States are defined by the full stimulus–choice mapping including modulatory variables (e.g., pupil).
• New (InputDriven): Modulatory covariates moved to the transition model. States are defined purely by the stimulus–choice mapping; modulatory variables influence when the animal switches states, not what the states are.

This addresses a common circularity concern in GLM-HMM analyses: if a variable (e.g., arousal/pupil) helps define the states, you can't then analyze that variable within states without circular reasoning.

Tools

glmhmm_cv_comparison.py — Cross-Validated Model Selection

5-fold cross-validation across K=1–4 states for both model types. Reports:

• Accuracy, ROC-AUC, PR-AUC
• Held-out log-likelihood (bits/trial)
• Comparison plots

python glmhmm_cv_comparison.py

Edit the DATA_PATH variable at the top to point to your .mat file.

fit_global.py — Global Fit + State Assignments

Fits a single model on all data and extracts per-trial state assignments with posterior probabilities.

python fit_global.py data.mat --K 3 --output results/

Outputs:

• original_K3_assignments.csv — per-trial state, posteriors, predicted P(go), inputs
• original_K3_params.json — observation weights, transition matrix, log-probability
• Same for new_K3_*

Data Format

Expects a .mat file with:

• preprocessed_input: (N_sessions, 1) cell array, each cell (T, M) matrix of inputs
• preprocessed_label: (N_sessions, 1) cell array, each cell (T, 1) vector of binary choices
• preprocessed_session (optional): (N_sessions, 1) cell array of session IDs

Important: SSM Sign Convention

The ssm library's input_driven_obs with C=2 uses the convention: positive logit → P(y=0). To get P(choice=1), compute P(go) = sigmoid(-logit) or equivalently 1 / (1 + exp(logit)). This tool handles the conversion internally.

Key Findings (Example: Pupil-Driven Transitions)

Model	Accuracy	ROC-AUC	PR-AUC
Original K=1	78.0%	0.864	0.873
Original K=2	84.5%	0.920	0.943
New K=2	84.6%	0.921	0.943
Original K=3	86.6%	0.949	0.959
New K=3	86.6%	0.951	0.961
Original K=4	86.5%	0.947	0.958
New K=4	86.8%	0.949	0.960

K=3 optimal. Restructured model matches or marginally beats original at every K — circularity resolved with zero performance cost.

References

• Ashwood, Z.C., et al. (2022). Mice alternate between discrete strategies during perceptual decision-making. Nature Neuroscience, 25, 201–212.
• Hulsey, D., et al. (2024). Decision-making dynamics are predicted by arousal and uninstructed movements. bioRxiv.
• Linderman, S. (2020). ssm: Bayesian learning and inference for state space models. GitHub.

Setup

pip install -r requirements.txt

Note: The ssm package must be installed from source:

pip install git+https://github.com/lindermanlab/ssm.git