ide4eeg 0.8__py3-none-any.whl

ide4eeg/__init__.py

@@ -0,0 +1,55 @@
+# Ensure "spawn" start method for multiprocessing — required on Linux
+# where the default "fork" crashes with Qt. macOS already uses "spawn"
+# by default since Python 3.8. Must run before any multiprocessing use.
+#
+# Only touch the start method from the main process: child processes
+# (e.g. joblib/loky workers) re-import this package during unpickling
+# and calling set_start_method there raises "context has already been
+# set" even when the context is already spawn (the guard below can't
+# tell the difference in a spawned child, because the child never
+# explicitly called set_start_method itself — see
+# https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods).
+import multiprocessing as _mp
+_is_main = _mp.current_process().name == "MainProcess"
+if _is_main:
+    if _mp.get_start_method(allow_none=True) != "spawn":
+        _mp.set_start_method("spawn")
+
+# Once-per-process migration of runtime data from old in-package /
+# upstream locations to the consolidated ~/.obci/ide4eeg/ tree.
+# Idempotent — silently no-ops when nothing to migrate.  Done eagerly
+# at import time so subsequent code (insightface_backend, l2cs_gaze)
+# sees the consolidated paths regardless of import order.  Skipped in
+# child processes (joblib/loky workers) because they inherit the
+# already-migrated state from the parent.
+if _is_main:
+    try:
+        from ide4eeg.download_tools import migrate_legacy_paths
+        migrate_legacy_paths()
+    except Exception as _exc:
+        # Per-step rename failures are caught + logged inside
+        # migrate_legacy_paths; this outer except covers anything
+        # broader (e.g. ImportError on a malformed download_tools).
+        # Log a warning so a real bug doesn't get silently swallowed.
+        import logging as _logging
+        _logging.getLogger(__name__).warning(
+            "Path migration skipped: %s: %s",
+            type(_exc).__name__, _exc)
+        del _logging, _exc
+
+del _mp, _is_main
+
+__version__ = "0.8"
+
+#: Prefix used for per-recording output directories.
+#: Layout: ``<output_root>/<OUTPUT_DIR_PREFIX><filename_core>/{preprocessing,analysis}/``
+#: Single source of truth — pipeline writers and GUI viewers should
+#: reference this rather than the literal string.
+OUTPUT_DIR_PREFIX = "IDE4EEG_OUT_"
+
+#: Sentinel value for ``config["electrodes_layout"]`` meaning
+#: "use the 3D positions already in the file, don't apply a
+#: standard montage".  Auto-set by the preprocessing step when
+#: native positions are detected; exposed as a selectable combobox
+#: item in the GUI.
+NATIVE_POSITIONS_SENTINEL = "native (from file)"

ide4eeg/__main__.py

@@ -0,0 +1,11 @@
+"""Module entry point: ``python -m ide4eeg`` delegates to the CLI.
+
+Equivalent to running the installed ``ide4eeg`` console script (also
+defined in pyproject.toml as the ``[project.gui-scripts]`` entry).
+The two paths share the same dispatcher so behaviour is identical.
+"""
+
+from ide4eeg.cli import main
+
+if __name__ == "__main__":
+    main()

ide4eeg/_appcds.py

@@ -0,0 +1,170 @@
+"""AppCDS (Application Class Data Sharing) flag builder for Java jars.
+
+When IDE4EEG launches Svarog or ConnectiVIS, the JVM normally re-loads
+all the Swing/AWT/3rd-party classes from scratch — a 0.5–1 s tax on
+every cold start.  AppCDS lets the JVM persist class metadata to a
+``.jsa`` archive on first run and reuse it on every subsequent run.
+
+This module centralises the flag construction so all four launch
+sites (gui.py ``_launch_svarog`` / ``_launch_connectivis``, the three
+``review_*_via_svarog`` entry points in ``preprocessing/svarog_review``)
+follow the same scheme as the standalone Svarog launcher
+(``standalone-package-files/svarog`` in svarog4) and the connecti-VIS
+``run.sh``.
+
+Filename scheme
+---------------
+
+``<jar-dir>/<jar-stem>-<jvm-id>.jsa``
+
+* ``<jar-dir>`` — directory containing the jar.  Putting the archive
+  next to the jar means an uninstall (rm -rf the install dir) cleans
+  it up automatically, and the launcher script + IDE4EEG share the
+  same file.
+* ``<jar-stem>`` — jar basename minus ``.jar``.  Different versions
+  of the same app land on different filenames automatically.
+* ``<jvm-id>`` — first 8 hex chars of ``sha1(<absolute path to java
+  binary>)``.  AppCDS archives are tied to the exact JVM build that
+  wrote them, so a JDK upgrade that lands on a new install path needs
+  a fresh archive.  Tagging with the path means the upgrade naturally
+  triggers regeneration instead of silently falling back via
+  ``-Xshare:auto`` on a stale file.
+
+Freshness check
+---------------
+
+If the archive's mtime is older than the jar's, treat it as stale
+(jar has been redeployed, the archive's class list is out of date)
+and regenerate.  Saves a manual ``rm`` step after every Svarog
+rebuild.
+
+JDK floor
+---------
+
+``-XX:ArchiveClassesAtExit`` (JEP 350, dynamic CDS) requires JDK 13+.
+On JDK 11/12 the JVM rejects the flag with "Unrecognized VM option"
+and aborts before main, so the version-probe gate is load-bearing.
+We probe lazily — only when the archive is missing or stale — because
+a fresh archive is itself proof that the JVM was JDK 13+ when it
+wrote it (path-tagged jvm-id means a JDK swap lands on a new
+filename), so reuse can skip the probe entirely and recover the full
+~380 ms cold-start win.
+
+Failure modes
+-------------
+
+Anything unexpected (jar dir read-only, jar gone between mtime calls,
+sha1 module missing on a platform we haven't seen, ``java`` not on
+PATH, version probe failed) → return ``[]`` and let the launch proceed
+without AppCDS.  AppCDS is a perf optimisation, never a correctness
+requirement.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import shutil
+import subprocess
+
+
+def _java_major(java_path: str) -> int | None:
+    """Probe ``java -version`` and return the feature version.
+
+    Returns ``None`` on any failure (binary missing, timeout, output
+    unparseable).  Callers treat ``None`` as "don't enable AppCDS".
+
+    Handles both the modern ``openjdk version "17.0.9"`` form and the
+    Java-8 legacy ``java version "1.8.0_392"`` form (where the real
+    major is 8, not 1).
+    """
+    resolved = shutil.which(java_path) or java_path
+    try:
+        out = subprocess.run(
+            [resolved, "-version"],
+            capture_output=True, text=True, timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    text = (out.stderr or "") + (out.stdout or "")
+    m = re.search(r'version "(\d+)(?:\.(\d+))?', text)
+    if not m:
+        return None
+    first = int(m.group(1))
+    return int(m.group(2)) if first == 1 and m.group(2) else first
+
+
+def appcds_flags(jar_path: str, java_path: str = "java") -> list[str]:
+    """Build AppCDS flags for launching ``jar_path`` under ``java_path``.
+
+    Parameters
+    ----------
+    jar_path : str
+        Absolute path to the jar.  Must exist; otherwise returns ``[]``.
+    java_path : str
+        ``java`` binary to launch with.  ``"java"`` (the default) is
+        resolved via :func:`shutil.which`; an absolute path is used
+        as-is.  The jvm-id is derived from the resolved path so a
+        JDK upgrade swapping out the binary changes the archive name.
+
+    Returns
+    -------
+    list[str]
+        Either ``[-XX:SharedArchiveFile=..., -Xshare:auto]`` (reuse a
+        valid archive), ``[-XX:ArchiveClassesAtExit=...]`` (generate
+        on next clean exit), or ``[]`` (fall back to no AppCDS — jar
+        missing, jar dir read-only, JDK < 13, etc.).
+    """
+    try:
+        jar_path = os.fspath(jar_path)
+        if not os.path.isfile(jar_path):
+            return []
+
+        resolved_java = shutil.which(java_path) or java_path
+        jvm_id = hashlib.sha1(
+            resolved_java.encode("utf-8")).hexdigest()[:8]
+
+        jar_dir = os.path.dirname(os.path.abspath(jar_path)) or "."
+        if not os.access(jar_dir, os.W_OK):
+            return []
+
+        jar_stem = os.path.splitext(os.path.basename(jar_path))[0]
+        archive = os.path.join(jar_dir, f"{jar_stem}-{jvm_id}.jsa")
+
+        try:
+            jar_mtime = os.path.getmtime(jar_path)
+        except OSError:
+            return []
+
+        if os.path.isfile(archive):
+            try:
+                archive_mtime = os.path.getmtime(archive)
+            except OSError:
+                archive_mtime = None
+            if archive_mtime is not None and archive_mtime > jar_mtime:
+                # Fresh archive → JVM that wrote it was JDK 13+ already
+                # (couldn't have written it otherwise), so skip the
+                # version probe and reuse directly.
+                return [
+                    f"-XX:SharedArchiveFile={archive}",
+                    "-Xshare:auto",
+                ]
+            # Stale (jar redeployed since we wrote the archive) — drop
+            # so the next clean exit regenerates.
+            try:
+                os.remove(archive)
+            except OSError:
+                pass
+
+        # No fresh archive → we need ArchiveClassesAtExit, which is
+        # JDK 13+ only.  Probe now (worth ~100 ms cold-path subprocess
+        # only on the first launch of a (jar, jvm) pair).
+        major = _java_major(java_path)
+        if major is None or major < 13:
+            return []
+
+        return [f"-XX:ArchiveClassesAtExit={archive}"]
+    except Exception:
+        # Any unexpected error: skip AppCDS, never block the launch.
+        return []

ide4eeg/analysis/__init__.py

@@ -0,0 +1,3 @@
+def _safe_tag(tag):
+    """Sanitize a tag name for use in file paths (replace '/' with '_')."""
+    return tag.replace("/", "_")

ide4eeg/analysis/analysis.py

@@ -0,0 +1,81 @@
+"""Analysis orchestrator for IDE4EEG.
+
+Dispatches time-domain and time-frequency analyses based on config flags.
+"""
+
+# Author: Szymon Bocian, 2023
+
+from .eeg_profiles import eeg_profiles
+from .connectivity_analysis import connectivity_analysis
+from .dipole_analysis import dipole_analysis
+
+import logging
+import matplotlib.pyplot as plt
+
+def analysis(rest, rest_clean, epochs, epochs_clean, data, config, path, tags_desc_id, file_name):
+    '''
+    Preparing analysis and plots for the prepared epochs.
+
+    Parameters
+    ----------
+    rest: mne.epochs.Epochs or None
+        Prepared rest segments from the signal. If None, REST path wasn't prepare in config file.
+    rest_clean: mne.epochs.Epochs or None
+        Prepared rest segments from the signal without segments with artifacts. If None, REST path wasn't
+        prepare in config file.
+    epochs: mne.epochs.Epochs or None
+        Prepared epochs from the signal. If None, EPOCHS path wasn't prepare in config file.
+    epochs_clean: mne.epochs.Epochs or None
+        Prepared epochs from the signal without epochs with artifacts. If None, REST path wasn't
+        prepare in config file.
+    data: pandas.core.frame.DataFrame
+        Dataframe with basic information about tags.
+    config: dict
+        Dictionary of configuration variables.
+    path: str
+        Path to the output directory.
+    tags_desc_id: dict
+        Dictionary of the names of prepared tags and their values in the prepared STIM signal.
+    file_name: str
+        Name of the file with raw signal.
+    '''
+
+    cancel = config.get("_cancel_event")
+
+    def _check_cancel():
+        if cancel is not None and cancel.is_set():
+            logging.info("Analysis cancelled by user.")
+            raise InterruptedError("Analysis cancelled by user")
+
+    if config.get("prepare_eeg_profiles"):
+        _check_cancel()
+        logging.info("Preparing EEG profiles.")
+        eeg_profiles(rest_clean, epochs_clean, config, path, file_name)
+
+    if config.get("prepare_connectivity_analysis"):
+        _check_cancel()
+        logging.info("Preparing connectivity analysis.")
+        connectivity_analysis(rest_clean, epochs_clean, config, path, file_name)
+
+    if config.get("prepare_dipole_fitting"):
+        _check_cancel()
+        logging.info("Preparing dipole fitting analysis.")
+        dipole_analysis(rest_clean, epochs_clean, config, path, file_name)
+
+    if config.get("prepare_tf_statistics"):
+        _check_cancel()
+        logging.info("Preparing ERD/ERS significance analysis.")
+        from .tf_statistics import tf_statistics_analysis
+        tf_statistics_analysis(rest_clean, epochs_clean, config, path, file_name)
+
+    # MNE catalog analyses
+    mne_ids = config.get("mne_catalog", [])
+    if mne_ids:
+        _check_cancel()
+        logging.info("Running MNE catalog analyses (%d selected).",
+                     len(mne_ids))
+        from .mne_catalog import run_mne_catalog
+        run_mne_catalog(mne_ids, rest_clean, epochs_clean, config,
+                        path, file_name)
+
+    plt.close("all")

ide4eeg/analysis/connectivity/__init__.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""Brain connectivity analysis based on ConnectiviPy.
+
+Original authors: Dominik Krzemiński, Maciej Kamiński (University of Warsaw).
+Developed during Google Summer of Code 2015 under the International
+Neuroinformatics Coordinating Facility (INCF).
+https://github.com/dokato/connectivipy
+Integrated into IDE4EEG for EEG connectivity estimation.
+"""
+
+from .data import Data
+from .conn import conn_estim_dc
+from .mvarmodel import Mvar
+from .mvar.fitting import mvar_gen, mvar_gen_inst, fitting_algorithms
+
+__all__ = [
+    "Data", "conn_estim_dc", "Mvar",
+    "mvar_gen", "mvar_gen_inst", "fitting_algorithms",
+]

ide4eeg/analysis/connectivity/aec/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

ide4eeg/analysis/connectivity/aec/utils.py

@@ -0,0 +1,53 @@
+import numpy as np
+import scipy.signal as ss
+
+FQ_BANDS = {'theta': [6, 7],
+            'alpha': [8, 13],
+            'beta': [15, 25],
+            'low-gamma': [30, 45],
+            'high-gamma': [55, 70]}
+
+def check_bands_correct(band):
+    return band in FQ_BANDS.keys()
+
+def design_band_filter(lowcut, highcut, fs, rp = None, rs = None,
+                       filttype = 'butter', btype = 'bandpass', order = 5):
+    btypes = {'bandpass', 'bandstop'}
+    filttypes = {'butter', 'cheby1', 'cheby2', 'ellip', 'bessel'}
+    if not btype in btypes:
+        raise ValueError("This is only for band filters: {'bandpass', 'bandstop'}")
+    if not filttype in filttypes:
+        raise ValueError('Not supported filter type, check docs.')
+    filtstr = 'ss.' + filttype + '(order,'
+    if filttype == 'cheby1' or filttype == 'ellip':
+        filtstr += 'rp,'
+    if filttype == 'cheby2' or filttype == 'ellip':
+        filtstr += 'rs,'
+    filtstr += '[low, high], btype = btype)'
+    f_nq = fs / 2
+    low, high = lowcut / f_nq, highcut / f_nq
+    b, a = eval(filtstr)
+    return b, a
+
+def butter_bandpass(lowcut, highcut, fs, order = 4):
+    return design_band_filter(lowcut, highcut, fs, order = order, btype = 'bandpass')
+
+def butter_bandstop(lowcut, highcut, fs, order = 4):
+    return design_band_filter(lowcut, highcut, fs, order = order, btype = 'bandstop')
+
+def filter_band(data, fs, band = None, filter = None, filtfilt = True):
+    if band == filter == None:
+        raise ValueError("When *band* is None, *filter* can't be None")
+    if filter is None:
+        b, a = butter_bandpass(band[0], band[1], fs)
+    else:
+        b, a = filter
+    if filtfilt:
+        fdata = ss.filtfilt(b, a, data)
+    else:
+        fdata = ss.lfilter(b, a, data)
+    return fdata
+
+def calc_ampenv(data):
+    return np.abs(ss.hilbert(data))
+