ANTS: update docs, thanks Martin

environment/unix.rst

+
 Useful \*nix programs
 =====================
 
@@ -6,6 +7,8 @@ tools to help with you daily workflow. If you have suggestions for awesome
 tools let me know!
 
 
+.. _tmux:
+
 tmux
 ----
 

software/ants.rst

 ANTS
 ====
 
-We are tracking ANTS from the `Neurodebian`_ repository. To use ANTS add the
-installation directory to your environment. This can be conveniently done with
-environment modules:
+We used to track ANTs from the `Neurodebian`_ repository, but right now the
+package is unavailable and there are some custom compiled environment modules
+instead.
+To use ANTs, you have to add the installation directory to your environment. This can be
+done done with environment modules:
 
 
 .. code-block:: bash
 
-   module load ants
-
-There are currently 2 versions of ANTS:
+   $ module avail ants
+   --- /opt/environment/modules ---
+   ants/2.1.0-mpib0  ants/2.3.3-mpib0  ants/2.3.5-mpib0
 
-+ 2.1.0 from neurodebian.org
-+ 2.1.0-mpib0 with some minor patches in Scripts/ for Torque PBS
+   $ module load ants
 
-Afterwards all ants* related programs are in your PATH and ready to use. There
-is no implicit job parallelism afaik except for some scripts like ``buildtemplateparallel.sh``.
+Afterwards all ants* related programs are in your PATH and ready to use.
 
-To use this add the options ``-c 4 -q default`` to the command line:
+Some of the convenient template building scripts distribute their tasks with
+different cluster systems using the ``-c`` switch. To use SLURM you need to
+pass ``-c 5`` to these scripts. For example to build a template with
+``antsMultivariateTemplateConstruction2.sh`` you could run:
 
 .. code-block:: bash
 
    module load ants
-   buildtemplateparallel.sh -d 3 -t GR -c 4 -q default -o ANTS T1*nii
-
-Hint: add an optional ``&`` at the end of the line to run the script in the background.
+   antsMultivariateTemplateConstruction2.sh -d 3 -i 3 -k 1 -f 4x2x1 -s 2x1x0vox -q 30x20x4 -t SyN -m CC -o your_prefix -c 5 -j 8 *T1w.nii.gz
 
+This will run some initial tasks directly on the cluster login node and start
+the more work intensive tasks automatically as a SLURM job.
 
 .. note::
 
-   Some scripts require ``-Q default`` instead of ``-q default``. Check the help page to get the correct parameter.
-
-
-
-All other programs need to be wrapped into a job file to be run on the cluster nodes:
-
+   Add an optional ``&`` at the end of the line to run the script in the
+   background. Alternatively, you could use :ref:`tmux` to start scripts in the
+   background.
+
+We also track a tiny set of patches on top of the regular scripts (as indicated
+with the `-mpibX` suffix). One of the changes in these patches reuses the
+``-j`` switch to configure the cores used for each of the template building sub
+tasks. Tuning this value further improves running time. The table below lists
+a simple benchmark for a template building pipeline using the first
+9 subjects from the ds000001 dataset using the ``antsMultivariateTemplateConstruction2.sh``
+command shown above.
+
+==== ==============
+-j X Time (minutes)
+==== ==============
+4    70
+8    39
+16   24
+32   15
+==== ==============
+
+All other ANTs programs need to be wrapped into a job file to be run on the cluster nodes:
 
 .. code-block:: bash