pineuro 1.0.0__py3-none-any.whl

pineuro/__init__.py

@@ -0,0 +1,284 @@
+"""pineuro - Python Real-Time fMRI Neurofeedback
+
+A complete pipeline for real-time fMRI neurofeedback research, from volume acquisition
+through preprocessing, network mask extraction, and moment-to-moment BOLD activation estimation.
+
+Main Functions
+--------------
+run_feedback_task : Run a complete real-time feedback task
+preprocessing : DICOM conversion, motion correction, brain extraction
+collect_volumes : Watch for and collect incoming scanner volumes (DICOM or NIfTI)
+mask_extraction_rest : Extract network masks using ICA and Yeo atlas
+mask_extraction_mni : Extract network masks directly from MNI atlas (no localizer needed)
+mask_extraction_task : Extract network masks using GLM contrasts from task localizer
+coregister_reference : Coregister masks to real-time scanner position
+
+Task Framework
+--------------
+BaseTask : Abstract base for custom neurofeedback tasks
+BaseLocalizerTask : Abstract base for localizer/stimulus tasks
+BallTask : Built-in dual-network ball game with adaptive difficulty
+ThermometerTask : Built-in single-network thermometer feedback
+create_task : Factory function to create tasks from registry
+NetworkRole : Declare network slot semantics for tasks
+ActivationSmoother : Exponential moving average smoothing
+ActivationNormalizer : Percentile-based normalization
+
+Session Orchestration
+--------------------
+SessionConfig : High-level session configuration
+LocalizerConfig / FeedbackRunConfig : Per-localizer and per-feedback-run configuration
+run_full_session : Run complete multi-run session
+setup_session : Initialize session (collection, preprocessing, mask extraction)
+run_single_task : Run one feedback/transfer task via task factory
+TaskState : Persistent state across runs
+
+Examples
+--------
+>>> from pineuro import preprocessing, mask_extraction_rest, run_feedback_task
+>>>
+>>> # Step 1: Preprocess resting-state data
+>>> preproc_file, mask_file, ref_file = preprocessing(
+...     participant_id='sub-01', session_id='ses-01', task='rest',
+...     root_dir='/data/sub-01/ses-01/preprocessing',
+...     input_dicoms='/scanner/sub-01/rest',
+... )
+>>>
+>>> # Step 2: Extract participant-specific network masks (ICA + Yeo atlas)
+>>> mask_paths = mask_extraction_rest(
+...     participant_id='sub-01', session_id='ses-01',
+...     root_dir='/data/sub-01/ses-01/mask_extraction',
+...     input_file=preproc_file, mask_file=mask_file, ref_file=ref_file,
+...     networks=['ContA', 'DefaultA'],  # returns a list of mask Paths
+... )
+>>>
+>>> # Step 3: Run a real-time feedback task (here, simulated offline)
+>>> result = run_feedback_task(
+...     mask_paths=mask_paths, subject='sub-01', session='ses-01',
+...     task='ball', run=1,
+...     output_dir='/data/sub-01/ses-01/feedback',
+...     collection_dir='/scanner/incoming',
+...     n_baseline=15, n_volumes=200, tr=2.0,
+...     simulator_source_dir='/data/sub-01/feedback_dicoms', simulator_speed=10.0,
+... )
+"""
+
+import importlib as _importlib
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    # Single source of truth: the version declared in pyproject.toml and
+    # recorded in the installed package metadata.
+    __version__ = _pkg_version("pineuro")
+except _PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "unknown"
+
+# ---------------------------------------------------------------------------
+# Lazy import system (PEP 562)
+#
+# Heavy neuroimaging libraries (ANTsPy, nilearn, scipy, nibabel) take 8-17s
+# to import on cold start. By deferring submodule imports until first access,
+# the GUI starts instantly and scripts only pay for what they actually use.
+# ---------------------------------------------------------------------------
+
+# Mapping: attribute_name -> (submodule_path, attribute_name_in_submodule)
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # --- feedback.py (heavy: nibabel, scipy, watchdog, pydicom) ---
+    "run_feedback_task": (".feedback", "run_feedback_task"),
+    "ConnectivityEstimator": (".feedback", "ConnectivityEstimator"),
+    "get_next_run_number": (".feedback", "get_next_run_number"),
+    "get_slot_run_info": (".feedback", "get_slot_run_info"),
+    # --- preprocessing.py (heavy: nibabel, scipy) ---
+    "preprocessing": (".preprocessing", "preprocessing"),
+    "collect_volumes": (".preprocessing", "collect_volumes"),
+    # --- mask_extraction.py (heavy: nibabel, scipy, pandas) ---
+    "mask_extraction_rest": (".mask_extraction", "mask_extraction_rest"),
+    "mask_extraction_mni": (".mask_extraction", "mask_extraction_mni"),
+    "mask_extraction_task": (".mask_extraction", "mask_extraction_task"),
+    "run_mask_extraction_from_config": (".mask_extraction", "run_mask_extraction_from_config"),
+    "import_manual_masks": (".mask_extraction", "import_manual_masks"),
+    "coregister_reference": (".mask_extraction", "coregister_reference"),
+    "create_tissue_masks": (".mask_extraction", "create_tissue_masks"),
+    "ATLAS_SOURCES": (".atlas_registry", "ATLAS_SOURCES"),
+    "get_atlas_labels": (".mask_extraction", "get_atlas_labels"),
+    # --- tasks (lightweight but deferred to avoid loading task modules) ---
+    "BaseTask": (".tasks", "BaseTask"),
+    "BaseLocalizerTask": (".tasks", "BaseLocalizerTask"),
+    "BallTask": (".tasks", "BallTask"),
+    "ThermometerTask": (".tasks", "ThermometerTask"),
+    "ActivationSmoother": (".tasks", "ActivationSmoother"),
+    "ActivationNormalizer": (".tasks", "ActivationNormalizer"),
+    "NetworkRole": (".tasks", "NetworkRole"),
+    "create_task": (".tasks", "create_task"),
+    "create_localizer_task": (".tasks", "create_localizer_task"),
+    # --- tasks.state ---
+    "TaskState": (".tasks.state", "TaskState"),
+    "RunInfo": (".tasks.state", "RunInfo"),
+    # --- session.py (lightweight: stdlib only) ---
+    "SessionConfig": (".session", "SessionConfig"),
+    "PathConfig": (".session", "PathConfig"),
+    "LocalizerConfig": (".session", "LocalizerConfig"),
+    "LocalizerExtractionConfig": (".session", "LocalizerExtractionConfig"),
+    "FeedbackRunConfig": (".session", "FeedbackRunConfig"),
+    "QCConfig": (".session", "QCConfig"),
+    "GLMConfig": (".session", "GLMConfig"),
+    "ConnectivityConfig": (".session", "ConnectivityConfig"),
+    "IntermittentConfig": (".session", "IntermittentConfig"),
+    "SimulatorConfig": (".session", "SimulatorConfig"),
+    "ScannerConfig": (".session", "ScannerConfig"),
+    "ReferenceConfig": (".session", "ReferenceConfig"),
+    "SessionMetadata": (".session", "SessionMetadata"),
+    "ShamConfig": (".session", "ShamConfig"),
+    "ShamRunConfig": (".session", "ShamRunConfig"),
+    "SimulatorSourceMapping": (".session", "SimulatorSourceMapping"),
+    "setup_session": (".session", "setup_session"),
+    "run_single_task": (".session", "run_single_task"),
+    "run_full_session": (".session", "run_full_session"),
+    "run_next_task": (".session", "run_next_task"),
+    "reset_task_state": (".session", "reset_task_state"),
+    "resolve_localizer_masks": (".session", "resolve_localizer_masks"),
+    "detect_existing_sessions": (".session", "detect_existing_sessions"),
+    "next_session_id": (".session", "next_session_id"),
+    # --- sham.py ---
+    "ShamActivationProvider": (".sham", "ShamActivationProvider"),
+    "ReplayActivationProvider": (".sham", "ReplayActivationProvider"),
+    "load_randomization": (".sham", "load_randomization"),
+    "generate_randomization": (".sham", "generate_randomization"),
+    "get_condition_for_participant": (".sham", "get_condition_for_participant"),
+    "find_feedbacklog_for_replay": (".sham", "find_feedbacklog_for_replay"),
+    # --- utils.py (heavy: numpy, nibabel, scipy, templateflow) ---
+    "enable_timing": (".utils", "enable_timing"),
+    "disable_timing": (".utils", "disable_timing"),
+    "get_timing_data": (".utils", "get_timing_data"),
+    "save_timing_report": (".utils", "save_timing_report"),
+    "Timer": (".utils", "Timer"),
+    "check_platform_requirements": (".utils", "check_platform_requirements"),
+    "outputs_exist": (".utils", "outputs_exist"),
+    "count_volume_files": (".utils", "count_volume_files"),
+    "collection_is_complete": (".utils", "collection_is_complete"),
+    "ProgressEmitter": (".utils", "ProgressEmitter"),
+    "compute_hrf": (".utils", "compute_hrf"),
+    "compute_boxcar_task_regressor": (".utils", "compute_boxcar_task_regressor"),
+    # --- script_generator.py ---
+    "generate_mask_extraction_script": (".script_generator", "generate_mask_extraction_script"),
+    "save_script": (".script_generator", "save_script"),
+    # --- scanner_setup.py (lightweight: stdlib only) ---
+    "test_scanner_connection": (".scanner_setup", "test_scanner_connection"),
+    "ConnectionTestResult": (".scanner_setup", "ConnectionTestResult"),
+    "ping_scanner": (".scanner_setup", "ping_scanner"),
+    "check_watch_directory": (".scanner_setup", "check_watch_directory"),
+    "get_setup_instructions": (".scanner_setup", "get_setup_instructions"),
+    # --- config module ---
+    "config": (".config", ""),  # Module import, not attribute
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        module = _importlib.import_module(module_path, __name__)
+        if not attr_name:
+            # Module-level import (e.g., config)
+            val = module
+        else:
+            val = getattr(module, attr_name)
+        globals()[name] = val  # Cache for subsequent access
+        return val
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core functions
+    "run_feedback_task",
+    "ConnectivityEstimator",
+    "get_next_run_number",
+    "get_slot_run_info",
+    "preprocessing",
+    "collect_volumes",
+    "mask_extraction_rest",
+    "mask_extraction_mni",
+    "mask_extraction_task",
+    "run_mask_extraction_from_config",
+    "import_manual_masks",
+    "coregister_reference",
+    "ATLAS_SOURCES",
+    "get_atlas_labels",
+    # Task classes
+    "BaseTask",
+    "BaseLocalizerTask",
+    "BallTask",
+    "ThermometerTask",
+    "ActivationSmoother",
+    "ActivationNormalizer",
+    # Task registry & factory
+    "NetworkRole",
+    "create_task",
+    "create_localizer_task",
+    # Task regressor computation
+    "compute_hrf",
+    "compute_boxcar_task_regressor",
+    # Task state
+    "TaskState",
+    "RunInfo",
+    # Configuration dataclasses
+    "SessionConfig",
+    "PathConfig",
+    "LocalizerConfig",
+    "LocalizerExtractionConfig",
+    "FeedbackRunConfig",
+    "QCConfig",
+    "GLMConfig",
+    "ConnectivityConfig",
+    "IntermittentConfig",
+    "SimulatorConfig",
+    "ScannerConfig",
+    "ReferenceConfig",
+    "SessionMetadata",
+    "ShamConfig",
+    "ShamRunConfig",
+    "SimulatorSourceMapping",
+    # Sham functionality
+    "ShamActivationProvider",
+    "ReplayActivationProvider",
+    "load_randomization",
+    "generate_randomization",
+    "get_condition_for_participant",
+    "find_feedbacklog_for_replay",
+    # Orchestration functions
+    "setup_session",
+    "run_single_task",
+    "run_full_session",
+    "run_next_task",
+    "reset_task_state",
+    # Multi-session support functions
+    "resolve_localizer_masks",
+    "detect_existing_sessions",
+    "next_session_id",
+    # Timing functions
+    "enable_timing",
+    "disable_timing",
+    "get_timing_data",
+    "save_timing_report",
+    "Timer",
+    # Platform checks
+    "check_platform_requirements",
+    # Utilities
+    "outputs_exist",
+    "count_volume_files",
+    "collection_is_complete",
+    "ProgressEmitter",
+    # Script generation
+    "generate_mask_extraction_script",
+    "save_script",
+    # Scanner setup
+    "test_scanner_connection",
+    "ConnectionTestResult",
+    "ping_scanner",
+    "check_watch_directory",
+    "get_setup_instructions",
+    # Configuration
+    "config",
+]

pineuro/atlas_registry.py

@@ -0,0 +1,49 @@
+"""Atlas source registry — lightweight metadata for GUI dropdowns.
+
+This module is intentionally free of heavy dependencies (no nibabel, scipy,
+nilearn, etc.) so that the GUI can build atlas-related dropdowns without
+triggering multi-second import chains.
+
+The actual atlas *fetching* and *label resolution* live in mask_extraction.py,
+which imports ATLAS_SOURCES from here.
+"""
+
+from typing import Any
+
+# ────────────────────────────────────────────────────────────────────
+# Atlas source registry
+# ────────────────────────────────────────────────────────────────────
+ATLAS_SOURCES: dict[str, dict[str, Any]] = {
+    # Network atlases (resting-state ICA pathway)
+    "yeo_7": {"display_name": "Yeo 7-network", "type": "network", "n_networks": 7},
+    "yeo_17": {"display_name": "Yeo 17-network", "type": "network", "n_networks": 17},
+    "schaefer_100_7net": {
+        "display_name": "Schaefer 100 (7-network)",
+        "type": "network",
+        "n_networks": 7,
+        "n_rois": 100,
+    },
+    "schaefer_100_17net": {
+        "display_name": "Schaefer 100 (17-network)",
+        "type": "network",
+        "n_networks": 17,
+        "n_rois": 100,
+    },
+    "schaefer_400_7net": {
+        "display_name": "Schaefer 400 (7-network)",
+        "type": "network",
+        "n_networks": 7,
+        "n_rois": 400,
+    },
+    "schaefer_400_17net": {
+        "display_name": "Schaefer 400 (17-network)",
+        "type": "network",
+        "n_networks": 17,
+        "n_rois": 400,
+    },
+    # Anatomical/parcel atlases (cluster thresholding pathway)
+    "harvard_oxford": {"display_name": "Harvard-Oxford Cortical", "type": "anatomical"},
+    "aal": {"display_name": "AAL (SPM12)", "type": "anatomical"},
+    # Whole-brain gray matter (no region selection needed)
+    "gray_matter": {"display_name": "Gray Matter (whole-brain)", "type": "tissue"},
+}

pineuro/backup.py

@@ -0,0 +1,210 @@
+"""Session backup: mirror a participant-session folder to a second location.
+
+Copies new and changed files from ``<data root>/<participant>/<session>`` to
+``<destination>/<participant>/<session>``. A file is copied when it is missing
+at the destination or its size or modification time differs, through a
+temporary name, so an interrupted copy never leaves a truncated file under the
+real name. Nothing at the destination is ever deleted: files later discarded or
+cleaned up locally stay in the backup. ``tmp/`` (simulator and per-run scratch)
+is never copied, and the raw DICOM copies in ``collection/`` only when the study
+opts in.
+
+The destination folder itself must already exist, so a backup to a drive that
+is not connected fails instead of silently filling the local disk under the
+drive's empty mount point. Standard library only, so the GUI can import it at
+top level; the participant workflow runs it between acquisitions.
+"""
+
+import json
+import logging
+import os
+import shutil
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# The study YAML's top-level ``backup:`` block, with its defaults.
+BACKUP_DEFAULTS: dict[str, Any] = {"enabled": False, "destination": "", "include_dicoms": True}
+
+# Never backed up: simulator incoming copies and other per-run scratch.
+_ALWAYS_EXCLUDED = frozenset({"tmp"})
+# Raw DICOM copies; backed up only with ``include_dicoms``.
+_DICOM_DIR = "collection"
+_PARTIAL_SUFFIX = ".pineuro-partial"
+MANIFEST_NAME = ".pineuro_backup.json"
+# Modification times are compared with this tolerance because FAT/exFAT drives
+# (common on external backup disks) store them at 2 s resolution.
+_MTIME_TOLERANCE = 2.0
+
+
+@dataclass
+class BackupResult:
+    """Outcome of one :func:`mirror_session` pass."""
+
+    destination: Path
+    copied: int = 0
+    skipped: int = 0  # already up to date at the destination
+    bytes_copied: int = 0
+    errors: list[str] = field(default_factory=list)
+    stopped: bool = False  # interrupted via stop_event before finishing
+
+    @property
+    def complete(self) -> bool:
+        return not self.errors and not self.stopped
+
+
+def backup_destination(session_dir: str | Path, destination: str | Path) -> Path:
+    """Where *session_dir* (``<root>/<participant>/<session>``) is mirrored to."""
+    session_dir = Path(session_dir)
+    return Path(destination) / session_dir.parent.name / session_dir.name
+
+
+def validate_backup_config(backup: dict[str, Any], data_root: str | Path) -> str | None:
+    """Return an error message for an unusable ``backup:`` study block, or None."""
+    if not backup.get("enabled"):
+        return None
+    destination = str(backup.get("destination") or "").strip()
+    if not destination:
+        return "Backup is enabled but no backup folder is set."
+    if data_root and _same_path(destination, data_root):
+        return "The backup folder cannot be the data directory itself."
+    return None
+
+
+def read_manifest(session_dir: str | Path, destination: str | Path) -> dict[str, Any] | None:
+    """The record of the last backup pass of *session_dir*, or None if there is none."""
+    path = backup_destination(session_dir, destination) / MANIFEST_NAME
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def mirror_session(
+    session_dir: str | Path,
+    destination: str | Path,
+    *,
+    include_dicoms: bool = True,
+    stop_event: Any = None,
+) -> BackupResult:
+    """Copy new and changed files from *session_dir* to its backup location.
+
+    Parameters
+    ----------
+    session_dir
+        The participant-session folder, ``<data root>/<participant>/<session>``.
+    destination
+        Backup folder; must already exist. The session is mirrored to
+        ``<destination>/<participant>/<session>``.
+    include_dicoms
+        Also copy the raw DICOM copies in ``collection/``.
+    stop_event
+        Anything with ``is_set()``; checked between files, so a pass can be
+        interrupted (e.g. when an acquisition starts) and resumed later.
+    """
+    src_root = Path(session_dir)
+    dst_root = backup_destination(src_root, destination)
+    result = BackupResult(destination=dst_root)
+
+    if not Path(destination).is_dir():
+        result.errors.append(f"Backup folder {destination} is not available (is the drive connected?)")
+        return result
+    if _same_path(dst_root, src_root) or _is_within(dst_root, src_root):
+        result.errors.append(f"Backup location {dst_root} is inside the session folder; nothing was copied")
+        return result
+
+    excluded = set(_ALWAYS_EXCLUDED)
+    if not include_dicoms:
+        excluded.add(_DICOM_DIR)
+
+    for src in _iter_files(src_root, excluded):
+        if stop_event is not None and stop_event.is_set():
+            result.stopped = True
+            break
+        rel = src.relative_to(src_root)
+        dst = dst_root / rel
+        try:
+            src_stat = src.stat()
+            if _up_to_date(src_stat, dst):
+                result.skipped += 1
+                continue
+            dst.parent.mkdir(parents=True, exist_ok=True)
+            partial = dst.with_name(dst.name + _PARTIAL_SUFFIX)
+            shutil.copy2(src, partial)
+            os.replace(partial, dst)
+        except OSError as exc:
+            result.errors.append(f"{rel}: {exc}")
+            continue
+        result.copied += 1
+        result.bytes_copied += src_stat.st_size
+
+    _write_manifest(src_root, result)
+    return result
+
+
+def _iter_files(root: Path, excluded_top_level: set[str]) -> Iterator[Path]:
+    """Regular files under *root* (symlinks skipped), minus excluded top-level folders."""
+    stack: list[tuple[Path, bool]] = [(root, True)]
+    while stack:
+        current, is_top = stack.pop()
+        try:
+            with os.scandir(current) as entries:
+                for entry in entries:
+                    try:
+                        if entry.is_dir(follow_symlinks=False):
+                            if not (is_top and entry.name in excluded_top_level):
+                                stack.append((Path(entry.path), False))
+                        elif entry.is_file(follow_symlinks=False) and not entry.name.endswith(_PARTIAL_SUFFIX):
+                            yield Path(entry.path)
+                    except OSError:
+                        continue
+        except OSError as exc:
+            logger.warning(f"Backup: cannot read {current}: {exc}")
+
+
+def _up_to_date(src_stat: os.stat_result, dst: Path) -> bool:
+    try:
+        dst_stat = dst.stat()
+    except OSError:
+        return False
+    return dst_stat.st_size == src_stat.st_size and abs(dst_stat.st_mtime - src_stat.st_mtime) <= _MTIME_TOLERANCE
+
+
+def _write_manifest(src_root: Path, result: BackupResult) -> None:
+    record = {
+        "source": str(src_root),
+        "finished": datetime.now().isoformat(timespec="seconds"),
+        "complete": result.complete,
+        "copied": result.copied,
+        "skipped": result.skipped,
+        "bytes_copied": result.bytes_copied,
+        "errors": len(result.errors),
+    }
+    path = result.destination / MANIFEST_NAME
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        partial = path.with_name(path.name + _PARTIAL_SUFFIX)
+        partial.write_text(json.dumps(record, indent=2), encoding="utf-8")
+        os.replace(partial, path)
+    except OSError as exc:
+        result.errors.append(f"{MANIFEST_NAME}: {exc}")
+
+
+def _same_path(a: str | Path, b: str | Path) -> bool:
+    try:
+        return Path(a).resolve() == Path(b).resolve()
+    except OSError:
+        return False
+
+
+def _is_within(path: Path, parent: Path) -> bool:
+    try:
+        return path.resolve().is_relative_to(parent.resolve())
+    except (OSError, ValueError):
+        return False