From c897a7d017779ab6a75760b54fa2f878965ce722 Mon Sep 17 00:00:00 2001 From: Marco Duering Date: Sun, 1 May 2022 10:40:05 +0000 Subject: [PATCH] Apptainer Container only for dependencies Bump to 1.8.3 --- README.md | 14 +++- container/README.md | 73 +++++++++++++++++ .../psmd_container.txt | 19 ++--- psmd.sh | 8 +- singularity/README.md | 82 ------------------- 5 files changed, 92 insertions(+), 104 deletions(-) create mode 100644 container/README.md rename singularity/singularity-psmd.txt => container/psmd_container.txt (92%) delete mode 100644 singularity/README.md diff --git a/README.md b/README.md index 76a7d06..30e5fa3 100644 --- a/README.md +++ b/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 diff --git a/container/README.md b/container/README.md new file mode 100644 index 0000000..dd98dd0 --- /dev/null +++ b/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!** + diff --git a/singularity/singularity-psmd.txt b/container/psmd_container.txt similarity index 92% rename from singularity/singularity-psmd.txt rename to container/psmd_container.txt index 6ca5173..a087190 100644 --- a/singularity/singularity-psmd.txt +++ b/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" diff --git a/psmd.sh b/psmd.sh index a6ed2b3..7e97719 100755 --- a/psmd.sh +++ b/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 < If you want to build the container with a specific version of PSMD, please see the detailed instructions below. Alternatively, you can use a psmd main script outside the container and start it with the container. - -## 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 (e.g. inside a virutal machine) -- Installation of [singularity](https://sylabs.io) version 3.6 or newer - -### Build the container - -- Download the Singularity recipe file `singularity-psmd.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 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/v1.0/psmd.sh | -| 1.5.1 | https://raw.githubusercontent.com/miac-research/psmd/v1.5.1/psmd.sh | -| 1.7 | https://raw.githubusercontent.com/miac-research/psmd/v1.7/psmd.sh | -| 1.8.2 | https://raw.githubusercontent.com/miac-research/psmd/v1.8.2/psmd.sh | - - -### 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 -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` of Singularity. 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/subjectA` and the skeleton mask is located at `/home/user/skeleton`. - -```bash -datafolder=/home/user/subjectA -skeletonfolder=/home/user/skeleton -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 - -While PSMD depends on FSL, it is not part of FSL. FSL is only used as a "library" when installed into the container. The container will thus 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!** -