Metadata-Version: 2.4
Name: mstsa
Version: 0.3.0
Summary: Microstate Time Series Analysis
Author-email: Frederic von Wegner <fvw.github@gmail.com>
Project-URL: Homepage, https://github.com/Frederic-vW/mstsa
Project-URL: Bug Tracker, https://github.com/Frederic-vW/mstsa/issues
Project-URL: Documentation, https://github.com/Frederic-vW/mstsa#readme
Keywords: EEG,microstate,time series,information theory,Markov chain,entropy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: matplotlib>=3.4
Requires-Dist: numba>=0.54
Requires-Dist: cffi>=1.15
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: numpydoc; extra == "dev"
Dynamic: license-file

# mstsa — Microstate Time Series Analysis

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)

`mstsa` is a Python package for information-theoretic and statistical analysis
of discrete symbolic time series, with a particular focus on EEG microstate
sequences.

The source code is available at [GitHub](https://github.com/Frederic-vW/mstsa).

---

## Features

### Symbol statistics
- Empirical probability mass function (`pmf`)
- Transition probability matrices — conditional (`tpm_cond`), joint
  (`tpm_joint`), expected under independence (`tpm_joint_exp`)
- Sojourn-time (lifetime) distributions (`lifetime_histograms`,
  `lifetimes_unordered`)
- Microstate duration, occurrence, and coverage (`dur_occ_cov`)
- Embedded jump process extraction (`embedded_process`)

### Information-theoretic measures
- Shannon entropy (`h1`), joint entropy (`h2`), *k*-gram entropy (`hk`)
- Rényi entropy (`renyi_entropy`), Tsallis entropy (`tsallis_entropy`)
- Entropy rate and excess entropy by linear regression (`entropy_rate`)
- Active information storage (`ais`)
- Auto-information function — empirical (`aif`) and Markov-predicted (`aif_mc`)
- Partial auto-information function (`paif`)
- Sample entropy for continuous signals (`sample_entropy_cont`,
  `sample_entropy_fast_cont_py`) and discrete sequences (`sample_entropy_disc`,
  `sample_entropy_fast_disc_py`)
- Lempel-Ziv complexity (`lz76`)

### Markov chain analysis
- First-order Markov chain surrogate generation (`mc_sample_path`)
- Theoretical entropy rate under Markov assumption (`entropy_rate_mc`, `entropy_rates_mc`)
- Theoretical auto-information function of a Markov chain (`aif_mc`)
- Expected sample entropy under a Markov model (`sample_entropy_mc`, `sample_entropies_mc`)
- Theoretical duration, occurrence, and coverage under a Markov model (`dur_occ_cov_mc`)
- Joint and trajectory probabilities under a Markov model (`p_joint_mc`, `p_ngram_mc`)
- Continuous-time Markov chain generator matrix (`generator_matrix`)
- Stationary distribution (`p_stationary`)
- Relaxation time / spectral gap (`relaxation_time`)
- Nearest reversible Markov chain (`nearest_reversible_mc`, requires `cvxopt`)

### Statistical tests (Kullback-Technometrics framework)
- Zero-order Markovianity / i.i.d. test (`test_markov0`)
- First-order Markovianity test (`test_markov1`)
- Second-order Markovianity test (`test_markov2`)
- Conditional homogeneity / stationarity (`test_cond_homogeneity`)
- Marginal homogeneity (`test_j_homogeneity`)
- Joint transition homogeneity (`test_jk_homogeneity`)
- Transition-matrix symmetry / detailed balance (`test_symmetry`)
- Geometric (exponential) sojourn-time test (`test_geometric_seq`, `test_geometric_dist`)
- Test against reference transition matrix (`test_transition_matrix`)
- Microstate syntax / transition test across subjects (`transition_syntax_test`)

### Other analyses
- Detrended fluctuation analysis (`dfa`) and rescaled-range analysis
  (`rescaled_range`), with Hurst exponents of microstate indicator functions
  (`hurst_exponents_dfa`, `hurst_exponents_rs`)
- Detailed balance statistics (`detailed_balance`, `detailed_balance_cond`,
  `detailed_balance_joint`)
- Random walk construction from symbolic sequence (`randomwalk`, `partitions`)
- Power spectral densities of characteristic microstate functions (`spectra`)
- EEG complexity measures Ω, Σ, Φ, LC (`complexity_ospl`)
- Multiple-comparisons correction (`multiple_comparisons`)
- Microstate syntax analysis (`Microsynt`)

### Optional C extensions
For improved performance on entropy computations (`hk`), sample entropy, and
Lempel-Ziv complexity, `mstsa` builds optional CFFI-linked C extensions
(`_c_entropy`, `_se`, `_lz76`) automatically during installation, provided a
C compiler is available on the system (e.g. `gcc`/`build-essential` on
Linux, Xcode Command Line Tools on macOS, MSVC Build Tools on Windows). No
manual build step is required.

If a compiler is unavailable or a compiled extension otherwise fails to
import, `mstsa` falls back automatically to pure-Python / Numba
implementations and emits a `UserWarning` noting the slower fallback is in
use.

---

## Installation

### From PyPI (once published)

```bash
pip install mstsa
```

### From source

```bash
git clone https://github.com/Frederic-vW/mstsa.git
cd mstsa/packaging
pip install -e .
```

### Optional dependencies

```bash
pip install mstsa[qp]    # nearest_reversible_mc (requires cvxopt)
pip install mstsa[mc_tests]  # multiple_comparisons (requires statsmodels)
```

---

## Quick start

```python
import numpy as np
from mstsa import pmf, tpm_cond, h1, entropy_rate, aif, test_markov0, test_markov1

# Load or create a symbolic sequence
rng = np.random.default_rng(42)
x = rng.integers(0, 4, size=10000)
nc = 4  # number of symbols

# Symbol distribution and transition matrix
p = pmf(x, nc)
T = tpm_cond(x, nc)

# Shannon entropy and entropy rate
print(f"Shannon entropy: {h1(x, nc):.3f} bits")
er, ee = entropy_rate(x, nc, kmax=8)
print(f"Entropy rate: {er:.3f} bits/sample")

# Auto-information function
aif_vals = aif(x, nc, kmax=20)

# Markov order tests
p0 = test_markov0(x, nc, verbose=True)
p1 = test_markov1(x, nc, verbose=True)
```

---

## Citation

If you use `mstsa` in your research, please cite:

> von Wegner, F. (2025). mstsa: Microstate Time Series Analysis.
> *Journal of Open Source Software* (submitted).

---

## License

MIT — see [LICENSE](LICENSE).
