From d2276b3ab3631ab4d2326893e476b81ea8a9db5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20K=C3=BCgler?= Date: Thu, 20 Jun 2024 15:54:05 +0200 Subject: [PATCH] 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 | 4 +++- HypVINN/run_prediction.py | 4 ++-- README.md | 5 +++++ doc/scripts/advanced.rst | 12 ++++++++++++ doc/scripts/hypvinn.rst | 19 +++++++++++++++++++ doc/scripts/index.rst | 6 +----- doc/sphinx_ext/fix_links/resolve.py | 19 ++++++++++++++++--- 7 files changed, 58 insertions(+), 11 deletions(-) create mode 100644 doc/scripts/advanced.rst create mode 100644 doc/scripts/hypvinn.rst diff --git a/HypVINN/README.md b/HypVINN/README.md index 26bb4bbb..66ae036d 100644 --- a/HypVINN/README.md +++ b/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 diff --git a/HypVINN/run_prediction.py b/HypVINN/run_prediction.py index ce6736a9..b1b99cac 100644 --- a/HypVINN/run_prediction.py +++ b/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", ""): diff --git a/README.md b/README.md index 845b38a5..8eb33540 100644 --- a/README.md +++ b/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 `, 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). diff --git a/doc/scripts/advanced.rst b/doc/scripts/advanced.rst new file mode 100644 index 00000000..9b81150d --- /dev/null +++ b/doc/scripts/advanced.rst @@ -0,0 +1,12 @@ +Advanced scripts +================ + +.. toctree:: + :titlesonly: + + fastsurfercnn + cerebnet + hypvinn + recon_surf + segstats + util diff --git a/doc/scripts/hypvinn.rst b/doc/scripts/hypvinn.rst new file mode 100644 index 00000000..2dad15a0 --- /dev/null +++ b/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 diff --git a/doc/scripts/index.rst b/doc/scripts/index.rst index 9313265d..8835ff0b 100644 --- a/doc/scripts/index.rst +++ b/doc/scripts/index.rst @@ -4,9 +4,5 @@ Scripts .. toctree:: :maxdepth: 2 - fastsurfercnn - cerebnet - recon_surf SLURM.md - segstats - util + advanced diff --git a/doc/sphinx_ext/fix_links/resolve.py b/doc/sphinx_ext/fix_links/resolve.py index 5a412c5a..3e3c7d78 100644 --- a/doc/sphinx_ext/fix_links/resolve.py +++ b/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