update docs

Author: bendhouseart

README.md

@@ -36,9 +36,10 @@ 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] input_dir
+       [--subject SUBJECT] [--session SESSION] [--docker] 
+       [--singularity] [--n_procs N_PROCS] [--skip_bids_validator] 
+       [--version] [--placement PLACEMENT] [--remove_existing] 
+       input_dir
 
 PetDeface
 
@@ -55,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
@@ -106,6 +108,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

@@ -145,4 +145,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.