Fixes to the documentation.

- slurm-help: does not change between different runs (on github actions)
- most documentation files

Docker/README.md

@@ -20,6 +20,27 @@ docker pull deepmi/fastsurfer:cpu-v2.2.2
 ### Running the official Docker Image
 After pulling the image, you can start a FastSurfer container and process a T1-weighted image (both segmentation and surface reconstruction) with the following command:
 
+```bash
+docker run --gpus all \
+         -B /share/my/my/mri_data \
+         -B /share/my/fastsurfer_analysis \
+         -B /share/software/freesurfer/license.txt:/.fslicense \
+         --rm --user $(id -u):$(id -g) \
+         deepmi/fastsurfer:cuda-v2.3.0 \
+         --t1 /share/my/mri_data/participant1/image1.nii.gz \
+         --sd /share/my/fastsurfer_analysis \
+         --sid part1_img1 \
+         --fs_license /.fslicense
+```
+
+
+   The `--gpus` flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).
+
+   The `-v` flag is used to tell docker, which folders FastSurfer can read and write to.
+
+
+
+
 ```bash
 docker run --gpus all -v /home/user/my_mri_data:/data \
                       -v /home/user/my_fastsurfer_analysis:/output \

README.md

@@ -60,53 +60,61 @@ We recommended you use Singularity or Docker on a Linux host system with a GPU.
 
 ### Usage
 
-All installation methods use the `run_fastsurfer.sh` call interface (replace `*fastsurfer-flags*` with [FastSurfer flags](doc/overview/FLAGS.md#required-arguments)), which is the general starting point for FastSurfer. However, there are different ways to call this script depending on the installation, which we explain here:
-
-1. For container installations, you need to define the hardware and mount the folders with the input (`/data`) and output data (`/output`):  
-   (a) For __singularity__, the syntax is 
-    ```
-    singularity exec --nv \
-                     --no-home \
-                     -B /home/user/my_mri_data:/data \
-                     -B /home/user/my_fastsurfer_analysis:/output \
-                     -B /home/user/my_fs_license_dir:/fs_license \
-                     ./fastsurfer-gpu.sif \
-                     /fastsurfer/run_fastsurfer.sh 
-                     *fastsurfer-flags*
-   ```
-   The `--nv` flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).
-
-   The `--no-home` flag tells singularity to not mount the home directory (see [Singularity documentation](Singularity/README.md#mounting-home) for more info).
-
-   The `-B` flag is used to tell singularity, which folders FastSurfer can read and write to.
+All installation methods use the `run_fastsurfer.sh` call interface (replace the placeholder `<*fastsurfer-flags*>` with [FastSurfer flags](doc/scripts/RUN_FASTSURFER.md#required-arguments)), which is the general starting point for FastSurfer. However, there are different ways to call this script depending on the installation, which we explain here:
+
+1. For container installations, you need to set up the container (`<*singularity-flags*>` or `<*docker-flags*>`) in addition to the `<*fastsurfer-flags*>`:  
+   1. For __Singularity__, the syntax is
+
+      ```bash
+      singularity run <*singularity-flags*> \
+                      fastsurfer.sif \
+                      <*fastsurfer-flags*>
+      ```
+      This command has two placeholders for flags: `<*singularity-flags*>` and `<*fastsurfer-flags*>`.
+      `<*singularity-flags*>` [sets up the singularity environment](doc/overview/SINGULARITY.md), `<*fastsurfer-flags*>` includes the options that determine the [behavior of FastSurfer](doc/scripts/RUN_FASTSURFER.md):
+      ### Basic FastSurfer Flags
+      - `--t1`: the path to the image to process.
+      - `--sd`: the path to the "Subject Directory", where all results will be stored.
+      - `--sid`: the identified for the results for this image (folder inside of "Subject Directory").
+      - `--fs_license`: path to the FreeSurfer license file.
+
+      An example for a simple full FastSurfer-Singularity command is
+      ```bash
+      singularity run --nv \
+                      -B /share/my/my/mri_data \
+                      -B /share/my/fastsurfer_analysis \
+                      -B /share/software/freesurfer/license.txt:/.fslicense \
+                      fastsurfer.sif \
+                      --t1 /share/my/mri_data/participant1/image1.nii.gz \
+                      --sd /share/my/fastsurfer_analysis \
+                      --sid part1_img1 \
+                      --fs_license /.fslicense
+      ```
+
+      See also __[Example 2](doc/overview/EXAMPLES.md#example-2-fastsurfer-singularity)__ for a full singularity FastSurfer run command and [the Singularity documentation](doc/overview/SINGULARITY.md#fastsurfer-singularity-image-usage) for details on more singularity flags and how to create the `fastsurfer.sif` file.  
+
+   b. For __docker__, the syntax is
+      ```bash
+      docker run <*docker-flags*> \
+                 deepmi/fastsurfer:<device>-v<version> \
+                 <*fastsurfer-flags*>
+      ```
+
+      The options for `<*docker-flags*>` and `<*fastsurfer-flags*>` follow very similar patterns as for Singularity.
 
-   See also __[Example 2](doc/overview/EXAMPLES.md#example-2-fastsurfer-singularity)__ for a full singularity FastSurfer run command and [the Singularity documentation](Singularity/README.md#fastsurfer-singularity-image-usage) for details on more singularity flags.  
-
-   (b) For __docker__, the syntax is
-    ```
-    docker run --gpus all \
-               -v /home/user/my_mri_data:/data \
-               -v /home/user/my_fastsurfer_analysis:/output \
-               -v /home/user/my_fs_license_dir:/fs_license \
-               --rm --user $(id -u):$(id -g) \
-               deepmi/fastsurfer:latest \
-               *fastsurfer-flags*
-    ```
-   The `--gpus` flag is needed to allow FastSurfer to run on the GPU (otherwise FastSurfer will run on the CPU).
-
-   The `-v` flag is used to tell docker, which folders FastSurfer can read and write to.
-
-   See also __[Example 1](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker)__ for a full FastSurfer run inside a Docker container and [the Docker documentation](Docker/README.md#docker-flags) for more details on the docker flags including `--rm` and `--user`.
+      See also __[Example 1](doc/overview/EXAMPLES.md#example-1-fastsurfer-docker)__ for a full FastSurfer run inside a Docker container and [the Docker documentation](Docker/README.md#docker-flags) for more details on `*docker flags*` and the naming of docker images (`<device>-v<version>`).
 
 2. For a __native install__, you need to activate your FastSurfer environment (e.g. `conda activate fastsurfer_gpu`) and make sure you have added the FastSurfer path to your `PYTHONPATH` variable, e.g. `export PYTHONPATH=$(pwd)`. 
 
-   You will then be able to run fastsurfer with `./run_fastsurfer.sh *fastsurfer-flags*`.
+   You will then be able to run fastsurfer with `./run_fastsurfer.sh <*fastsurfer-flags*>`.
 
    See also [Example 3](doc/overview/EXAMPLES.md#example-3-native-fastsurfer-on-subjectx-with-parallel-processing-of-hemis) for an illustration of the commands to run the entire FastSurfer pipeline (FastSurferCNN + recon-surf) natively.
 
 <!-- start of flags -->
 ### FastSurfer_Flags
-Please refer to [FASTSURFER_FLAGS](doc/overview/FLAGS.md).
+Replace the placeholder `<*fastsurfer-flags*>` with your options. Please see the Examples below for some example flags.
+
+For a detailed explanation of FastSurfer's options (`<*fastsurfer-flags*>`), please refer to [FASTSURFER_FLAGS](doc/scripts/RUN_FASTSURFER.md).
 
 
 ## Examples

doc/overview/EXAMPLES.md

@@ -41,7 +41,7 @@ A directory with the name as specified in `--sid` (here subjectX) will be create
 If you do not have a GPU, you can also run our CPU-Docker by dropping the `--gpus all` flag and specifying `--device cpu` at the end as a FastSurfer flag, see also [FastSurfer's docker documentation](../../Docker/README.md) for more details.
 
 ## Example 2: FastSurfer Singularity
-After building the Singularity image (see below or [these instructions](../../Singularity/README.md)), you also need to register at the FreeSurfer website (https://surfer.nmr.mgh.harvard.edu/registration.html) to acquire a valid license (for free) - same as when using Docker. This license needs to be passed to the script via the `--fs_license` flag. This is not necessary if you want to run the segmentation only.
+After building the Singularity image (see below or [these instructions](README.md)), you also need to register at the FreeSurfer website (https://surfer.nmr.mgh.harvard.edu/registration.html) to acquire a valid license (for free) - same as when using Docker. This license needs to be passed to the script via the `--fs_license` flag. This is not necessary if you want to run the segmentation only.
 
 To run FastSurfer on a given subject using the Singularity image with GPU access, execute the following commands from a directory where you want to store singularity images. This will create a singularity image from our Dockerhub image and execute it:
 

doc/overview/INSTALL.md

@@ -22,9 +22,9 @@ Assuming you have singularity installed already (by a system admin), you can bui
 ```bash
 singularity build fastsurfer-gpu.sif docker://deepmi/fastsurfer:latest
 ```
-Additionally, [the Singularity README](../../Singularity/README.md) contains detailed directions for building your own Singularity images from Docker.
+Additionally, [the Singularity README](README.md) contains detailed directions for building your own Singularity images from Docker.
 
-[Example 2](EXAMPLES.md#example-2-fastsurfer-singularity) explains how to run FastSurfer (for the full pipeline you will also need a FreeSurfer .license file!) and you can find details on how to build your own images here: [Docker](../../Docker/README.md) and [Singularity](../../Singularity/README.md). 
+[Example 2](EXAMPLES.md#example-2-fastsurfer-singularity) explains how to run FastSurfer (for the full pipeline you will also need a FreeSurfer .license file!) and you can find details on how to build your own images here: [Docker](../../Docker/README.md) and [Singularity](README.md). 
 
 
 ### Docker
@@ -130,12 +130,12 @@ Build the Docker container with ROCm support.
 python Docker/build.py --device rocm --tag my_fastsurfer:rocm
 ```
 
-You will need to add a couple of flags to your docker run command for AMD, see [Example 1](EXAMPLES.md#example-1-fastsurfer-docker) for `**other-docker-flags**` or `**fastsurfer-flags**`:
+You will need to add a couple of flags to your docker run command for AMD, see [Example 1](EXAMPLES.md#example-1-fastsurfer-docker) for `**other-docker-flags**` or `*<*fastsurfer-flags*>*`:
 ```bash
 docker run --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --device=/dev/kfd \
         --device=/dev/dri --group-add video --ipc=host --shm-size 8G \
         **other-docker-flags** my_fastsurfer:rocm \
-                **fastsurfer-flags**
+                *<*fastsurfer-flags*>*
 ```
 Note, that this docker image is experimental, uses a different Python version and python packages, so results can differ from our validation results. Please do visual QC.
 

Singularity/README.md → doc/overview/SINGULARITY.md

@@ -1,5 +1,18 @@
 # FastSurfer Singularity Support
 
+
+## Sandbox
+
+
+## 
+
+`<*singularity-flags*>` includes flags that set up the singularity container:
+- `--nv`: enable nVidia GPUs in Singularity (otherwise FastSurfer will run on the CPU),
+- `-B <path>`: is used to share data between the host and Singularity (only paths listed here will be available to FastSurfer, see [Singularity documentation](doc/overview/README.md#sandbox) for more info).
+  This should specifically include the "Subject Directory". If two paths are given like `-B /my/path/host:/other`, this means `/my/path/host/somefile` will be accessible inside Singularity in directory as `/other/somefile`.  
+
+
+
 For use on HPCs (or in other cases where Docker is not available or preferred) you can easily create a Singularity image from the Docker image. 
 Singularity uses its own image format, so the Docker images must be converted (we publish our releases as docker images available on [Dockerhub](https://hub.docker.com/r/deepmi/fastsurfer/tags)). 
 
@@ -21,7 +34,7 @@ If you want to manually convert the local Docker image `fastsurfer:myimage`, run
 singularity build /home/user/my_singlarity_images/fastsurfer-myimage.sif docker-daemon://fastsurfer:myimage
 ```
 
-For more information on how to create your own Docker images, see our [Docker guide](../Docker/README.md).
+For more information on how to create your own Docker images, see our [Docker guide](../../Docker/README.md).
 
 ## FastSurfer Singularity Image Usage
 

doc/overview/index.rst

@@ -7,10 +7,9 @@ User Guide
     intro
     INSTALL.md
     EXAMPLES.md
-    FLAGS.md
     OUTPUT_FILES.md
     docker
-    singularity
+    SINGULARITY.md
     EDITING.md
     SECURITY.md
     CODE_OF_CONDUCT.md

doc/overview/FLAGS.md → doc/scripts/RUN_FASTSURFER.md

@@ -1,10 +1,14 @@
-# Flags
-Next, you will need to select the `*fastsurfer-flags*` and replace `*fastsurfer-flags*` with your options. Please see the Examples below for some example flags.
+run_fastsurfer.sh
+=================
 
-The `*fastsurfer-flags*` will usually include the subject directory (`--sd`; Note, this will be the mounted path - `/output` - for containers), the subject name/id (`--sid`) and the path to the input image (`--t1`). For example:
+`run_fastsurfer.sh` is the central command of FastSurfer. In general, `run_fastsurfer.sh` is called once for each T1w MRI image that is to be processed and each call will result in one "Subject Folder" with segmentation maps, surfaces and statistics tables. If you want to process multiple images, you can either loop through the images yourself or use [brun_fastsurfer.sh](BATCH.md) or [srun_fastsurfer.sh](SLURM.md), which are multi-subject extensions to `run_fastsurfer.sh`.
+
+On this page, we explain FastSurfer's options, usually referred to as `<*fastsurfer-flags*>` in this documentation. 
+
+The `<*fastsurfer-flags*>` will usually include the subject directory (`--sd`; Note, this will be the mounted path - `/output` - for containers), the subject name/id (`--sid`) and the path to the input image (`--t1`). For example:
 
 ```bash
-... --sd /output --sid test_subject --t1 /data/test_subject_t1.nii.gz --3T
+$FASTSURFER_HOME/run_fastsurfer.sh --sd /output --sid test_subject --t1 /data/test_subject_t1.nii.gz --3T
 ```
 Additionally, you can use `--seg_only` or `--surf_only` to only run a part of the pipeline or `--no_biasfield`, `--no_cereb` and `--no_asegdkt` to switch off some segmentation modules (see above).
 Here, we have also added the `--3T` flag, which tells fastsurfer to register against the 3T atlas for ICV estimation (eTIV).
@@ -55,3 +59,10 @@ In the following, we give an overview of the most important options, but you can
 * `--conformed_name`: Name of the file in which the conformed input image will be saved. Default location: \$SUBJECTS_DIR/\$sid/mri/orig.mgz
 * `--ignore_fs_version`: Switch on to avoid check for FreeSurfer version. Program will terminate if the supported version (see recon-surf.sh) is not sourced. Can be used for testing dev versions.
 * `-h`, `--help`: Prints help text
+
+Usage
+-----
+
+```{command-output} ./run_fastsurfer.sh --help
+:cwd: /../
+```

doc/scripts/index.rst

@@ -4,6 +4,7 @@ Scripts
 .. toctree::
     :maxdepth: 2
 
+    RUN_FASTSURFER.md
     BATCH.md
     SLURM.md
     advanced

recon_surf/README.md

@@ -92,7 +92,7 @@ Check [Dockerhub](https://hub.docker.com/r/deepmi/fastsurfer/tags) to find out t
 ### Singularity Flags: 
 * The `-B` commands mount your output, and directory with the FreeSurfer license file into the Singularity container. Inside the container these are visible under the name following the colon (in this case /data, /output, and /fs_license). 
 
-* The `--no-home` command disables the automatic mount of the users home directory (see [Best Practice](../Singularity/README.md#mounting-home))
+* The `--no-home` command disables the automatic mount of the users home directory (see [Best Practice](../doc/overview/README.md#mounting-home))
 
 The `--t1` and `--asegdkt_segfile` flags point to the already existing conformed T1 input and segmentation from the segmentation module. Also other files from that pipeline
 will be reused (e.g. the `mask.mgz`, `orig_nu.mgz`). The subject directory will then be populated with the FreeSurfer file structure, including surfaces, statistics 

srun_fastsurfer.sh

@@ -86,14 +86,14 @@ Data- and subject-related options:
   Note: files will be copied here only after all jobs have finished, so most IO happens on
   a work directory, which can use IO-optimized cluster storage (see --work).
 --work: directory with fast filesystem on cluster
-  (default: \$HPCWORK/fastsurfer-processing/$(date +%Y%m%d-%H%M%S))
+  (default: \$HPCWORK/fastsurfer-processing/<date as YYMMDD-HHMMSS>)
   NOTE: THIS SCRIPT considers this directory to be owned by this script and job!
   No modifications should be made to the directory after the job is started until it is
   finished (if the job fails, cleanup of this directory may be necessary) and it should be
   empty!
 --data: (root) directory to search in for t1 files (default: current work directory).
 --pattern: glob string to find image files in 'data directory' (default: *.{nii,nii.gz,mgz}),
-   for example --data /data/ --pattern \*/\*/mri/t1.nii.gz
+   for example '--data /data/ --pattern "*/*/mri/t1.nii.gz"'
    will find all images of format /data/<somefolder>/<otherfolder>/mri/t1.nii.gz
 --subject_list: alternative way to define cases to process, files are of format:
   subject_id1=/path/to/t1.mgz