regqc feature

[ataha24]

Add Registration Quality Control (regqc) Feature

This PR adds a new regqc workflow to evaluate registration quality using anatomical fiducials (AFIDs). It supports derivatives from LEAD-DBS, and provides quantitative error metrics, interactive HTML visualizations, and transformed coordiante files.

---

✨ Features

• New Snakefile rule: regqc

  • Automatically runs if LEAD_DBS_DIR or FMRIPREP_DIR is specified
  • Outputs:
    • .html dashboard with interactive plots and MRI viewer
    • .csv file with dx/dy/dz/ED errors per AFID
    • .fcsv with transformed AFID coordinates

• Flexible input support

  • Handles:
    • LEAD-DBS warp fields (.nii.gz) and optional .mat affine transforms

• Interactive visual outputs

  • Plotly 3D scatter of predicted vs reference AFIDs
  • Toggleable heatmap of localization errors
  • Side-by-side slice views (axial, sagittal, coronal) with fade animations

• New script: regqc.py

  • Applies transforms to AFIDs
  • Computes errors (dx, dy, dz, ED)
  • Builds a summary dashboard using Plotly and Jinja2

• Config updates

  • Adds support for:
    • --LEAD-DBS-DIR
    • --FMRIPREP-DIR
    • templatet1w_lead, fcsv_mni_lead paths

---

✅ Validation

• Tested with multiple LEAD-DBS datasets
• Verified correct application of transforms and AFID alignment
• Confirmed output rendering in standalone HTML viewers
• Maintains compatibility with existing Snakebids structure

---

📁 Files Added / Modified

• workflow/rules/regqc.smk
• workflow/scripts/regqc.py
• config/snakebids.yml
• resources/tpl-MNI152NLin2009bAsym_res-01_T1w.nii.gz (skull stripped to meet GitHub file size req)
• resources/tpl-MNI152NLin2009bAsym_res-01_desc-groundtruth_afids.fcsv

---

⚠️ Non-Breaking Issues

• Support for fMRIPrep is not currently working as the workflow has no logic to handle (.h5) transforms
• Template used is set to default in either LeadDBS or fMRIPrep -- best to integrate AutoAFIDs with TemplateFlow and pull appropriate template based log files
• Parsing for registration matricies and warps is done in script and not via PyBIDS/Snakemake as certain directories may be conditional depending on how user applied LeadDBS or fMRIPrep.
• Could improve naming of derivative files to include space BIDS entity

---

🚨 Breaking Issues

• conda libararies are NOT updated in this PR (e.g., .yaml files in /env are still inherited from main branch). However, all installations (e.g., plotly) were performed using mamba/conda install.
• SimpleITK is used to apply deformable warps generated from LeadDBS.

[ataha24]

updated snakemake profile to use conda and utils.yaml to include needed packages

[Dhananjhay]

Hey @ataha24! Amazing work with this PR, can't wait to test it out! If you can add a little description of how to reproduce the results, it'd be awesome.

[ataha24]

In brief: when you run the workflow with the --LEAD-DBS-DIR flag and point to a typical leaddbs derivatives directory, you can think of this as a natural extension of Lead-DBS. The main purpose is to generate QC plots for the core registration step — typically the transformation of the T1w image to MNI space.

Currently, the workflow supports the default Lead-DBS template (MNI152NLin2009bAsym). We can extend support to additional templates by integrating with TemplateFlow for automated retrieval. The workflow relies on the gen_fcsv rule, which generates AFID coordinates used for the registration evaluation.

To reproduce the results:

Input: BIDS-compliant dataset with derivative Lead-DBS outputs. This is typically a derivatives directory called leaddbs that is provided from a LEAD-DBS run.

A typical run for the workflow would be:
autoafids <DATASET>/rawdata <DATASET>/derivatives/autoafids participant --LEAD-DBS-DIR <DATASET>/derivatives/leaddbs

**Note, the "rawdata" directory is also provided by Lead-DBS. It is just a BIDS dataset with various images used in the typical Lead-DBS analysis.

This run will output 3 files:

1. an fcsv file which is the coordinates (i.e., ones generated from gen_fcsv) transformed using LEAD-DBS generated warps to MNI space.
2. a csv file which represents the errors in the x,y,z dimentions and Euclidean distance between the .fcsv file and MNI template annotations (typically we get that from our resources directory)
3. an HTML file for QC of the registration error.

If you want some real data, I uploaded a full Lead-DBS dataset (n=1) here: https://drive.google.com/file/d/1vz5184Cp_U7pcBfL566PS5K-cQwRqW8Q/view?usp=sharing

[Dhananjhay]

Thanks for the detailed comment @ataha24. Will test this feature out and update this PR accordingly!

[Dhananjhay]

Hey @ataha24! The data you provided here: https://drive.google.com/file/d/1vz5184Cp_U7pcBfL566PS5K-cQwRqW8Q/view?usp=sharing doesn't have the necessary normalization folder in it and therefore when I try to run autoafids with this flag, I get an error:

InputFunctionException in rule regqc in file "/local/scratch/autoafids/autoafids/workflow/rules/regqc.smk", line 105:
Error:
  FileNotFoundError: No resampled image found for subject RUN in LEAD-DBS
Wildcards:
  subject=RUN
  session=preop
  acq=iso
Traceback:
  File "/local/scratch/autoafids/autoafids/workflow/rules/regqc.smk", line 114, in <lambda>
  File "/local/scratch/autoafids/autoafids/workflow/rules/regqc.smk", line 66, in get_resampled_im (rule regqc, line 105, /local/scratch/autoafids/autoafids/workflow/rules/regqc.smk)

[ataha24]

Hey @ataha24! The data you provided here: https://drive.google.com/file/d/1vz5184Cp_U7pcBfL566PS5K-cQwRqW8Q/view?usp=sharing doesn't have the necessary normalization folder in it and therefore when I try to run autoafids with this flag, I get an error:

InputFunctionException in rule regqc in file "/local/scratch/autoafids/autoafids/workflow/rules/regqc.smk", line 105:
Error:
  FileNotFoundError: No resampled image found for subject RUN in LEAD-DBS
Wildcards:
  subject=RUN
  session=preop
  acq=iso
Traceback:
  File "/local/scratch/autoafids/autoafids/workflow/rules/regqc.smk", line 114, in <lambda>
  File "/local/scratch/autoafids/autoafids/workflow/rules/regqc.smk", line 66, in get_resampled_im (rule regqc, line 105, /local/scratch/autoafids/autoafids/workflow/rules/regqc.smk)

@Dhananjhay -- just downloaded the zip folder and looks like it does have the normalization folder. WIill clone branch and give it a shot to see if issues arise

[Dhananjhay]

Ahh I figured it out. The problem wasn't the missing normalization folder (it's indeed there), but how you specify the path to leaddbs when running autoafids; it errors out if the path is relative and works fine if absolute, is that behaviour on purpose?

[Dhananjhay]

I was able to run an end to end pipeline with the regqc feature! I had to add some missing packages into the conda env to make it run though. I also added ants for testing! Amazing work as always @ataha24. Once we figure out the relative vs absolute path choice, this PR should be good to be merged!