FastSurfer Longitudinal Run: Missing aseg+DKT Outputs and Unexpected Differences vs Cross-sectional Output

[julii-a]

Question/Support Request

Hello,

I would like to ask whether my FastSurfer longitudinal processing was executed correctly.
After running the longitudinal pipeline, I noticed the following issues:

1. Do I need to run the cross-sectional processing separately first?

2. Missing aseg+DKT outputs
I expected aseg+DKT-related outputs (e.g., DKT parcellation combined with aseg), but those files were not generated in the output directory.

3. Longitudinal output is not the same as cross-sectional output
The longitudinal output is different from the cross-sectional output, but I am not sure whether the differences are expected or indicate an issue in the longitudinal processing.
Could you please confirm whether this behavior is expected, or if there may be an issue with my command / setup?

Additionally, I have a question regarding Docker permissions:

4. Root / user issue
I cannot run the container as root due to permission issues.
Is it required to run FastSurfer longitudinal as root, or is it fine to run it as a normal (non-root) user?
Thank you.

Screenshots / Log files

Please provide error messages (can be a screenshot), stack traces, log files (specifically $SUBJECTS_DIR/$SUBJECT_ID/scripts/deep-seg.log and $SUBJECTS_DIR/$SUBJECT_ID/scripts/recon-surf.log) and any snippets useful in describing your problem here.

/scripts/deep-seg

Log file for FastSurfer pipeline, run_fastsurfer.sh and segmentation(s)
python3.10 -s /fastsurfer/FastSurferCNN/run_prediction.py --t1 /output/sub-b001/long-inputs/sub-b001_b1/long_conform.nii.gz --asegdkt_segfile /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.mgz --conformed_name /output/sub-b001_b1/mri/orig.mgz --brainmask_name /output/sub-b001_b1/mri/mask.mgz --aseg_name /output/sub-b001_b1/mri/aseg.auto_noCCseg.mgz --sid sub-b001_b1 --seg_log /output/sub-b001_b1/scripts/deep-seg.log --vox_size min --batch_size 1 --viewagg_device auto --device auto --threads 1 --sd /output
[INFO: run_prediction.py:  647]: Checking or downloading default checkpoints ...
[INFO: common.py:  820]: Single subject with absolute file path for input.
[INFO: common.py:  878]: Analyzing single subject /output/sub-b001/long-inputs/sub-b001_b1/long_conform.nii.gz
[INFO: common.py:  979]: Output will be stored in Subjects Directory: /output
[INFO: common.py:  106]: Using device: cuda
[INFO: common.py:  106]: Using viewagg_device: cuda
[INFO: run_prediction.py:  245]: Running view aggregation on cuda
[INFO: inference.py:  200]: Loading checkpoint /fastsurfer/checkpoints/aparc_vinn_coronal_v2.0.0.pkl
[INFO: inference.py:  200]: Loading checkpoint /fastsurfer/checkpoints/aparc_vinn_sagittal_v2.0.0.pkl
[INFO: inference.py:  200]: Loading checkpoint /fastsurfer/checkpoints/aparc_vinn_axial_v2.0.0.pkl
[INFO: run_prediction.py:  324]: Successfully loaded image from /output/sub-b001/long-inputs/sub-b001_b1/long_conform.nii.gz.
[INFO: run_prediction.py:  441]: Output image directory /output/sub-b001_b1/mri/orig does not exist. Creating it now...
[INFO: run_prediction.py:  454]: Successfully saved image   as /output/sub-b001_b1/mri/orig/001.mgz.
[INFO: conform.py:  823]: The input image is not conformed.
[INFO: conform.py:  826]: A min-conformedconformed image must satisfy the following criteria:
[INFO: conform.py:  828]:  - Number of Dimensions 3        : True
[INFO: conform.py:  828]:  - Dimensions 256x256x256        : True
[INFO: conform.py:  828]:  - Voxel Size 1.0x1.0x1.0        : True
[INFO: conform.py:  828]:  - Orientation LIA               : True
[INFO: conform.py:  828]:  - Dtype uint8                   : BUT dtype int16
[INFO: run_prediction.py:  337]: Conforming image
[INFO: run_prediction.py:  454]: Successfully saved image   as /output/sub-b001_b1/mri/orig.mgz.
[INFO: run_prediction.py:  400]: Run coronal prediction
[INFO: dataset.py:   78]: Loading Coronal with input voxelsize (1.0, 1.0)
[INFO: inference.py:  408]: Inference on 256 batches for coronal successful
[INFO: inference.py:  469]: Coronal inference on /output/sub-b001/long-inputs/sub-b001_b1/long_conform.nii.gz finished in 10.2691 seconds
[INFO: run_prediction.py:  400]: Run sagittal prediction
[INFO: dataset.py:   69]: Loading Sagittal with input voxelsize (1.0, 1.0)
[INFO: inference.py:  408]: Inference on 256 batches for sagittal successful
[INFO: inference.py:  469]: Sagittal inference on /output/sub-b001/long-inputs/sub-b001_b1/long_conform.nii.gz finished in 10.3530 seconds
[INFO: run_prediction.py:  400]: Run axial prediction
[INFO: dataset.py:   74]: Loading Axial with input voxelsize (1.0, 1.0)
[INFO: inference.py:  408]: Inference on 256 batches for axial successful
[INFO: inference.py:  469]: Axial inference on /output/sub-b001/long-inputs/sub-b001_b1/long_conform.nii.gz finished in 10.0360 seconds
[INFO: run_prediction.py:  454]: Successfully saved image   as /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.mgz.
[INFO: run_prediction.py:  724]: Creating brainmask based on segmentation...
[INFO: run_prediction.py:  454]: Successfully saved image   as /output/sub-b001_b1/mri/mask.mgz.
[INFO: run_prediction.py:  743]: Creating aseg based on segmentation...
[INFO: run_prediction.py:  454]: Successfully saved image   as /output/sub-b001_b1/mri/aseg.auto_noCCseg.mgz.
[INFO: run_prediction.py:  762]: Running volume-based QC check on segmentation...
INFO: Running N4 bias-field correction...
python3.10 -s /fastsurfer/recon_surf/N4_bias_correct.py --in /output/sub-b001_b1/mri/orig.mgz --rescale /output/sub-b001_b1/mri/orig_nu.mgz --aseg /output/sub-b001_b1/mri/aseg.auto_noCCseg.mgz --threads 1

N4 Bias Correction Parameters:

- verbosity: -1
- input volume: /output/sub-b001_b1/mri/orig.mgz
- output volume: do not save
- rescaled volume: /output/sub-b001_b1/mri/orig_nu.mgz
- mask: default (>0)
- aseg: /output/sub-b001_b1/mri/aseg.auto_noCCseg.mgz
- shrink factor: 4
- number fitting levels: 4
- number iterations: 50
- convergence threshold: 0.0
- threads: 1
read MGZ (FreeSurfer) image via nibabel...
executing N4 correction ...
- mask: ones (default)
normalize WM to 105.0 (find WM from aseg)
read MGZ (FreeSurfer) image via nibabel...
- source white matter intensity: 70.51
- m: 1.4466
converting rescaled to UCHAR
writing PosixPath: /output/sub-b001_b1/mri/orig_nu.mgz
write MGZ (FreeSurfer) image via nibabel...
INFO: Running talairach registration...
/fastsurfer/recon_surf/talairach-reg.sh /output/sub-b001_b1/scripts/deep-seg.log --dir /output/sub-b001_b1/mri --conformed_name /output/sub-b001_b1/mri/orig.mgz --norm_name /output/sub-b001_b1/mri/orig_nu.mgz --long  --3T
ERROR: Talairach registration failed!
=========================================================
Start of the log for a new run_fastsurfer.sh invocation
=========================================================
Version: 2.4.2+7e53343
Fri Jan 23 04:46:55 UTC 2026

Log file for FastSurfer pipeline, run_fastsurfer.sh and segmentation(s)
INFO: Running run_fastsurfer.sh without segmentation pipeline;
  expecting previous --seg_only run in /output/sub-b001_b1.
WARNING: Found 7 files in subject directory $SUBJECTS_DIR/sub-b001_b1:
 Potentially Overwriting: ./mri/aparc.DKTatlas+aseg.deep.mgz ./mri/aseg.auto_noCCseg.mgz ./mri/mask.mgz ./mri/orig/001.mgz ./mri/orig.mgz ./mri/orig_nu.mgz ...
cd /fastsurfer/recon_surf
./recon-surf.sh --sid sub-b001_b1 --sd /output --t1 /output/sub-b001_b1/mri/orig.mgz --mask_name /output/sub-b001_b1/mri/mask.mgz --asegdkt_segfile /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.mgz --threads 2 --py python3.10\ -s --long sub-b001 --3T

/scripts/recon-surf

error in mid anterior detected - correcting...
writing aseg with callosum to /output/sub-b001_b1/mri/aseg.auto.mgz...
corpus callosum segmentation took 0.2 minutes
#VMPC# mri_cc VmPeak  172212
mri_cc done
@#@FSTIME  2026:01:23:04:47:48 mri_cc N 7 e 9.75 S 0.14 U 9.73 P 101% M 142780 F 0 R 63091 W 0 c 5 w 368 I 0 O 0 L 1.98 1.84 1.81
@#@FSLOADPOST 2026:01:23:04:47:57 mri_cc N 7 1.98 1.85 1.81
python3.10 -s /fastsurfer/recon_surf/paint_cc_into_pred.py -in_cc /output/sub-b001_b1/mri/aseg.auto.mgz -in_pred /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.mgz -out /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.withCC.mgz
@#@FSLOADPRE 2026:01:23:04:47:57 recon_surf/paint_cc_into_pred.py N 6 1.98 1.85 1.81
Reading inputs: /output/sub-b001_b1/mri/aseg.auto.mgz /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.mgz...
Writing segmentation with corpus callosum to: /output/sub-b001_b1/mri/aparc.DKTatlas+aseg.deep.withCC.mgz
@#@FSTIME  2026:01:23:04:47:57 recon_surf/paint_cc_into_pred.py N 6 e 0.54 S 0.10 U 0.41 P 94% M 129476 F 0 R 35797 W 0 c 11 w 1162 I 0 O 0 L 1.98 1.85 1.81
@#@FSLOADPOST 2026:01:23:04:47:58 recon_surf/paint_cc_into_pred.py N 6 1.98 1.85 1.81
 
========= Creating filled from brain (brainfinalsurfs, wm.asegedit, wm)  =======
 
recon-all -s sub-b001_b1 -asegmerge -normalization2 -maskbfs -segmentation -threads 2 -itkthreads 2
@#@FSLOADPRE 2026:01:23:04:47:58 recon-all N 10 1.98 1.85 1.81
fs-check-version --s sub-b001_b1 --o /tmp/tmp.fBCsf0
Fri Jan 23 04:47:58 UTC 2026

================= DONE =========================================================

Started at Fri Jan 23 04:46:56 UTC 2026
Ended   at Fri Jan 23 05:04:20 UTC 2026
#@#%# recon-surf-run-time-hours  0.000
recon-surf.sh sub-b001_b1 finished without error at Fri Jan 23 05:04:20 UTC 2026

/scripts/recon-all

ERROR: The binary /opt/freesurfer/bin/mri_motion_correct.fsl is not included, your call is forwarded to not-here.sh
ERROR: The binary /opt/freesurfer/bin/nu_correct is not included, your call is forwarded to not-here.sh

ERROR: The binary /opt/freesurfer/bin/mri_motion_correct.fsl is not included, your call is forwarded to not-here.sh
ERROR: The binary /opt/freesurfer/bin/mri_motion_correct.fsl is not included, your call is forwarded to not-here.sh

ERROR: The binary /opt/freesurfer/bin/nu_correct is not included, your call is forwarded to not-here.sh
ERROR: The binary /opt/freesurfer/bin/nu_correct is not included, your call is forwarded to not-here.sh

recon-all -s sub-b001_b1 finished without error at Fri Jan 23 04:50:11 UTC 2026
Started at Fri Jan 23 04:50:07 UTC 2026 
Ended   at Fri Jan 23 04:50:11 UTC 2026
#@#%# recon-all-run-time-hours 0.001
recon-all -s sub-b001_b1 finished without error at Fri Jan 23 04:50:11 UTC 2026

stats

mri

scripts

Environment

• FastSurfer Verions: 2.4.2
• Installation type: Docker
• FreeSurfer Version: 7.4.1
• OS: Windows

...

Execution

Include the command you used to run FastSurfer that cause the problem.

docker run --gpus all `
  --rm `
  --user 1000:1000 `
  -e FS_LICENSE=/fs_license/license.txt `
  -v "$FS_LICENSE:/fs_license/license.txt" `
  -v "D:/fastsurfer/test_long:/data" `
  -v "D:/fastsurfer/test_long/bl:/output" `
  --entrypoint "/fastsurfer/long_fastsurfer.sh" `
  deepmi/fastsurfer:latest `
  --fs_license /fs_license/license.txt `
  --tid "$tid" `
  --t1s "$t1_1" "$t1_2" `
  --tpids "$tp1id" "$tp2id" `
  --sd /output `
  --3T `
  --tal_reg `
  --parallel_surf max `
  --threads_surf 2

[m-reuter]

Hi Julii ,

1. the long_fastsurfer script does everything for you also the internal processing is different from FreeSurfer. In FreeSurfer you need to run the cross sectionals, the base (=tempalte creation) and the longitudinals manually. In FastSurfer we don't need cross sectionals as we merged some of that functionality into the template creation step. All of this is handeled by long_fastsurfer so no need to run cross.

2. I see the aparc.DKTatlas+aseg* files in your output mri directory. So which files are you missing?

3. Running fastsurfer individually (that is what you mean with cross sectional output I think) will of course give you different results than running it through the longitudinal pipeline. The longitudinal pipeline processes all images in the individual template spaces, initializes surfaces from the template etc. This produces more reliable and sensitive estimates compared to individual processing (the main reason why we created the longitudinal pipline :-)

4. running as normal user should be fine.

The other warning and even ERROR messages are OK, we should work on better output avoiding ERROR when it is in fact only a warning and not relevant here. So from my perspective everything looks fine. I did this in #771 for the error above.

[julii-a]

Thank you for your response.

I would like to clarify which files should be considered the final outputs for cross-sectional and longitudinal analyses, particularly with respect to volumetric (subcortical) and surface-based results.

Based on my understanding of the pipeline, I would appreciate clarification on the following points:

1. Cross-sectional analysis (volumetric / subcortical)
For cross-sectional volumetric analyses, is /stats/aseg.stats the correct final output file?
My understanding is that /stats/aseg+DKT is produced by the segmentation module, whereas /stats/aseg reflects the surface-module–refined volumetric estimates.

2. Cross-sectional analysis (volumetric&surface-based/ subcortical ROIs)
For subcortical structures (e.g., hippocampus), are the ROI volume values expected to be identical between /stats/aseg+DKT and /stats/aseg, or do they differ due to surface-module fine-tuning (such as partial volume correction or boundary refinement)?

3. Longitudinal analysis (volumetric&surface-based/ cortical)
For longitudinal cortical analyses, is /stats/lh.aparc.DKTatlas.mapped and /stats/rh.aparc.DKTatlas.mapped the correct final output generated by the surface module?
If so, is it appropriate to run longitudinal cortical analyses directly using these /stats/lh&rh.aparc.DKTatlas.mapped files?

4. Longitudinal analysis (volumetric&surface-based/ subcortical)
In the longitudinal pipeline, are the ROI values in /stats/aseg.presurf.hypos expected to be the same as those in the final /stats/aseg?
If not, could you clarify the differences between /stats/aseg.presurf and the /stats/aseg outputs, and how these should be interpreted for longitudinal analyses?

Thank you in advance for your clarification.

[m-reuter]

These are great questions (and show that we need to update our documentation to be more clear). Generally when looking at the output of the longitudinal stream you need to look into the directories of each time points (tID1, tID2 ..) and not in the templateID which will not have all regular outputs (as it is just used as a common space and for initialisation).

The documentation of the longitudinal processing is here: https://deep-mi.org/FastSurfer/dev/overview/LONG.html (but you probably knew that).

The documentation of the output files is here: https://deep-mi.org/FastSurfer/dev/overview/OUTPUT_FILES.html

1. yes. aseg is surface corrected while the aseg+DKT is directly after the segmentation at an earlier stage.

2. not totally sure, but the surface fine tuning could affect the volume of subcortical structures that touch the cortex (so could be true for hippocampus). Differences for subcortical structures should be 0 or small. We should double check which structures could change (if at all).

3. Yes, ?h.aparc.DKTatlas.mapped.stats are the final outputs of the surface module (both for independent and long processing)

4. We usually don't look at the presurf results. They are produces as in FreeSurfer during surface processing and are from steps before the final surface is used to clean the segmentation. For FreeSurfer recon-all steps (could be outdated) see https://surfer.nmr.mgh.harvard.edu/fswiki/ReconAllDevTable and not all these steps are run in FastSurfer. So the recommendation is to use the values from aseg.stats over those from presurf unless you have a good reason not to.

[julii-a]

Thank you very much for your kind and detailed explanation.

If possible, it might be helpful to add a dedicated section describing the longitudinal output files to the documentation at the link below, as this information is currently not clearly documented:https://deep-mi.org/FastSurfer/dev/overview/OUTPUT_FILES.html
I believe this addition could help users better understand and interpret the longitudinal outputs.

Thank you again for your time and assistance.

[m-reuter]

The general information about longitudinal processing is in the LONG.md file and there it says already that one should inspect tID1 etc which should have the same files as an independent run (so there should not be a difference between cross and long regarding output files at all). Maybe we can say that more clearly in LONG.md ? And we are planning to add more information on all output files created by FastSurfer in an expert-output file table.

Let me know if you mean something else or have an idea what information would have helped. Thanks.

[julii-a]

Thank you for the clarification. My understanding aligns with your explanation. As a junior researcher, I found the page
(https://deep-mi.org/FastSurfer/dev/overview/OUTPUT_FILES.html) to be particularly helpful, as the output files are clearly organized by module, which makes the overall pipeline easier to follow.

In my case, I expected /stats/aseg+DKT to be present in the longitudinal outputs as well, since it exists in the cross-sectional results. Based on this expectation, and on the description stating that there should be no differences between cross-sectional and longitudinal processing with respect to output files, I reported this issue. From the perspective of a beginner, even minor discrepancies in the output files can make it difficult to determine whether they indicate an error or are part of the intended and correct behavior.

For this reason, it might be helpful to include a dedicated section for longitudinal processing in
https://deep-mi.org/FastSurfer/dev/overview/OUTPUT_FILES.html, with a table documenting the expected output files not only for tID1, tID2, and related directories, but also for the template ID directory. Such documentation would make it easier for users to compare their own outputs against the expected results and to assess whether their processing completed successfully.

I appreciate your willingness to listen to even minor feedback, and I am grateful for your efforts.

[m-reuter]

Thanks. Just to clarify, the aseg+DKT are available in the long tID1 directories, correct? They should be. And I understand that the confusing part was that these are not available in the template. I think it would be good to add some information in both the OUTPU_FILES and in the LONG.

[m-reuter]

I updated the documentation on both pages. Will close the issue for now. Thanks for your information to help improve the documentation.