fdnkit 1.0.0__tar.gz

fdnkit-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint with ruff
+        run: ruff check src tests
+      - name: Run tests
+        run: pytest --cov=fdnkit --cov-report=term-missing

fdnkit-1.0.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.vscode/
+.idea/
+
+# Data / outputs (never commit private cohort data)
+*.edf
+*.h5
+*.hdf5
+data/private/
+scratch/
+*.log
+
+# Example output artifacts
+quickstart_panel.png
+examples/*.png
+*.csv
+
+# Internal planning docs: not for the public repo (contain local/private paths)
+BUILD_PLAN.md

fdnkit-1.0.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to FDNkit are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-09-05
+
+Initial public release.
+
+### Added
+- `fdnkit.dfa`: monofractal DFA Hurst exponent.
+- `fdnkit.mfdfa`: MFDFA generalized Hurst `h(q)`, multifractal width `Δh`, and
+  the `f(α)` singularity spectrum.
+- `fdnkit.fodn`: fractional-order dynamical network model (per-channel `α`,
+  sparse directed coupling matrix, eigenvector hub scores, sparseness).
+- `fdnkit.features`: tidy per-trial feature tables with a five-feature "core"
+  set matching the reference study.
+- `fdnkit.classify`: subject-wise cross-validation by default (leave-one-subject-out),
+  group-aware permutation test, bootstrap confidence intervals; trial-wise LOO is
+  opt-in and labeled optimistic.
+- `fdnkit.io`: EDF (MNE) and HDF5 (h5py) readers, Excel label loading, feature CSV IO.
+- `fdnkit.preprocessing`: z-scoring, bad-channel flagging, windowing.
+- `fdnkit.viz`: fluctuation, `h(q)`, spectrum, coupling-heatmap, and hub plots.
+- `fdnkit.synthetic`: fractional Gaussian noise / motion (Davies–Harte),
+  binomial cascades, and coupled multi-channel iEEG-like signals.
+- `fdnkit` command-line interface: `extract`, `classify`, `demo`.
+- Test suite (79 tests, ~91% coverage) validating the numerical core against
+  signals with known scaling properties; GitHub Actions CI on Python 3.9–3.12.
+- JOSS paper draft (`paper/`), documentation (`docs/`), and runnable examples:
+  a synthetic quickstart (`examples/quickstart.py`) and a real-data walkthrough
+  on public PhysioNet EEG (`examples/real_data_eegbci.py`).

fdnkit-1.0.0/CITATION.cff

@@ -0,0 +1,55 @@
+cff-version: 1.2.0
+message: "If you use FDNkit, please cite it as below."
+title: "FDNkit: Fractional Dynamical Network & Multifractal toolkit for intracranial EEG"
+abstract: >-
+  FDNkit is an open-source Python library and command-line tool that turns
+  intracranial-EEG recordings into fractal and fractional-dynamical-network
+  features (DFA Hurst, MFDFA generalized Hurst, fractional-order dynamical
+  network coupling matrices, fractional exponents, and eigenvector hubs), with
+  plotting utilities and a classification harness that defaults to honest,
+  subject-wise cross-validation.
+type: software
+authors:
+  - family-names: Hossain
+    given-names: Samir
+    orcid: "https://orcid.org/0009-0003-8986-0946"
+    affiliation: "Department of Electrical and Computer Engineering, Texas Tech University, Lubbock, TX, USA"
+version: 1.0.0
+date-released: "2026-09-05"
+doi: "10.5281/zenodo.22366240"
+identifiers:
+  - type: doi
+    value: "10.5281/zenodo.22366240"
+    description: "Concept DOI resolving to the latest version of FDNkit"
+  - type: doi
+    value: "10.5281/zenodo.22366241"
+    description: "Archived snapshot of FDNkit v1.0.0"
+license: MIT
+repository-code: "https://github.com/SamirHossain099/fdnkit"
+keywords:
+  - iEEG
+  - DFA
+  - MFDFA
+  - multifractal
+  - fractional dynamics
+  - network physiology
+references:
+  - type: article
+    title: "Quantifying cognitive effort's impact on suppression of epilepsy-associated after discharges"
+    authors:
+      - family-names: Beeram
+        given-names: Sai Pavan
+      - family-names: Farris
+        given-names: Matthew
+      - family-names: Hossain
+        given-names: Samir
+      - family-names: Rethans
+        given-names: Nicholas
+      - family-names: Kang
+        given-names: Joon Y.
+      - family-names: Pereira
+        given-names: Emily A.
+    year: 2026
+    journal: "Frontiers in Network Physiology"
+    volume: "6"
+    doi: "10.3389/fnetp.2026.1768476"

fdnkit-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing to FDNkit
+
+Thanks for your interest in improving FDNkit! Bug reports, feature requests, and
+pull requests are all welcome.
+
+## Development setup
+
+```bash
+git clone https://github.com/SamirHossain099/fdnkit
+cd fdnkit
+python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+## Before opening a pull request
+
+```bash
+ruff check src tests        # lint
+pytest --cov=fdnkit         # tests + coverage
+```
+
+Please:
+
+- Keep the numerical core **array-first and pure**: pandas/IO/plotting layer on
+  top, and matplotlib/MNE/h5py stay optional (lazily imported).
+- Add a test for any new behavior. Where possible, validate against **ground
+  truth** (a signal with a known Hurst exponent, a cascade with a known
+  multifractal width), not just against the current output.
+- Match the existing docstring style (NumPy-format) and keep public functions
+  documented.
+- Do **not** commit data. The private clinical cohort must never be added;
+  examples and tests use `fdnkit.synthetic`.
+
+## Reporting bugs
+
+Open an issue with a minimal reproducer, ideally one built from
+`fdnkit.synthetic` so it runs anywhere.
+
+## Scope
+
+FDNkit is intentionally focused on fractal / fractional-dynamical-network methods
+for iEEG. General EEG preprocessing, montages, and filtering belong in
+MNE-Python; connectivity beyond FODN (Granger, transfer entropy) and a result
+database are candidate future additions but out of scope for the core.

fdnkit-1.0.0/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.

fdnkit-1.0.0/PKG-INFO

@@ -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/PORTING_NOTES.md

@@ -0,0 +1,41 @@
+# Porting notes
+
+FDNkit generalizes a validated but single-purpose research codebase into a
+reusable library. This table maps each ported piece to its origin in the
+original single-purpose research tool and records what changed.
+
+| FDNkit module | Ported from | Notes on the port |
+|---|---|---|
+| `mfdfa.py` | `software_app/gui/mfdfa_analysis_window.py::run_mfdfa`; `MATLAB_Code/MFDFA.m`, `DFA_of_EEG.m` | Extracted the core maths out of the PyQt window into pure functions. Same forward-partition algorithm, `q=0` log-average limit, and `eps` flooring. Added `MFDFAResult`, `delta_h`, and a Legendre-transform `f(α)` spectrum. |
+| `dfa.py` | same as above (the `q=2` special case) | Thin, single-purpose entry point sharing `mfdfa.py`'s internals. Verified `h(q=2) == dfa.hurst` exactly. |
+| `fodn.py` | `software_app/utils/fodn_code.py::fracOrdUU`, `HaarWaveletTransform` | Preserved the numerical procedure (Haar-wavelet order estimation, Grünwald–Letnikov differencing, regularized least squares + ADMM-LASSO). Renamed to a scikit-learn-style `FODN.fit`/`result`. Replaced silent `print`-and-continue error handling with proper exceptions; a rank-deficient `B` now falls back to a well-conditioned selector instead of raising. Removed the unused sparse-computation branches. |
+| `features.py` | `software_app/utils/feature_extractor.py::FeatureExtractor` | Reimplemented to compute features directly from arrays / result objects instead of scraping a directory tree of CSVs. Kept the five "core" feature names (`MeanAlpha`, `VarAlpha`, `LeadingEig`, `MF_DFA_H`, `MF_DFA_Hq_mean`) as aliases so results line up with the reference study. |
+| `io.py` | `software_app/utils/file_utils.py`, `label_strategies.py::ExcelMathScoreLabeler` | Removed the PyQt `QMessageBox` coupling; IO now raises plain exceptions. EDF via MNE and HDF5 via h5py are optional, lazily imported dependencies. |
+| `classify.py` | the original model-training window and honest-CV revalidation script | Folded the honest-CV revalidation logic into the library. The GUI's random 80/20 split is deliberately **not** the default; leave-one-subject-out is, with a required `groups` argument, a group-aware permutation test, and bootstrap CIs. |
+| `viz.py` | `scripts/analysis_scripts/{plotter,EigenvectorHeatmap}.py`; the GUI plotting code | Reduced to composable, `ax`-returning functions with matplotlib as an optional dependency. |
+| `preprocessing.py` | scattered windowing/artifact logic in the GUI windows | Consolidated z-scoring, bad-channel flagging, and fixed-length windowing. |
+| `synthetic.py` | new | Added for tests/examples: exact fGn/fBm (Davies–Harte), binomial cascades, and coupled multi-channel signals, so the toolkit runs with no data download. |
+
+## Known issues from the source that were fixed cleanly
+
+- `log2(0)` / divide-by-zero warnings in DFA/MFDFA: handled with `eps` flooring
+  and finite-value masking in the log–log regression.
+- **Negative-`q` MFDFA blow-up on real (integer-quantized) recordings**: the
+  original machine-epsilon RMS floor let degenerately-detrended segments collapse
+  to ~0 and dominate negative-`q` moments, fabricating a huge multifractal width
+  (observed `Δh ≈ 10` on real EEG). Replaced with a **scale-relative floor**
+  (`rel_floor`, a fraction of each scale's median fluctuation, default `1e-3`);
+  this restores physical `Δh` on real data while leaving synthetic results
+  (cascade `Δh`, monofractal `Δh`, Hurst recovery) numerically unchanged.
+- FODN order-estimation `log2` of zero variance: floored at `1e-10` (as in the
+  source) and documented.
+- Rank-deficient heuristic `B` matrix previously raised: now falls back to a
+  standard-basis selector.
+- Silent `except: print(...)` blocks in `fracOrdUU.fit`: replaced with explicit
+  `ValueError`s so callers can handle failures.
+
+## Deliberately deferred (out of scope for v1)
+
+- DuckDB result store (`database_scripts/`).
+- Directed-connectivity measures (Granger/transfer entropy).
+- A graphical interface: the core is headless by design.

fdnkit-1.0.0/README.md

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