High Order Discrete Energy Landscape Analysis for Neural Time Series Data

This repository provides a lightweight implementation of a discrete energy landscape (DEL) framework for multivariate neural time series. It supports two analysis modes:

1. Direct DEL: fit the discrete energy landscape directly after binarizing the input signals.
2. KMeans-clustered / higher-order DEL: cluster signals first, aggregate them into cluster-level time series, then binarize and fit the discrete energy landscape.

The repository is designed for workflows that estimate an exact maximum-entropy / Ising-style model and then summarize the resulting energy trajectory using metrics such as:

• local minima and maxima in the energy trajectory
• number of discrete state transitions
• magnitude of energy changes between consecutive time points
• magnitude of energy changes specifically at state-change events
• simple model-fit accuracy metrics against an independent baseline

Workflow overview

The figure above summarizes the clustered / higher-order workflow used in this repository: signals are grouped into clusters, converted into cluster-level signals, binarized into brain states, fit with the MEM model, and then used to construct the discrete energy landscape.

---

Acknowledgement

If you use this code, please cite the following paper:

Triet M. Tran and Sina Khanmohammadi. "Neural Energy Landscapes Predict Working Memory Decline After Brain Tumor Resection." arXiv:2507.23057 (2025)

https://doi.org/10.48550/arXiv.2507.23057.

---

Authors

1. Triet M Tran:
2. Sina Khanmohammadi:

---

Repository structure

DiscreteEnergyLandscape/
├── discrete_energy.py
├── higher_order_energy.py
├── energy_metrics.py
├── README.md
├── requirements.txt
├── pyproject.toml
├── CITATION.cff
├── .gitignore
├── examples/
│   └── example_discrete_energy_landscape.py
└── figs/
    ├── repo_workflow.png
    ├── repo_workflow.pdf
    └── example_direct_vs_clustered.png

---

Main modules

discrete_energy.py

Core DEL / exact MEM utilities:

• binarize(X): mean-threshold binarization
• fit_exact_mem(X01): fit exact Ising parameters using all 2^D states
• calc_energy(h, W, X): compute energy values
• calc_prob(h, W, X): compute Boltzmann probabilities
• calc_state_no(X): convert binary states to integer state IDs
• calc_accuracy(h, W, X): compare DEL fit to an independent model

higher_order_energy.py

Higher-order / clustered DEL utilities:

• cluster_signals_kmeans(X, n_clusters): cluster input signals across time
• aggregate_cluster_signals(X, labels): compute cluster-level representative signals
• fit_direct_energy_landscape(X): direct DEL pipeline
• fit_clustered_energy_landscape(X, n_clusters): KMeans-clustered DEL pipeline

energy_metrics.py

Post-fit summary functions:

• find_local_extrema(energy)
• count_transitions(states)
• transition_step_magnitudes(energy)
• state_change_magnitudes(energy, states)
• summarize_energy_landscape(energy, states)

---

Installation

Option 1: install dependencies only

pip install -r requirements.txt

Option 2: editable install

pip install -e .

---

Minimal usage

A. Direct DEL

import numpy as np
from higher_order_energy import fit_direct_energy_landscape

X = np.random.randn(4, 200)  # shape (D, T)
results = fit_direct_energy_landscape(X)

print(results['summary'])
print(results['energy'])

B. KMeans-clustered / higher-order DEL

import numpy as np
from higher_order_energy import fit_clustered_energy_landscape

X = np.random.randn(10, 200)  # shape (D, T)
results = fit_clustered_energy_landscape(X, n_clusters=5)

print(results['cluster_members'])
print(results['summary'])

---

Run the example

From the repository root:

python examples/example_discrete_energy_landscape.py

This example:

1. generates a synthetic multivariate time series with latent cluster structure
2. runs Direct DEL on the full signal matrix
3. runs KMeans-clustered DEL on cluster-aggregated signals
4. computes energy trajectories and transition summaries for both versions
5. saves a comparison figure to figs/example_direct_vs_clustered.png

---

Input format

The code expects data with shape:

• (D, T)
• D: number of variables / ROIs / channels / PCA dimensions
• T: number of time points

For the clustered / higher-order version, clustering is applied across the rows of X, meaning each row is treated as a signal to be grouped into a smaller set of cluster-level representative signals.

---

Practical note on scalability

Because exact MEM fitting enumerates all 2^D binary states, the direct DEL model is only tractable for modest dimensionality. In practice, this usually means:

• using a small number of ROIs
• or reducing dimensionality first
• or clustering signals into a smaller number of groups before fitting

The clustered / higher-order DEL option in this repository is one practical way to reduce the effective dimensionality before MEM estimation.

---

Notes

• discrete_energy.py is kept close to the current DEL implementation.
• higher_order_energy.py adds a simple KMeans-based higher-order DEL workflow.
• The direct and clustered pipelines return dictionaries so they are easy to plug into notebooks and downstream analyses.