voxelops 0.1.0__py3-none-any.whl

voxelops/runners/qsiparc.py

@@ -0,0 +1,150 @@
+"""QSIParc parcellation runner using parcellate package."""
+
+import logging
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from parcellate.interfaces.qsirecon.models import QSIReconConfig
+from parcellate.interfaces.qsirecon.qsirecon import run_parcellations
+
+from voxelops.exceptions import ProcedureExecutionError
+from voxelops.runners._base import (
+    validate_input_dir,
+    validate_participant,
+)
+from voxelops.schemas.qsiparc import (
+    QSIParcDefaults,
+    QSIParcInputs,
+    QSIParcOutputs,
+)
+
+
+def run_qsiparc(
+    inputs: QSIParcInputs, config: Optional[QSIParcDefaults] = None, **overrides
+) -> Dict[str, Any]:
+    """Run parcellation on QSIRecon outputs using parcellate.
+
+    Atlases are auto-discovered from the QSIRecon derivatives directory
+    (BIDS dseg files). No manual atlas list is needed.
+
+    Parameters
+    ----------
+    inputs : QSIParcInputs
+        Required inputs (qsirecon_dir, participant, etc.).
+    config : Optional[QSIParcDefaults], optional
+        Configuration (uses brain bank defaults if not provided), by default None.
+    **overrides
+        Override any config parameter.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Execution record with:
+            - tool: "qsiparc"
+            - participant: Participant label
+            - start_time, end_time: ISO format timestamps
+            - duration_seconds, duration_human: Execution duration
+            - success: Boolean success status
+            - output_files: List of output TSV paths
+            - inputs: QSIParcInputs instance
+            - config: QSIParcDefaults instance
+            - expected_outputs: QSIParcOutputs instance
+
+    Raises
+    ------
+    InputValidationError
+        If inputs are invalid.
+    ProcedureExecutionError
+        If parcellation fails.
+
+    Examples
+    --------
+    >>> inputs = QSIParcInputs(
+    ...     qsirecon_dir=Path("/data/derivatives/qsirecon"),
+    ...     participant="01",
+    ... )
+    >>> result = run_qsiparc(inputs)
+    >>> print(result['output_files'])
+    """
+
+    # Use brain bank defaults if config not provided
+    config = config or QSIParcDefaults()
+
+    # Apply overrides
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+
+    # Validate inputs
+    validate_input_dir(inputs.qsirecon_dir, "QSIRecon")
+    validate_participant(inputs.qsirecon_dir, inputs.participant)
+
+    # Setup output directory
+    output_dir = inputs.output_dir or inputs.qsirecon_dir.parent
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate expected outputs
+    expected_outputs = QSIParcOutputs.from_inputs(inputs, output_dir)
+
+    # Build parcellate config
+    log_level = getattr(logging, config.log_level.upper(), logging.INFO)
+    parcellate_config = QSIReconConfig(
+        input_root=inputs.qsirecon_dir,
+        output_dir=output_dir,
+        subjects=[inputs.participant],
+        sessions=[inputs.session] if inputs.session else None,
+        mask=config.mask,
+        background_label=config.background_label,
+        resampling_target=config.resampling_target,
+        force=config.force,
+        log_level=log_level,
+        atlases=inputs.atlases or [],
+        n_jobs=inputs.n_jobs or config.n_jobs,
+        n_procs=inputs.n_procs or config.n_procs,
+    )
+
+    print(f"\n{'='*80}")
+    print(f"Running qsiparc for participant {inputs.participant}")
+    print(f"{'='*80}")
+    print(f"Input: {inputs.qsirecon_dir}")
+    print(f"Output: {output_dir}")
+    print(f"{'='*80}\n")
+
+    start_time = datetime.now()
+
+    try:
+        output_files = run_parcellations(parcellate_config)
+
+        end_time = datetime.now()
+        duration = end_time - start_time
+
+        record = {
+            "tool": "qsiparc",
+            "participant": inputs.participant,
+            "start_time": start_time.isoformat(),
+            "end_time": end_time.isoformat(),
+            "duration_seconds": duration.total_seconds(),
+            "duration_human": str(duration),
+            "success": True,
+            "output_files": output_files,
+            "inputs": inputs,
+            "config": config,
+            "expected_outputs": expected_outputs,
+        }
+
+        print(f"\n{'='*80}")
+        print("qsiparc completed successfully")
+        print(f"Duration: {duration}")
+        print(f"Output files: {len(output_files)}")
+        print(f"{'='*80}\n")
+
+        return record
+
+    except Exception as e:
+        if isinstance(e, ProcedureExecutionError):
+            raise
+        raise ProcedureExecutionError(
+            procedure_name="qsiparc",
+            message=str(e),
+            original_error=e,
+        ) from e

voxelops/runners/qsiprep.py

@@ -0,0 +1,187 @@
+"""QSIPrep diffusion preprocessing runner."""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from voxelops.runners._base import (
+    run_docker,
+    validate_input_dir,
+    validate_participant,
+)
+from voxelops.schemas.qsiprep import (
+    QSIPrepDefaults,
+    QSIPrepInputs,
+    QSIPrepOutputs,
+)
+
+
+def _build_qsiprep_docker_command(
+    inputs: QSIPrepInputs,
+    config: QSIPrepDefaults,
+    output_dir: Path,
+    work_dir: Path,
+) -> list[str]:
+    """Builds the Docker command for QSIPrep."""
+    uid = os.getuid()
+    gid = os.getgid()
+
+    cmd = [
+        "docker",
+        "run",
+        "-ti",
+        "--rm",
+        "--user",
+        f"{uid}:{gid}",
+        "-v",
+        f"{inputs.bids_dir}:/data:ro",
+        "-v",
+        f"{output_dir}:/out",
+        "-v",
+        f"{work_dir}:/work",
+    ]
+
+    # Add FreeSurfer license if provided
+    if config.fs_license and config.fs_license.exists():
+        cmd.extend(["-v", f"{config.fs_license}:/license.txt:ro"])
+    # Add BIDS filters if provided
+    if inputs.bids_filters and inputs.bids_filters.exists():
+        cmd.extend(["-v", f"{inputs.bids_filters}:/bids_filters.json:ro"])
+
+    # Container image
+    cmd.append(config.docker_image)
+
+    # QSIPrep arguments
+    cmd.extend(
+        [
+            "/data",
+            "/out",
+            "participant",
+            "--participant-label",
+            inputs.participant,
+            "--output-resolution",
+            str(config.output_resolution),
+            "--nprocs",
+            str(config.nprocs),
+            "--mem-mb",
+            str(config.mem_mb),
+            "--work-dir",
+            "/work",
+        ]
+    )
+
+    # Output spaces
+    for space in config.anatomical_template:
+        cmd.extend(["--anatomical-template", space])
+
+    # Optional flags
+    if config.longitudinal:
+        cmd.append("--longitudinal")
+
+    # Optional subject anatomical reference
+    if (
+        hasattr(config, "subject_anatomical_reference")
+        and config.subject_anatomical_reference
+    ):
+        cmd.extend(
+            ["--subject-anatomical-reference", config.subject_anatomical_reference]
+        )
+
+    if config.skip_bids_validation:
+        cmd.append("--skip-bids-validation")
+
+    if config.fs_license and config.fs_license.exists():
+        cmd.extend(["--fs-license-file", "/license.txt"])
+
+    if inputs.bids_filters and inputs.bids_filters.exists():
+        cmd.extend(["--bids-filter-file", "/bids_filters.json"])
+
+    return cmd
+
+
+def run_qsiprep(
+    inputs: QSIPrepInputs, config: Optional[QSIPrepDefaults] = None, **overrides
+) -> Dict[str, Any]:
+    """Run QSIPrep diffusion MRI preprocessing.
+
+    Parameters
+    ----------
+    inputs : QSIPrepInputs
+        Required inputs (bids_dir, participant, etc.).
+    config : Optional[QSIPrepDefaults], optional
+        Configuration (uses brain bank defaults if not provided), by default None.
+    **overrides
+        Override any config parameter (e.g., nprocs=16).
+
+    Returns
+    -------
+    Dict[str, Any]
+        Execution record with:
+            - tool: "qsiprep"
+            - 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: QSIPrepInputs instance
+            - config: QSIPrepDefaults instance
+            - expected_outputs: QSIPrepOutputs instance
+
+    Raises
+    ------
+    InputValidationError
+        If inputs are invalid.
+    ProcedureExecutionError
+        If preprocessing fails.
+
+    Examples
+    --------
+    >>> inputs = QSIPrepInputs(
+    ...     bids_dir=Path("/data/bids"),
+    ...     participant="01",
+    ... )
+    >>> result = run_qsiprep(inputs, nprocs=16)  # Override default nprocs
+    >>> print(f"Completed in {result['duration_human']}")
+    >>> print(f"Outputs in: {result['expected_outputs'].qsiprep_dir}")
+    """
+    # Use brain bank defaults if config not provided
+    config = config or QSIPrepDefaults()
+
+    # Apply overrides
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+
+    # Validate inputs
+    validate_input_dir(inputs.bids_dir, "BIDS")
+    validate_participant(inputs.bids_dir, inputs.participant)
+
+    # Setup directories
+    output_dir = inputs.output_dir or (inputs.bids_dir.parent / "derivatives")
+    work_dir = inputs.work_dir or (output_dir.parent / "work" / "qsiprep")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate expected outputs
+    expected_outputs = QSIPrepOutputs.from_inputs(inputs, output_dir, work_dir)
+
+    # Build Docker command
+    cmd = _build_qsiprep_docker_command(inputs, config, output_dir, work_dir)
+
+    # Execute
+    log_dir = output_dir.parent / "logs"
+    result = run_docker(
+        cmd=cmd,
+        tool_name="qsiprep",
+        participant=inputs.participant,
+        log_dir=log_dir,
+    )
+
+    # Add inputs, config, and expected outputs to result
+    result["inputs"] = inputs
+    result["config"] = config
+    result["expected_outputs"] = expected_outputs
+
+    return result

voxelops/runners/qsirecon.py

@@ -0,0 +1,173 @@
+"""QSIRecon diffusion reconstruction runner."""
+
+import os
+from typing import Any, Dict, Optional
+
+from voxelops.runners._base import (
+    run_docker,
+    validate_input_dir,
+    validate_participant,
+)
+from voxelops.schemas.qsirecon import (
+    QSIReconDefaults,
+    QSIReconInputs,
+    QSIReconOutputs,
+)
+
+
+def run_qsirecon(
+    inputs: QSIReconInputs, config: Optional[QSIReconDefaults] = None, **overrides
+) -> Dict[str, Any]:
+    """Run QSIRecon diffusion reconstruction and connectivity.
+
+    Parameters
+    ----------
+    inputs : QSIReconInputs
+        Required inputs (qsiprep_dir, participant, etc.).
+    config : Optional[QSIReconDefaults], optional
+        Configuration (uses brain bank defaults if not provided), by default None.
+    **overrides
+        Override any config parameter.
+
+    Returns
+    -------
+    Dict[str, Any]
+        Execution record with:
+            - tool: "qsirecon"
+            - 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: QSIReconInputs instance
+            - config: QSIReconDefaults instance
+            - expected_outputs: QSIReconOutputs instance
+
+    Raises
+    ------
+    InputValidationError
+        If inputs are invalid.
+    ProcedureExecutionError
+        If reconstruction fails.
+
+    Examples
+    --------
+    >>> inputs = QSIReconInputs(
+    ...     qsiprep_dir=Path("/data/derivatives/qsiprep"),
+    ...     participant="01",
+    ... )
+    >>> result = run_qsirecon(inputs, atlases=["schaefer100"])
+    >>> print(result['expected_outputs'].qsirecon_dir)
+    """
+    # Use brain bank defaults if config not provided
+    config = config or QSIReconDefaults()
+
+    # Apply overrides
+    for key, value in overrides.items():
+        if hasattr(config, key):
+            setattr(config, key, value)
+
+    # Validate inputs
+    validate_input_dir(inputs.qsiprep_dir, "QSIPrep")
+    validate_participant(inputs.qsiprep_dir, inputs.participant)
+
+    # Setup directories
+    output_dir = inputs.output_dir or (inputs.qsiprep_dir.parent)
+    work_dir = inputs.work_dir or (output_dir.parent / "work" / "qsirecon")
+    output_dir.mkdir(parents=True, exist_ok=True)
+    work_dir.mkdir(parents=True, exist_ok=True)
+
+    # Generate expected outputs
+    expected_outputs = QSIReconOutputs.from_inputs(inputs, output_dir, work_dir)
+
+    # Get current user/group IDs for Docker
+    uid = os.getuid()
+    gid = os.getgid()
+
+    # Build Docker command
+    cmd = [
+        "docker",
+        "run",
+        "-it",
+        "--rm",
+        "--user",
+        f"{uid}:{gid}",
+        "-v",
+        f"{inputs.qsiprep_dir}:/data:ro",
+        "-v",
+        f"{output_dir}:/out",
+        "-v",
+        f"{work_dir}:/work",
+        "-v",
+        f"{inputs.recon_spec}:/recon_spec.yaml:ro",
+    ]
+
+    # Add optional mounts
+    if config.fs_license and config.fs_license.exists():
+        cmd.extend(["-v", f"{config.fs_license}:/license.txt:ro"])
+
+    if config.fs_subjects_dir and config.fs_subjects_dir.exists():
+        cmd.extend(["-v", f"{config.fs_subjects_dir}:/subjects:ro"])
+
+    if inputs.datasets:
+        for name, path in inputs.datasets.items():
+            cmd.extend(["-v", f"{path}:/datasets/{name}:ro"])
+
+    # Container image
+    cmd.append(config.docker_image)
+
+    # QSIRecon arguments
+    cmd.extend(
+        [
+            "/data",
+            "/out",
+            "participant",
+            "--participant-label",
+            inputs.participant,
+            "--nprocs",
+            str(config.nprocs),
+            "--mem-mb",
+            str(config.mem_mb),
+            "--work-dir",
+            "/work",
+        ]
+    )
+
+    # Datasets
+    if inputs.datasets:
+        cmd.extend(["--datasets"])
+        for name in inputs.datasets.keys():
+            addition = f"{name}=/datasets/{name}"
+            cmd.extend([addition])
+    # Atlases
+    if config.atlases:
+        cmd.extend(["--atlases", *config.atlases])
+    if inputs.atlases:
+        cmd.extend([*inputs.atlases])
+    # Optional arguments
+    if inputs.recon_spec and inputs.recon_spec.exists():
+        cmd.extend(["--recon-spec", "/recon_spec.yaml"])
+
+    if config.fs_subjects_dir and config.fs_subjects_dir.exists():
+        cmd.extend(["--freesurfer-input", "/subjects"])
+
+    if config.fs_license and config.fs_license.exists():
+        cmd.extend(["--fs-license-file", "/license.txt"])
+
+    # Execute
+    log_dir = output_dir.parent / "logs"
+    result = run_docker(
+        cmd=cmd,
+        tool_name="qsirecon",
+        participant=inputs.participant,
+        log_dir=log_dir,
+    )
+
+    # Add inputs, config, and expected outputs to result
+    result["inputs"] = inputs
+    result["config"] = config
+    result["expected_outputs"] = expected_outputs
+
+    return result

voxelops/schemas/__init__.py

@@ -0,0 +1,41 @@
+"""Schemas for procedure inputs, outputs, and defaults."""
+
+from voxelops.schemas.heudiconv import (
+    HeudiconvDefaults,
+    HeudiconvInputs,
+    HeudiconvOutputs,
+)
+from voxelops.schemas.qsiparc import (
+    QSIParcDefaults,
+    QSIParcInputs,
+    QSIParcOutputs,
+)
+from voxelops.schemas.qsiprep import (
+    QSIPrepDefaults,
+    QSIPrepInputs,
+    QSIPrepOutputs,
+)
+from voxelops.schemas.qsirecon import (
+    QSIReconDefaults,
+    QSIReconInputs,
+    QSIReconOutputs,
+)
+
+__all__ = [
+    # HeudiConv
+    "HeudiconvInputs",
+    "HeudiconvOutputs",
+    "HeudiconvDefaults",
+    # QSIPrep
+    "QSIPrepInputs",
+    "QSIPrepOutputs",
+    "QSIPrepDefaults",
+    # QSIRecon
+    "QSIReconInputs",
+    "QSIReconOutputs",
+    "QSIReconDefaults",
+    # QSIParc
+    "QSIParcInputs",
+    "QSIParcOutputs",
+    "QSIParcDefaults",
+]

voxelops/schemas/heudiconv.py

@@ -0,0 +1,121 @@
+"""HeudiConv schemas: inputs, outputs, and defaults."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class HeudiconvInputs:
+    """Required inputs for HeudiConv DICOM to BIDS conversion.
+
+    Parameters
+    ----------
+    dicom_dir : Path
+        Directory containing DICOM files.
+    participant : str
+        Participant label (without 'sub-' prefix).
+    output_dir : Optional[Path], optional
+        Output BIDS directory, by default None.
+        If None, defaults to dicom_dir/../bids.
+    session : Optional[str], optional
+        Session label (without 'ses-' prefix), by default None.
+    heuristic : Optional[Path], optional
+        Path to heuristic.py file, by default None.
+    """
+
+    dicom_dir: Path
+    participant: str
+    output_dir: Optional[Path] = None
+    session: Optional[str] = None
+    heuristic: Optional[Path] = None
+
+    def __post_init__(self):
+        """Ensure paths are Path objects."""
+        self.dicom_dir = Path(self.dicom_dir)
+        if self.output_dir:
+            self.output_dir = Path(self.output_dir)
+
+
+@dataclass
+class HeudiconvOutputs:
+    """Expected outputs from HeudiConv.
+
+    Parameters
+    ----------
+    bids_dir : Path
+        Root BIDS directory.
+    participant_dir : Path
+        Participant-specific directory (sub-XX/).
+    dataset_description : Path
+        dataset_description.json file.
+    """
+
+    bids_dir: Path
+    participant_dir: Path
+    dataset_description: Path
+
+    @classmethod
+    def from_inputs(cls, inputs: HeudiconvInputs, output_dir: Path):
+        """Generate expected output paths from inputs.
+
+        Parameters
+        ----------
+        inputs : HeudiconvInputs
+            HeudiconvInputs instance.
+        output_dir : Path
+            Resolved output directory.
+
+        Returns
+        -------
+        HeudiconvOutputs
+            HeudiconvOutputs with expected paths.
+        """
+        participant_dir = output_dir / f"sub-{inputs.participant}"
+        if inputs.session:
+            participant_dir = participant_dir / f"ses-{inputs.session}"
+
+        return cls(
+            bids_dir=output_dir,
+            participant_dir=participant_dir,
+            dataset_description=output_dir / "dataset_description.json",
+        )
+
+
+@dataclass
+class HeudiconvDefaults:
+    """Default configuration for HeudiConv.
+
+    Parameters
+    ----------
+    heuristic : Optional[Path], optional
+        Path to heuristic.py file (required for conversion), by default None.
+    bids_validator : bool, optional
+        Run BIDS validator after conversion, by default True.
+    overwrite : bool, optional
+        Overwrite existing output, by default False.
+    converter : str, optional
+        DICOM converter to use, by default "dcm2niix".
+    docker_image : str, optional
+        Docker image to use, by default "nipy/heudiconv:1.3.4".
+    post_process : bool, optional
+        Enable post-heudiconv processing, by default True.
+    post_process_dry_run : bool, optional
+        Test mode - report only, don't modify, by default False.
+    """
+
+    heuristic: Optional[Path] = None
+    bids_validator: bool = True
+    overwrite: bool = False
+    converter: str = "dcm2niix"
+    bids: Optional[str] = "notop"
+    grouping: Optional[str] = "all"
+    docker_image: str = "nipy/heudiconv:1.3.4"
+    # Post-processing options
+    post_process: bool = True  # Enable post-heudiconv processing
+    post_process_dry_run: bool = False  # Test mode - report only, don't modify
+
+    def __post_init__(self):
+        """Ensure heuristic path is Path object if provided."""
+        if self.heuristic:
+            self.heuristic = Path(self.heuristic)