Documentation

- add comment paper vs. retrained weights.
- add hypothal module in main README
- fix sphinx errors
- add an additional message in fix_links to debug errors
- add the hypvinn script documentation

HypVINN/README.md

@@ -13,12 +13,14 @@ Hypothalamic subfields segmentation pipeline
 * EUDAT (FZ Jülich) data repository: https://b2share.fz-juelich.de/records/2af6da63d5c1414b832c1f606bbd068a
 * Zenodo data repository: https://zenodo.org/records/11184216
 
+Note: These weights (version 1.1) are retrained compared to paper ([version 1.0](https://b2share.fz-juelich.de/records/27ab0a28c11741558679c819d608f1e7)) for better rotation generalization, performance is equivalent.
+
 ### Pipeline Steps
 1. Registration (optional, only required for multi-modal input)
 2. Hypothalamus Segmentation
 
 ### Running the tool
-- The HypVINN output can be obtained by running the default  `run_fastsurfer.sh` script (for more information see [Fastsurfer documentation](../README.md)).
+- The HypVINN output can be obtained by running the default  `run_fastsurfer.sh` script (for more information see [FastSurfer documentation](../README.md)).
 - HypVINN can also be run independently by running `HypVINN/run_prediction.py`, however we recommend running the whole FastSurfer pipeline as it includes all the required pre-processing steps.
 - HypVINN has the following arguments:
 ### Input and output arguments

HypVINN/run_prediction.py

@@ -63,9 +63,9 @@ def optional_path(a: Path | str) -> Optional[Path]:
 
     Returns
     -------
-    Path, optional
+    Path, None
         The converted Path object.
-    f"""
+    """
     if isinstance(a, Path):
         return a
     if a.lower() in ("none", ""):

README.md

@@ -28,6 +28,11 @@ Modules (all run by default):
    - requires `asegdkt_segfile`, outputs cerebellar sub-segmentation with detailed WM/GM delineation.
    - requires a T1w image ([notes on input images](#requirements-to-input-images)), which will be resampled to 1mm isotropic images (no native high-res support).
    - calculates volume statistics corrected for partial volume effects (skipped if `--no_biasfield` is passed).
+3. `hypothal`: [HypVINN](HypVINN/README.md) for hypothalamus subsegmentation (deactivate with `no_hypothal`)
+   - outputs a hypothalamic subsegmentation including 3rd ventricle, c. mammilare, fornix and optic tracts.
+   - a T1w image is highly recommended ([notes on input images](#requirements-to-input-images)), supports high-res (up to 0.7mm, but experimental beyond that).
+   - allows the additional passing of a T2w image with `--t2 <path>`, which will be registered to the T1w image (see `--reg_mode` option).
+   - calculates volume statistics corrected for partial volume effects based on the T1w image (skipped if `--no_bias_field` is passed).
 
 ### Surface reconstruction
 - approximately 60-90 minutes, `--surf_only` runs only [the surface part](recon_surf/README.md).

doc/scripts/advanced.rst

@@ -0,0 +1,12 @@
+Advanced scripts
+================
+
+.. toctree::
+    :titlesonly:
+
+    fastsurfercnn
+    cerebnet
+    hypvinn
+    recon_surf
+    segstats
+    util

doc/scripts/hypvinn.rst

@@ -0,0 +1,19 @@
+HypVINN: run_prediction.py
+==========================
+
+.. note::
+   We recommend to run HypVINN with the standard `run_fastsurfer.sh` interfaces!
+
+The `HypVINN/run_prediction.py` script enables the inference with HypVINN. In most
+situations, it will be called from `run_fastsurfer.sh` a direct call to
+`HypVINN/run_prediction.py` is not needed.
+
+.. argparse::
+    :module: HypVINN.run_prediction
+    :func: option_parse
+    :prog: HypVINN/run_prediction.py
+
+
+.. include:: ../../HypVINN/README.md
+    :parser: fix_links.parser
+    :start-line: 1

doc/scripts/index.rst

@@ -4,9 +4,5 @@ Scripts
 .. toctree::
     :maxdepth: 2
 
-    fastsurfercnn
-    cerebnet
-    recon_surf
     SLURM.md
-    segstats
-    util
+    advanced

doc/sphinx_ext/fix_links/resolve.py

@@ -147,12 +147,13 @@ def resolve_xref(
                 if ref is not None:
                     return ref
 
-        source = f"/{relpath(target_path, env.srcdir)}{_uri_sep}{_uri_id}"
+        source = f"/{_uri_path}{_uri_sep}{_uri_id}"
         for key, (pat, repls) in subs.items():
             # if this search string does not match, try next
             if not pat.match(source):
                 continue
 
+            tries = []
             # iterate over different replacement options
             for repl in repls:
                 # repeatedly replace until no more changes are occur
@@ -173,12 +174,24 @@ def resolve_xref(
                 # check and return the reference, if it is valid
                 if ref is not None:
                     return ref
+
+                tries.append(str(replaced).lower())
             # if the pattern matched, but none of the replacements lead to a valid
             # reference
             logger.warning(
-                f"[fix_links] Could not find reference {node['reftarget']}!",
-                location=node.source,
+                f"[fix_links] Target '{source}' matched the pattern '{pat.pattern}', "
+                f"but could not be resolved by any of the replacements {tuple(tries)} "
+                f": {node['reftarget']}!",
+                location=loc(node),
             )
+
+        if env.included and _uri_path.startswith("../"):
+            logger.warning(
+                f"[fix_links] Could not find the external target {_uri_path} in "
+                f"included files, it is likely not included.",
+                location=loc(node),
+            )
+
         # restore the reftarget attribute
         node[attr] = uri
     # node["reftype"] = prev_type