voxelops package

Top-level exports, version, and convenience imports.

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

Subpackages

Exceptions

Custom exceptions for yalab-procedures.

This module defines a hierarchy of exceptions for consistent error handling across all procedures in the yalab-procedures package.

exception BIDSValidationError[source]

Bases: YALabProcedureError

Raised when BIDS dataset validation fails.

This indicates the input data does not conform to BIDS specification requirements for the procedure.

exception DependencyError(dependency: str, message: str | None = None)[source]

Bases: 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.

exception DockerExecutionError(procedure_name: str, container: str, exit_code: int, stderr: str)[source]

Bases: 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.

exception FreeSurferLicenseError(message: str | None = None)[source]

Bases: 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.

exception InputValidationError[source]

Bases: YALabProcedureError

Raised when input validation fails.

This is raised during pre-flight checks when inputs don’t meet the requirements for procedure execution.

exception OutputCollectionError[source]

Bases: YALabProcedureError

Raised when expected outputs are not found after procedure execution.

This indicates the procedure may have failed silently or produced unexpected output structure.

exception ProcedureConfigurationError[source]

Bases: YALabProcedureError

Raised when procedure configuration is invalid.

This includes missing required inputs, invalid input combinations, or configuration that cannot be used together.

ProcedureError

alias of YALabProcedureError

exception ProcedureExecutionError(procedure_name: str, message: str, original_error: Exception | None = None)[source]

Bases: 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.

exception YALabProcedureError[source]

Bases: 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.