Existing Workflows

VoxelOps is designed to facilitate common neuroimaging data processing workflows. This section outlines established workflows and how VoxelOps components can be integrated to build robust pipelines.

DICOM to BIDS Conversion (Heudiconv)

This workflow focuses on converting raw DICOM data into the Brain Imaging Data Structure (BIDS) format using Heudiconv. This is often the first step in any neuroimaging pipeline, ensuring standardized data organization.

Procedure: voxelops.run_heudiconv() Inputs: voxelops.HeudiconvInputs Configuration: voxelops.HeudiconvDefaults

Key Steps:

  1. Data Acquisition: Obtain DICOM data from MRI scanners.

  2. Heuristic Definition: Write a heuristic.py file to define how DICOM sequences map to BIDS entities.

  3. VoxelOps Execution: Use run_heudiconv() to automate the conversion within a Docker container.

  4. Post-processing: VoxelOps includes optional post-processing steps (see voxelops.utils.bids.post_process_heudiconv_output()) to refine BIDS outputs, such as adding IntendedFor fields to fieldmap JSONs.

Example: An example demonstrating the Heudiconv workflow can be found at examples/dicom_to_bids.py.

Diffusion MRI Preprocessing (QSIPrep)

After data is in BIDS format, QSIPrep is used for comprehensive preprocessing of diffusion MRI (dMRI) data. This involves motion correction, eddy current correction, susceptibility distortion correction, and co-registration to anatomical images.

Procedure: voxelops.run_qsiprep() Inputs: voxelops.QSIPrepInputs Configuration: voxelops.QSIPrepDefaults

Key Steps:

  1. BIDS Dataset: Ensure you have a BIDS-compliant dataset, potentially generated by the Heudiconv workflow.

  2. VoxelOps Execution: Run run_qsiprep() with your BIDS directory and participant labels. QSIPrep will generate preprocessed dMRI derivatives.

Example: Refer to examples/qsiprep.py and the Getting Started guide for a practical demonstration.

Diffusion Reconstruction & Connectivity (QSIRecon)

Following QSIPrep, QSIRecon performs advanced reconstruction of diffusion signals and calculates various connectivity measures.

Procedure: voxelops.run_qsirecon() Inputs: voxelops.QSIReconInputs Configuration: voxelops.QSIReconDefaults

Key Steps:

  1. QSIPrep Derivatives: QSIRecon requires outputs from QSIPrep.

  2. Reconstruction Specification: Define a recon_spec.yaml file detailing the desired reconstruction models (e.g., DSI, CSD) and processing steps.

  3. VoxelOps Execution: Use run_qsirecon() to execute QSIRecon, generating reconstructed images and connectivity matrices.

Example: See examples/qsirecon.py for an example of setting up and running a QSIRecon pipeline.

Parcellation (QSIParc)

The parcellate package, integrated through VoxelOps, allows for parcellation of QSIRecon outputs, creating region-of-interest (ROI) specific data.

Procedure: voxelops.run_qsiparc() Inputs: voxelops.QSIParcInputs Configuration: voxelops.QSIParcDefaults

Key Steps:

  1. QSIRecon Outputs: Ensure QSIRecon has been successfully run and its outputs are available.

  2. Atlas Selection: QSIParc can auto-discover atlases from your QSIRecon derivatives or you can explicitly specify them.

  3. VoxelOps Execution: Execute run_qsiparc() to perform parcellation, generating TSV files with ROI-level metrics.

Example: An example of running QSIParc is available in examples/qsiparc.py.