Singularity (#41)

* update petdeface to handle environment supplied freesurfer license
* updated singuarity run to work
* moved brainlife app to it's own repo
* fixed version string fetching
* bump version
* update docs

Author: bendhouseart

.gitignore

@@ -39,4 +39,10 @@ freesurfer_binaries/*
 
 # ignore html files that are generated by sphinx "make html"
 docs/_build/
-*.doctree
+*.doctree
+
+# ignore freesurfer license
+license.txt
+
+# ignore derivatives folder
+data/derivatives/

README.md

@@ -37,9 +37,9 @@ This software can be installed via source or via pip from PyPi with `pip install
 ```bash
 usage: petdeface.py [-h] [--output_dir OUTPUT_DIR] [--anat_only]
        [--subject SUBJECT] [--session SESSION] [--docker]
-       [--n_procs N_PROCS] [--skip_bids_validator] [--version]
-       [--placement PLACEMENT] [--remove_existing] [--excludesubject] 
-       input_dir
+       [--singularity] [--n_procs N_PROCS] [--skip_bids_validator] 
+       [--version] [--placement PLACEMENT] [--remove_existing] 
+       [--excludesubject] input_dir
 
 PetDeface
 
@@ -56,6 +56,7 @@ options:
   --session SESSION, -ses SESSION
                         The label of the session to be processed.
   --docker, -d          Run in docker container
+  --singularity, -si    Run in singularity container
   --n_procs N_PROCS     Number of processors to use when running the workflow
   --skip_bids_validator
   --version, -v         show programs version number and exit
@@ -109,6 +110,29 @@ docker run --user=$UID:$GID -a stderr -a stdout --rm \
 petdeface:latest  /input --output_dir /output --n_procs 16 --skip_bids_validator  --placement adjacent --user=$UID:$GID system_platform=Linux
 ```
 
+### Singularity Usage
+
+Requirements:
+  - Singularity must be installed
+  - `openneuropet/petdeface` must be present or reachable at dockerhub
+
+One can execute petdeface in singularity either directly via:
+
+```bash
+singularity exec -e --bind license.txt:/opt/freesurfer/license.txt docker://openneuropet/petdeface:0.1.1 petdeface
+```
+
+Input and Output directories don't need to be bound, but one does need to bind a freesurfer license to the image before they can proceed with defacing.
+Otherwise, one can run and execute petdeface with the same syntax as calling it from the command line, the only difference being that petdeface is prepended
+with `singularity exec -e`
+
+```bash
+singularity exec -e --bind license.txt:/opt/freesurfer/license.txt docker://openneuropet/petdeface:0.1.1 petdeface /input --output-dir /output --n_procs 10
+```
+
+**_NOTE_**: Testing with singularity has been limited to version singularity-ce 4.2.0, please let us know in the issues section of this repo if you have 
+trouble running this container in singularity/apptainer.
+
 ## Development
 
 This project uses poetry to package and build, to create a pip installable version of the package run:

docs/usage.rst

@@ -147,4 +147,23 @@ One needs to create 3 bind mounts to the docker container when running PETdeface
 If one is running PETdeface on a linux machine and desires non-root execution of the container, 
 the ``--user`` flag needs to be set to the UID and GID of the user running the container.
 
-Of course all of the above is done automatically when running PETdeface using the ``--docker`` flag.
+Of course all of the above is done automatically when running PETdeface using the ``--docker`` flag.
+
+Singularity Based
+-----------------
+
+PETdeface can also be run using singularity, however one will need access to the internet/dockerhub as 
+it relies on being able to retrieve the docker image from dockerhub. The syntax is as follows::
+
+    petdeface /inputfolder --output_dir /outputfolder --singularity
+
+Running petdeface in singularity will generate then execute a singularity command that will pull the 
+docker image from dockerhub and run the pipeline.
+
+    singularity exec -e --bind license.txt:/opt/freesurfer/license.txt docker://openneuropet/petdeface:latest petdeface /inputfolder --output_dir /outputfolder --n_procs 2 --placement adjacent
+
+PETdeface will do it's best to locate a valid FreeSurfer license file on the host machine and bind it 
+to the container by checking `FREESURFER_HOME`  and `FREESURFER_LICENSE` environment variables. If you 
+receive an error message relating to the FreeSurfer license file, try setting and exporting the 
+`FREESURFER_LICENSE` environment variable to the location of the FreeSurfer license file on the host 
+machine.

petdeface/petdeface.py

@@ -6,6 +6,7 @@
 import sys
 import shutil
 from bids import BIDSLayout
+import importlib
 import glob
 from platform import system
 
@@ -51,7 +52,7 @@
 for place in places_to_look:
     for root, folders, files in os.walk(place):
         for file in files:
-            if file.endswith("pyproject.toml"):
+            if file.endswith("pyproject.toml") and "petdeface" in os.path.join(root, file):
                 toml_file = os.path.join(root, file)
 
                 with open(toml_file, "r") as f:
@@ -66,7 +67,16 @@
                             __bids_version__ = (
                                 line.split("=")[1].strip().replace('"', "")
                             )
-                break
+                # if the version number is found and is formatted  with major.minor.patch formating we can break
+                # we check the version with a regex expression to see if all of the parts are there
+                if re.match(r"\d+\.\d+\.\d+", __version__):
+                    break
+            
+            if __version__ != "unable to locate version number in pyproject.toml":
+                    # we try to load the version using import lib
+                    __version__ = importlib.metadata.version("petdeface")
+                    if re.match(r"\d+\.\d+\.\d+", __version__):
+                        break
 
 
 def locate_freesurfer_license():
@@ -79,20 +89,32 @@ def locate_freesurfer_license():
     :return: full path to Freesurfer license file
     :rtype: pathlib.Path
     """
-    # collect freesurfer home environment variable
-    fs_home = pathlib.Path(os.environ.get("FREESURFER_HOME", ""))
-    if not fs_home:
-        raise ValueError(
-            "FREESURFER_HOME environment variable is not set, unable to determine location of license file"
-        )
+
+    # check to see if FREESURFER_LICENSE variable is set, if so we can skip the rest of this function
+    if os.environ.get("FREESURFER_LICENSE", ""):
+        fs_license_env_var = pathlib.Path(os.environ.get("FREESURFER_LICENSE", ""))
+        if not fs_license_env_var.exists():
+            raise ValueError(
+                f"Freesurfer license file does not exist at {fs_license_env_var}, but is set under $FREESURFER_LICENSE variable."
+                f"Update or unset this varible to use the license.txt at $FREESURFER_HOME"
+            )
+        else:
+            return fs_license_env_var
     else:
-        fs_license = fs_home / pathlib.Path("license.txt")
-        if not fs_license.exists():
+    # collect freesurfer home environment variable and look there instead
+        fs_home = pathlib.Path(os.environ.get("FREESURFER_HOME", ""))
+        if not fs_home:
             raise ValueError(
-                "Freesurfer license file does not exist at {}".format(fs_license)
+                "FREESURFER_HOME environment variable is not set, unable to determine location of license file"
             )
         else:
-            return fs_license
+            fs_license = fs_home / pathlib.Path("license.txt")
+            if not fs_license.exists():
+                raise ValueError(
+                    "Freesurfer license file does not exist at {}".format(fs_license)
+                )
+            else:
+                return fs_license
 
 
 def check_docker_installed():
@@ -198,7 +220,7 @@ def deface(args: Union[dict, argparse.Namespace]) -> None:
     else:
         args = args
 
-    if not check_valid_fs_license():
+    if not check_valid_fs_license() and not locate_freesurfer_license().exists():
         raise Exception("You need a valid FreeSurfer license to proceed!")
 
     if args.subject:
@@ -721,7 +743,11 @@ def __init__(
         # check if freesurfer license is valid
         self.fs_license = check_valid_fs_license()
         if not self.fs_license:
-            raise ValueError("Freesurfer license is not valid")
+            self.fs_license = locate_freesurfer_license()
+            if not self.fs_license.exists():
+                raise ValueError("Freesurfer license is not valid")
+            else:
+                print(f"Using freesurfer license at {self.fs_license} found in system env at $FREESURFER_LICENSE")
 
     def run(self):
         """
@@ -800,6 +826,13 @@ def cli():
         default=False,
         help="Run in docker container",
     ),
+    parser.add_argument(
+        "--singularity",
+        "-si",
+        action="store_true",
+        default=False,
+        help="Run in singularity container",
+    ),
     parser.add_argument(
         "--n_procs",
         help="Number of processors to use when running the workflow",
@@ -943,8 +976,16 @@ def main():  # noqa: max-complexity: 12
             docker_command += f"-v {code_dir}:/petdeface "
 
         # collect location of freesurfer license if it's installed and working
-        if check_valid_fs_license():
-            license_location = locate_freesurfer_license()
+        try:
+            check_valid_fs_license()
+        except:
+            if locate_freesurfer_license().exists():
+                license_location = locate_freesurfer_license()
+            else:
+                raise FileNotFoundError(
+                    "Freesurfer license not found, please set FREESURFER_LICENSE environment variable or place license.txt in FREESURFER_HOME"
+                )
+
             if license_location:
                 docker_command += f"-v {license_location}:/opt/freesurfer/license.txt "
 
@@ -960,6 +1001,60 @@ def main():  # noqa: max-complexity: 12
 
         subprocess.run(docker_command, shell=True)
 
+    elif args.singularity:
+        singularity_command = f"singularity exec -e"
+
+        if args.output_dir == "None" or args.output_dir is None or args.output_dir == "":
+            args.output_dir = args.input_dir / "derivatives" / "petdeface"
+
+        # create output directory if it doesn't exist
+        if not args.output_dir.exists():
+            args.output_dir.mkdir(parents=True, exist_ok=True)
+
+        # convert args to dictionary
+        args_dict = vars(args)
+        for key, value in args_dict.items():
+            if isinstance(value, pathlib.PosixPath):
+                args_dict[key] = str(value)
+
+        args_dict.pop("singularity")
+
+        # remove False boolean keys and values, and set true boolean keys to empty string
+        args_dict = {key: value for key, value in args_dict.items() if value}
+        set_to_empty_str = [key for key, value in args_dict.items() if value == True]
+        for key in set_to_empty_str:
+            args_dict[key] = "empty_str"
+
+        args_string = " ".join(
+            ["--{} {}".format(key, value) for key, value in args_dict.items() if value]
+        )
+        args_string = args_string.replace("empty_str", "")
+
+        # remove --input_dir from args_string as input dir is positional, we
+        # we're simply removing an artifact of argparse
+        args_string = args_string.replace("--input_dir", "")
+
+        # collect location of freesurfer license if it's installed and working
+        try:
+            check_valid_fs_license()
+        except:
+            if locate_freesurfer_license().exists():
+                license_location = locate_freesurfer_license()
+            else:
+                raise FileNotFoundError(
+                    "Freesurfer license not found, please set FREESURFER_LICENSE environment variable or place license.txt in FREESURFER_HOME"
+                )
+
+        singularity_command += f" --bind {str(license_location)}:/opt/freesurfer/license.txt"
+        singularity_command += f" docker://openneuropet/petdeface:{__version__}"
+        singularity_command += f" petdeface"
+        singularity_command += args_string
+
+        print("Running singularity command: \n{}".format(singularity_command))
+
+        subprocess.run(singularity_command, shell=True)
+
+
     else:
         petdeface = PetDeface(
             bids_dir=args.input_dir,

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "petdeface"
-version = "0.1.2"
+version = "0.2.1"
 description = "A nipype PET and MR defacing pipeline for BIDS datasets utilizing FreeSurfer's MiDeFace."
 authors = ["Martin Nørgaard <[email protected]>", "Anthony Galassi <[email protected]>", "Murat Bilgel <[email protected]>"]
 license = "MIT"