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:** :func:`voxelops.run_heudiconv`
**Inputs:** :class:`voxelops.HeudiconvInputs`
**Configuration:** :class:`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 :func:`~voxelops.run_heudiconv` to automate the conversion within a Docker container.
4.  **Post-processing**: VoxelOps includes optional post-processing steps (see :func:`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:** :func:`voxelops.run_qsiprep`
**Inputs:** :class:`voxelops.QSIPrepInputs`
**Configuration:** :class:`voxelops.QSIPrepDefaults`

**Key Steps:**

1.  **BIDS Dataset**: Ensure you have a BIDS-compliant dataset, potentially generated by the Heudiconv workflow.
2.  **VoxelOps Execution**: Run :func:`~voxelops.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:** :func:`voxelops.run_qsirecon`
**Inputs:** :class:`voxelops.QSIReconInputs`
**Configuration:** :class:`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 :func:`~voxelops.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:** :func:`voxelops.run_qsiparc`
**Inputs:** :class:`voxelops.QSIParcInputs`
**Configuration:** :class:`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 :func:`~voxelops.run_qsiparc` to perform parcellation, generating TSV files with ROI-level metrics.

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

