feat: add dataset-level registration QC summary with error decomposition

[ataha24]

Add a new regqc_summary rule that aggregates per-subject registration QC data into a single interactive HTML report. The report includes:

• Dataset summary statistics (mean/median/std ED, best/worst subject)
• Sortable per-subject table with hyperlinks to individual reports
• Registration error heatmap (subjects × AFIDs)
• ED distribution boxplots per AFID
• Mean ED bar chart per subject (colour-coded)
• 3D scatter of all subjects' AFIDs in MNI space
• Error decomposition: systematic bias vs random scatter per AFID
• 3D cone plot showing bias direction/magnitude at each AFID

The error decomposition separates registration error into a systematic component (mean signed error vector, consistent across subjects and potentially correctable) and a random component (standard deviation, the precision floor of the registration). This enables targeted diagnosis of registration pipeline failures.

Scalability: tested on 50 synthetic subjects (r=0.994 bias recovery, 5.1MB file size). Uses single-trace Plotly rendering and conditional boxpoints for efficient rendering at large N.

Files:

• NEW: autoafids/workflow/scripts/regqc_summary.py
• MOD: autoafids/workflow/rules/regqc.smk (regqc_summary rule)
• MOD: autoafids/workflow/Snakefile (wire into rule all)

Proposed changes

Describe the changes implemented in this pull request. If the changes fix a bug or resolves a feature request, be sure to link the issue. Please explain the issue and how the changes address the issue.

Types of changes

What types of changes does your code introduce? Put an x in the boxes that apply

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionalitiy)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation (non-breaking change which adds content to documentation)
• Other (if none of the other choices apply)

Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you are unsure about any of the choices, don't hesitate to ask!

• Changes have been tested to ensure that fix is effective or that a feature works.
• Changes pass the unit tests
• Changes pass the wet run tests
• Code has been run through the poe quality task
• I have included necessary documentation or comments (as necessary)
• Any dependent changes have been merged and published

Notes

All PRs will undergo unit and wet run testing before being reviewed. You may be requested to explain or make additional changes before the PR is accepted.

[Dhananjhay]

@ataha24 Any reason why the html file is stored in the dataset dir outside of the subject output?

config  dataset  logs  sub-RUN  work

[ataha24]

@ataha24 Any reason why the html file is stored in the dataset dir outside of the subject output?

config  dataset  logs  sub-RUN  work

Are you referring to the new html? That is dataset level summary (i.e., all subjects aggregated)! I am not sure how bids would organize that. Also we should think about how to name that based on dataset too. Would love your thoughts on this!

[Dhananjhay]

@ataha24 Any reason why the html file is stored in the dataset dir outside of the subject output?

config  dataset  logs  sub-RUN  work

Are you referring to the new html? That is dataset level summary (i.e., all subjects aggregated)! I am not sure how bids would organize that. Also we should think about how to name that based on dataset too. Would love your thoughts on this!

Yep! I was just wondering why isn't it inside sub-RUN/ses-preop/regqc dir?

[ataha24]

@ataha24 Any reason why the html file is stored in the dataset dir outside of the subject output?

config  dataset  logs  sub-RUN  work

Are you referring to the new html? That is dataset level summary (i.e., all subjects aggregated)! I am not sure how bids would organize that. Also we should think about how to name that based on dataset too. Would love your thoughts on this!

Yep! I was just wondering why isn't it inside sub-RUN/ses-preop/regqc dir?

Ahh, thats because it is produced from pooling the data across ALL subjects in the bids dataset. So, I am not sure the new html file should sit within a specific subject directory.