mstsa 0.3.0__tar.gz

mstsa-0.3.0/PKG-INFO

@@ -0,0 +1,190 @@
+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).

mstsa-0.3.0/README.md

@@ -0,0 +1,154 @@
+# 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).

mstsa-0.3.0/mstsa/__init__.py

@@ -0,0 +1,92 @@
+"""mstsa: Microstate Time Series Analysis.
+
+A Python package for information-theoretic and statistical analysis
+of discrete symbolic time series, with a focus on EEG microstate sequences.
+"""
+
+from .mstsa import (
+    # Entropy
+    h1,
+    h2,
+    hk,
+    entropy_rate,
+    renyi_entropy,
+    tsallis_entropy,
+    # Information / auto-information
+    aif,
+    ais,
+    paif,
+    # Sample entropy (discrete)
+    sample_entropy_disc,
+    sample_entropy_fast_disc_py,
+    # Sequence utilities
+    lifetime_histograms,
+    lifetimes_unordered,
+    dur_occ_cov,
+    embedded_process,
+    randomwalk,
+    spectra,
+    dfa,
+    rescaled_range,
+    hurst_exponents_dfa,
+    hurst_exponents_rs,
+    lz76,
+    partitions,
+)
+
+from .markov import (
+    # Entropy
+    entropy_rate_mc,
+    entropy_rates_mc,
+    # Information / auto-information
+    aif_mc,
+    # Sample entropy
+    sample_entropy_mc,
+    sample_entropies_mc,
+    # Markov chain
+    mc_sample_path,
+    dur_occ_cov_mc,
+    generator_matrix,
+    p_joint_mc,
+    p_stationary,
+    p_ngram_mc,
+    relaxation_time,
+    nearest_reversible_mc,
+    tpm_cond,
+    tpm_joint,
+    tpm_joint_exp,
+    # Detailed balance
+    detailed_balance,
+    detailed_balance_cond,
+    detailed_balance_joint,
+    # Sequence utilities
+    pmf,
+)
+
+from .eeg import (
+    complexity_ospl,
+    # Sample entropy (continuous)
+    sample_entropy_cont,
+    sample_entropy_fast_cont_py,
+)
+
+from .microsynt import Microsynt
+
+from .stats import (
+    multiple_comparisons,
+    test_cond_homogeneity,
+    test_geometric_dist,
+    test_geometric_seq,
+    test_j_homogeneity,
+    test_jk_homogeneity,
+    test_markov0,
+    test_markov1,
+    test_markov2,
+    test_symmetry,
+    test_transition_matrix,
+    transition_syntax_test,
+)
+
+__version__ = "0.3.0"
+__author__ = "Frederic von Wegner"
+__email__ = "fvw.github@gmail.com"

mstsa-0.3.0/mstsa/_c_entropy_build.py

@@ -0,0 +1,23 @@
+import os
+from cffi import FFI
+
+ffi = FFI()
+
+ffi.cdef("""
+    double c_entropy(int *x, size_t n, size_t m, size_t k);
+""")
+
+_src = os.path.join(os.path.dirname(__file__), "src", "c_entropy.c")
+
+ffi.set_source(
+    "mstsa._c_entropy",
+    """
+        double c_entropy(int *x, size_t n, size_t m, size_t k);
+    """,
+    sources=[_src],
+    libraries=["m"],
+    extra_compile_args=["-O3"],
+)
+
+if __name__ == "__main__":
+    ffi.compile(verbose=True)

mstsa-0.3.0/mstsa/_lz76_build.py

@@ -0,0 +1,22 @@
+import os
+from cffi import FFI
+
+ffi = FFI()
+
+ffi.cdef("""
+    int lz76(int *x, int n);
+""")
+
+_src = os.path.join(os.path.dirname(__file__), "src", "lz76.c")
+
+ffi.set_source(
+    "mstsa._lz76",
+    """
+        int lz76(int *x, int n);
+    """,
+    sources=[_src],
+    extra_compile_args=["-O3"],
+)
+
+if __name__ == "__main__":
+    ffi.compile(verbose=True)

mstsa-0.3.0/mstsa/_se_build.py

@@ -0,0 +1,29 @@
+import os
+from cffi import FFI
+
+ffi = FFI()
+
+ffi.cdef("""
+    double sample_entropy_cont(double *x, size_t n, size_t m, size_t tau, double r);
+    double sample_entropy_disc(long *x, size_t n, size_t m, size_t tau);
+    int    sample_entropy_cont_fast(double *se, double *x, size_t n, size_t m, double r);
+    int    sample_entropy_disc_fast(double *se, long *x, size_t n, size_t m);
+""")
+
+_src = os.path.join(os.path.dirname(__file__), "src", "se.c")
+
+ffi.set_source(
+    "mstsa._se",
+    """
+        double sample_entropy_cont(double *x, size_t n, size_t m, size_t tau, double r);
+        double sample_entropy_disc(long *x, size_t n, size_t m, size_t tau);
+        int    sample_entropy_cont_fast(double *se, double *x, size_t n, size_t m, double r);
+        int    sample_entropy_disc_fast(double *se, long *x, size_t n, size_t m);
+    """,
+    sources=[_src],
+    libraries=["m"],
+    extra_compile_args=["-O3"],
+)
+
+if __name__ == "__main__":
+    ffi.compile(verbose=True)