w2t-bkin 0.0.6__py3-none-any.whl

w2t_bkin/exceptions.py

@@ -0,0 +1,426 @@
+"""Structured exception hierarchy for W2T-BKIN pipeline.
+
+All exceptions inherit from W2TError and include structured metadata:
+- error_code: Stable identifier for programmatic handling
+- message: Human-readable description
+- context: Machine-readable error details (dict)
+- hint: Actionable resolution suggestion
+- stage: Pipeline stage where error occurred
+
+Exception Hierarchy:
+-------------------
+W2TError (base)
+├── ConfigError
+│   ├── ConfigMissingKeyError
+│   ├── ConfigExtraKeyError
+│   └── ConfigValidationError
+├── SessionError
+│   ├── SessionMissingKeyError
+│   ├── SessionExtraKeyError
+│   └── SessionValidationError
+├── IngestError
+│   ├── FileNotFoundError
+│   ├── CameraUnverifiableError
+│   └── VerificationError
+│       └── MismatchExceedsToleranceError
+├── SyncError
+│   ├── TimebaseProviderError
+│   ├── JitterExceedsBudgetError
+│   └── AlignmentError
+├── EventsError
+│   ├── BpodParseError
+│   └── BpodValidationError
+├── TranscodeError
+├── PoseError
+├── FacemapError
+├── NWBError
+│   └── ExternalToolError
+├── ValidationError
+└── QCError
+
+Example:
+    >>> from w2t_bkin.exceptions import MismatchExceedsToleranceError
+    >>> try:
+    ...     raise MismatchExceedsToleranceError(
+    ...         camera_id="cam0",
+    ...         frame_count=8580,
+    ...         ttl_count=8578,
+    ...         mismatch=2,
+    ...         tolerance=1
+    ...     )
+    ... except W2TError as e:
+    ...     print(e.error_code)  # MISMATCH_EXCEEDS_TOLERANCE
+    ...     print(e.context)     # {'camera_id': 'cam0', ...}
+    ...     print(e.hint)        # "Check TTL files..."
+"""
+
+from typing import Any, Dict, Optional
+
+
+class W2TError(Exception):
+    """Base exception for W2T-BKIN pipeline errors.
+
+    All exceptions inherit from this base and include structured metadata
+    for debugging, logging, and programmatic error handling.
+
+    Attributes:
+        error_code: Stable identifier (e.g., "CONFIG_MISSING_KEY")
+        message: Human-readable description
+        context: Machine-readable details as dict
+        hint: Actionable resolution suggestion
+        stage: Pipeline stage (config, ingest, sync, etc.)
+    """
+
+    def __init__(
+        self,
+        error_code: str,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        hint: Optional[str] = None,
+        stage: Optional[str] = None,
+    ):
+        self.error_code = error_code
+        self.message = message
+        self.context = context or {}
+        self.hint = hint
+        self.stage = stage
+        super().__init__(self._format_message())
+
+    def _format_message(self) -> str:
+        """Format error with all structured fields."""
+        parts = [f"[{self.error_code}]", self.message]
+        if self.stage:
+            parts.insert(1, f"(stage: {self.stage})")
+        if self.context:
+            parts.append(f"Context: {self.context}")
+        if self.hint:
+            parts.append(f"Hint: {self.hint}")
+        return " ".join(parts)
+
+
+# =============================================================================
+# Configuration Errors
+# =============================================================================
+
+
+class ConfigError(W2TError):
+    """Base for configuration errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="CONFIG_ERROR", message=message, context=context, hint=hint, stage="config")
+
+
+class ConfigMissingKeyError(ConfigError):
+    """Required configuration key not found."""
+
+    def __init__(self, key: str, file_path: str):
+        super().__init__(
+            message=f"Required configuration key missing: {key}",
+            context={"key": key, "file_path": file_path},
+            hint=f"Add '{key}' to {file_path}",
+        )
+        self.error_code = "CONFIG_MISSING_KEY"
+
+
+class ConfigExtraKeyError(ConfigError):
+    """Unknown configuration key detected."""
+
+    def __init__(self, key: str, file_path: str, valid_keys: list):
+        super().__init__(
+            message=f"Unknown configuration key: {key}",
+            context={"key": key, "file_path": file_path, "valid_keys": valid_keys},
+            hint=f"Remove '{key}' or check for typos. Valid keys: {', '.join(valid_keys)}",
+        )
+        self.error_code = "CONFIG_EXTRA_KEY"
+
+
+class ConfigValidationError(ConfigError):
+    """Configuration value failed validation."""
+
+    def __init__(self, key: str, value: Any, expected: str):
+        super().__init__(
+            message=f"Invalid value for '{key}': {value}",
+            context={"key": key, "value": value, "expected": expected},
+            hint=f"Expected {expected}",
+        )
+        self.error_code = "CONFIG_VALIDATION_ERROR"
+
+
+# =============================================================================
+# Session Errors
+# =============================================================================
+
+
+class SessionError(W2TError):
+    """Base for session configuration errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="SESSION_ERROR", message=message, context=context, hint=hint, stage="session")
+
+
+class SessionMissingKeyError(SessionError):
+    """Required session key not found."""
+
+    def __init__(self, key: str, file_path: str):
+        super().__init__(
+            message=f"Required session key missing: {key}",
+            context={"key": key, "file_path": file_path},
+            hint=f"Add '{key}' to {file_path}",
+        )
+        self.error_code = "SESSION_MISSING_KEY"
+
+
+class SessionExtraKeyError(SessionError):
+    """Unknown session key detected."""
+
+    def __init__(self, key: str, file_path: str, valid_keys: list):
+        super().__init__(
+            message=f"Unknown session key: {key}",
+            context={"key": key, "file_path": file_path, "valid_keys": valid_keys},
+            hint=f"Remove '{key}' or check for typos. Valid keys: {', '.join(valid_keys)}",
+        )
+        self.error_code = "SESSION_EXTRA_KEY"
+
+
+class SessionValidationError(SessionError):
+    """Session value failed validation."""
+
+    def __init__(self, key: str, value: Any, expected: str):
+        super().__init__(
+            message=f"Invalid value for '{key}': {value}",
+            context={"key": key, "value": value, "expected": expected},
+            hint=f"Expected {expected}",
+        )
+        self.error_code = "SESSION_VALIDATION_ERROR"
+
+
+# =============================================================================
+# Ingest Errors
+# =============================================================================
+
+
+class IngestError(W2TError):
+    """Base for file discovery and ingestion errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="INGEST_ERROR", message=message, context=context, hint=hint, stage="ingest")
+
+
+class FileNotFoundError(IngestError):
+    """Required file not found during discovery."""
+
+    def __init__(self, pattern: str, search_path: str):
+        super().__init__(
+            message=f"No files matching pattern: {pattern}",
+            context={"pattern": pattern, "search_path": search_path},
+            hint=f"Check that files exist in {search_path} and pattern is correct",
+        )
+        self.error_code = "FILE_NOT_FOUND"
+
+
+class CameraUnverifiableError(IngestError):
+    """Camera references unknown TTL channel."""
+
+    def __init__(self, camera_id: str, ttl_id: str):
+        super().__init__(
+            message=f"Camera '{camera_id}' references unknown TTL '{ttl_id}'",
+            context={"camera_id": camera_id, "ttl_id": ttl_id},
+            hint=f"Add TTL entry for '{ttl_id}' to session.toml or correct camera.ttl_id",
+        )
+        self.error_code = "CAMERA_UNVERIFIABLE"
+
+
+class VerificationError(IngestError):
+    """Base for frame/TTL verification errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(message=message, context=context, hint=hint)
+        self.error_code = "VERIFICATION_ERROR"
+
+
+class MismatchExceedsToleranceError(VerificationError):
+    """Frame count vs TTL count mismatch exceeds tolerance."""
+
+    def __init__(self, camera_id: str, frame_count: int, ttl_count: int, mismatch: int, tolerance: int):
+        super().__init__(
+            message=f"Camera '{camera_id}' mismatch ({mismatch} frames) exceeds tolerance ({tolerance})",
+            context={
+                "camera_id": camera_id,
+                "frame_count": frame_count,
+                "ttl_count": ttl_count,
+                "mismatch": mismatch,
+                "tolerance": tolerance,
+            },
+            hint="Check TTL files for missing pulses or video corruption. " "Increase verification.mismatch_tolerance_frames if acceptable.",
+        )
+        self.error_code = "MISMATCH_EXCEEDS_TOLERANCE"
+
+
+# =============================================================================
+# Sync Errors
+# =============================================================================
+
+
+class SyncError(W2TError):
+    """Base for timebase synchronization errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="SYNC_ERROR", message=message, context=context, hint=hint, stage="sync")
+
+
+class TimebaseProviderError(SyncError):
+    """Timebase provider initialization failed."""
+
+    def __init__(self, source: str, reason: str):
+        super().__init__(
+            message=f"Failed to initialize timebase provider '{source}': {reason}",
+            context={"source": source, "reason": reason},
+            hint="Check that timebase source files exist and are readable",
+        )
+        self.error_code = "TIMEBASE_PROVIDER_ERROR"
+
+
+class JitterExceedsBudgetError(SyncError):
+    """Alignment jitter exceeds configured budget."""
+
+    def __init__(self, max_jitter_s: float, p95_jitter_s: float, budget_s: float):
+        super().__init__(
+            message=f"Alignment jitter (max={max_jitter_s:.6f}s, p95={p95_jitter_s:.6f}s) exceeds budget ({budget_s}s)",
+            context={"max_jitter_s": max_jitter_s, "p95_jitter_s": p95_jitter_s, "budget_s": budget_s},
+            hint="Increase timebase.jitter_budget_s or investigate timing quality. " "Check TTL pulse spacing and video framerate stability.",
+        )
+        self.error_code = "JITTER_EXCEEDS_BUDGET"
+
+
+class AlignmentError(SyncError):
+    """Sample alignment failed."""
+
+    def __init__(self, reason: str, context: Optional[Dict[str, Any]] = None):
+        super().__init__(message=f"Sample alignment failed: {reason}", context=context, hint="Check timebase configuration and data quality")
+        self.error_code = "ALIGNMENT_ERROR"
+
+
+# =============================================================================
+# Events Errors
+# =============================================================================
+
+
+class EventsError(W2TError):
+    """Base for behavioral events parsing errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="EVENTS_ERROR", message=message, context=context, hint=hint, stage="events")
+
+
+class BpodParseError(EventsError):
+    """Bpod .mat file parsing failed."""
+
+    def __init__(self, reason: str, file_path: Optional[str] = None):
+        context = {"reason": reason}
+        if file_path:
+            context["file_path"] = file_path
+        super().__init__(
+            message=f"Failed to parse Bpod file: {reason}",
+            context=context,
+            hint="Check that file is valid Bpod .mat format and not corrupted",
+        )
+        self.error_code = "BPOD_PARSE_ERROR"
+
+
+class BpodValidationError(EventsError):
+    """Bpod file or data validation failed."""
+
+    def __init__(self, reason: str, file_path: Optional[str] = None):
+        context = {"reason": reason}
+        if file_path:
+            context["file_path"] = file_path
+        super().__init__(
+            message=f"Bpod validation failed: {reason}",
+            context=context,
+            hint="Check file path, size, extension, and data structure",
+        )
+        self.error_code = "BPOD_VALIDATION_ERROR"
+
+
+# =============================================================================
+# Transcode Errors
+# =============================================================================
+
+
+class TranscodeError(W2TError):
+    """Base for video transcoding errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="TRANSCODE_ERROR", message=message, context=context, hint=hint, stage="transcode")
+
+
+# =============================================================================
+# Pose Errors
+# =============================================================================
+
+
+class PoseError(W2TError):
+    """Base for pose estimation errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="POSE_ERROR", message=message, context=context, hint=hint, stage="pose")
+
+
+# =============================================================================
+# Facemap Errors
+# =============================================================================
+
+
+class FacemapError(W2TError):
+    """Base for facemap processing errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="FACEMAP_ERROR", message=message, context=context, hint=hint, stage="facemap")
+
+
+# =============================================================================
+# NWB Errors
+# =============================================================================
+
+
+class NWBError(W2TError):
+    """Base for NWB assembly errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="NWB_ERROR", message=message, context=context, hint=hint, stage="nwb")
+
+
+class ExternalToolError(NWBError):
+    """External tool execution failed."""
+
+    def __init__(self, tool: str, command: str, return_code: int, stderr: str):
+        super().__init__(
+            message=f"External tool '{tool}' failed with code {return_code}",
+            context={"tool": tool, "command": command, "return_code": return_code, "stderr": stderr},
+            hint=f"Check that {tool} is installed and accessible in PATH",
+        )
+        self.error_code = "EXTERNAL_TOOL_ERROR"
+
+
+# =============================================================================
+# Validation Errors
+# =============================================================================
+
+
+class ValidationError(W2TError):
+    """Base for NWB validation errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="VALIDATION_ERROR", message=message, context=context, hint=hint, stage="validation")
+
+
+# =============================================================================
+# QC Errors
+# =============================================================================
+
+
+class QCError(W2TError):
+    """Base for QC report generation errors."""
+
+    def __init__(self, message: str, context: Optional[Dict[str, Any]] = None, hint: Optional[str] = None):
+        super().__init__(error_code="QC_ERROR", message=message, context=context, hint=hint, stage="qc")

w2t_bkin/facemap/__init__.py

@@ -0,0 +1,42 @@
+"""Facemap motion energy computation and alignment module (Phase 3 - Optional).
+
+Provides Facemap ROI handling, signal import/compute, and alignment to reference timebase
+for facial motion analysis.
+
+Public API:
+-----------
+All public functions and models are re-exported at the package level:
+
+    from w2t_bkin.facemap import (
+        FacemapBundle,
+        FacemapROI,
+        FacemapSignal,
+        define_rois,
+        import_facemap_output,
+        compute_facemap_signals,
+        align_facemap_to_timebase,
+    )
+
+See core and models modules for detailed documentation.
+"""
+
+# Re-export core functions
+from .core import FacemapError, align_facemap_to_timebase, compute_facemap_signals, define_rois, import_facemap_output, validate_facemap_sampling_rate
+
+# Re-export models
+from .models import FacemapBundle, FacemapROI, FacemapSignal
+
+__all__ = [
+    # Models
+    "FacemapBundle",
+    "FacemapROI",
+    "FacemapSignal",
+    # Exceptions
+    "FacemapError",
+    # Core functions
+    "define_rois",
+    "import_facemap_output",
+    "compute_facemap_signals",
+    "align_facemap_to_timebase",
+    "validate_facemap_sampling_rate",
+]