vorig, ve2a, va2t QC blocks missing from APQC HTML in AFNI 26.1.01

AFNI Message Board
1

AFNI version info (afni -ver): AFNI_26.1.01, linux_openmp_64, May 05 2026
System: Ubuntu 24.04 Noble Numbat, x86_64

Problem:
After running afni_proc.py for resting state data, the APQC HTML report is missing the volumetric QC blocks: vorig, ve2a (EPI-to-anat alignment), and va2t (anat-to-template). Only the mot, regr, warns, and qsumm blocks appear.

The preprocessing itself completed without errors. The issue is only with the QC HTML generation.

What I found:
In out.ss_review_uvars.json, the align_anat entry points to a file that does not exist:
"align_anat": "sub-001_al_keep+orig.HEAD"

The actual alignment file in the results directory is:
sub-001_ses-01_T1w_al_junk+orig.HEAD

I also note that templ_vol is not present in the uvars JSON, only template.

I tried patching the uvars JSON manually to point to the correct file and adding templ_vol, then rerunning apqc_make_html.py, but the volumetric blocks still did not appear.

afni_proc.py command used:

afni_proc.py -subj_id sub-001 -copy_anat sub-001/ses-01/anat/sub-001_ses-01_T1w.nii.gz -dsets sub-001/ses-01/func/sub-001_ses-01_task-rest_bold.nii.gz -blocks tshift align tlrc volreg blur mask scale regress -radial_correlate_blocks tcat volreg regress -tcat_remove_first_trs 1 -align_unifize_epi local -align_opts_aea -cost lpc+ZZ -giant_move -check_flip -tlrc_base /home/rodtif/abin/MNI152_2009_template_SSW.nii.gz -tlrc_NL_warp -volreg_align_to MIN_OUTLIER -volreg_align_e2a -volreg_tlrc_warp -volreg_compute_tsnr yes -mask_epi_anat yes -blur_size 6 -regress_motion_per_run -regress_censor_motion 0.3 -regress_censor_outliers 0.05 -regress_apply_mot_types demean deriv -regress_bandpass 0.01 0.1 -regress_est_blur_epits -regress_est_blur_errts -regress_run_clustsim no -html_review_style pythonic -execute

Question:
Is the al_keep vs al_junk filename mismatch a known issue in 26.1.01? Is there a fix or workaround to get the volumetric QC blocks to appear in the HTML? Thank you!!

Update:
The .niivue.html files in the QC media folder contain only empty placeholder divs:

No NiiVue JavaScript or brain data references are present in these files.

2

Hello,
I ran your command but just changing the anat/EPI to those from our class data and it ran fully. So I must guess that perhaps the NIFTI file have an odd space in them, or you are using AFNI_NIFTI_VIEW.

What is the output from:

nifti_tool -disp_hdr                                                                \
           -infiles   sub-001/ses-01/anat/sub-001_ses-01_T1w.nii.gz                 \
                      sub-001/ses-01/func/sub-001_ses-01_task-rest_bold.nii.gz      \
           | grep form_code

afni -get_processed_env | grep NIFTI

That will show the q/sform_code fields of those input datasets. It might be the EPI that we are worried about, but we can see.
Then show any AFNI/NIFTI env vars set.

Thanks,

-rick

3

Hi-

In addition to Rick's comment, could you also just try running this command, and see if it gives an error or produces a set of 3 images:

@chauffer_afni -ulay DSET -prefix TEST_IMG

The DSET there can be any volumetric dataset, such as your anatomical T1w volume. Let's make sure that the program that makes the volumetric images has all dependencies installed, just to verify.

Also, for reference, this is your AP command with options vertically aligned, so it is easier to see in the webpage format here, for anyone reading it:

afni_proc.py                                                                 \
    -subj_id                  sub-001                                        \
    -copy_anat                sub-001/ses-01/anat/sub-001_ses-01_T1w.nii.gz  \
    -dsets                    sub-001/ses-01/func/sub-001_ses-01_task-rest_bold.nii.gz \
    -blocks                   tshift align tlrc volreg blur mask scale       \
                              regress                                        \
    -radial_correlate_blocks  tcat volreg regress                            \
    -tcat_remove_first_trs    1                                              \
    -align_unifize_epi        local                                          \
    -align_opts_aea           -cost lpc+ZZ                                   \
                              -giant_move                                    \
                              -check_flip                                    \
    -tlrc_base                /home/rodtif/abin/MNI152_2009_template_SSW.nii.gz \
    -tlrc_NL_warp                                                            \
    -volreg_align_to          MIN_OUTLIER                                    \
    -volreg_align_e2a                                                        \
    -volreg_tlrc_warp                                                        \
    -volreg_compute_tsnr      yes                                            \
    -mask_epi_anat            yes                                            \
    -blur_size                6                                              \
    -regress_motion_per_run                                                  \
    -regress_censor_motion    0.3                                            \
    -regress_censor_outliers  0.05                                           \
    -regress_apply_mot_types  demean deriv                                   \
    -regress_bandpass         0.01 0.1                                       \
    -regress_est_blur_epits                                                  \
    -regress_est_blur_errts                                                  \
    -regress_run_clustsim     no                                             \
    -html_review_style        pythonic                                       \
    -execute

Most of those options look good to go, and I might just comment (separately from the APQC HTML image considerations above) that:

  • we typically run sswarper2 to do skullstropining and nonlinear alignment to a template prior to running afni_proc.py, and then provide the results to the program. Not only does it do a better job of nonlinear warping than the default "auto_warp.py" that AP would use, but it also saves a lot of time when rerunning AP.
  • we typically don't recommend bandpassing to the standard LFF range during processing. It removes a lot of degrees of freedom, and there is still useful information above that cutoff (and many breathing/heartrate frequencies will still be aliased into the lower range, often).
  • we often include the -anat_has_skull .. option to explicitly state whether AP needs to do skullstripping or not on the anatomical. The default will be to do so, so that is fine here. But if/when you use sswarper2 to do so beforehand, you would then want to say -anat_has_skull yes

Each of these things are discussed in this description paper for afni_proc.py. You can search for "sswarper" in the text, and Appendix A describes more detail about the bandpassing considerations. And for what it's worth, there are many discussions of options and various considerations, with example commands shown/linked on GitHub, if that is helpful.

--pt

4

Hi Rick and Paul,

Thank you both for the quick and helpful responses.

Re: Rick's diagnostic

Here is the output from your requested commands:

nifti_tool -disp_hdr | grep form_code:
qform_code           252      1    1
sform_code           254      1    1
qform_code           252      1    1
sform_code           254      1    1

afni -get_processed_env | grep NIFTI:
(no output - no NIFTI environment variables set)

Rupate on the original QC HTML issue

I installed AFNI 25.2.03 on my system (using a tarball from a colleague). On my colleague's machine running 25.2.03, the QC HTML works correctly with all volumetric blocks. However on my system (Ubuntu 24.04, AMD GPU), the @chauffeur_afni image generation fails on both 25.2.03 and 26.1.01 due to the Xvfb crash described below. The result is that on my system, the QC HTML is missing volumetric images regardless of AFNI version.

@chauffeur_afni testing

Following Paul's suggestion, I ran the @chauffeur_afni test on both versions. It fails to produce images on our system on both 25.2.03 and 26.1.01. The script always attempts to start its own Xvfb virtual display, ignoring both DISPLAY=:0 and AFNI_DONT_USE_XVFB=YES. Xvfb crashes immediately with:

-- trying to start Xvfb :999
radeonsi: driver missing
(EE) Segmentation fault at address...
Fatal server error: Caught signal 11 (Segmentation fault). Server aborting
Error: Can't open display: :999

This occurs on Ubuntu 24.04 with an AMD GPU. Setting DISPLAY=:0 works fine for the AFNI GUI itself, but @chauffeur_afni ignores this and always launches its own Xvfb instance which then crashes.

Interestingly, despite this Xvfb failure, AFNI 25.2.03 still generates QC JPG images correctly and the HTML report looks complete. AFNI 26.1.01 fails entirely, likely because the new NiiVue-based QC system has a different image generation pathway that is more dependent on Xvfb working correctly.

Is there a way to force @chauffeur_afni to use the existing display :0 rather than spawning a new Xvfb? And is the Xvfb/AMD GPU crash a known issue on Ubuntu 24.04?

Re: Paul's recommendations

Thank you for pointing me to the paper regarding sswarper2 and bandpassing. I will review Appendix A carefully regarding the bandpass considerations before running my full cohort.

Thank you again for your time and help.

Best,
Tiffany

5

Also just as an aside, this is what i've come up with for the AP command given the suggestions:

Step 1: Run sswarper2 first (skullstripping + nonlinear alignment)

cd /media/rodtif/Lozano_12TB/TIFFANY/AFNI_TWH

sswarper2
-input sub-001/ses-01/anat/sub-001_ses-01_T1w.nii.gz
-base /home/rodtif/abin_25/MNI152_2009_template_SSW.nii.gz
-subid sub-001
-odir sub-001/sswarper_output

Step 2: Run afni_proc.py using sswarper2 results

afni_proc.py
-subj_id sub-001
-copy_anat sub-001/sswarper_output/anatSS.sub-001.nii
-anat_has_skull no
-dsets sub-001/ses-01/func/sub-001_ses-01_task-rest_bold.nii.gz
-blocks tshift align tlrc volreg blur mask scale regress
-radial_correlate_blocks tcat volreg regress
-tcat_remove_first_trs 1
-align_unifize_epi local
-align_opts_aea -cost lpc+ZZ -giant_move -check_flip
-tlrc_base /home/rodtif/abin_25/MNI152_2009_template_SSW.nii.gz
-tlrc_NL_warp
-tlrc_NL_warped_dsets sub-001/sswarper_output/anatQQ.sub-001.nii
sub-001/sswarper_output/anatQQ.sub-001.aff12.1D
sub-001/sswarper_output/anatQQ.sub-001_WARP.nii
-volreg_align_to MIN_OUTLIER
-volreg_align_e2a
-volreg_tlrc_warp
-volreg_compute_tsnr yes
-mask_epi_anat yes
-blur_size 6
-regress_motion_per_run
-regress_censor_motion 0.3
-regress_censor_outliers 0.05
-regress_apply_mot_types demean deriv
-regress_est_blur_epits
-regress_est_blur_errts
-regress_run_clustsim no
-html_review_style pythonic
-execute

6

Hi, Tiffany-

Perhaps we can target the @chauffer_afni crash first. It would help if you could please copy+paste the system check info:

afni_system_check.py -check_all

Also, are you working on a WSL (windows subsystem linux) version of Linux?

Also, @chauffeur_afni needs to use Xvfb. We should make sure that your system is fully set up for all codebase dependencies.

What is "AFNI_DONT_USE_XVFB"? It appears to be named like an AFNI environment variable, but that does not appear in the code base, nor in the online list.

--pt

7

Hi Paul,

Thank you for following up — and to answer your question, no, I'm not using WSL. This is native Ubuntu 24.04.

I actually managed to track down and fix the issue in the meantime, so I wanted to share it here in case it helps others. The afni_system_check.py output is below as well.

Root cause: Miniconda libtinfo conflict

The @chauffeur_afni image rendering was silently failing because Miniconda's libtinfo.so.6 was being picked up via LD_LIBRARY_PATH, overriding the system version. This caused every tcsh-based AFNI script (including @chauffeur_afni) to fail without producing an obvious error. The HTML skeleton was generated fine (Python-based), but the JPEG rendering step never completed. The telltale warning in the proc log was:

tcsh: /home/rodtif/miniconda3/lib/libtinfo.so.6: no version information available (required by tcsh)

To clarify your question about AFNI_DONT_USE_XVFB — you're right that it's not a real AFNI environment variable. I had come across it in a forum post while troubleshooting and tried it as a shot in the dark. It had no effect, which makes sense now.

The fix:

One-time fix for existing results:

cd sub-001.results
LD_LIBRARY_PATH="" tcsh -c 'foreach s (run_qc_*.tcsh); echo "== running $s =="; tcsh $s; end'
afni_open -b QC_sub-001/index.html

Permanent fix (added to ~/.bashrc):

export LD_LIBRARY_PATH=$(echo $LD_LIBRARY_PATH | tr ':' '\n' | grep -v miniconda3 | tr '\n' ':' | sed 's/:$//')

After sourcing ~/.bashrc, future afni_proc.py runs with -html_review_style pythonic produce complete reports automatically.

afni_system_check.py -check_all output:

-------------------------------- general ---------------------------------
architecture:         64bit ELF
cpu type:             x86_64
system:               Linux
release:              6.8.0-110-generic
distribution:         ubuntu 24.04 Noble Numbat
number of CPUs:       16
apparent login shell: bash

--------------------- AFNI and related program tests ---------------------
which afni           : /home/rodtif/abin_25/afni
afni version         : AFNI_25.2.03 'Gordian I'
which python         : /home/rodtif/miniconda3/bin/python
python version       : 3.13.9
which R              : /home/rodtif/miniconda3/bin/R
R version            : R version 4.4.1 (x86_64-conda-linux-gnu)

testing ability to start various programs...
    afni, suma, 3dSkullStrip, 3dAllineate, 3dRSFC, SurfMesh,
    3dClustSim, build_afni.py, uber_subject.py, 3dMVM,
    rPkgsInstall  : all success

** missing binary library 'libR.so' in program R_io.so

------------------------ dependent programs -----------------------------
which tcsh           : /usr/bin/tcsh (6.24.10)
which Xvfb           : /usr/bin/Xvfb

------------------------------ env vars --------------------------------
PATH = /home/rodtif/miniconda3/bin:...:/home/rodtif/abin_25
LD_LIBRARY_PATH = /home/rodtif/abin:
CONDA_DEFAULT_ENV = base

=========================  summary, please fix:  =========================
*  just be aware: login shell 'bash', but our code examples use 'tcsh'
*  missing binary library: libR.so
*  dot file test: want 2 modifications across 3 files
*  insufficient data for AFNI bootcamp

A couple of notes from the output: the LD_LIBRARY_PATH at the time of this check only shows /home/rodtif/abin: (not miniconda3), because I had already applied the permanent fix before running the check. The miniconda3 lib path was present before the fix.

Also noting the libR.so warning — is that something that would affect any resting-state preprocessing steps, or is it only relevant for R-based cluster simulations?

Thank you again for all the help and for pointing me toward @chauffeur_afni as the right place to look.

Best,
Tiffany

8

Hi, Tiffany-

Wow, that is really weird. I have never seen that issue come up with miniconda installs, thanks for troubleshooting it.

Re. your computer setup: did you follow the setup instructions here on the AFNI documentation? We typically don't install R through miniconda, for example. We just typically use the one distributed with the standard Ubuntu package manager (Aptitude). if you need to get a more modern version than what they have, for example, then there are instuctions online somewhere about doing that with a public key.

Also, we have miniconda instructions here for what resources might be needed via miniconda, but actually I don't know that Ubuntu even needs that. We typically just use miniconda for getting/managing Python libraries, but this can generally be done fine from the Ubuntu package manager (Aptitude), so it probably isn't even necessary.

--pt