updated documentation on when to use template anats

Author: bendhouseart

README.md

@@ -71,6 +71,9 @@ 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        Open browser to show QA reports after completion
 ```
 
@@ -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:

docs/usage.rst

@@ -123,6 +123,9 @@ 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
@@ -175,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 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:
+
+.. code-block:: bash
+
+    petdeface /inputfolder /outputfolder --use_template_anat t1 --n_procs 16

petdeface/petdeface.py

@@ -37,7 +37,7 @@
         sys.path.insert(0, str(current_dir))
 
     # Import using absolute imports (script mode)
-    from mideface import ApplyMideface, Mideface
+    from mideface import ApplyMideface, Mideface, TemplateFacemask
     from pet import WeightedAverage
     from qa import run_qa
     from utils import run_validator
@@ -436,39 +436,84 @@ def init_single_subject_wf(
         if determine_in_docker():
             preview_pics = False
 
-        deface_t1w = Node(
-            Mideface(
-                in_file=pathlib.Path(t1w_file),
-                pics=preview_pics,
-                odir=".",
-                code=f"{anat_string}",
-            ),
-            name=f"deface_t1w_{anat_string}",
+        # Check if this is a template anatomical image created from PET averaging
+        is_template_from_pet = use_template_anat == "pet" and "desc-totallyat1w" in str(
+            t1w_file
         )
-        t1w_wf.connect(
-            [
-                (
-                    deface_t1w,
-                    datasink,
-                    [
-                        ("out_file", f"{anat_string.replace('_', '.')}.anat"),
-                        (
-                            "out_facemask",
-                            f"{anat_string.replace('_', '.')}.anat.@defacemask",
-                        ),
-                        (
-                            "out_before_pic",
-                            f"{anat_string.replace('_', '.')}.anat.@before",
-                        ),
-                        (
-                            "out_after_pic",
-                            f"{anat_string.replace('_', '.')}.anat.@after",
-                        ),
-                    ],
+
+        if is_template_from_pet:
+            # For PET-averaged templates, we need to create a facemask without defacing the template
+            # We'll use TemplateFacemask to generate the facemask without defacing the template
+            from mideface import TemplateFacemask
+
+            # Create a node that generates facemask but doesn't deface the template
+            template_facemask = Node(
+                TemplateFacemask(
+                    in_file=pathlib.Path(t1w_file),
+                    no_pics=True,  # No preview pics for templates
+                    no_post=True,  # No post-processing for templates
+                    odir=".",
+                    code=f"{anat_string}_template",
                 ),
-            ]
-        )
-        t1w_workflows[t1w_file] = {"workflow": t1w_wf, "anat_string": anat_string}
+                name=f"deface_t1w_{anat_string}",
+            )
+
+            # Only connect the facemask output, not the defaced template
+            # This way we get the facemask for PET defacing but don't deface the template itself
+            t1w_wf.connect(
+                [
+                    (
+                        template_facemask,
+                        datasink,
+                        [
+                            (
+                                "out_facemask",
+                                f"{anat_string.replace('_', '.')}.anat.@defacemask",
+                            ),
+                        ],
+                    ),
+                ]
+            )
+        else:
+            # Normal defacing for real anatomical images
+            deface_t1w = Node(
+                Mideface(
+                    in_file=pathlib.Path(t1w_file),
+                    pics=preview_pics,
+                    odir=".",
+                    code=f"{anat_string}",
+                ),
+                name=f"deface_t1w_{anat_string}",
+            )
+            t1w_wf.connect(
+                [
+                    (
+                        deface_t1w,
+                        datasink,
+                        [
+                            ("out_file", f"{anat_string.replace('_', '.')}.anat"),
+                            (
+                                "out_facemask",
+                                f"{anat_string.replace('_', '.')}.anat.@defacemask",
+                            ),
+                            (
+                                "out_before_pic",
+                                f"{anat_string.replace('_', '.')}.anat.@before",
+                            ),
+                            (
+                                "out_after_pic",
+                                f"{anat_string.replace('_', '.')}.anat.@after",
+                            ),
+                        ],
+                    ),
+                ]
+            )
+
+        t1w_workflows[t1w_file] = {
+            "workflow": t1w_wf,
+            "anat_string": anat_string,
+            "is_template_from_pet": is_template_from_pet,
+        }
 
     workflow = Workflow(name=name)
     if anat_only:
@@ -1111,7 +1156,7 @@ def cli():
     )
     parser.add_argument(
         "--use_template_anat",
-        help="Use template anatomical image when no T1w is available for PET scans. Options: 't1', 'mni', or 'pet'",
+        help="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).",
         type=str,
         required=False,
         default=False,
@@ -1354,29 +1399,29 @@ def main():  # noqa: max-complexity: 12
 
 def collect_subject_files(file_list: list) -> dict:
     """Collect files that share the same subject ID into a dictionary.
-    
+
     Parameters
     ----------
     file_list : list
         List of file paths to process
-        
+
     Returns
     -------
     dict
         Dictionary mapping subject IDs to lists of their files
         Format: {"sub-*": ["file1", "file2", ...]}
     """
     subject_files = {}
-    
+
     for file_path in file_list:
         # Extract subject ID using regex - matches 'sub-' followed by alphanumeric chars until underscore
-        match = re.search(r'sub-[a-zA-Z0-9]+(?=_)', str(file_path))
+        match = re.search(r"sub-[a-zA-Z0-9]+(?=_)", str(file_path))
         if match:
             sub_id = match.group(0)
             if sub_id not in subject_files:
                 subject_files[sub_id] = []
             subject_files[sub_id].append(str(file_path))
-            
+
     return subject_files
 
 

pyproject.toml

@@ -23,23 +23,19 @@ python = ">=3.10, <4.0"
 setuptools = "^68.1.2"
 petutils = "^0.0.1"
 niworkflows = "^1.11.0"
-<<<<<<< HEAD
 matplotlib = "^3.10.1"
-=======
 niftifixer = {git = "https://github.com/openneuropet/nifti_fixer.git"}
 bids-validator-deno = "^2.0.5"
 nipreps = "^1.0"
 nireports = "^25.2.0"
 nibabel = "^5.3.2"
 nilearn = "^0.10.4"
-matplotlib = "^3.9.2"
 numpy = "^2.1.3"
 scipy = "^1.14.1"
 seaborn = "^0.13.2"
 pillow = "^11.0.0"
 imageio = "^2.36.0"
 
->>>>>>> 3d1900349781365c748e8581f6dc6b975a675da9
 
 [tool.poetry.group.dev.dependencies]
 black = "^23.7.0"