lmeeeg 0.1.0__tar.gz

lmeeeg-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: lmeeeg
+Version: 0.1.0
+Summary: Minimal Python implementation of lmeEEG for random-intercept mass-univariate M/EEG analysis
+Author-email: Hiro YAMASAKI <hiroyoshi.YAMASAKI@univ-amu.fr>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: patsy>=0.5
+Provides-Extra: mne
+Requires-Dist: mne>=1.5; extra == "mne"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+
+# LmeEEG
+
+Minimal Python package implementing the core lmeEEG workflow for epoched M/EEG data with **random intercepts**:
+
+1. parse a mixed-model style formula at the API edge,
+2. fit a random-intercept mixed model at each channel × timepoint,
+3. subtract the fitted random effects to obtain marginal EEG,
+4. run fast mass-univariate OLS on the marginalized data,
+5. perform max-stat, cluster, or TFCE correction.
+
+## Current scope
+
+- One grouping factor in the public API
+- Random intercept only
+- Trial-wise epoched data shaped `(n_observations, n_channels, n_times)`
+- Cluster / TFCE correction via MNE-Python when installed
+- Tiny simulation utilities for recovery / null checks
+
+## Not yet included
+
+- Random slopes
+- Two grouping factors in the public API
+- Real-data validation workflows
+- Parallel / distributed optimization
+
+## Basic example
+
+```python
+import numpy as np
+import pandas as pd
+
+from lmeeeg.api.fit import fit_lmm_mass_univariate
+from lmeeeg.api.infer import permute_fixed_effect
+from lmeeeg.simulation.generator import simulate_random_intercept_dataset
+
+simulated = simulate_random_intercept_dataset(
+    n_subjects=10,
+    n_trials_per_subject=12,
+    n_channels=4,
+    n_times=25,
+    effect_channels=[1, 2],
+    effect_times=range(8, 14),
+    beta=0.8,
+    seed=13,
+)
+
+fit_result = fit_lmm_mass_univariate(
+    eeg=simulated.eeg,
+    metadata=simulated.metadata,
+    formula="y ~ condition + latency + (1|subject)",
+    variable_types={
+        "condition": "categorical",
+        "latency": "numeric",
+        "subject": "group",
+    },
+)
+
+inference = permute_fixed_effect(
+    fit_result=fit_result,
+    effect="condition[T.B]",
+    correction="maxstat",
+    n_permutations=200,
+    seed=13,
+)
+
+print(inference.corrected_p_values.shape)
+```

lmeeeg-0.1.0/README.md

@@ -0,0 +1,67 @@
+# LmeEEG
+
+Minimal Python package implementing the core lmeEEG workflow for epoched M/EEG data with **random intercepts**:
+
+1. parse a mixed-model style formula at the API edge,
+2. fit a random-intercept mixed model at each channel × timepoint,
+3. subtract the fitted random effects to obtain marginal EEG,
+4. run fast mass-univariate OLS on the marginalized data,
+5. perform max-stat, cluster, or TFCE correction.
+
+## Current scope
+
+- One grouping factor in the public API
+- Random intercept only
+- Trial-wise epoched data shaped `(n_observations, n_channels, n_times)`
+- Cluster / TFCE correction via MNE-Python when installed
+- Tiny simulation utilities for recovery / null checks
+
+## Not yet included
+
+- Random slopes
+- Two grouping factors in the public API
+- Real-data validation workflows
+- Parallel / distributed optimization
+
+## Basic example
+
+```python
+import numpy as np
+import pandas as pd
+
+from lmeeeg.api.fit import fit_lmm_mass_univariate
+from lmeeeg.api.infer import permute_fixed_effect
+from lmeeeg.simulation.generator import simulate_random_intercept_dataset
+
+simulated = simulate_random_intercept_dataset(
+    n_subjects=10,
+    n_trials_per_subject=12,
+    n_channels=4,
+    n_times=25,
+    effect_channels=[1, 2],
+    effect_times=range(8, 14),
+    beta=0.8,
+    seed=13,
+)
+
+fit_result = fit_lmm_mass_univariate(
+    eeg=simulated.eeg,
+    metadata=simulated.metadata,
+    formula="y ~ condition + latency + (1|subject)",
+    variable_types={
+        "condition": "categorical",
+        "latency": "numeric",
+        "subject": "group",
+    },
+)
+
+inference = permute_fixed_effect(
+    fit_result=fit_result,
+    effect="condition[T.B]",
+    correction="maxstat",
+    n_permutations=200,
+    seed=13,
+)
+
+print(inference.corrected_p_values.shape)
+```

lmeeeg-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lmeeeg"
+version = "0.1.0"
+description = "Minimal Python implementation of lmeEEG for random-intercept mass-univariate M/EEG analysis"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Hiro YAMASAKI", email = "hiroyoshi.YAMASAKI@univ-amu.fr"}]
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "statsmodels>=0.14",
+    "patsy>=0.5",
+]
+
+[project.optional-dependencies]
+mne = ["mne>=1.5"]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

lmeeeg-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lmeeeg-0.1.0/src/lmeeeg/__init__.py

@@ -0,0 +1,12 @@
+"""Top-level package for LmeEEG."""
+
+from lmeeeg.api.fit import fit_lmm_mass_univariate
+from lmeeeg.api.infer import permute_fixed_effect
+from lmeeeg.api.simulate import simulate_erp_random_intercept_dataset, simulate_random_intercept_dataset
+
+__all__ = [
+    "fit_lmm_mass_univariate",
+    "permute_fixed_effect",
+    "simulate_erp_random_intercept_dataset",
+    "simulate_random_intercept_dataset",
+]

lmeeeg-0.1.0/src/lmeeeg/api/__init__.py

@@ -0,0 +1,14 @@
+"""Public API layer."""
+
+from lmeeeg.api.fit import FitConfig, fit_lmm_mass_univariate
+from lmeeeg.api.infer import PermutationConfig, permute_fixed_effect
+from lmeeeg.api.simulate import simulate_erp_random_intercept_dataset, simulate_random_intercept_dataset
+
+__all__ = [
+    "FitConfig",
+    "PermutationConfig",
+    "fit_lmm_mass_univariate",
+    "permute_fixed_effect",
+    "simulate_erp_random_intercept_dataset",
+    "simulate_random_intercept_dataset",
+]

lmeeeg-0.1.0/src/lmeeeg/api/fit.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from lmeeeg.backends.lmm.statsmodels_backend import StatsModelsLMMBackend
+from lmeeeg.backends.ols.numpy_backend import NumPyOLSBackend
+from lmeeeg.core.design import build_design_spec
+from lmeeeg.core.marginal import compute_marginal_eeg
+from lmeeeg.core.results import ConvergenceSummary, FitResult
+
+
+@dataclass(slots=True)
+class FitConfig:
+    """Configuration for the public fit API.
+
+    Parameters
+    ----------
+    lmm_backend_name : str
+        Name of the LMM backend.
+    ols_backend_name : str
+        Name of the OLS backend.
+    """
+
+    lmm_backend_name: str = "statsmodels"
+    ols_backend_name: str = "numpy"
+
+
+# ==============================
+# Public fit entry point
+# ==============================
+
+def fit_lmm_mass_univariate(
+    eeg: np.ndarray,
+    metadata: pd.DataFrame,
+    formula: str,
+    variable_types: dict[str, str],
+    fit_intercept: bool = True,
+    config: FitConfig | None = None,
+) -> FitResult:
+    """Fit the minimal lmeEEG pipeline.
+
+    Parameters
+    ----------
+    eeg : np.ndarray
+        EEG data with shape `(n_observations, n_channels, n_times)`.
+    metadata : pd.DataFrame
+        Observation-level metadata. One row per EEG observation.
+    formula : str
+        Mixed-model style formula, e.g. ``"y ~ condition + latency + (1|subject)"``.
+        The response variable must be `y` and is treated as symbolic only.
+    variable_types : dict[str, str]
+        Explicit variable typing map. Allowed values are ``categorical``,
+        ``numeric``, and ``group``.
+    fit_intercept : bool
+        Whether to include a fixed intercept.
+    config : FitConfig | None
+        Backend configuration.
+
+    Returns
+    -------
+    FitResult
+        Result object containing design information, convergence diagnostics,
+        marginal EEG, and OLS summary statistics.
+
+    Usage example
+    -------------
+        fit_result = fit_lmm_mass_univariate(
+            eeg=eeg,
+            metadata=metadata,
+            formula="y ~ condition + latency + (1|subject)",
+            variable_types={
+                "condition": "categorical",
+                "latency": "numeric",
+                "subject": "group",
+            },
+        )
+    """
+    config = config or FitConfig()
+    design_spec = build_design_spec(
+        metadata=metadata,
+        formula=formula,
+        variable_types=variable_types,
+        fit_intercept=fit_intercept,
+    )
+
+    if config.lmm_backend_name != "statsmodels":
+        raise ValueError(f"Unsupported LMM backend: {config.lmm_backend_name}")
+    if config.ols_backend_name != "numpy":
+        raise ValueError(f"Unsupported OLS backend: {config.ols_backend_name}")
+
+    lmm_backend = StatsModelsLMMBackend()
+    lmm_result = lmm_backend.fit_mass_univariate(
+        eeg=eeg,
+        metadata=metadata,
+        design_spec=design_spec,
+    )
+
+    marginal_eeg = compute_marginal_eeg(eeg=eeg, fitted_random_effects=lmm_result.fitted_random_effects)
+
+    ols_backend = NumPyOLSBackend()
+    ols_result = ols_backend.fit_mass_univariate(
+        eeg=marginal_eeg,
+        design_matrix=design_spec.fixed_design_matrix,
+        column_names=design_spec.fixed_column_names,
+    )
+
+    convergence_summary = ConvergenceSummary.from_feature_table(lmm_result.feature_diagnostics)
+
+    return FitResult(
+        formula=formula,
+        variable_types=variable_types,
+        design_spec=design_spec,
+        fixed_effects_maps=lmm_result.fixed_effects_maps,
+        random_effect_variance_map=lmm_result.random_effect_variance_map,
+        residual_variance_map=lmm_result.residual_variance_map,
+        fitted_random_effects=lmm_result.fitted_random_effects,
+        feature_diagnostics=lmm_result.feature_diagnostics,
+        convergence_summary=convergence_summary,
+        marginal_eeg=marginal_eeg,
+        ols_betas=ols_result.beta_maps,
+        ols_t_values=ols_result.t_value_maps,
+        ols_residual_variance=ols_result.residual_variance_map,
+        backend_metadata={
+            "lmm_backend": config.lmm_backend_name,
+            "ols_backend": config.ols_backend_name,
+        },
+    )

lmeeeg-0.1.0/src/lmeeeg/api/infer.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lmeeeg.backends.correction.maxstat_backend import MaxStatCorrectionBackend
+from lmeeeg.backends.correction.mne_cluster_backend import MNEClusterCorrectionBackend
+from lmeeeg.backends.correction.mne_tfce_backend import MNETFCorrectionBackend
+from lmeeeg.core.results import FitResult, InferenceResult
+
+
+@dataclass(slots=True)
+class PermutationConfig:
+    """Configuration for permutation inference."""
+
+    n_permutations: int = 1000
+    seed: int = 0
+    tail: int = 0
+
+
+# ==============================
+# Public inference entry point
+# ==============================
+
+def permute_fixed_effect(
+    fit_result: FitResult,
+    effect: str,
+    correction: str = "cluster",
+    n_permutations: int = 1000,
+    seed: int = 0,
+    tail: int = 0,
+    threshold: float | dict[str, float] | None = None,
+    adjacency=None,
+) -> InferenceResult:
+    """Run permutation-based inference for one fixed effect.
+
+    Parameters
+    ----------
+    fit_result : FitResult
+        Result returned by :func:`fit_lmm_mass_univariate`.
+    effect : str
+        Exact fixed-effect column name to test.
+    correction : str
+        Correction backend: ``maxstat``, ``cluster``, or ``tfce``.
+    n_permutations : int
+        Number of permutations.
+    seed : int
+        Random seed.
+    tail : int
+        Tail for MNE-compatible permutation code. Use 0 for two-sided,
+        1 for positive, -1 for negative.
+    threshold : float | dict[str, float] | None
+        Cluster threshold or TFCE threshold dictionary.
+    adjacency : Any
+        Optional adjacency matrix passed through to MNE correction backends.
+
+    Returns
+    -------
+    InferenceResult
+        Corrected inference output.
+
+    Usage example
+    -------------
+        inference = permute_fixed_effect(
+            fit_result=fit_result,
+            effect="condition[T.B]",
+            correction="tfce",
+            n_permutations=500,
+            seed=1,
+        )
+    """
+    if effect not in fit_result.design_spec.fixed_column_names:
+        available = ", ".join(fit_result.design_spec.fixed_column_names)
+        raise ValueError(f"Unknown effect '{effect}'. Available fixed effects: {available}")
+
+    if correction == "maxstat":
+        backend = MaxStatCorrectionBackend()
+    elif correction == "cluster":
+        backend = MNEClusterCorrectionBackend()
+    elif correction == "tfce":
+        backend = MNETFCorrectionBackend()
+    else:
+        raise ValueError(f"Unsupported correction backend: {correction}")
+
+    return backend.run(
+        fit_result=fit_result,
+        effect=effect,
+        n_permutations=n_permutations,
+        seed=seed,
+        tail=tail,
+        threshold=threshold,
+        adjacency=adjacency,
+    )

lmeeeg-0.1.0/src/lmeeeg/api/simulate.py

@@ -0,0 +1,23 @@
+"""Public simulation helpers."""
+
+from lmeeeg.simulation.generator import (
+    ERPComponentSpec,
+    ERPSimulationConfig,
+    ERPSimulationMetadata,
+    ERPSimulationResult,
+    SimulatedDataset,
+    simulate_erp_random_intercept_dataset,
+    simulate_random_intercept_dataset,
+)
+from lmeeeg.simulation.scenarios import build_default_erp_component_specs
+
+__all__ = [
+    "ERPComponentSpec",
+    "ERPSimulationConfig",
+    "ERPSimulationMetadata",
+    "ERPSimulationResult",
+    "SimulatedDataset",
+    "build_default_erp_component_specs",
+    "simulate_erp_random_intercept_dataset",
+    "simulate_random_intercept_dataset",
+]

lmeeeg-0.1.0/src/lmeeeg/backends/__init__.py

@@ -0,0 +1 @@
+"""Backend interfaces and implementations."""

lmeeeg-0.1.0/src/lmeeeg/backends/correction/__init__.py

@@ -0,0 +1 @@
+"""Correction backends."""

lmeeeg-0.1.0/src/lmeeeg/backends/correction/base.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from lmeeeg.core.results import FitResult, InferenceResult
+
+
+class BaseCorrectionBackend(ABC):
+    """Abstract base class for correction backends."""
+
+    @abstractmethod
+    def run(
+        self,
+        fit_result: FitResult,
+        effect: str,
+        n_permutations: int,
+        seed: int,
+        tail: int,
+        threshold: float | dict[str, float] | None,
+        adjacency: Any,
+    ) -> InferenceResult:
+        """Run correction backend."""

lmeeeg-0.1.0/src/lmeeeg/backends/correction/maxstat_backend.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import numpy as np
+
+from lmeeeg.backends.correction.base import BaseCorrectionBackend
+from lmeeeg.core.results import FitResult, InferenceResult
+
+
+# ==============================
+# Max-stat correction backend
+# ==============================
+
+class MaxStatCorrectionBackend(BaseCorrectionBackend):
+    """Permutation max-statistic backend on OLS t maps."""
+
+    def run(
+        self,
+        fit_result: FitResult,
+        effect: str,
+        n_permutations: int,
+        seed: int,
+        tail: int,
+        threshold: float | dict[str, float] | None,
+        adjacency,
+    ) -> InferenceResult:
+        """Run max-statistic correction.
+
+        Notes
+        -----
+        This backend uses row shuffling of the design matrix as a simple MVP
+        permutation scheme on marginalized data. It is intentionally explicit
+        and easy to inspect.
+        """
+        del threshold, adjacency, tail
+        rng = np.random.default_rng(seed)
+        observed_t = fit_result.ols_t_values[effect]
+        x_matrix = fit_result.design_spec.fixed_design_matrix
+        y = fit_result.marginal_eeg
+        n_observations, n_channels, n_times = y.shape
+        y_2d = y.reshape(n_observations, n_channels * n_times)
+
+        effect_index = fit_result.design_spec.fixed_column_names.index(effect)
+        null_distribution = np.zeros(n_permutations, dtype=float)
+
+        for permutation_index in range(n_permutations):
+            permuted_indices = rng.permutation(n_observations)
+            x_perm = x_matrix[permuted_indices, :]
+            xtx_inv = np.linalg.inv(x_perm.T @ x_perm)
+            beta = xtx_inv @ x_perm.T @ y_2d
+            residuals = y_2d - x_perm @ beta
+            residual_variance = np.sum(residuals ** 2, axis=0) / (n_observations - x_perm.shape[1])
+            standard_error = np.sqrt(residual_variance * xtx_inv[effect_index, effect_index])
+            t_values = beta[effect_index, :] / standard_error
+            null_distribution[permutation_index] = np.max(np.abs(t_values))
+
+        corrected_p_values = (1 + np.sum(null_distribution[:, None, None] >= np.abs(observed_t)[None, :, :], axis=0)) / (n_permutations + 1)
+
+        return InferenceResult(
+            effect=effect,
+            correction="maxstat",
+            observed_statistic=observed_t,
+            corrected_p_values=corrected_p_values,
+            null_distribution=null_distribution,
+            clusters=None,
+            cluster_p_values=None,
+            backend_metadata={
+                "backend": "maxstat",
+                "n_permutations": n_permutations,
+                "permutation_scheme": "row_shuffle_on_marginal_design",
+            },
+        )

lmeeeg-0.1.0/src/lmeeeg/backends/correction/mne_cluster_backend.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import os
+
+import numpy as np
+
+from lmeeeg.backends.correction.base import BaseCorrectionBackend
+from lmeeeg.core.results import FitResult, InferenceResult
+
+
+# ==============================
+# MNE cluster correction backend
+# ==============================
+
+class MNEClusterCorrectionBackend(BaseCorrectionBackend):
+    """Cluster-based permutation correction using MNE-Python."""
+
+    def run(
+        self,
+        fit_result: FitResult,
+        effect: str,
+        n_permutations: int,
+        seed: int,
+        tail: int,
+        threshold: float | dict[str, float] | None,
+        adjacency,
+    ) -> InferenceResult:
+        """Run cluster-based permutation correction with MNE.
+
+        The test is performed on observation-level marginalized data using a
+        simple two-model Freedman-Lane style residualization for the selected
+        effect. This keeps the correction layer separated from the LMM layer.
+        """
+        # Some environments expose MNE through a Numba caching path that is not
+        # available at runtime. Disabling JIT here keeps the optional backend
+        # usable without affecting the public API.
+        os.environ.setdefault("NUMBA_DISABLE_JIT", "1")
+        os.environ.setdefault("MNE_DONTWRITE_HOME", "true")
+        try:
+            from mne.stats import permutation_cluster_1samp_test
+        except Exception as error:  # pragma: no cover
+            raise ImportError("MNE-Python is required for cluster correction.") from error
+
+        x_matrix = fit_result.design_spec.fixed_design_matrix
+        column_names = fit_result.design_spec.fixed_column_names
+        effect_index = column_names.index(effect)
+        reduced_columns = [index for index in range(len(column_names)) if index != effect_index]
+
+        y = fit_result.marginal_eeg
+        n_observations, n_channels, n_times = y.shape
+        y_2d = y.reshape(n_observations, n_channels * n_times)
+
+        if reduced_columns:
+            x_reduced = x_matrix[:, reduced_columns]
+            beta_reduced = np.linalg.pinv(x_reduced) @ y_2d
+            residuals = y_2d - x_reduced @ beta_reduced
+        else:
+            residuals = y_2d.copy()
+
+        residuals_3d = residuals.reshape(n_observations, n_channels, n_times)
+        data_for_mne = np.transpose(residuals_3d, (0, 2, 1))
+        cluster_threshold = threshold if threshold is not None else 2.0
+
+        observed_t, clusters, cluster_p_values, null_distribution = permutation_cluster_1samp_test(
+            X=data_for_mne,
+            threshold=cluster_threshold,
+            n_permutations=n_permutations,
+            tail=tail,
+            adjacency=adjacency,
+            out_type="mask",
+            seed=seed,
+            verbose=False,
+        )
+        observed_t = observed_t.T
+        corrected_p_values = np.ones_like(observed_t, dtype=float)
+        for cluster_mask, cluster_p_value in zip(clusters, cluster_p_values):
+            corrected_p_values[cluster_mask.T] = np.minimum(corrected_p_values[cluster_mask.T], cluster_p_value)
+
+        return InferenceResult(
+            effect=effect,
+            correction="cluster",
+            observed_statistic=observed_t,
+            corrected_p_values=corrected_p_values,
+            null_distribution=np.asarray(null_distribution),
+            clusters=clusters,
+            cluster_p_values=np.asarray(cluster_p_values),
+            backend_metadata={
+                "backend": "mne_cluster",
+                "n_permutations": n_permutations,
+                "threshold": cluster_threshold,
+            },
+        )