Merge branch 'dev' into simple-svg-report

Author: bendhouseart

.github/workflows/check_python_compatibility.yaml

@@ -0,0 +1,65 @@
+name: Check Python Compatibility
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  test-python-compatibility:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        toolchain: [uv, pip]
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install UV
+      if: matrix.toolchain == 'uv'
+      uses: astral-sh/setup-uv@v2
+      with:
+        version: "latest"
+
+    - name: Build package with ${{ matrix.toolchain }}
+      if: matrix.toolchain == 'uv'
+      run: |
+        uv build
+        ls -lh dist/
+
+    - name: Build package with ${{ matrix.toolchain }}
+      if: matrix.toolchain == 'pip'
+      run: |
+        python -m pip install --upgrade pip build
+        python -m build
+        ls -lh dist/
+
+    - name: Install package with ${{ matrix.toolchain }}
+      if: matrix.toolchain == 'uv'
+      run: |
+        uv pip install --system dist/*.whl
+        uv run python -c "import petdeface; print('Package installed successfully')"
+
+    - name: Test CLI
+      if: matrix.toolchain == 'uv'
+      run: |
+        uv run petdeface --help
+
+    - name: Install package with ${{ matrix.toolchain }}
+      if: matrix.toolchain == 'pip'
+      run: |
+        python -m pip install dist/*.whl
+        python -c "import petdeface; print('Package installed successfully')"
+
+    - name: Test CLI
+      if: matrix.toolchain == 'pip'
+      run: |
+        petdeface --help 

.github/workflows/petdeface.yaml

@@ -13,14 +13,28 @@ jobs:
   test_petdeface:
     runs-on: ubuntu-latest
     name: Test petdeface
+    strategy:
+      matrix:
+        toolchain: [uv, pip]
     steps:
       - uses: actions/checkout@v3
-      - name: Install Poetry
-        run: pipx install poetry
       - uses: actions/setup-python@v4
         with:
           python-version: 3.11
-          cache: poetry
-      - run: poetry install
-      - name: Run All Tests
-        run: poetry run make testall
+      - name: Install dependencies (UV)
+        if: matrix.toolchain == 'uv'
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+          uv sync --dev
+      - name: Install dependencies (pip)
+        if: matrix.toolchain == 'pip'
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run All Tests (UV)
+        if: matrix.toolchain == 'uv'
+        run: uv run make testall
+      - name: Run All Tests (pip)
+        if: matrix.toolchain == 'pip'
+        run: make testall

.github/workflows/publish_to_pypi.yaml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - '**'
+  workflow_call:
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+env:
+  PYPI_TOKEN: ${{ secrets.PYPI_TOKEN_PETDEFACE }}
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Build Package
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+          uv sync --dev
+          uv build
+
+      - name: Check PyPI token
+        run: |
+          if [ -z "$PYPI_TOKEN" ]; then
+            echo "Error: PYPI_TOKEN_PETDEFACE is not set or is empty check your secrets"
+            exit 1
+          fi
+
+      - name: Publish Package
+        run: |
+          uv publish --token $PYPI_TOKEN

.gitignore

@@ -4,13 +4,17 @@
 
 # ignore virtualenv
 venv/
+.venv/
 
 # ignore pycache
 __pycache__/
 
 # ignore dist
 dist/
 
+# ignore egg-info
+petdeface.egg-info/
+
 # nipype generates pickle files, we need to redirect where it stores them,
 # but until then hack fix
 *.pkl

.readthedocs.yaml

@@ -2,33 +2,27 @@
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
+# Build environment
 build:
   os: ubuntu-22.04
   tools:
     python: "3.12"
-  jobs:
-    post_create_environment:
-      - pip install poetry
-      - poetry config virtualenvs.create false
-    post_install:
-      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --with=dev
+
+# Python environment setup
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - dev
 
 # Build documentation in the "docs/" directory with Sphinx
 sphinx:
-   configuration: docs/conf.py
+  configuration: docs/conf.py
 
 # Optionally build your docs in additional formats such as PDF and ePub
 # formats:
 #    - pdf
 #    - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#    install:
-#    - requirements: docs/requirements.txt

README.md

@@ -14,6 +14,9 @@ This software can be installed via source or via pip from PyPi with `pip install
 |---------| ------ |
 | `docker build . -t petdeface` | ![docker_build](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoiYzdXV0tYSkQzTVNkcG04cHA2S055UXlKRlZTU1VONThUMVRoZVcwU3l1aHFhdVBlNDNaRGVCYzdWM1Q0WjYzQ1lRU2ZTSHpmSERPWFRkVXVyb3k3RTZBPSIsIml2UGFyYW1ldGVyU3BlYyI6IjRCZFFIQnNGT2lKcDA1VG4iLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main) |
 | `docker push` | ![docker push icon](https://codebuild.us-east-1.amazonaws.com/badges?uuid=eyJlbmNyeXB0ZWREYXRhIjoia0c1bEJYUGI2SXlWYi9JMm1tcGtiYWVTdVd3bmlnOUFaTjN4QjJITU5PTVpvQnN3TlowajhxNmhHY2RwQ2Z5SU93OExqc2xvMzFnTHFvajlqVk1MV2FzPSIsIml2UGFyYW1ldGVyU3BlYyI6Ikl6SzRyc1RabzBnSkplTjciLCJtYXRlcmlhbFNldFNlcmlhbCI6MX0%3D&branch=main) |
+| `Python 3.14 >= 3.10` | [![Check Python Compatibility](https://github.com/openneuropet/petdeface/actions/workflows/check_python_compatibility.yaml/badge.svg)](https://github.com/openneuropet/petdeface/actions/workflows/check_python_compatibility.yaml) |
+| `packaging` | [![Publish to PyPI](https://github.com/openneuropet/petdeface/actions/workflows/publish_to_pypi.yaml/badge.svg)](https://github.com/openneuropet/petdeface/actions/workflows/publish_to_pypi.yaml) |
+| `Docs` | ![RTD BADGE](https://app.readthedocs.org/projects/petdeface/badge/?version=latest&style=default) |
 
 ## Requirements
 
@@ -36,9 +39,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 +66,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 +86,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:
@@ -138,12 +164,27 @@ 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:
+This project supports both [UV](https://github.com/astral-sh/uv) and standard Python (pip + build) workflows for development and packaging.
+
+### Using UV (recommended for speed)
+
+```bash
+git clone https://github.com/openneuropet/petdeface.git
+cd petdeface
+uv build
+pip install dist/petdeface-<X.X.X>-py3-none-any.whl # where X.X.X is the version number of the generated file
+```
+
+### Using pip and python (no UV required)
 
 ```bash
 git clone https://github.com/openneuropet/petdeface.git
 cd petdeface
-poetry build
+pip install --upgrade pip
+pip install .[dev]
+# To build a wheel or sdist:
+pip install build
+python -m build
 pip install dist/petdeface-<X.X.X>-py3-none-any.whl # where X.X.X is the version number of the generated file
 ```
 

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

@@ -9,11 +9,22 @@ PETdeface can be installed via PyPi_::
 
     pip install petdeface
 
-Or cloned and installed from source::
+Or cloned and installed from source (using UV)::
 
     git clone https://github.com/openneuropet/petdeface.git
     cd petdeface
-    poetry build
+    uv build
+    pip install dist/petdeface-<X.X.X>-py3-none-any.whl 
+    # where X.X.X is the version number of the generated file
+
+Or cloned and installed from source (using pip and python)::
+
+    git clone https://github.com/openneuropet/petdeface.git
+    cd petdeface
+    pip install --upgrade pip
+    pip install .[dev]
+    pip install build
+    python -m build
     pip install dist/petdeface-<X.X.X>-py3-none-any.whl 
     # where X.X.X is the version number of the generated file
 

data/sub-02/ses-baseline/anat/sub-02_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