fdnkit 1.0.0__py3-none-any.whl

fdnkit/viz.py

@@ -0,0 +1,146 @@
+"""Plotting utilities (matplotlib, optional dependency).
+
+Import matplotlib lazily so the core library has no hard plotting dependency.
+Install with ``pip install fdnkit[viz]``. Every function accepts an optional
+``ax`` and returns the Axes it drew on, so plots compose into larger figures.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = [
+    "plot_fluctuation",
+    "plot_hq",
+    "plot_multifractal_spectrum",
+    "plot_hurst_over_time",
+    "plot_alpha_distribution",
+    "plot_coupling_matrix",
+    "plot_eigenvector_hubs",
+]
+
+
+def _get_ax(ax):
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "Plotting requires matplotlib. Install with `pip install fdnkit[viz]`."
+        ) from exc
+    if ax is None:
+        _, ax = plt.subplots(figsize=(6, 4))
+    return ax
+
+
+def plot_fluctuation(result, ax=None, **kwargs):
+    """Log-log fluctuation function ``F`` vs scale, with the fitted Hurst slope.
+
+    Parameters
+    ----------
+    result : DFAResult | MFDFAResult
+        Must expose ``scales``, ``fluct``, and ``hurst``.
+    """
+    ax = _get_ax(ax)
+    scales = np.asarray(result.scales, dtype=float)
+    fluct = np.asarray(result.fluct, dtype=float)
+    good = np.isfinite(fluct) & (fluct > 0)
+    ax.plot(np.log2(scales[good]), np.log2(fluct[good]), "o-", **kwargs)
+    ax.set_xlabel("log2(scale)")
+    ax.set_ylabel("log2(F)")
+    ax.set_title(f"DFA fluctuation (H = {result.hurst:.3f})")
+    return ax
+
+
+def plot_hq(result, ax=None, **kwargs):
+    """Generalized Hurst exponent ``h(q)`` against ``q``."""
+    ax = _get_ax(ax)
+    order = np.argsort(result.q)
+    ax.plot(np.asarray(result.q)[order], np.asarray(result.hq)[order], "s-", **kwargs)
+    ax.set_xlabel("q")
+    ax.set_ylabel("h(q)")
+    ax.set_title(f"Generalized Hurst (delta_h = {result.delta_h:.3f})")
+    return ax
+
+
+def plot_multifractal_spectrum(result, ax=None, **kwargs):
+    """Singularity spectrum ``f(alpha)`` from an :class:`~fdnkit.mfdfa.MFDFAResult`."""
+    from .mfdfa import multifractal_spectrum
+
+    ax = _get_ax(ax)
+    alpha, f_alpha = multifractal_spectrum(result)
+    ax.plot(alpha, f_alpha, "o-", **kwargs)
+    ax.set_xlabel(r"$\alpha$ (Holder exponent)")
+    ax.set_ylabel(r"$f(\alpha)$")
+    ax.set_title("Multifractal spectrum")
+    return ax
+
+
+def plot_hurst_over_time(times, hurst_values, ax=None, *, label=None, **kwargs):
+    """Trace of a scaling exponent (Hurst / alpha) across analysis windows.
+
+    Parameters
+    ----------
+    times : array-like
+        Window centre times (or indices).
+    hurst_values : array-like
+        One value per window.
+    """
+    ax = _get_ax(ax)
+    ax.plot(np.asarray(times), np.asarray(hurst_values), "-o", label=label, **kwargs)
+    ax.set_xlabel("time (s)")
+    ax.set_ylabel("Hurst / exponent")
+    ax.set_title("Scaling exponent over time")
+    if label:
+        ax.legend()
+    return ax
+
+
+def plot_alpha_distribution(alphas, ax=None, *, bins=20, **kwargs):
+    """Histogram of per-channel (or per-chunk) fractional orders ``alpha``."""
+    ax = _get_ax(ax)
+    a = np.asarray(alphas, dtype=float).ravel()
+    a = a[np.isfinite(a)]
+    ax.hist(a, bins=bins, **kwargs)
+    ax.set_xlabel(r"fractional order $\alpha$")
+    ax.set_ylabel("count")
+    ax.set_title("FODN alpha distribution")
+    return ax
+
+
+def plot_coupling_matrix(coupling, channel_names=None, ax=None, *, cmap="RdBu_r", **kwargs):
+    """Heatmap of a FODN coupling matrix ``A``.
+
+    Parameters
+    ----------
+    coupling : array-like, shape (n, n)
+    channel_names : sequence of str, optional
+    """
+    ax = _get_ax(ax)
+    a = np.asarray(coupling, dtype=float)
+    vmax = np.max(np.abs(a)) or 1.0
+    im = ax.imshow(a, cmap=cmap, vmin=-vmax, vmax=vmax, **kwargs)
+    ax.figure.colorbar(im, ax=ax, fraction=0.046, pad=0.04, label="coupling")
+    ax.set_title("FODN coupling matrix A")
+    ax.set_xlabel("source channel")
+    ax.set_ylabel("target channel")
+    if channel_names is not None:
+        ax.set_xticks(range(len(channel_names)))
+        ax.set_yticks(range(len(channel_names)))
+        ax.set_xticklabels(channel_names, rotation=90, fontsize=7)
+        ax.set_yticklabels(channel_names, fontsize=7)
+    return ax
+
+
+def plot_eigenvector_hubs(dominant_eigvec, channel_names=None, ax=None, **kwargs):
+    """Bar chart of per-channel hub scores (dominant-eigenvector magnitude)."""
+    ax = _get_ax(ax)
+    v = np.asarray(dominant_eigvec, dtype=float).ravel()
+    idx = np.arange(v.size)
+    ax.bar(idx, v, **kwargs)
+    ax.set_xlabel("channel")
+    ax.set_ylabel("hub score |eigvec|")
+    ax.set_title("FODN eigenvector hubs")
+    if channel_names is not None:
+        ax.set_xticks(idx)
+        ax.set_xticklabels(channel_names, rotation=90, fontsize=7)
+    return ax

fdnkit-1.0.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: fdnkit
+Version: 1.0.0
+Summary: Fractional Dynamical Network & Multifractal toolkit for intracranial EEG
+Project-URL: Homepage, https://github.com/SamirHossain099/fdnkit
+Project-URL: Documentation, https://github.com/SamirHossain099/fdnkit#readme
+Project-URL: Repository, https://github.com/SamirHossain099/fdnkit
+Project-URL: Issues, https://github.com/SamirHossain099/fdnkit/issues
+Author: Samir Hossain
+License: MIT
+License-File: LICENSE
+Keywords: DFA,EEG,MFDFA,fractional dynamics,iEEG,multifractal,network physiology,neuroscience
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.4
+Requires-Dist: scikit-learn>=1.1
+Requires-Dist: scipy>=1.8
+Provides-Extra: all
+Requires-Dist: h5py>=3.0; extra == 'all'
+Requires-Dist: matplotlib>=3.5; extra == 'all'
+Requires-Dist: mne>=1.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: h5py>=3.0; extra == 'dev'
+Requires-Dist: matplotlib>=3.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: io
+Requires-Dist: h5py>=3.0; extra == 'io'
+Requires-Dist: mne>=1.0; extra == 'io'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# FDNkit
+
+**Fractional Dynamical Network & Multifractal toolkit for intracranial EEG**
+
+[![CI](https://github.com/SamirHossain099/fdnkit/actions/workflows/ci.yml/badge.svg)](https://github.com/SamirHossain099/fdnkit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SamirHossain099/fdnkit/blob/main/LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22366240.svg)](https://doi.org/10.5281/zenodo.22366240)
+
+FDNkit turns intracranial-EEG (iEEG) recordings into **fractal** and
+**fractional-dynamical-network** features and evaluates them **honestly**. It
+packages methods validated in Beeram et al. (2026, *Front. Netw. Physiol.*
+6:1768476) and the fractional-dynamical-network line of work of Gupta et al.
+(2018) and Xue & Bogdan (2017) as a clean, documented, tested library, not a one-off GUI welded to a single dataset.
+
+It computes:
+
+- **DFA**: monofractal Hurst exponent `H`.
+- **MFDFA**: generalized Hurst `h(q)`, multifractal width `Δh`, and the
+  singularity spectrum `f(α)`.
+- **FODN**: a fractional-order dynamical network: per-channel fractional orders
+  `α`, a sparse directed coupling matrix `A`, and eigenvector "hub" scores.
+- **Feature tables**: tidy, one-row-per-trial pandas DataFrames.
+- **Honest classification**: a logistic-regression harness that defaults to
+  **leave-one-subject-out** cross-validation with a subject-level permutation
+  test, because row-wise splits leak patient identity and inflate accuracy.
+
+## Install
+
+```bash
+pip install fdnkit                # core: numpy, scipy, pandas, scikit-learn
+pip install "fdnkit[viz]"         # + matplotlib for plots
+pip install "fdnkit[io]"          # + mne (EDF) and h5py (HDF5) readers
+pip install "fdnkit[all]"         # everything
+```
+
+From source:
+
+```bash
+git clone https://github.com/SamirHossain099/fdnkit
+cd fdnkit
+pip install -e ".[dev]"
+pytest
+```
+
+## 60-second example (no data download)
+
+```python
+from fdnkit.synthetic import synthetic_ieeg
+from fdnkit.features import extract_features
+
+# A small, sparsely-coupled synthetic iEEG trial (8 channels, 5 s @ 1 kHz).
+signals, channel_names = synthetic_ieeg(n_channels=8, n_samples=5000, seed=0)
+
+# One tidy feature row: DFA H, MFDFA h(q)/Δh, FODN α / leading eigenvalue / hubs.
+features = extract_features(signals)
+print(features["MF_DFA_H"], features["MeanAlpha"], features["LeadingEig"])
+```
+
+Analyze a single signal directly:
+
+```python
+import numpy as np
+from fdnkit.dfa import dfa
+from fdnkit.mfdfa import mfdfa
+from fdnkit.fodn import fit_fodn
+
+x = signals[0]
+print("Hurst:", dfa(x).hurst)
+print("multifractal width Δh:", mfdfa(x).delta_h)
+
+fodn = fit_fodn(signals)                 # (channels, timepoints)
+print("leading eigenvalue:", fodn.leading_eig)
+print("hub scores:", np.round(fodn.dominant_eigvec, 3))
+```
+
+## Honest classification
+
+```python
+from fdnkit.classify import classify_dataframe
+
+# df has feature columns plus 'label' and 'group' (e.g. subject id) columns.
+result = classify_dataframe(df, label_col="label", group_col="group", cv="loso")
+print(result.summary())
+# Leave-one-subject-out balanced accuracy, ROC-AUC, a subject-level
+# permutation p-value, and a bootstrap 95% CI.
+```
+
+`cv="loso"` (the default) holds out whole subjects and **requires** `groups`.
+Trial-wise `cv="loo"` is available but must be requested explicitly and is
+labeled *optimistic*: it is the leakage-prone scheme FDNkit exists to warn about.
+
+## Command line
+
+```bash
+# Self-contained demo: synthesize a labeled cohort and classify it honestly.
+fdnkit demo --out demo_features.csv
+fdnkit classify demo_features.csv --label label --group group
+
+# Extract features from your own recording (EDF via MNE, or HDF5).
+fdnkit extract recording.edf --window 1.0 --drop-bad --zscore --out features.csv
+```
+
+## Design principles
+
+- **Array-first core.** `dfa(signal)`, `mfdfa(signal)`, `fit_fodn(signals)` are
+  pure functions on NumPy arrays. Pandas/IO/plotting layer on top.
+- **Depend, don't duplicate.** IO, montages, and filtering defer to
+  [MNE-Python](https://mne.tools); FDNkit adds only the fractal/FODN methods.
+- **Deterministic and seedable.** Bad channels log a warning instead of crashing.
+- **Honest by default.** Subject-wise CV and permutation testing are the
+  headline, not an afterthought.
+
+## Validation
+
+FDNkit's numerical core is checked against ground truth (see `tests/`):
+
+- DFA recovers the Hurst exponent of fractional Gaussian noise across
+  `H = 0.3…0.9`; white noise → `H ≈ 0.5`, Brownian motion → `H ≈ 1.5`.
+- MFDFA reports a wide `h(q)` for a multiplicative binomial cascade and a narrow
+  one for a monofractal signal; `h(q=2)` matches the DFA Hurst exponent exactly.
+- FODN recovers finite fractional orders, coupling, and hubs on synthetic
+  coupled systems.
+
+## Citation
+
+If you use FDNkit, please cite the software:
+
+> Hossain, S. (2026). *FDNkit: Fractional Dynamical Network & Multifractal
+> toolkit for intracranial EEG* (v1.0.0). Zenodo.
+> https://doi.org/10.5281/zenodo.22366240
+
+(`10.5281/zenodo.22366240` always resolves to the latest release; cite
+`10.5281/zenodo.22366241` for v1.0.0 specifically. See
+[`CITATION.cff`](https://github.com/SamirHossain099/fdnkit/blob/main/CITATION.cff).)
+
+Please also cite the methods paper:
+
+> Beeram, S. P., Farris, M., Hossain, S., Rethans, N., Kang, J. Y., & Pereira,
+> E. A. (2026). *Quantifying cognitive effort's impact on suppression of
+> epilepsy-associated after discharges.* Frontiers in Network Physiology, 6,
+> 1768476. https://doi.org/10.3389/fnetp.2026.1768476
+
+## License
+
+MIT; see [LICENSE](https://github.com/SamirHossain099/fdnkit/blob/main/LICENSE). The underlying fractional-dynamical-network method
+is due to Gupta, Pequito & Bogdan (2018) and Xue & Bogdan (2017); please cite
+them when using the FODN module.

fdnkit-1.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+fdnkit/__init__.py,sha256=oOb6f0ykH8WpQvnck1C_24qsSupOP2dbfl4oEzj2lXg,2772
+fdnkit/classify.py,sha256=-pahHHUCcEuuNidhCRdxfgNKvl9RlTOZb2LPqMQdsqk,11301
+fdnkit/cli.py,sha256=bZ17hSDUsRy7JtgFAN-X7DzMegpgKd9Uaf1hBEbIL_c,6388
+fdnkit/dfa.py,sha256=4N9cO-GTrbKKmgf00Cc6KQCc6cMLfQmNWVIJ0sTwwz4,2764
+fdnkit/features.py,sha256=nWSey1kD0yXzFFC0NVf_JO1A8sYlkk53K_3ExQhhEoI,7545
+fdnkit/fodn.py,sha256=6-AQdkhmtEOdb_2iW29Y4_Pqy0QiXohCM0dIJfgHQqg,12715
+fdnkit/io.py,sha256=7kHIk1kdLWCdqa8iFfh6CialQR4Ot-NDrSqw4u_OHN4,5273
+fdnkit/mfdfa.py,sha256=tX5aT6LwKEYmCwtf3BiFptClFjaX8SY8TdOjwb5FMtM,8533
+fdnkit/preprocessing.py,sha256=vboQ7A3tx-aCk6PrvjopzkOLKmGrjhHMk06HoVCtozg,4315
+fdnkit/synthetic.py,sha256=t0G0UE3HaaIzV1sPqhpwCnuGH4GkJCae9UHX_gQz0CA,6174
+fdnkit/viz.py,sha256=5ffZS07GGeylbGYXsIi4GHuXj5Ga64Hqp7DKaTzhwRU,4807
+fdnkit-1.0.0.dist-info/METADATA,sha256=jOKLOTnIymFpcMnvKuG0LFfwRgGXBaKQ-X62pmfUrx8,7739
+fdnkit-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fdnkit-1.0.0.dist-info/entry_points.txt,sha256=f87Fzkl7fFwzmB4gghGg9xXyESTt5Jtuic2RbiaoKms,43
+fdnkit-1.0.0.dist-info/licenses/LICENSE,sha256=svWXpNvhapALKx_4mnGhEP7AIDhIgWP1egNv0U6SUtc,1070
+fdnkit-1.0.0.dist-info/RECORD,,

fdnkit-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fdnkit-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fdnkit = fdnkit.cli:main

fdnkit-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samir Hossain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.