Merge pull request #55 from openneuropet/no-anatomical

If no T1w is present, attempt to deface with a template t1w contained in petdeface/data/*

Author: mnoergaard

README.md

@@ -36,9 +36,9 @@ This software can be installed via source or via pip from PyPi with `pip install
 
 ```bash
 usage: petdeface.py [-h] [--anat_only] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [--docker] [--singularity] [--n_procs N_PROCS]
-                    [--skip_bids_validator] [--version] [--placement PLACEMENT] [--remove_existing] [--preview_pics]
+                    [--skip_bids_validator] [--version] [--placement PLACEMENT] [--remove_existing]
                     [--participant_label_exclude participant_label_exclude [participant_label_exclude ...]] [--session_label SESSION [SESSION ...]]
-                    [--session_label_exclude session_label_exclude [session_label_exclude ...]]
+                    [--session_label_exclude session_label_exclude [session_label_exclude ...]] [--open_browser]
                     bids_dir [output_dir] [analysis_level]
 
 PetDeface
@@ -63,15 +63,18 @@ options:
                         Where to place the defaced images. Options are 'adjacent': next to the bids_dir (default) in a folder appended with _defaced'inplace':
                         defaces the dataset in place, e.g. replaces faced PET and T1w images w/ defaced at bids_dir'derivatives': does all of the defacing within
                         the derivatives folder in bids_dir.
-  --remove_existing, -r
-                        Remove existing output files in output_dir.
-  --preview_pics        Create preview pictures of defacing, defaults to false for docker
+  --remove_existing, -r Remove existing output files in output_dir.
+  --preview_pics        Create preview pictures of defacing, defaults to false for docker (only works if FreeView is installed on machine)
   --participant_label_exclude participant_label_exclude [participant_label_exclude ...]
                         Exclude a subject(s) from the defacing workflow. e.g. --participant_label_exclude sub-01 sub-02
   --session_label SESSION [SESSION ...]
                         Select only a specific session(s) to include in the defacing workflow
   --session_label_exclude session_label_exclude [session_label_exclude ...]
                         Select a specific session(s) to exclude from the defacing workflow
+  --use_template_anat   Use template anatomical image when no T1w is available for PET scans. 
+                        Options: 't1' (included T1w template), 'mni' (MNI template), or 'pet' 
+                        (averaged PET image).
+  --open_browser        Open browser to show QA reports after completion
 ```
 
 Working example usage:
@@ -80,6 +83,26 @@ Working example usage:
 petdeface /inputfolder /outputfolder --n_procs 16 --skip_bids_validator --placement adjacent
 ```
 
+### Template Anatomical Images
+
+When PET scans lack corresponding T1w anatomical images, PETdeface can use template anatomical images for registration and defacing. Three options are available:
+
+- **`--use_template_anat t1`**: Uses a T1w template included with the PETdeface library
+- **`--use_template_anat mni`**: Uses the MNI standard brain template  
+- **`--use_template_anat pet`**: Creates a template by averaging the PET data across time
+
+**Important**: When using template anatomical images, it's crucial to validate the defacing quality. Inspect the output using the generated HTML report (with `--open_browser`) or a NIfTI viewer to ensure the defacing is valid for your data.
+
+**Recommended workflow for subjects missing T1w images**:
+1. First, exclude subjects missing T1w using `--participant_label_exclude`
+2. Run defacing on subjects with T1w images
+3. Then run defacing separately on subjects missing T1w using `--participant_label` and test different templates (`t1`, `mni`, `pet`) to determine which works best for your data
+
+Example usage with template anatomical:
+```bash
+petdeface /inputfolder /outputfolder --use_template_anat t1 --n_procs 16
+```
+
 ### Docker Usage
 
 Requirements:

data/participants.tsv

@@ -1,3 +1,4 @@
 participant_id	height	weight	age	gender
 sub-01	178	58	28	male
+sub-mni305	200	65	10	n/a
 sub-02	178	58	28	male

data/sub-01/ses-baseline/anat/sub-01_ses-baseline_T1w.nii

@@ -123,6 +123,10 @@ options:
                         Select only a specific session(s) to include in the defacing workflow
   --session_label_exclude session_label_exclude [session_label_exclude ...]
                         Select a specific session(s) to exclude from the defacing workflow
+  --use_template_anat   Use template anatomical image when no T1w is available for PET scans. 
+                        Options: 't1' (included T1w template), 'mni' (MNI template), or 'pet' 
+                        (averaged PET image).
+  --open_browser        Following defacing this flag will open the browser to view the defacing results
 
 Docker Based
 ------------
@@ -174,4 +178,31 @@ PETdeface will do it's best to locate a valid FreeSurfer license file on the hos
 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.
+machine.
+
+Template Anatomical Images
+-------------------------
+
+When PET scans lack corresponding T1w anatomical images, PETdeface can use template anatomical images for 
+registration and defacing. Three options are available:
+
+- **`--use_template_anat t1`**: Uses a T1w template included with the PETdeface library
+- **`--use_template_anat mni`**: Uses the MNI standard brain template  
+- **`--use_template_anat pet`**: Creates a template by averaging a subjects PET image and using that averaged image in place of a T1 image 
+
+**Important**: When using template anatomical images, it's crucial to validate the defacing quality. 
+Inspect the output using the generated HTML report (with `--open_browser`) or a NIfTI viewer to ensure 
+the defacing is valid for your data.
+
+**Recommended workflow for subjects missing T1w images**:
+
+1. First, exclude subjects missing T1w using `--participant_label_exclude`
+2. Run defacing on subjects with T1w images  
+3. Then run defacing separately on subjects missing T1w using `--participant_label` and test 
+   different templates (`t1`, `mni`, `pet`) to determine which works best for your data
+
+Example usage with template anatomical:
+
+.. code-block:: bash
+
+    petdeface /inputfolder /outputfolder --use_template_anat t1 --n_procs 16

data/sub-01/ses-baseline/anat/sub-01_ses-baseline_T1w.nii.gz

@@ -0,0 +1,73 @@
+"""
+PET Deface - A nipype PET and MR defacing pipeline for BIDS datasets.
+
+This package provides tools for defacing PET and MR images using FreeSurfer's MiDeFace.
+"""
+
+import sys
+from pathlib import Path
+
+# Add the package directory to sys.path when running as script
+if __name__ == "__main__" or (
+    len(sys.argv) > 0 and sys.argv[0].endswith("petdeface.py")
+):
+    # Running as script - add current directory to path
+    package_dir = Path(__file__).parent
+    if str(package_dir) not in sys.path:
+        sys.path.insert(0, str(package_dir))
+
+# Import main components
+try:
+    from .petdeface import PetDeface, deface, cli, main
+    from .mideface import ApplyMideface, Mideface
+    from .pet import WeightedAverage
+    from .qa import run_qa
+    from .utils import run_validator
+    from .noanat import copy_default_anat_to_subject, remove_default_anat
+except ImportError:
+    # Fallback for when running as script
+    try:
+        from petdeface import PetDeface, deface, cli, main
+        from mideface import ApplyMideface, Mideface
+        from pet import WeightedAverage
+        from qa import run_qa
+        from utils import run_validator
+        from noanat import copy_default_anat_to_subject, remove_default_anat
+    except ImportError:
+        # Last resort - import from current directory
+        import os
+
+        sys.path.insert(0, os.path.dirname(__file__))
+        from petdeface import PetDeface, deface, cli, main
+        from mideface import ApplyMideface, Mideface
+        from pet import WeightedAverage
+        from qa import run_qa
+        from utils import run_validator
+        from noanat import copy_default_anat_to_subject, remove_default_anat
+
+# Version info
+try:
+    from importlib.metadata import version
+
+    __version__ = version("petdeface")
+except ImportError:
+    __version__ = "unknown"
+
+__bids_version__ = "1.8.0"
+
+# Main exports
+__all__ = [
+    "PetDeface",
+    "deface",
+    "cli",
+    "main",
+    "ApplyMideface",
+    "Mideface",
+    "WeightedAverage",
+    "run_qa",
+    "run_validator",
+    "copy_default_anat_to_subject",
+    "remove_default_anat",
+    "__version__",
+    "__bids_version__",
+]