voxelops 0.3.2

Clean, simple neuroimaging pipeline automation for brain banks.

Brain banks need to process neuroimaging data consistently, reproducibly, and auditably. VoxelOps makes that simple by wrapping Docker-based neuroimaging tools into clean Python functions that return plain dicts – ready for your database, your logs, and your peace of mind.

Features

• Simple Functions – No classes, no inheritance – just run_*() functions that return dicts

• Clear Schemas – Typed dataclass inputs, outputs, and defaults for every procedure

• Reproducibility – The exact Docker command is stored in every execution record

• Database-Ready – Results are plain dicts, trivial to save to PostgreSQL, MongoDB, or JSON

• Brain Bank Defaults – Define your standard parameters once, reuse across all participants

• Comprehensive Logging – Every run logged to JSON with timestamps, duration, and exit codes

• Validation Framework – Pre- and post-execution validation with detailed reports

• Audit Trail – Full audit logging for every procedure run

Installation

pip install voxelops

For development:

git clone https://github.com/yalab-devops/VoxelOps.git
cd VoxelOps
pip install -e ".[dev]"

Requirements: Python >= 3.10, Docker installed and accessible.

Quick Start

Basic (direct execution):

from voxelops import run_qsiprep, QSIPrepInputs

inputs = QSIPrepInputs(
    bids_dir="/data/bids",
    participant="01",
)

result = run_qsiprep(inputs, nprocs=16)

print(f"Completed in: {result['duration_human']}")
print(f"Outputs: {result['expected_outputs'].qsiprep_dir}")
print(f"Command: {' '.join(result['command'])}")

With validation and audit logging (recommended):

from voxelops import run_procedure, QSIPrepInputs

inputs = QSIPrepInputs(
    bids_dir="/data/bids",
    participant="01",
)

result = run_procedure("qsiprep", inputs)

if result.success:
    print(f"Completed in {result.duration_seconds:.1f}s")
else:
    print(f"Failed: {result.get_failure_reason()}")

# Save complete audit trail to your database
db.save_procedure_result(result.to_dict())

Available Procedures

Brain Bank Standards

Define your standard parameters once, use them everywhere:

from voxelops import run_qsiprep, QSIPrepInputs, QSIPrepDefaults

BRAIN_BANK_QSIPREP = QSIPrepDefaults(
    nprocs=16,
    mem_mb=32000,
    output_resolution=1.6,
    anatomical_template=["MNI152NLin2009cAsym"],
    docker_image="pennlinc/qsiprep:latest",
)

for participant in participants:
    inputs = QSIPrepInputs(bids_dir=bids_root, participant=participant)
    result = run_qsiprep(inputs, config=BRAIN_BANK_QSIPREP)
    db.save_processing_record(result)

Validation & Audit

run_procedure() wraps any runner with pre-validation, post-validation, and a full audit trail:

from voxelops import run_procedure, HeudiconvInputs, HeudiconvDefaults

inputs = HeudiconvInputs(
    dicom_dir="/data/dicoms",
    participant="01",
    session="baseline",
)
config = HeudiconvDefaults(heuristic="/code/heuristic.py")

result = run_procedure("heudiconv", inputs, config)

# result.pre_validation  -- ValidationReport before execution
# result.post_validation -- ValidationReport after execution
# result.audit_log_file  -- path to the JSON audit log

Logging

All runners accept an optional log_dir parameter. When provided, an execution JSON log is written alongside any audit logs. The log directory defaults to <output_dir>/../logs derived from the inputs.

result = run_qsiprep(inputs, log_dir="/data/logs/qsiprep")

Documentation

Full documentation is available at voxelops.readthedocs.io.

License

MIT License – see the LICENSE file for details.