w2t-bkin 0.0.6__py3-none-any.whl

w2t_bkin/__init__.py

@@ -0,0 +1,85 @@
+"""W2T Body Kinematics Pipeline (w2t_bkin).
+
+A modular, reproducible Python pipeline for processing multi-camera rodent
+behavior recordings with synchronization, pose estimation, facial metrics,
+and behavioral events into standardized NWB datasets.
+
+Architecture: NWB-First
+------------------------
+This pipeline uses NWB (Neurodata Without Borders) as its foundational data layer.
+All processing modules produce NWB-native data structures directly, eliminating
+intermediate models and conversion layers.
+
+Modules:
+--------
+- utils: Shared utilities (hashing, paths, JSON I/O, video analysis, frame counting)
+- config: Configuration and session file loading
+- session: NWB file creation from session metadata
+- sync: Timebase providers and alignment
+- behavior: Behavioral task recording (ndx-structured-behavior)
+- bpod: Bpod .mat file parsing
+- ttl: TTL hardware signals loading and EventsTable extraction (ndx-events)
+- transcode: Video transcoding to mezzanine format
+- pose: Pose estimation import and harmonization (DLC/SLEAP with ndx-pose)
+- facemap: Facial metrics computation and alignment
+- pipeline: High-level orchestration (NWB-first workflow)
+
+Pipeline Phases:
+----------------
+Phase 0 (Foundation): Load config, create NWBFile from session.toml
+Phase 1 (Discovery): Discover files, verify, add ImageSeries to NWBFile
+Phase 2 (Behavior): Parse Bpod, add TaskRecording/TrialsTable to NWBFile
+Phase 3 (Sync): Compute alignment stats, select timebase
+Phase 4 (Optionals): DLC inference, pose, facemap
+Phase 5 (Output): Write NWBFile to disk, validate
+
+Quick Start:
+-----------
+>>> from w2t_bkin.pipeline import run_session
+>>>
+>>> # Run complete pipeline (NWB-first)
+>>> result = run_session(
+...     config_path="config.toml",
+...     session_id="Session-000001"
+... )
+>>>
+>>> # Access NWBFile
+>>> nwbfile = result['nwbfile']
+>>> print(f"Identifier: {nwbfile.identifier}")
+>>> print(f"Acquisition: {list(nwbfile.acquisition.keys())}")
+>>>
+>>> # NWB file written to disk
+>>> print(f"Output: {result['nwb_path']}")
+
+Requirements:
+-------------
+- Python 3.10+
+- pynwb~=3.1.0, hdmf~=4.1.0
+- ndx-pose~=0.2.0, ndx-structured-behavior~=0.1.0
+- scipy, numpy, pydantic
+
+License:
+--------
+Apache-2.0
+
+Documentation:
+--------------
+See docs/ for detailed module documentation and design principles.
+"""
+
+# Import main modules for convenient access
+from . import behavior, bpod, config, facemap, pipeline, pose, session, sync, transcode, ttl, utils
+
+__all__ = [
+    "behavior",
+    "bpod",
+    "config",
+    "facemap",
+    "pipeline",
+    "pose",
+    "session",
+    "sync",
+    "transcode",
+    "ttl",
+    "utils",
+]

w2t_bkin/behavior/__init__.py

@@ -0,0 +1,115 @@
+"""Behavior module for Bpod behavioral data with ndx-structured-behavior.
+
+This module provides transformation functions to convert Bpod .mat files
+into ndx-structured-behavior NWB classes (StatesTable, EventsTable, ActionsTable,
+TrialsTable, TaskRecording).
+
+Following the NWB-first architecture established in Phase 1 (pose module),
+this module produces community-standard ndx-structured-behavior objects directly,
+eliminating intermediate custom models and conversion layers.
+
+Public API:
+    Core transformation functions:
+        - extract_state_types: Parse unique state names → StateTypesTable
+        - extract_states: Convert trial states → StatesTable
+        - extract_event_types: Parse unique event names → EventTypesTable
+        - extract_events: Convert hardware events → EventsTable
+        - extract_action_types: Identify action states → ActionTypesTable
+        - extract_actions: Convert action states → ActionsTable
+        - build_trials_table: Combine states/events/actions → TrialsTable
+        - extract_trials_table: Complete extraction (convenience) → TrialsTable
+        - build_task_recording: Package tables → TaskRecording
+        - extract_task_recording: Complete extraction (convenience) → TaskRecording
+        - extract_task_arguments: Extract task parameters → TaskArgumentsTable
+        - build_task: Assemble Task container with type tables
+        - extract_task: Complete extraction (convenience) → Task
+
+    Re-exported ndx-structured-behavior types:
+        - StateTypesTable, StatesTable
+        - EventTypesTable, EventsTable
+        - ActionTypesTable, ActionsTable
+        - TrialsTable
+        - TaskRecording
+        - Task, TaskArgumentsTable
+
+Example:
+    >>> from pathlib import Path
+    >>> from w2t_bkin.bpod.code import parse_bpod
+    >>> from w2t_bkin.behavior import (
+    ...     extract_state_types, extract_states,
+    ...     extract_event_types, extract_events,
+    ...     extract_action_types, extract_actions,
+    ...     build_trials_table, build_task_recording
+    ... )
+    >>>
+    >>> # Parse Bpod data
+    >>> bpod_data = parse_bpod(Path("data"), "Bpod/*.mat", "name_asc")
+    >>>
+    >>> # Build type tables
+    >>> state_types = extract_state_types(bpod_data)
+    >>> event_types = extract_event_types(bpod_data)
+    >>> action_types = extract_action_types(bpod_data)
+    >>>
+    >>> # Build data tables (returns tuples with row indices)
+    >>> states, state_indices = extract_states(bpod_data, state_types)
+    >>> events, event_indices = extract_events(bpod_data, event_types)
+    >>> actions, action_indices = extract_actions(bpod_data, action_types)
+    >>>
+    >>> # Build trials and recording (pass indices for trial references)
+    >>> trials = build_trials_table(bpod_data, states, events, actions,
+    ...                             state_indices, event_indices, action_indices)
+    >>> task_recording = build_task_recording(states, events, actions)
+    >>>
+    >>> # Build Task container (optional but recommended)
+    >>> task_arguments = extract_task_arguments(bpod_data)  # optional
+    >>> task = build_task(state_types, event_types, action_types,
+    ...                   task_arguments=task_arguments)
+"""
+
+from ndx_structured_behavior import ActionsTable, ActionTypesTable, EventsTable, EventTypesTable, StatesTable, StateTypesTable, Task, TaskArgumentsTable, TaskRecording, TrialsTable
+
+from .core import (
+    build_task,
+    build_task_recording,
+    build_trials_table,
+    extract_action_types,
+    extract_actions,
+    extract_behavioral_data,
+    extract_event_types,
+    extract_events,
+    extract_state_types,
+    extract_states,
+    extract_task,
+    extract_task_arguments,
+    extract_task_recording,
+    extract_trials_table,
+)
+
+__all__ = [
+    # Core transformation functions
+    "extract_state_types",
+    "extract_states",
+    "extract_event_types",
+    "extract_events",
+    "extract_action_types",
+    "extract_actions",
+    "build_trials_table",
+    "extract_trials_table",
+    "build_task_recording",
+    "extract_task_recording",
+    "extract_task_arguments",
+    "build_task",
+    "extract_task",
+    "extract_behavioral_data",
+    # Re-exported ndx-structured-behavior types
+    "StateTypesTable",
+    "StatesTable",
+    "EventTypesTable",
+    "EventsTable",
+    "ActionTypesTable",
+    "ActionsTable",
+    "TrialsTable",
+    "TaskRecording",
+    "Task",
+    "TaskArgumentsTable",
+]