Merge pull request #10 from marcoduering/main

1.8.3

README.md

@@ -4,22 +4,28 @@ 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).**
 
+
 ## IMPORTANT DISCLAIMER  
 
 PSMD is NOT a medical device and therefore **for research use only**. Do not use PSMD for diagnosis, prognosis, monitoring or any other clinical routine use. Any application in clinical routine is forbidden by law, e.g. by Medical Device Regulation article 5 in the EU.
 
+
 ## Usage
 
-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.
+Download 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 version throughout a project.  
+
+For even better replicability and traceability, we strongly recommend using a container for the software dependencies, e.g. the **[PSMD container recipe](https://github.com/miac-research/psmd/tree/main/container)** for Apptainer/Singularity.
+
+For more information, please see the project website at [www.psmd-marker.com](https://www.psmd-marker.com) or type `./psmd.sh -h` at the command line.
 
-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
+* `psmd.sh` - PSMD script
 * `skeleton_mask_2019.nii.gz` - Updated (2019) skeleton mask image
-* `LICENSE` - Please have a look at the license file
+* `LICENSE` - Please take a minute to read the license file
 * Folder `examples` - Sample dataset for testing
+* Folder `container` - Apptainer/Singularity container recipe
 
 
 ## Version history

container/README.md

@@ -0,0 +1,73 @@
+# Container for PSMD dependencies
+
+**Please report any bugs with the Singularity container on the [issues page](https://github.com/miac-research/psmd/issues).**
+
+Using containers can solve problems arising from inconsistent dependencies and heterogeneous environments.
+
+Singularity or Apptainer (the Linux Foundation variant of Singularity) is a well-established container solution, developed with scientific computing and deployment on HPC infrastructure (compute cluster) in mind.
+
+This container recipe installs the required system packages and FSL 6.0.3 on top of Ubuntu Bionic as operating system.
+
+> **Please note**: As of version 1.8.3, the PSMD script itself is no longer part of the container. It needs to downloaded separately from the [releases page](https://github.com/miac-research/psmd/releases).
+
+
+## IMPORTANT DISCLAIMER  
+
+PSMD is NOT a medical device and therefore **for research use only**. Do not use PSMD for diagnosis, prognosis, monitoring or any other clinical routine use. Any application of the psmd script in clinical routine is forbidden by law, e.g. by Medical Device Regulation article 5 in the EU.
+
+
+## Instructions
+
+### Prerequisites
+
+- Linux operating system
+- For Windows or macOS: A Linux virtual machine
+- Installation of [Singularity >3.6](https://github.com/sylabs/singularity) or [Apptainer](http://apptainer.org)
+
+> In the following code examples, **if you are using Apptainer** always substitute `singularity` with `apptainer`.
+
+### Build the container
+
+- Download the cotnainer recipe file `psmd_container.txt`
+- Build the container `psmd.sif` from the recipe file (as root or using sudo)
+
+```
+wget https://raw.githubusercontent.com/miac-research/psmd/main/singularity/singularity-psmd.txt
+sudo singularity build psmd.sif psmd_container.txt
+```
+
+> Please note that the container will be quite large, usually around 2.5 GB. 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 installation suited for diffusion processing and PSMD calculation. You can modify the recipe file in order to retain a full FSL installation.
+
+### Run the container
+
+- All dependencies are within the container, but the PSMD script itself needs to be provided outside of the container. Please make sure not to switch the PSMD script version within one project!
+
+- Example for a PSMD pipeline using the Singularity container, assuming the container, the PSMD script and the data are all in the current folder:
+
+```bash
+singularity exec -B $(pwd) psmd.sif psmd.sh -d data.nii.gz -b data.bvals \
+  -r data.bvecs -s skeleton_mask_2019.nii.gz 
+```
+
+- **IMPORTANT**: By default, the container has access only to your home folder. 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`. This is why `-B $(pwd)` was added to the command above. It will bind the current folder into the container.
+
+- You can also bind specific paths to the container. The following example works if subjectA (from the example subjects provided in this repository) is located at `/home/user/data/subjectA` and the PSMD script, the container and the skeleton mask are located at `/home/user/psmd`:
+
+```bash
+datafolder=/home/user/data/subjectA
+psmdfolder=/home/user/psmd
+singularity exec -B ${datafolder} -B ${psmdfolder} ${psmdfolder}/psmd.sif ${psmdfolder}/psmd.sh \
+  -f ${datafolder}/subjectA_FA.nii.gz -m ${datafolder}/subjectA_MD.nii.gz \
+  -s ${psmdfolder}/skeleton_mask_2019.nii.gz
+```
+
+
+## Acknowledgements
+
+The container recipe was in part generated by [Neurodocker](https://github.com/ReproNim/neurodocker).
+
+
+## License
+
+While PSMD depends on FSL, it is not part of FSL. FSL is only used as a library/dependency in the container. Make sure to comply with the [FSL license conditions](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Licence). **In particular, commercial use requires a paid license of FSL!**
+

singularity/singularity-psmd.txt → container/psmd_container.txt

@@ -1,4 +1,4 @@
-# PSMD Singularity Container Definition File
+# PSMD Dependencies Singularity Container Definition File
 # https://www.psmd-marker.com
 
 # Partly generated by: Neurodocker version 0.7.0
@@ -51,7 +51,7 @@ if [ ! -f "$ND_ENTRYPOINT" ]; then
 fi
 chmod -R 777 /neurodocker && chmod a+s /neurodocker
 
-# FSL 6.0.3
+# System packages
 apt-get update -qq
 apt-get install -y -q --no-install-recommends \
     bc \
@@ -75,6 +75,8 @@ apt-get install -y -q --no-install-recommends \
     wget
 apt-get clean
 rm -rf /var/lib/apt/lists/*
+
+# FSL 6.0.3
 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 \
@@ -120,17 +122,6 @@ 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",
@@ -164,7 +155,7 @@ 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 PATH="/opt/fsl-6.0.3/bin:$PATH"
 export FSLOUTPUTTYPE="NIFTI_GZ"
 export FSLMULTIFILEQUIT="TRUE"
 export FSLTCLSH="/opt/fsl-6.0.3/bin/fsltclsh"

psmd.sh

@@ -2,7 +2,7 @@
 #
 # FOR MORE INFORMATION, PLEASE VISIT: http://www.psmd-marker.com
 #
-# PSMD processing pipeline, v1.8.2 (2021-04)
+# PSMD processing pipeline, v1.8.3 (2021-04)
 #
 # IMPORTANT: This tool is NOT a medical device and for research use only!
 # Do NOT use this tool for diagnosis, prognosis, monitoring or any other
@@ -54,7 +54,7 @@
 usage(){
 cat <<USAGE
 
-PSMD - Peak width of Skeletonized Mean Diffusivity - pipeline version 1.8.2 (2021-04)
+PSMD - Peak width of Skeletonized Mean Diffusivity - pipeline version 1.8.3 (2022-05)
 http://www.psmd-marker.com
 
 Disclaimer:
@@ -171,7 +171,7 @@ while getopts ":d:p:b:r:f:m:s:e:l:ogtcqvh" opt; do
       ppdwi=${OPTARG}
       if [ -r "$ppdwi" ]; then ppdwifile=$(get_abs_filename "$ppdwi"); else { echo ""; echo "ERROR: Pre-processed DWI data file not found";echo ""; exit 1; }; fi
       ;;
-	b)
+	  b)
       bval=${OPTARG}
       if [ -r "$bval" ]; then bvalfile=$(get_abs_filename "$bval"); else { echo ""; echo "ERROR: Bval file not found";echo ""; exit 1; }; fi
       ;;
@@ -280,7 +280,7 @@ if [ -r psmdtemp ];then
 fi
 
 # Set reporting level from options
-[ ${silent} == false ] && { echo "";echo "${metric} processing pipeline, v1.8.2"; } 
+[ ${silent} == false ] && { echo "";echo "${metric} processing pipeline, v1.8.3"; } 
 [ ${verbose} == true ] && { silent=false;echo "";echo "Reporting level: Verbose (all status and error messages are displayed)"; }
 
 redirect_cmd mkdir psmdtemp