Merge pull request #2 from marcoduering/main

Singularity Container Beta

README.md

@@ -4,8 +4,13 @@ PSMD is a robust, fully-automated and easy-to-implement marker for cerebral smal
 
 **For more information on usage, including FAQ, please visit [www.psmd-marker.com](https://www.psmd-marker.com).**
 
+## Usage
 
-## Contents
+We recommend downloading one of our [releases](https://github.com/miac-research/psmd/releases) (for a new project, take the latest release). It is best practice to stick with one release in a given project. For even better replicability and traceability, consider using the [container version](https://github.com/miac-research/psmd/tree/main/singularity) of PSMD.
+
+For more information, please see the project website at [www.psmd-marker.com](https://www.psmd-marker.com).
+
+## Contents of download packages
 
 * `psmd.sh` - Main analysis script
 * `skeleton_mask_2019.nii.gz` - Updated (2019) skeleton mask image
@@ -21,16 +26,20 @@ See the [GitHub releases page](https://github.com/miac-research/psmd/releases) f
 
 ## Roadmap of future development
 
-See the [GitHub issues page](https://github.com/miac-research/psmd/issues) for current development topics.
+See the [GitHub issues page](https://github.com/miac-research/psmd/issues) for current development topics. If you found a bug or have suggestions for new features, please feel free to open an issue.
 
 
 ## License
 
-BSD 3-clause. Please see the `LICENSE` file provided in this repository.
+The script itself is published under the BSD 3-clause license. Please see the `LICENSE` file provided in this repository.
+
+An [FSL license](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence) is required to run PSMD.
 
 
 ## Support
 
+The PSMD project was initiated at the Institue for Stroke and Dementia Research (ISD), Munich, Germany, with funding support by the LMU FöFoLe program (grant 808), the Else Kröner-Fresenius-Stiftung (EKFS, grant 2014_A200), and the Vascular Dementia Research Foundation.
+
 The ongoing development of PSMD is supported by Medical Image Analysis Center (MIAC), Basel, Switzerland.
 
 <img alt="MIAC logo" src="https://miac.swiss/gallery/normal/116/miaclogo@2x.png" width="400" href="http://miac.swiss">

singularity/README.md

@@ -0,0 +1,77 @@
+# PSMD Singularity Conatainer BETA
+
+**The container version is still in Beta. Please report any bugs on the [issues page](https://github.com/miac-research/psmd/issues).
+
+Using containers can solve problems arising from dependencies and heterogeneous environments.
+
+Singularity is a well-established container solution, developed with scientific computing and deployment on HPC infrastructure (compute cluster) in mind.
+
+This singularity recipe installs FSL 6.0.3 and the latest version of the PSMD script into a container using Ubuntu Bionic as operating system.
+
+> If you want to build the container with a specific version of PSMD, please see the detailed instructions below!
+
+## Instructions
+
+### Prerequisites
+
+- Installation of [singularity](https://sylabs.io) version 3.6 or newer, preferably installed on Linux
+- Linux is needed for building the container. A virtual machine setup is available for Windows and Mac users, please consult the [Singularity user guide](https://sylabs.io/docs/) for details.
+- After building the container, besides Linux, it can also be executed on macOS using [Singularity Desktop](https://sylabs.io/singularity-desktop-macos/).
+
+### Build the container
+
+- Download the Singularity recipe file `singularity-psmd.txt`
+- Build the container `psmd.sif` from the recipe file (using sudo)
+
+```
+wget https://raw.githubusercontent.com/miac-research/psmd/main/singularity/singularity-psmd.txt
+sudo singularity build psmd.sif singularity-psmd.txt
+```
+
+> Please note that the container will be quite large, usually around 2.5 GB. Also note that in order to save space, some parts of the FSL installation are deleted. The container does not contain a fully functional FSL installation, but a minimal install suited for diffusion processing and PSMD calculation. You can modify the recipe file in order to retain a full FSL install.
+
+### Using a specific version of PSMD in the container
+
+By default, the container will use the latest version of the psmd script from the repository. To run a specific version (from a specific release, you need to edit the recipe file. Find the following line: `wget -O /psmd/psmd.sh https://raw.githubusercontent.com/miac-research/psmd/main/psmd.sh` and substitute the URL with one of the following URLs:
+
+| version | URL |
+| ---     | --- |
+| 1.0     | https://raw.githubusercontent.com/miac-research/psmd/8f6b1495a65972111ec099b7f304d9f3954bd983/psmd.sh | 
+| 1.5.1   | https://raw.githubusercontent.com/miac-research/psmd/d0de74fe0b190d04588b934981c7464334f83b9f/psmd.sh |
+| 1.7     | tbd |
+
+
+### Run the container
+
+- In general, on a system with Singularity or Singularity Desktop, run with:
+
+```bash
+singularity exec psmd.sif psmd.sh
+```
+
+- After this command, specify the options as usually for the psmd script (see [www.psmd-marker.com](https://www.psmd-marker.com) for details on available options), e.g.
+
+```bash
+singularity exec psmd.sif psmd.sh -d data.nii.gz -b data.bvals \
+  -r data.bvecs -s skeleton_mask_2019.nii.gz 
+```
+
+- The container has access only to the current folder of your system, where you are running the command. If your data (or the skeleton) is in another folder, you need to make the folder available to the container using the bind option `-B` of singularity.
+
+- The following example works if subjectA (from the example subjects provided in this repository) is located at `/home/user/subjectA` and the skeleton mask is located at `/home/user`.
+
+```bash
+datafolder=/home/user/subjectA
+skeletonfolder=/home/user
+singularity exec -B ${datafolder} -B ${skeletonfolder} psmd.sif psmd.sh \
+  -f ${datafolder}/subjectA_FA.nii.gz -m ${datafolder}/subjectA_MD.nii.gz \
+  -s ${skeletonfolder}/skeleton_mask_2019.nii.gz
+```
+
+## Acknowledgements
+
+The container recipe was in part generated by [Neurodocker](https://github.com/ReproNim/neurodocker).
+
+## License
+
+The container will contain an (incomplete) FSL installation. Please make sure to comply with the [FSL license conditions](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence). Especially commercial use requires a paid license of FSL!

singularity/singularity-psmd.txt

@@ -0,0 +1,174 @@
+# PSMD Singularity Container Definition File
+# https://www.psmd-marker.com
+
+# Partly generated by: Neurodocker version 0.7.0
+# https://github.com/ReproNim/neurodocker
+
+# Executing this container requires a valid license of FSL.
+# Please see https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence
+
+Bootstrap: docker
+From: ubuntu:bionic-20200921
+
+%help
+Visit the PSMD repository https://github.com/miac-research/psmd
+or the PSMD homepage https://www.psmd-marker.com for help.
+
+%labels
+    Author Marco Duering
+    Maintainer MIAC AG
+    Recipe_version v1.0
+
+%post
+su - root
+
+# Neurodocker Environment
+export ND_ENTRYPOINT="/neurodocker/startup.sh"
+apt-get update -qq
+apt-get install -y -q --no-install-recommends \
+    apt-utils \
+    bzip2 \
+    ca-certificates \
+    curl \
+    locales \
+    unzip
+apt-get clean
+rm -rf /var/lib/apt/lists/*
+sed -i -e 's/# en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen
+dpkg-reconfigure --frontend=noninteractive locales
+update-locale LANG="en_US.UTF-8"
+chmod 777 /opt && chmod a+s /opt
+mkdir -p /neurodocker
+if [ ! -f "$ND_ENTRYPOINT" ]; then
+  echo '#!/usr/bin/env bash' >> "$ND_ENTRYPOINT"
+  echo 'set -e' >> "$ND_ENTRYPOINT"
+  echo 'export USER="${USER:=`whoami`}"' >> "$ND_ENTRYPOINT"
+  echo 'if [ -n "$1" ]; then "$@"; else /usr/bin/env bash; fi' >> "$ND_ENTRYPOINT";
+fi
+chmod -R 777 /neurodocker && chmod a+s /neurodocker
+
+# FSL 6.0.3
+apt-get update -qq
+apt-get install -y -q --no-install-recommends \
+    bc \
+    dc \
+    file \
+    libfontconfig1 \
+    libfreetype6 \
+    libgl1-mesa-dev \
+    libgl1-mesa-dri \
+    libglu1-mesa-dev \
+    libgomp1 \
+    libice6 \
+    libopenblas-dev \
+    libxcursor1 \
+    libxft2 \
+    libxinerama1 \
+    libxrandr2 \
+    libxrender1 \
+    libxt6 \
+    sudo \
+    wget
+apt-get clean
+rm -rf /var/lib/apt/lists/*
+echo "Downloading FSL ..."
+mkdir -p /opt/fsl-6.0.3
+curl -fsSL --retry 5 https://fsl.fmrib.ox.ac.uk/fsldownloads/fsl-6.0.3-centos6_64.tar.gz \
+| tar -xz -C /opt/fsl-6.0.3 --strip-components 1 
+sed -i '$isource $FSLDIR/etc/fslconf/fsl.sh' $ND_ENTRYPOINT
+bash /opt/fsl-6.0.3/etc/fslconf/fslpython_install.sh -f /opt/fsl-6.0.3
+
+# Thin out FSL installation by deleting some components not needed by PSMD
+rm -r /opt/fsl-6.0.3/bin/contrast_mgr
+rm -r /opt/fsl-6.0.3/bin/fabber
+rm -r /opt/fsl-6.0.3/bin/fabber_asl
+rm -r /opt/fsl-6.0.3/bin/fabber_cest
+rm -r /opt/fsl-6.0.3/bin/fabber_dce
+rm -r /opt/fsl-6.0.3/bin/fabber_dsc
+rm -r /opt/fsl-6.0.3/bin/fabber_dualecho
+rm -r /opt/fsl-6.0.3/bin/fabber_dwi
+rm -r /opt/fsl-6.0.3/bin/fabber_qbold
+rm -r /opt/fsl-6.0.3/bin/fabber_t1
+rm -r /opt/fsl-6.0.3/bin/fdt_matrix_merge
+rm -r /opt/fsl-6.0.3/bin/film_gls
+rm -r /opt/fsl-6.0.3/bin/flameo
+rm -r /opt/fsl-6.0.3/bin/fsl_mvlm
+rm -r /opt/fsl-6.0.3/bin/ftoz
+rm -r /opt/fsl-6.0.3/bin/melodic
+rm -r /opt/fsl-6.0.3/bin/mist
+rm -r /opt/fsl-6.0.3/bin/mm
+rm -r /opt/fsl-6.0.3/bin/mvntool
+rm -r /opt/fsl-6.0.3/bin/probtrackx
+rm -r /opt/fsl-6.0.3/bin/probtrackx2
+rm -r /opt/fsl-6.0.3/bin/probtrackx2_gpu
+rm -r /opt/fsl-6.0.3/bin/pvmfit
+rm -r /opt/fsl-6.0.3/bin/qboot
+rm -r /opt/fsl-6.0.3/bin/run_mesh_utils
+rm -r /opt/fsl-6.0.3/bin/surf_proj
+rm -r /opt/fsl-6.0.3/bin/surf2surf
+rm -r /opt/fsl-6.0.3/bin/swe
+rm -r /opt/fsl-6.0.3/bin/ttologp
+rm -r /opt/fsl-6.0.3/bin/ttoz
+rm -r /opt/fsl-6.0.3/bin/vecreg
+rm -r /opt/fsl-6.0.3/bin/xfibres
+rm -r /opt/fsl-6.0.3/data/first/
+rm -r /opt/fsl-6.0.3/extras
+rm -r /opt/fsl-6.0.3/fslpython/pkgs
+rm -r /opt/fsl-6.0.3/src
+
+# PSMD
+apt-get update -qq
+apt-get install -y -q --no-install-recommends \
+    dc
+apt-get clean
+rm -rf /var/lib/apt/lists/*
+mkdir /psmd
+wget -O /psmd/psmd.sh https://raw.githubusercontent.com/miac-research/psmd/main/psmd.sh
+chmod -R 777 /psmd
+chmod +x /psmd/psmd.sh
+
+# Neurodocker Specs
+echo '{
+\n  "pkg_manager": "apt",
+\n  "instructions": [
+\n    [
+\n      "base",
+\n      "ubuntu:bionic-20200921"
+\n    ],
+\n    [
+\n      "user",
+\n      "root"
+\n    ],
+\n    [
+\n      "_header",
+\n      {
+\n        "version": "generic",
+\n        "method": "custom"
+\n      }
+\n    ],
+\n    [
+\n      "fsl",
+\n      {
+\n        "version": "6.0.3"
+\n      }
+\n    ]
+\n  ]
+\n}' > /neurodocker/neurodocker_specs.json
+
+%environment
+export LANG="en_US.UTF-8"
+export LC_ALL="en_US.UTF-8"
+export ND_ENTRYPOINT="/neurodocker/startup.sh"
+export FSLDIR="/opt/fsl-6.0.3"
+export PATH="/opt/fsl-6.0.3/bin:/psmd:$PATH"
+export FSLOUTPUTTYPE="NIFTI_GZ"
+export FSLMULTIFILEQUIT="TRUE"
+export FSLTCLSH="/opt/fsl-6.0.3/bin/fsltclsh"
+export FSLWISH="/opt/fsl-6.0.3/bin/fslwish"
+export FSLLOCKDIR=""
+export FSLMACHINELIST=""
+export FSLREMOTECALL=""
+export FSLGECUDAQ="cuda.q"
+
+%runscript
+/neurodocker/startup.sh "$@"