FastSurfer output: NaNs for holes_lh/holes_rh and cc_size in FSQC

[julii-a]

Question/Support Request

Although fsqc finishes successfully without any error messages, I am still getting NaN values for the following variables: holes_lh, holes_rh, cc_size

My data are cross-sectional, and the recon-all.done file is present in each subject directory.

Following the guidance from this issue thread (#82), I checked the corresponding FastSurfer log output, and I can see the Euler number results for both hemispheres:

mris_euler_number ../surf/lh.orig.premesh 

euler # = v-e+f = 2g-2: 95232 - 285690 + 190460 = 2 --> 0 holes
      F =2V-4:          190460 = 190464-4 (0)
      2E=3F:            571380 = 571380 (0)

total defect index = 0
Sun Jan 18 10:30:45 UTC 2026


mris_euler_number ../surf/rh.orig.premesh 

euler # = v-e+f = 2g-2: 96823 - 290463 + 193642 = 2 --> 0 holes
      F =2V-4:          193642 = 193646-4 (0)
      2E=3F:            580926 = 580926 (0)

total defect index = 0
Sun Jan 18 10:31:10 UTC 2026

From my understanding, the --> 0 holes part indicates that the number of holes is zero for both hemispheres.
However, holes_lh and holes_rh are still reported as NaN in the fsqc output.

Could you please clarify:

1. Does the --> 0 holes output above indeed mean that the surface has 0 holes (and thus holes_lh/rh should be 0 rather than NaN)?

2. I am also getting cc_size = NaN. Is there a way to verify / extract the cc_size manually from FastSurfer(and also FreeSurfer) outputs (e.g., aseg.stats) in a way that matches how fsqc defines cc_size?

3. Is there a recommended way to obtain holes_lh/holes_rh, cc_size values correctly when using FastSurfer outputs?

Environment

• qatools-python Version: fsqc version 2.1.4
• OS: Windows 10 / Ubuntu 22.04
• FastSurfer Version: 2.4.2
• FreeSurfer: 7.4.1

[kdiers]

Hi, thanks for getting back to this issue.

After some inspection, the fundamental problem seems to be that the fsqc toolbox has missed some changes in FastSurfer output that were introduced with the FastSurfer 2.3.0 release. We will address this in an update of the fsqc toolbox to version 2.1.5 soon.

Regarding your questions:

1. Not quite, because this particular line refers to surface quality after topological fixing. What we report as holes_lh and holes_rh is the number of holes in the initial surfaces before the topology fixer is run. In that sense, the expected output for holes_lh and holes_rh might (and probably would) be different.

2. Internally, the cc_size is calculated as the sum across all CC_* structures in the aseg.stats file divided by the estimated intracranial volume: (CC_Posterior + CC_Mid_Posterior + CC_Central + CC_Mid_Anterior + CC_Anterior) / EstimatedTotalIntraCranialVol. This could be reimplemented after extracting these volume estimates from the aseg.stats file.

3. The recommended way will be updating to the upcoming 2.1.5. release of the toolbox. If that is difficult, these quantities can also be computed retroscpectively:

• for holes_lh, holes_rh: search the recon-all.log files for before topology correction, eno=.... eno is the so-called euler characteristic, from which the number of holes can be computed. A closed surface without holes will have an euler characteristic of 2, and each additional hole will decrease this number by -2 if I remember correcty.
• for cc_size, see answer to 2)

Hope this helps for the moment, and let us know if anything else should be clarified. The update to version 2.1.5 can probably be expected within this week.

[kdiers]

This issue has been addressed with pull request #92, and is now fixed in release 2.1.5 of the software.

[julii-a]

This issue has been addressed with pull request #92, and is now fixed in release 2.1.5 of the software.

Hello, I am running fsqc v2.1.5 on FastSurfer outputs and consistently get a topology check error for all subjects, even though the surface files appear valid.

Command
run_fsqc --subjects_dir /mnt/d/fastsurfer/test_all --output_dir /mnt/d/fastsurfer/all --fastsurfer

Error message
For each subject (e.g., sub-013_ses-2), I get:

ERROR: Topology check failed for sub-013_ses-2
Reason: File does not appear to be a Freesurfer surface (triangle file)

Resulting metrics
The topology-related metrics are all NaN:
holes_lh, holes_rh, defects_lh, defects_rh, topo_lh, topo_rh

Additional info
fsqc version: 2.1.5
FastSurfer Version: 2.4.2

Surfaces exist in the subject directory (e.g., surf/lh.white, surf/lh.orig, surf/lh.pial.T1, etc.). Other checks (SNR, contrast, rotation angles, etc.) run successfully; only the topology step fails.

Thank you.

[kdiers]

Hi, thanks for the feedback!

I speculate this is due to the version of a dependency package:

Could you check which version of the lapy package is currently installed? I have just seen that this error occurs for lapy versions <1.1.1, but should not happen for lapy==1.1.1 or newer.

The fsqc requirements.txt file currently still specifies lapy>=1.0.0, so we'll fix this as soon as possible.

[julii-a]

Thank you so much for your quick response. I just ran a test, and the NaN issue has been resolved. I really appreciate your help.

I was also wondering if you have any guidance on how to perform quality checks using FSQC. If there are any recommended references or documentation, I would really appreciate it.

[kdiers]

Thanks for your reporting as well, this also helps a lot.

We currently do not have, unfortunately, a dedicated tutorial or similar besides the documentation.

The general idea is that the fsqc tools cannot replace visual inspection, but can hopefully make it easier. The various screenshots may help with this. For the metrics that we report, there are typically no hard cut-offs to determine failure; what I'd recommend to do is to look at the distributions of these metrics in your sample, check for outliers, and potentially inspect these cases more closely using a program like Freeview or similar.

[julii-a]

Thank you. I appreciate the developers for providing the documentation and making the tool available.

[julii-a]

I would like to ask again. In longitudinal FastSurfer, NaNs(holes_lh, holes_rh, defects_lh, defects_rh, topo_lh, topo_rh) are also occurring, and I would like to know whether this situation corresponds to the issue described here:
#70

As far as I understand, FastSurfer does not perform cross-sectional processing first and then longitudinal processing. Rather, in the longitudinal pipeline, processing is performed simultaneously within a single workflow, rather than as a separate or analogous cross-sectional step. I understand this to be different from FreeSurfer’s longitudinal pipeline, in which cross-sectional processing is performed first and then used as the basis for longitudinal processing.

In such a case, I would like to ask whether QC is still performed using cross-sectional results generated separately. I am also wondering whether there is any need to run longitudinal FSQC separately.

Thank you for your assistance.

[kdiers]

Yes, the situation is similar to what is described in the referenced issue.

Specifically, no topology fixing is done for surfaces of individual time points in the FastSurfer longitudinal stream. This is because the individual time point surfaces are initialized with the surfaces from the base template. Therefore, the topology-related information is not present in the log files of individual time points, and NaNs would be expected in this scenario.

You're also right that the longitudinal stream is run somewhat dfferently in FastSurfer than in FreeSurfer.

Regarding your question, it does not hurt to do QC on separately processed cross-sectional cases, since issues could be expected to show up for both long- and cross-sectional processing, especially if they are profound. But cross-sectional QC should not completely substitute longitudinal QC, and it's not necessary to do cross-sectional processing just for the purpose of QC.

In that sense, some longitudinal QC is a good idea, and this should include both the person-specific template as well as the individual time points.

[julii-a]

Thank you for your reply.

Just to confirm my understanding: topology-related issues(e.g., holes_lh, holes_rh, defects_lh, defects_rh, topo_lh, topo_rh) should be assessed using the cross-sectional results, while the remaining longitudinal processing quality checks should be performed within the longitudinal stream itself, including review of the subject-specific template and consistency across individual time points.

[m-reuter]

In the longitudinal pipeline surfaces are only looked at in the long and in the template. Surfaces are created in the template (including topology fix) and then fine-tuned in each time point. FastSurfer does not produce surfaces cross sectionally when running the longitudinal pipeline and in FreeSurfer these are created, but never analyzed or looked at.
Since the subject-wise template is usually higher qulity (as it incorporates information from all time points) it should have less issues than individual time points, which can have stronger signal loss or motion artifacts. Not sure how the topological related metrics are of value in the template. In the long time points, they will be nan, as no additional topology fixing is necessary.

[julii-a]

In the longitudinal pipeline surfaces are only looked at in the long and in the template. Surfaces are created in the template (including topology fix) and then fine-tuned in each time point. FastSurfer does not produce surfaces cross sectionally when running the longitudinal pipeline and in FreeSurfer these are created, but never analyzed or looked at. Since the subject-wise template is usually higher qulity (as it incorporates information from all time points) it should have less issues than individual time points, which can have stronger signal loss or motion artifacts. Not sure how the topological related metrics are of value in the template. In the long time points, they will be nan, as no additional topology fixing is necessary.

In issue #70, I saw your response recommending that the subject-specific template should be checked when surfaces appear problematic in the longitudinal stream. I also read through the discussion there, including the explanation that topology fixing is performed only at the template level.

Since FSQC does not appear to be run for the template ID in the longitudinal analysis, I would like to ask more concretely how template-level QC is typically performed.

In particular, I would appreciate your guidance on the following points:
Which files in the template directory are most important to inspect for QC, and How this inspection is typically performed in practice (for example, visual inspection using Freeview).

For example, is it generally sufficient to visually inspect, using Freeview, segmentation results such as templateID/mri/aseg.auto.mgz and templateID/mri/aparc.DKTatlas+aseg.deep.mgz in the template directory?
In other words, is visually checking these files usually considered adequate for template QC, or are there other specific files or concrete checks that you would recommend for assessing template quality (for example, overlaying certain results on T1.mgz)?

If there is any official guideline or documentation describing recommended QC procedures for FastSurfer longitudinal templates, I would be grateful if you could point me to it.
If not, I would very much appreciate your recommended or commonly used approach (for example, which structures or failure modes are most important to verify).

Thank you very much for your time and clarification.

[m-reuter]

Sure, these are good questions.
You would not check the segmentations in the template, these are re-created in the longitudinal time points.
Things that can be checked in the template (some of this can also be manually corrected with edits there):

• skull strip (make sure masks are large enough to not crop brain areas)
• talairach registration (if eTIV values seem wrong, as these are taken from the talairach registration in the template)
• alignment of the longitudinal images to the template (e.g. all norm.mgz files are aligned in template space)
• placement of white and pial surfaces (to make sure that WM strands are not missed, and that large chuncks of dura do not get included in pial surface.

I think these are the main things. Inspection would be in freeview as described also in the FreeSurfer tutorials.

[julii-a]

Sure, these are good questions. You would not check the segmentations in the template, these are re-created in the longitudinal time points. Things that can be checked in the template (some of this can also be manually corrected with edits there):

• skull strip (make sure masks are large enough to not crop brain areas)
• talairach registration (if eTIV values seem wrong, as these are taken from the talairach registration in the template)
• alignment of the longitudinal images to the template (e.g. all norm.mgz files are aligned in template space)
• placement of white and pial surfaces (to make sure that WM strands are not missed, and that large chuncks of dura do not get included in pial surface.

I think these are the main things. Inspection would be in freeview as described also in the FreeSurfer tutorials.

Thank you for your response. If there is an issue with the template’s pial, would it be better to manually edit it, or can it be addressed by adjusting each time point separately?
Also, within the template, if the segmentation is correct and the issue exists only in the pial surface, is it sufficient to modify only the pial?
If the pial issue within the template is caused by the white matter being incorrectly captured, should the white matter be corrected instead in the template?