voxelops package — VoxelOps 2.0.0 documentation

# 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

- voxelops.runners package
  - Shared Utilities
    - `run_docker()`
    - `validate_input_dir()`
    - `validate_participant()`
  - HeudiConv
    - `run_heudiconv()`
  - QSIPrep
    - `run_qsiprep()`
  - QSIRecon
    - `run_qsirecon()`
  - QSIParc
    - `run_qsiparc()`
  - Module contents
- voxelops.schemas package
  - HeudiConv
    - `HeudiconvDefaults`
      - `HeudiconvDefaults.__post_init__()`
      - `HeudiconvDefaults.bids`
      - `HeudiconvDefaults.bids_validator`
      - `HeudiconvDefaults.converter`
      - `HeudiconvDefaults.docker_image`
      - `HeudiconvDefaults.grouping`
      - `HeudiconvDefaults.heuristic`
      - `HeudiconvDefaults.overwrite`
      - `HeudiconvDefaults.post_process`
      - `HeudiconvDefaults.post_process_dry_run`
    - `HeudiconvInputs`
      - `HeudiconvInputs.__post_init__()`
      - `HeudiconvInputs.dicom_dir`
      - `HeudiconvInputs.heuristic`
      - `HeudiconvInputs.output_dir`
      - `HeudiconvInputs.participant`
      - `HeudiconvInputs.session`
    - `HeudiconvOutputs`
      - `HeudiconvOutputs.bids_dir`
      - `HeudiconvOutputs.dataset_description`
      - `HeudiconvOutputs.from_inputs()`
      - `HeudiconvOutputs.participant_dir`
  - QSIPrep
    - `QSIPrepDefaults`
      - `QSIPrepDefaults.__post_init__()`
      - `QSIPrepDefaults.anatomical_template`
      - `QSIPrepDefaults.docker_image`
      - `QSIPrepDefaults.fs_license`
      - `QSIPrepDefaults.longitudinal`
      - `QSIPrepDefaults.mem_mb`
      - `QSIPrepDefaults.nprocs`
      - `QSIPrepDefaults.output_resolution`
      - `QSIPrepDefaults.skip_bids_validation`
      - `QSIPrepDefaults.subject_anatomical_reference`
    - `QSIPrepInputs`
      - `QSIPrepInputs.__post_init__()`
      - `QSIPrepInputs.bids_dir`
      - `QSIPrepInputs.bids_filters`
      - `QSIPrepInputs.output_dir`
      - `QSIPrepInputs.participant`
      - `QSIPrepInputs.work_dir`
    - `QSIPrepOutputs`
      - `QSIPrepOutputs.figures_dir`
      - `QSIPrepOutputs.from_inputs()`
      - `QSIPrepOutputs.html_report`
      - `QSIPrepOutputs.participant_dir`
      - `QSIPrepOutputs.qsiprep_dir`
      - `QSIPrepOutputs.work_dir`
  - QSIRecon
    - `QSIReconDefaults`
      - `QSIReconDefaults.__post_init__()`
      - `QSIReconDefaults.atlases`
      - `QSIReconDefaults.docker_image`
      - `QSIReconDefaults.fs_license`
      - `QSIReconDefaults.fs_subjects_dir`
      - `QSIReconDefaults.mem_mb`
      - `QSIReconDefaults.nprocs`
    - `QSIReconInputs`
      - `QSIReconInputs.__post_init__()`
      - `QSIReconInputs.atlases`
      - `QSIReconInputs.datasets`
      - `QSIReconInputs.output_dir`
      - `QSIReconInputs.participant`
      - `QSIReconInputs.qsiprep_dir`
      - `QSIReconInputs.recon_spec`
      - `QSIReconInputs.work_dir`
    - `QSIReconOutputs`
      - `QSIReconOutputs.from_inputs()`
      - `QSIReconOutputs.html_report`
      - `QSIReconOutputs.participant_dir`
      - `QSIReconOutputs.qsirecon_dir`
      - `QSIReconOutputs.work_dir`
  - QSIParc
    - `QSIParcDefaults`
      - `QSIParcDefaults.background_label`
      - `QSIParcDefaults.force`
      - `QSIParcDefaults.log_level`
      - `QSIParcDefaults.mask`
      - `QSIParcDefaults.n_jobs`
      - `QSIParcDefaults.n_procs`
      - `QSIParcDefaults.resampling_target`
    - `QSIParcInputs`
      - `QSIParcInputs.__post_init__()`
      - `QSIParcInputs.atlases`
      - `QSIParcInputs.n_jobs`
      - `QSIParcInputs.n_procs`
      - `QSIParcInputs.output_dir`
      - `QSIParcInputs.participant`
      - `QSIParcInputs.qsirecon_dir`
      - `QSIParcInputs.session`
    - `QSIParcOutputs`
      - `QSIParcOutputs.from_inputs()`
      - `QSIParcOutputs.output_dir`
  - Module contents
- voxelops.utils package
  - BIDS Utilities
    - `add_intended_for_to_fmaps()`
    - `post_process_heudiconv_output()`
    - `remove_bval_bvec_from_fmaps()`
    - `verify_fmap_epi_files()`
  - Module contents

## 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

  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)

  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)

  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)

  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

  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

  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

  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)

  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

  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.