motionbids 0.1.0__py3-none-any.whl

motionbids/__init__.py

@@ -0,0 +1,92 @@
+"""
+motionbids: Lightweight converter for motion data to BIDS format.
+
+This package provides tools to define, validate, and export BIDS-compliant
+motion capture data.
+
+Example usage:
+    >>> from motionbids import MotionData, validate_motion_data, export_bids_motion
+    >>> import numpy as np
+    >>> 
+    >>> # Create motion data object
+    >>> motion = MotionData(
+    ...     subject_id="01",
+    ...     task_name="rest",
+    ...     sampling_frequency=100,
+    ...     tracked_points_count=10,
+    ...     manufacturer="Vicon",
+    ...     data=np.random.randn(1000, 10),
+    ...     columns=[f"marker{i}" for i in range(10)],
+    ...     units=["mm"] * 10
+    ... )
+    >>> 
+    >>> # Validate
+    >>> validate_motion_data(motion)
+    True
+    >>> 
+    >>> # Export to BIDS format
+    >>> files = export_bids_motion(motion, out_dir="bids_out/")
+    >>> print(files)
+    {'json': ..., 'tsv': ..., 'channels': ...}
+"""
+
+__version__ = "0.1.0"
+__author__ = "Julius Welzel"
+__email__ = "julius.welzel@gmail.com"
+
+# Import main classes and functions
+# Using dynamic schema-based MotionData class
+from .datamodel_dynamic import MotionData
+from .channel import Channel
+from .validator import (
+    validate_motion_data,
+    validate_bids_compliance,
+    ValidationError,
+    ValidationWarning,
+    check_required_fields,
+    check_recommended_fields,
+)
+from .exporter import (
+    export_bids_motion,
+    export_json_metadata,
+    export_tsv_data,
+    export_channels_tsv,
+    export_scans_tsv,
+    create_bids_directory_structure,
+    export_dataset_description,
+)
+
+# Optional: Schema utilities (users typically won't need these directly)
+from . import schema_utils
+
+# Define public API
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    "__email__",
+    
+    # Core data model
+    "MotionData",
+    "Channel",
+    
+    # Validation
+    "validate_motion_data",
+    "validate_bids_compliance",
+    "ValidationError",
+    "ValidationWarning",
+    "check_required_fields",
+    "check_recommended_fields",
+    
+    # Export functions
+    "export_bids_motion",
+    "export_json_metadata",
+    "export_tsv_data",
+    "export_channels_tsv",
+    "export_scans_tsv",
+    "create_bids_directory_structure",
+    "export_dataset_description",
+    
+    # Schema utilities module (advanced usage)
+    "schema_utils",
+]

motionbids/bids_constants.py

@@ -0,0 +1,46 @@
+"""
+BIDS schema constants for motion data validation.
+
+This module defines the allowed values for channel components and types
+according to the BIDS specification.
+"""
+
+# Allowed channel components (from BIDS schema)
+ALLOWED_CHANNEL_COMPONENTS = {
+    'x',       # Position along X-axis, rotation about X-axis, or magnetic field strength along X-axis
+    'y',       # Position along Y-axis, rotation about Y-axis, or magnetic field strength along Y-axis
+    'z',       # Position along Z-axis, rotation about Z-axis, or magnetic field strength along Z-axis
+    'quat_x',  # Quaternion component associated with X-axis
+    'quat_y',  # Quaternion component associated with Y-axis
+    'quat_z',  # Quaternion component associated with Z-axis
+    'quat_w',  # Non-axial quaternion component
+    'n/a',     # Channels with no corresponding spatial axis
+}
+
+# Allowed channel types (from BIDS schema - uppercase required)
+ALLOWED_CHANNEL_TYPES = {
+    'POS',       # Position in space
+    'ORNT',      # Orientation
+    'VEL',       # Velocity
+    'ACCEL',     # Accelerometer
+    'GYRO',      # Gyrometer
+    'ANGACCEL',  # Angular acceleration
+    'MAGN',      # Magnetic field strength
+    'JNTANG',    # Joint angle between bodyparts
+    'LATENCY',   # Sample latency from recording onset
+    'MISC',      # Miscellaneous channels
+}
+
+# Component requirements for each channel type
+CHANNEL_TYPE_COMPONENT_REQUIREMENTS = {
+    'POS': {'x', 'y', 'z'},                                           # Requires spatial axes
+    'ORNT': {'x', 'y', 'z', 'quat_x', 'quat_y', 'quat_z', 'quat_w'}, # Requires axes or quaternions
+    'VEL': {'x', 'y', 'z'},                                           # Requires spatial axes
+    'ACCEL': {'x', 'y', 'z'},                                         # Requires spatial axes
+    'GYRO': {'x', 'y', 'z'},                                          # Requires spatial axes
+    'ANGACCEL': {'x', 'y', 'z'},                                      # Requires spatial axes
+    'MAGN': {'x', 'y', 'z'},                                          # Requires spatial axes
+    'JNTANG': ALLOWED_CHANNEL_COMPONENTS,                             # Can use any component
+    'LATENCY': ALLOWED_CHANNEL_COMPONENTS,                            # Can use any component
+    'MISC': ALLOWED_CHANNEL_COMPONENTS,                               # Can use any component
+}

motionbids/channel.py

@@ -0,0 +1,135 @@
+"""
+Channel model for BIDS-compliant motion data.
+
+This module defines the Channel dataclass that represents a single channel
+in motion capture data, following the BIDS specification.
+"""
+from dataclasses import dataclass
+from typing import Optional
+from .bids_constants import (
+    ALLOWED_CHANNEL_COMPONENTS,
+    ALLOWED_CHANNEL_TYPES,
+    CHANNEL_TYPE_COMPONENT_REQUIREMENTS
+)
+
+
+@dataclass
+class Channel:
+    """
+    Dataclass representing a single channel in BIDS motion data.
+    
+    This follows the BIDS specification for channels.tsv files:
+    https://bids-specification.readthedocs.io/en/stable/modality-specific-files/motion.html#channels-description-_channelstsv
+    
+    Required Fields (MUST appear in this order in channels.tsv):
+        name: Label of the channel (e.g., "marker0_x", "imu1_acc_x")
+        component: Spatial axis or quaternion component
+                   Must be one of: x, y, z, quat_x, quat_y, quat_z, quat_w, n/a
+        type: Channel type (MUST be uppercase)
+              Must be one of: POS, ORNT, VEL, ACCEL, GYRO, ANGACCEL, MAGN, JNTANG, LATENCY, MISC
+        tracked_point: Label of the tracked point (e.g., "LeftFoot", "RightWrist")
+        units: Physical or virtual unit (e.g., "m", "rad", "m/s^2", "deg")
+    
+    Recommended Fields:
+        placement: Placement on body (e.g., "torso", "left arm")
+        reference_frame: Reference frame specification (links to channels.json)
+        description: Brief description or other info
+        sampling_frequency: Sampling rate in Hz (if different from main rate)
+        status: Data quality - "good", "bad", or "n/a"
+        status_description: Explanation if status is "bad"
+    
+    Example:
+        >>> channel = Channel(
+        ...     channel_name="marker0_x",
+        ...     channel_component="x",
+        ...     channel_type="POS",
+        ...     channel_tracked_point="marker0",
+        ...     channel_units="mm"
+        ... )
+    
+    Component-Type Compatibility:
+        - Quaternion components (quat_*) can only be used with ORNT type
+        - Spatial components (x, y, z) can be used with POS, VEL, ACCEL, GYRO, MAGN, ANGACCEL
+        - n/a can be used with JNTANG, LATENCY, MISC
+    """
+    
+    # Required fields (MUST be in this order)
+    channel_name: str
+    channel_component: str
+    channel_type: str
+    channel_tracked_point: str
+    channel_units: str
+    
+    # Recommended fields
+    channel_placement: Optional[str] = None
+    channel_reference_frame: Optional[str] = None
+    channel_description: Optional[str] = None
+    channel_sampling_frequency: Optional[float] = None
+    channel_status: Optional[str] = None
+    channel_status_description: Optional[str] = None
+    
+    def __post_init__(self):
+        """Validate channel fields against BIDS schema."""
+        # Validate component
+        if self.channel_component not in ALLOWED_CHANNEL_COMPONENTS:
+            raise ValueError(
+                f"Invalid component '{self.channel_component}' for channel '{self.channel_name}'. "
+                f"Must be one of: {sorted(ALLOWED_CHANNEL_COMPONENTS)}"
+            )
+        
+        # Validate type (must be uppercase)
+        if self.channel_type not in ALLOWED_CHANNEL_TYPES:
+            raise ValueError(
+                f"Invalid type '{self.channel_type}' for channel '{self.channel_name}'. "
+                f"Must be one of (uppercase required): {sorted(ALLOWED_CHANNEL_TYPES)}"
+            )
+        
+        # Validate component-type compatibility
+        if self.channel_type in CHANNEL_TYPE_COMPONENT_REQUIREMENTS:
+            allowed_components = CHANNEL_TYPE_COMPONENT_REQUIREMENTS[self.channel_type]
+            if self.channel_component not in allowed_components:
+                raise ValueError(
+                    f"Component '{self.channel_component}' is not allowed for type '{self.channel_type}' "
+                    f"in channel '{self.channel_name}'. "
+                    f"Allowed components for {self.channel_type}: {sorted(allowed_components)}"
+                )
+        
+        # Validate status if provided
+        if self.channel_status is not None and self.channel_status not in ["good", "bad", "n/a"]:
+            raise ValueError(
+                f"Invalid status '{self.channel_status}' for channel '{self.channel_name}'. "
+                f"Must be one of: 'good', 'bad', 'n/a'"
+            )
+    
+    def to_tsv_row(self) -> dict:
+        """
+        Convert channel to dictionary for TSV row export.
+        
+        Returns only non-None fields in the correct BIDS order.
+        
+        Returns:
+            Dictionary with channel data for TSV export
+        """
+        row = {
+            'name': self.channel_name,
+            'component': self.channel_component,
+            'type': self.channel_type,
+            'tracked_point': self.channel_tracked_point,
+            'units': self.channel_units,
+        }
+        
+        # Add optional fields if present
+        if self.channel_placement is not None:
+            row['placement'] = self.channel_placement
+        if self.channel_reference_frame is not None:
+            row['reference_frame'] = self.channel_reference_frame
+        if self.channel_description is not None:
+            row['description'] = self.channel_description
+        if self.channel_sampling_frequency is not None:
+            row['sampling_frequency'] = self.channel_sampling_frequency
+        if self.channel_status is not None:
+            row['status'] = self.channel_status
+        if self.channel_status_description is not None:
+            row['status_description'] = self.channel_status_description
+        
+        return row

motionbids/datamodel.py

@@ -0,0 +1,230 @@
+"""
+Data model for BIDS-compliant motion data.
+
+This module defines the MotionData dataclass that represents motion capture
+data with BIDS-compliant metadata fields.
+"""
+from dataclasses import dataclass, field
+from typing import Optional, List, Dict, Any
+import numpy as np
+from dataclasses_json import dataclass_json
+from .channel import Channel
+
+
+@dataclass_json
+@dataclass
+class MotionData:
+    """
+    Dataclass representing BIDS-compliant motion capture data.
+    
+    This class includes both required and optional metadata fields for motion data,
+    along with the actual motion time series data.
+    
+    **Data Format:**
+    - `data`: NumPy array where **rows = timepoints** and **columns = channels** (REQUIRED)
+    - `channels`: List of Channel objects defining channel metadata (REQUIRED)
+    
+    The `channels` list follows the BIDS specification for channels.tsv files.
+    Each Channel object contains: name, component, type, tracked_point, units (all required),
+    plus optional fields like placement, reference_frame, description, sampling_frequency, status.
+    
+    The number of Channel objects MUST match the number of columns in the data array.
+    Channel metadata is validated against BIDS schema during Channel construction.
+    
+    Required Fields (must be provided):
+        subject_id: Subject identifier (BIDS entity 'sub')
+        task_name: Name of the task (BIDS metadata 'TaskName')
+        sampling_frequency: Sampling frequency in Hz (BIDS metadata 'SamplingFrequency')
+        tracked_points_count: Number of tracked points (BIDS metadata 'TrackedPointsCount')
+        tracksys: Tracking system label (BIDS entity 'tracksys') - REQUIRED for filenames
+    
+    Recommended Fields (should be provided when available):
+        manufacturer: Manufacturer of the motion capture system
+        manufacturers_model_name: Model name of the motion capture system
+        software_versions: Software version used for acquisition
+        motion_channel_count: Total number of motion channels
+        recording_duration: Duration of the recording in seconds
+        recording_type: Type of recording (e.g., 'continuous')
+    
+    Optional Fields:
+        session_id: Session identifier (BIDS entity 'ses')
+        acquisition: Acquisition label (BIDS entity 'acq')
+        run: Run index (BIDS entity 'run')
+        acq_time: Acquisition time in ISO 8601 format with optional fractional seconds
+                  (e.g., '2023-06-15T14:30:00' or '2023-06-15T14:30:00.123456')
+                  Supports sub-millisecond precision. If provided, a scans.tsv file will be generated
+        additional_metadata: Dictionary for any additional custom metadata
+    
+    Example:
+        >>> import numpy as np
+        >>> from motionbids.channel import Channel
+        >>> data = np.random.randn(1000, 30)  # 1000 timepoints, 30 channels
+        >>> channels = [
+        ...     Channel(channel_name=f"marker{i//3}_{ax}", channel_component=ax, channel_type="POS",
+        ...             tracked_point=f"marker{i//3}", channel_units="mm")
+        ...     for i in range(30) for ax in ['x', 'y', 'z'] if i % 3 == ['x', 'y', 'z'].index(ax)
+        ... ]
+        >>> motion = MotionData(
+        ...     subject_id="01",
+        ...     task_name="walk",
+        ...     sampling_frequency=120.0,
+        ...     tracked_points_count=10,
+        ...     tracksys="optical",
+        ...     data=data,
+        ...     channels=channels
+        ... )
+    """
+    
+    # Required fields
+    subject_id: str
+    task_name: str
+    sampling_frequency: float
+    tracked_points_count: int
+    tracksys: str  # REQUIRED for BIDS motion data filenames
+    
+    # Recommended fields
+    manufacturer: Optional[str] = None
+    manufacturers_model_name: Optional[str] = None
+    software_versions: Optional[str] = None
+    motion_channel_count: Optional[int] = None
+    recording_duration: Optional[float] = None
+    recording_type: Optional[str] = "continuous"
+    
+    # Optional BIDS entities
+    session_id: Optional[str] = None
+    acquisition: Optional[str] = None
+    run: Optional[int] = None
+    acq_time: Optional[str] = None  # ISO 8601 with optional fractional seconds (e.g., '2023-06-15T14:30:00.123456')
+    
+    # Motion data (REQUIRED - have defaults to avoid field ordering issues, validated in __post_init__)
+    data: Optional[np.ndarray] = field(default=None, repr=False)
+    channels: Optional[List[Channel]] = None
+    
+    # Additional metadata
+    additional_metadata: Optional[Dict[str, Any]] = field(default_factory=dict)
+    
+    def __post_init__(self):
+        """Validate basic field types and constraints."""
+        if self.sampling_frequency <= 0:
+            raise ValueError("sampling_frequency must be positive")
+        
+        if self.tracked_points_count <= 0:
+            raise ValueError("tracked_points_count must be positive")
+        
+            if self.run is not None and self.run < 1:
+                raise ValueError("run must be >= 1")
+            
+            # Validate data and channels together - both required if either is provided
+            if self.data is not None or self.channels is not None:
+                if self.data is None:
+                    raise ValueError("data is required when channels are provided")
+                
+                if self.channels is None:
+                    raise ValueError("channels is required when data is provided")
+                
+                if not isinstance(self.data, np.ndarray):
+                    raise TypeError("data must be a numpy array")
+                
+                if self.data.ndim not in [1, 2]:
+                    raise ValueError("data must be 1D or 2D array")
+                
+                # Determine expected number of channels
+                if self.data.ndim == 1:
+                    expected_channels = 1
+                else:
+                    expected_channels = self.data.shape[1]
+                
+                # Validate channels list length matches data dimensions
+                if len(self.channels) != expected_channels:
+                    raise ValueError(
+                        f"Number of channels ({len(self.channels)}) must match "
+                        f"data columns ({expected_channels})"
+                    )
+                
+                # Channel validation happens in Channel.__post_init__
+    
+    def get_bids_filename(self, suffix: str = "motion", extension: str = "json") -> str:
+        """
+        Generate BIDS-compliant filename for this motion data.
+        
+        Args:
+            suffix: BIDS suffix (default: 'motion')
+            extension: File extension without dot (default: 'json')
+        
+        Returns:
+            BIDS-compliant filename string
+        
+        Raises:
+            ValueError: If tracksys is not provided (required for motion data)
+        
+        Example:
+            >>> motion = MotionData(subject_id="01", task_name="rest", tracksys="optical", ...)
+            >>> motion.get_bids_filename()
+            'sub-01_task-rest_tracksys-optical_motion.json'
+        
+        Note:
+            Entity order follows BIDS specification:
+            sub-<label>[_ses-<label>]_task-<label>_tracksys-<label>[_acq-<label>][_run-<index>]
+            The tracksys entity is REQUIRED for motion data.
+        """
+        if not self.tracksys:
+            raise ValueError(
+                "tracksys entity is required for BIDS motion data filenames. "
+                "Please provide a tracking system label (e.g., 'optical', 'imu', 'video')."
+            )
+        
+        parts = [f"sub-{self.subject_id}"]
+        
+        if self.session_id:
+            parts.append(f"ses-{self.session_id}")
+        
+        parts.append(f"task-{self.task_name}")
+        
+        # tracksys is REQUIRED and comes before acq
+        parts.append(f"tracksys-{self.tracksys}")
+        
+        if self.acquisition:
+            parts.append(f"acq-{self.acquisition}")
+        
+        if self.run:
+            parts.append(f"run-{self.run:02d}")
+        
+        parts.append(suffix)
+        
+        filename = "_".join(parts) + f".{extension}"
+        return filename
+    
+    def to_metadata_dict(self) -> Dict[str, Any]:
+        """
+        Convert MotionData to a dictionary suitable for JSON export.
+        
+        Returns:
+            Dictionary containing all metadata fields (excluding data array, columns, and units)
+        """
+        metadata = {
+            "TaskName": self.task_name,
+            "SamplingFrequency": self.sampling_frequency,
+            "TrackedPointsCount": self.tracked_points_count,
+        }
+        
+        # Add recommended fields if present
+        if self.manufacturer:
+            metadata["Manufacturer"] = self.manufacturer
+        if self.manufacturers_model_name:
+            metadata["ManufacturersModelName"] = self.manufacturers_model_name
+        if self.software_versions:
+            metadata["SoftwareVersions"] = self.software_versions
+        if self.motion_channel_count:
+            metadata["MotionChannelCount"] = self.motion_channel_count
+        if self.recording_duration:
+            metadata["RecordingDuration"] = self.recording_duration
+        if self.recording_type:
+            metadata["RecordingType"] = self.recording_type
+        
+        # Note: columns and units are NOT exported to JSON - they go in channels.tsv
+        
+        # Add any additional metadata
+        if self.additional_metadata:
+            metadata.update(self.additional_metadata)
+        
+        return metadata