voxelops 0.1.0__py3-none-any.whl

voxelops/__init__.py

@@ -0,0 +1,98 @@
+"""VoxelOps: Clean, simple neuroimaging pipeline automation for brain banks.
+
+This package provides straightforward functions for running neuroimaging procedures
+in Docker containers. Each procedure follows a simple pattern:
+1. Define inputs (required paths and parameters)
+2. Run the procedure (returns execution record)
+3. Use expected outputs (generated from inputs)
+
+Quick Start:
+    >>> from voxelops import run_qsiprep, QSIPrepInputs
+    >>>
+    >>> inputs = QSIPrepInputs(
+    ...     bids_dir="/data/bids",
+    ...     participant="01",
+    ... )
+    >>> result = run_qsiprep(inputs, nprocs=16)
+    >>>
+    >>> # Result is a dict with everything you need
+    >>> print(f"Completed in {result['duration_human']}")
+    >>> print(f"Outputs: {result['expected_outputs'].qsiprep_dir}")
+    >>>
+    >>> # Perfect for databases
+    >>> db.save_processing_record(result)
+
+Available Procedures:
+    - run_heudiconv: DICOM → BIDS conversion
+    - run_qsiprep: Diffusion MRI preprocessing
+    - run_qsirecon: Diffusion reconstruction & connectivity
+    - run_qsiparc: Parcellation using parcellate package
+
+For full pipeline example, see examples/full_pipeline.py
+"""
+
+__author__ = "YALab DevOps"
+__email__ = "yalab.dev@gmail.com"
+__version__ = "2.0.0"
+
+# Runner functions
+# Exceptions
+from voxelops.exceptions import (
+    InputValidationError,
+    ProcedureError,
+    ProcedureExecutionError,
+)
+from voxelops.runners import (
+    run_heudiconv,
+    run_qsiparc,
+    run_qsiprep,
+    run_qsirecon,
+)
+
+# Schemas for inputs, outputs, and defaults
+from voxelops.schemas import (
+    HeudiconvDefaults,
+    # HeudiConv
+    HeudiconvInputs,
+    HeudiconvOutputs,
+    QSIParcDefaults,
+    # QSIParc
+    QSIParcInputs,
+    QSIParcOutputs,
+    QSIPrepDefaults,
+    # QSIPrep
+    QSIPrepInputs,
+    QSIPrepOutputs,
+    QSIReconDefaults,
+    # QSIRecon
+    QSIReconInputs,
+    QSIReconOutputs,
+)
+
+__all__ = [
+    # Runners
+    "run_heudiconv",
+    "run_qsiprep",
+    "run_qsirecon",
+    "run_qsiparc",
+    # Schemas - HeudiConv
+    "HeudiconvInputs",
+    "HeudiconvOutputs",
+    "HeudiconvDefaults",
+    # Schemas - QSIPrep
+    "QSIPrepInputs",
+    "QSIPrepOutputs",
+    "QSIPrepDefaults",
+    # Schemas - QSIRecon
+    "QSIReconInputs",
+    "QSIReconOutputs",
+    "QSIReconDefaults",
+    # Schemas - QSIParc
+    "QSIParcInputs",
+    "QSIParcOutputs",
+    "QSIParcDefaults",
+    # Exceptions
+    "ProcedureError",
+    "InputValidationError",
+    "ProcedureExecutionError",
+]

voxelops/exceptions.py

@@ -0,0 +1,158 @@
+"""Custom exceptions for yalab-procedures.
+
+This module defines a hierarchy of exceptions for consistent error handling
+across all procedures in the yalab-procedures package.
+"""
+
+from typing import Optional
+
+
+class YALabProcedureError(Exception):
+    """Base exception for all yalab-procedures errors.
+
+    All custom exceptions in this package inherit from this class,
+    allowing callers to catch all yalab-procedures errors with a single
+    except clause if desired.
+    """
+
+    pass
+
+
+class ProcedureExecutionError(YALabProcedureError):
+    """Raised when a procedure fails during execution.
+
+    Parameters
+    ----------
+    procedure_name : str
+        Name of the procedure that failed.
+    message : str
+        The error message.
+    original_error : Optional[Exception], optional
+        The underlying exception that caused the failure, if any, by default None.
+    """
+
+    def __init__(
+        self,
+        procedure_name: str,
+        message: str,
+        original_error: Optional[Exception] = None,
+    ):
+        self.procedure_name = procedure_name
+        self.original_error = original_error
+        super().__init__(f"{procedure_name} failed: {message}")
+
+
+class ProcedureConfigurationError(YALabProcedureError):
+    """Raised when procedure configuration is invalid.
+
+    This includes missing required inputs, invalid input combinations,
+    or configuration that cannot be used together.
+    """
+
+    pass
+
+
+class InputValidationError(YALabProcedureError):
+    """Raised when input validation fails.
+
+    This is raised during pre-flight checks when inputs don't meet
+    the requirements for procedure execution.
+    """
+
+    pass
+
+
+class OutputCollectionError(YALabProcedureError):
+    """Raised when expected outputs are not found after procedure execution.
+
+    This indicates the procedure may have failed silently or produced
+    unexpected output structure.
+    """
+
+    pass
+
+
+class DockerExecutionError(ProcedureExecutionError):
+    """Raised when a Docker-based procedure fails.
+
+    Parameters
+    ----------
+    procedure_name : str
+        Name of the procedure that failed.
+    container : str
+        The Docker image/container that was running.
+    exit_code : int
+        The exit code returned by the Docker container.
+    stderr : str
+        Standard error output from the container.
+    """
+
+    def __init__(
+        self,
+        procedure_name: str,
+        container: str,
+        exit_code: int,
+        stderr: str,
+    ):
+        self.container = container
+        self.exit_code = exit_code
+        self.stderr = stderr
+        message = f"Docker container '{container}' exited with code {exit_code}"
+        if stderr:
+            # Truncate very long stderr for the message
+            stderr_preview = stderr[:500] + "..." if len(stderr) > 500 else stderr
+            message += f": {stderr_preview}"
+        super().__init__(procedure_name, message)
+
+
+class FreeSurferLicenseError(ProcedureConfigurationError):
+    """Raised when FreeSurfer license file cannot be found.
+
+    This is a specific configuration error for procedures that require
+    FreeSurfer and cannot locate a valid license file.
+    """
+
+    def __init__(self, message: Optional[str] = None):
+        if message is None:
+            message = (
+                "FreeSurfer license not found. Set FS_LICENSE or FREESURFER_HOME "
+                "environment variable, or provide fs_license_file parameter."
+            )
+        super().__init__(message)
+
+
+class BIDSValidationError(YALabProcedureError):
+    """Raised when BIDS dataset validation fails.
+
+    This indicates the input data does not conform to BIDS specification
+    requirements for the procedure.
+    """
+
+
+
+    pass
+
+
+class DependencyError(YALabProcedureError):
+    """Raised when a required external dependency is not available.
+
+    This includes missing Docker, missing command-line tools, or
+    unavailable Python packages.
+
+    Parameters
+    ----------
+    dependency : str
+        The name of the missing dependency.
+    message : Optional[str], optional
+        The error message, by default None.
+    """
+
+    def __init__(self, dependency: str, message: Optional[str] = None):
+        self.dependency = dependency
+        if message is None:
+            message = f"Required dependency '{dependency}' is not available"
+        super().__init__(message)
+
+
+# Alias for backwards compatibility
+ProcedureError = YALabProcedureError

voxelops/runners/__init__.py

@@ -0,0 +1,13 @@
+"""Procedure runners for brain bank neuroimaging pipelines."""
+
+from voxelops.runners.heudiconv import run_heudiconv
+from voxelops.runners.qsiparc import run_qsiparc
+from voxelops.runners.qsiprep import run_qsiprep
+from voxelops.runners.qsirecon import run_qsirecon
+
+__all__ = [
+    "run_heudiconv",
+    "run_qsiprep",
+    "run_qsirecon",
+    "run_qsiparc",
+]

voxelops/runners/_base.py

@@ -0,0 +1,191 @@
+"""Base utilities for all procedure runners."""
+
+import json
+import subprocess
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from voxelops.exceptions import (
+    InputValidationError,
+    ProcedureExecutionError,
+)
+
+
+def validate_input_dir(input_dir: Path, dir_type: str = "Input") -> None:
+    """Validate that an input directory exists.
+
+    Parameters
+    ----------
+    input_dir : Path
+        Directory to validate.
+    dir_type : str, optional
+        Type of directory for error message, by default "Input".
+
+    Raises
+    ------
+    InputValidationError
+        If directory doesn't exist.
+    """
+    if not input_dir.exists():
+        raise InputValidationError(f"{dir_type} directory not found: {input_dir}")
+
+    if not input_dir.is_dir():
+        raise InputValidationError(f"{dir_type} path is not a directory: {input_dir}")
+
+
+def validate_participant(
+    input_dir: Path, participant: str, prefix: str = "sub-"
+) -> None:
+    """Validate that a participant exists in the input directory.
+
+    Parameters
+    ----------
+    input_dir : Path
+        Directory containing participant data.
+    participant : str
+        Participant label (without prefix).
+    prefix : str, optional
+        Expected prefix, by default "sub-".
+
+    Raises
+    ------
+    InputValidationError
+        If participant not found.
+    """
+    participant_dir = input_dir / f"{prefix}{participant}"
+    if not participant_dir.exists():
+        raise InputValidationError(
+            f"Participant {prefix}{participant} not found in {input_dir}"
+        )
+
+
+def run_docker(
+    cmd: List[str],
+    tool_name: str,
+    participant: str,
+    log_dir: Optional[Path] = None,
+    capture_output: bool = True,
+) -> Dict[str, Any]:
+    """Execute Docker command and return execution record.
+
+    Parameters
+    ----------
+    cmd : List[str]
+        Docker command as list of strings.
+    tool_name : str
+        Name of the tool being run (for logging).
+    participant : str
+        Participant label.
+    log_dir : Optional[Path], optional
+        Directory to save execution log JSON, by default None.
+    capture_output : bool, optional
+        Whether to capture stdout/stderr, by default True.
+
+    Returns
+    -------
+    Dict[str, Any]
+        A dictionary with execution details:
+            - tool: Tool name
+            - participant: Participant label
+            - command: Full command that was executed
+            - exit_code: Process exit code
+            - start_time: ISO format timestamp
+            - end_time: ISO format timestamp
+            - duration_seconds: Duration in seconds
+            - duration_human: Human-readable duration
+            - success: Boolean success status
+            - log_file: Path to JSON log (if log_dir provided)
+            - stdout: Process stdout (if captured)
+            - stderr: Process stderr (if captured)
+            - error: Error message (if failed)
+
+    Raises
+    ------
+    ProcedureExecutionError
+        If command fails.
+    """
+    # Setup logging
+    if log_dir:
+        log_dir.mkdir(parents=True, exist_ok=True)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        log_file = log_dir / f"{tool_name}_{participant}_{timestamp}.json"
+    else:
+        log_file = None
+
+    print(f"\n{'='*80}")
+    print(f"Running {tool_name} for participant {participant}")
+    print(f"{'='*80}")
+    print(f"Command: {' '.join(cmd)}")
+    print(f"{'='*80}\n")
+
+    start_time = datetime.now()
+
+    try:
+        result = subprocess.run(
+            cmd, capture_output=capture_output, text=True, check=False
+        )
+
+        end_time = datetime.now()
+        duration = end_time - start_time
+
+        # Build execution record
+        record = {
+            "tool": tool_name,
+            "participant": participant,
+            "command": cmd,
+            "exit_code": result.returncode,
+            "start_time": start_time.isoformat(),
+            "end_time": end_time.isoformat(),
+            "duration_seconds": duration.total_seconds(),
+            "duration_human": str(duration),
+            "success": result.returncode == 0,
+        }
+
+        if capture_output:
+            record["stdout"] = result.stdout
+            record["stderr"] = result.stderr
+
+        # Save to JSON log
+        if log_file:
+            record["log_file"] = str(log_file)
+            with open(log_file, "w") as f:
+                json.dump(record, f, indent=2)
+            print(f"Execution log saved: {log_file}")
+
+        # Check for errors
+        if result.returncode != 0:
+            error_msg = f"{tool_name} failed with exit code {result.returncode}"
+            if capture_output and result.stderr:
+                error_msg += f"\n\nStderr (last 1000 chars):\n{result.stderr[-1000:]}"
+
+            record["error"] = error_msg
+
+            # Update log file with error
+            if log_file:
+                with open(log_file, "w") as f:
+                    json.dump(record, f, indent=2)
+
+            raise ProcedureExecutionError(
+                procedure_name=tool_name,
+                message=error_msg,
+            )
+
+        print(f"\n{'='*80}")
+        print(f"✓ {tool_name} completed successfully")
+        print(f"Duration: {duration}")
+        print(f"{'='*80}\n")
+
+        return record
+
+    except subprocess.TimeoutExpired as e:
+        raise ProcedureExecutionError(
+            procedure_name=tool_name,
+            message=f"Process timed out after {e.timeout} seconds",
+        ) from e
+    except Exception as e:
+        if not isinstance(e, ProcedureExecutionError):
+            raise ProcedureExecutionError(
+                procedure_name=tool_name, message=str(e), original_error=e
+            ) from e
+        raise

voxelops/runners/heudiconv.py

@@ -0,0 +1,202 @@
+"""HeudiConv DICOM to BIDS converter runner."""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from voxelops.exceptions import InputValidationError
+from voxelops.runners._base import run_docker, validate_input_dir
+from voxelops.schemas.heudiconv import (
+    HeudiconvDefaults,
+    HeudiconvInputs,
+    HeudiconvOutputs,
+)
+from voxelops.utils.bids import post_process_heudiconv_output
+
+
+def _build_heudiconv_docker_command(
+    inputs: HeudiconvInputs, config: HeudiconvDefaults, output_dir: Path
+) -> list[str]:
+    """Builds the Docker command for HeudiConv."""
+    uid = os.getuid()
+    gid = os.getgid()
+
+    cmd = [
+        "docker",
+        "run",
+        "--rm",
+        "--user",
+        f"{uid}:{gid}",
+        "-v",
+        f"{inputs.dicom_dir}:/dicom:ro",
+        "-v",
+        f"{output_dir}:/output",
+        "-v",
+        f"{config.heuristic}:/heuristic.py:ro",
+        config.docker_image,
+        "--files",
+        "/dicom",
+        "--outdir",
+        "/output",
+        "--subjects",
+        inputs.participant,
+        "--converter",
+        config.converter,
+        "--heuristic",
+        "/heuristic.py",
+    ]
+
+    if inputs.session:
+        cmd.extend(["--ses", inputs.session])
+
+    if config.overwrite:
+        cmd.append("--overwrite")
+
+    if config.bids_validator:
+        cmd.append("--bids")
+
+    if config.bids:
+        cmd.extend(["--bids", config.bids])
+
+    if config.grouping:
+        cmd.extend(["--grouping", config.grouping])
+
+    if config.overwrite:
+        cmd.append("--overwrite")
+    return cmd
+
+
+def _handle_heudiconv_post_processing(
+    result: Dict[str, Any],
+    config: HeudiconvDefaults,
+    output_dir: Path,
+    inputs: HeudiconvInputs,
+) -> Dict[str, Any]:
+    """Handles post-processing steps for HeudiConv."""
+    if result["success"] and config.post_process:
+        print(f"\n{'='*80}")
+        print(f"Running post-HeudiConv processing for participant {inputs.participant}")
+        print(f"{'='*80}\n")
+
+        try:
+            post_result = post_process_heudiconv_output(
+                bids_dir=output_dir,
+                participant=inputs.participant,
+                session=inputs.session,
+                dry_run=config.post_process_dry_run,
+            )
+            result["post_processing"] = post_result
+
+            if not post_result["success"]:
+                print("\n⚠ Post-processing completed with warnings:")
+                for error in post_result.get("errors", []):
+                    print(f"  - {error}")
+            else:
+                print("\n✓ Post-processing completed successfully")
+
+        except Exception as e:
+            print(f"\n⚠ Post-processing failed: {e}")
+            result["post_processing"] = {"success": False, "error": str(e)}
+            # Don't fail the entire conversion if post-processing fails
+    return result
+
+
+def run_heudiconv(
+    inputs: HeudiconvInputs, config: Optional[HeudiconvDefaults] = None, **overrides
+) -> Dict[str, Any]:
+    """Convert DICOM to BIDS using HeudiConv.
+
+    Parameters
+    ----------
+    inputs : HeudiconvInputs
+        Required inputs (dicom_dir, participant, etc.).
+    config : Optional[HeudiconvDefaults], optional
+        Configuration (uses defaults if not provided), by default None.
+    **overrides
+        Override any config parameter.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Execution record with:
+            - tool: "heudiconv"
+            - participant: Participant label
+            - command: Full Docker command executed
+            - exit_code: Process exit code
+            - start_time, end_time: ISO format timestamps
+            - duration_seconds, duration_human: Execution duration
+            - success: Boolean success status
+            - log_file: Path to JSON log
+            - inputs: HeudiconvInputs instance
+            - config: HeudiconvDefaults instance
+            - expected_outputs: HeudiconvOutputs instance
+
+    Raises
+    ------
+    InputValidationError
+        If inputs are invalid.
+    ProcedureExecutionError
+        If conversion fails.
+
+    Examples
+    --------
+    >>> inputs = HeudiconvInputs(
+    ...     dicom_dir=Path("/data/dicoms"),
+    ...     participant="01",
+    ... )
+    >>> config = HeudiconvDefaults(
+    ...     heuristic=Path("/code/heuristic.py"),
+    ... )
+    >>> result = run_heudiconv(inputs, config)
+    >>> print(result['expected_outputs'].bids_dir)
+    PosixPath('/data/bids')
+    """
+    # Use defaults if config not provided
+    config = config or HeudiconvDefaults()
+
+    # Apply overrides
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            print(f"Overriding config.{key} with value: {value}")
+            setattr(config, key, value)
+
+    # Validate inputs
+    validate_input_dir(inputs.dicom_dir, "DICOM")
+
+    if not config.heuristic:
+        raise InputValidationError(
+            "Heuristic file is required for HeudiConv. "
+            "Provide it via config.heuristic or heuristic= keyword argument."
+        )
+
+    if not config.heuristic.exists():
+        raise InputValidationError(f"Heuristic file not found: {config.heuristic}")
+
+    # Setup output directory
+    output_dir = inputs.output_dir or (inputs.dicom_dir.parent / "bids")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate expected outputs
+    expected_outputs = HeudiconvOutputs.from_inputs(inputs, output_dir)
+
+    # Build Docker command
+    cmd = _build_heudiconv_docker_command(inputs, config, output_dir)
+
+    # Execute
+    log_dir = output_dir.parent / "logs"
+    result = run_docker(
+        cmd=cmd,
+        tool_name="heudiconv",
+        participant=inputs.participant,
+        log_dir=log_dir,
+    )
+
+    # Post-processing steps
+    result = _handle_heudiconv_post_processing(result, config, output_dir, inputs)
+
+    # Add inputs, config, and expected outputs to result
+    result["inputs"] = inputs
+    result["config"] = config
+    result["expected_outputs"] = expected_outputs
+
+    return result