added session inclusion/exclusion

Author: bendhouseart

README.md

@@ -35,37 +35,43 @@ This software can be installed via source or via pip from PyPi with `pip install
 **_NOTE:_** This project is currently in beta release, some features listed below may not be available for version numbers < 1.0.0
 
 ```bash
-usage: petdeface.py [-h] [--anat_only] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [--session SESSION] [--docker] [--singularity] [--n_procs N_PROCS] [--skip_bids_validator] [--version] [--placement PLACEMENT] [--remove_existing] [--preview_pics]
-                    [--excludeparticipant EXCLUDEPARTICIPANT [EXCLUDEPARTICIPANT ...]]
+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]
+                    [--exclude_participant EXCLUDE_PARTICIPANT [EXCLUDE_PARTICIPANT ...]] [--session SESSION [SESSION ...]]
+                    [--exclude_session EXCLUDE_SESSION [EXCLUDE_SESSION ...]]
                     bids_dir [output_dir] [analysis_level]
 
 PetDeface
 
 positional arguments:
   bids_dir              The directory with the input dataset
   output_dir            The directory where the output files should be stored, if not supplied will default to <bids_dir>/derivatives/petdeface
-  analysis_level        This BIDS app always operates at the participant level, if this argument is changed it will be ignored and run as a participant level analysis
+  analysis_level        This BIDS app always operates at the participant level, if this argument is changed it will be ignored and run as a participant level
+                        analysis
 
 options:
   -h, --help            show this help message and exit
   --anat_only, -a       Only deface anatomical images
   --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], -pl PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
                         The label(s) of the participant/subject to be processed. When specifying multiple subjects separate them with spaces.
-  --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 program's version number and exit
   --placement PLACEMENT, -p PLACEMENT
-                        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.
+                        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
-  --excludeparticipant EXCLUDEPARTICIPANT [EXCLUDEPARTICIPANT ...]
-                        Exclude a subject(s) from the defacing workflow. e.g. --excludeparticipant sub-01 sub-02
+  --exclude_participant EXCLUDE_PARTICIPANT [EXCLUDE_PARTICIPANT ...]
+                        Exclude a subject(s) from the defacing workflow. e.g. --exclude_participant sub-01 sub-02
+  --session SESSION [SESSION ...]
+                        Select only a specific session(s) to include in the defacing workflow
+  --exclude_session EXCLUDE_SESSION [EXCLUDE_SESSION ...]
+                        Select a specific session(s) to exclude from the defacing workflow
 ```
 
 Working example usage:

docs/usage.rst

@@ -86,37 +86,43 @@ The number of processors made available to PETdeface can be set by the `--n_proc
 Additional options can be found in the help menu::
 
     petdeface -h
-    usage: petdeface.py [-h] [--anat_only] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [--session SESSION] [--docker] [--singularity] [--n_procs N_PROCS] [--skip_bids_validator] [--version] [--placement PLACEMENT] [--remove_existing] [--preview_pics]
-                    [--excludeparticipant EXCLUDEPARTICIPANT [EXCLUDEPARTICIPANT ...]]
+    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]
+                    [--exclude_participant EXCLUDE_PARTICIPANT [EXCLUDE_PARTICIPANT ...]] [--session SESSION [SESSION ...]]
+                    [--exclude_session EXCLUDE_SESSION [EXCLUDE_SESSION ...]]
                     bids_dir [output_dir] [analysis_level]
 
-    PetDeface
-
-    positional arguments:
-    bids_dir              The directory with the input dataset
-    output_dir            The directory where the output files should be stored, if not supplied will default to <bids_dir>/derivatives/petdeface
-    analysis_level        This BIDS app always operates at the participant level, if this argument is changed it will be ignored and run as a participant level analysis
-
-    options:
-    -h, --help            show this help message and exit
-    --anat_only, -a       Only deface anatomical images
-    --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], -pl PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
-                            The label(s) of the participant/subject to be processed. When specifying multiple subjects separate them with spaces.
-    --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 program's version number and exit
-    --placement PLACEMENT, -p PLACEMENT
-                            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
-    --excludeparticipant EXCLUDEPARTICIPANT [EXCLUDEPARTICIPANT ...]
-                            Exclude a subject(s) from the defacing workflow. e.g. --excludeparticipant sub-01 sub-02
+PetDeface
+
+positional arguments:
+  bids_dir              The directory with the input dataset
+  output_dir            The directory where the output files should be stored, if not supplied will default to <bids_dir>/derivatives/petdeface
+  analysis_level        This BIDS app always operates at the participant level, if this argument is changed it will be ignored and run as a participant level
+                        analysis
+
+options:
+  -h, --help            show this help message and exit
+  --anat_only, -a       Only deface anatomical images
+  --participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...], -pl PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]
+                        The label(s) of the participant/subject to be processed. When specifying multiple subjects separate them with spaces.
+  --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 program's version number and exit
+  --placement PLACEMENT, -p PLACEMENT
+                        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
+  --exclude_participant EXCLUDE_PARTICIPANT [EXCLUDE_PARTICIPANT ...]
+                        Exclude a subject(s) from the defacing workflow. e.g. --exclude_participant sub-01 sub-02
+  --session SESSION [SESSION ...]
+                        Select only a specific session(s) to include in the defacing workflow
+  --exclude_session EXCLUDE_SESSION [EXCLUDE_SESSION ...]
+                        Select a specific session(s) to exclude from the defacing workflow
 
 Docker Based
 ------------

petdeface/petdeface.py

@@ -249,15 +249,15 @@ def deface(args: Union[dict, argparse.Namespace]) -> None:
         )
 
     # check to see if any subjects are excluded from the defacing workflow
-    if args.excludeparticipant != []:
+    if args.exclude_participant != []:
         print(
-            f"Removing the following subjects {args.excludeparticipant} from the defacing workflow"
+            f"Removing the following subjects {args.exclude_participant} from the defacing workflow"
         )
-        args.excludeparticipant = [
-            subject.replace("sub-", "") for subject in args.excludeparticipant
+        args.exclude_participant = [
+            subject.replace("sub-", "") for subject in args.exclude_participant
         ]
         subjects = [
-            subject for subject in subjects if subject not in args.excludeparticipant
+            subject for subject in subjects if subject not in args.exclude_participant
         ]
 
         print(f"Subjects remaining in the defacing workflow: {subjects}")
@@ -277,6 +277,8 @@ def deface(args: Union[dict, argparse.Namespace]) -> None:
                 args.bids_dir,
                 preview_pics=args.preview_pics,
                 anat_only=args.anat_only,
+                session=args.session,
+                exclude_session=args.exclude_session,
             )
         except FileNotFoundError:
             single_subject_wf = None
@@ -303,6 +305,8 @@ def init_single_subject_wf(
     output_dir: pathlib.Path = None,
     preview_pics=False,
     anat_only=False,
+    session=[],
+    exclude_session=[],
 ) -> Workflow:
     """
     Organize the preprocessing pipeline for a single subject.
@@ -317,6 +321,10 @@ def init_single_subject_wf(
     :type preview_pics: bool, optional
     :param anat_only: _description_, defaults to False
     :type anat_only: bool, optional
+    :param session: _description_, will default to only selecting session(s) supplied to this argument, defaults to []
+    :type session: list, optional
+    :param exclude_session: _description_, will exclude any session(s) supplied to this argument, defaults to []
+    :type exclude_session: list, optional
     :raises FileNotFoundError: _description_
     :return: _description_
     :rtype: Workflow
@@ -333,6 +341,13 @@ def init_single_subject_wf(
     if subject_data is None:
         raise FileNotFoundError(f"Could not find data for subject sub-{subject_id}")
 
+    # we combine the sessions to include and exclude into a single set of sessions to exclude from 
+    # the set of all sessions
+    if session:
+        sessions_to_exclude = list(set(bids_data.get_sessions()) - (set(bids_data.get_sessions()) & set(session)) | set(exclude_session))
+    else:
+        sessions_to_exclude = exclude_session
+
     # check if any t1w images exist for the pet images
     for pet_image, t1w_image in subject_data.items():
         if t1w_image == "":
@@ -426,6 +441,10 @@ def init_single_subject_wf(
                 ses_id = ""
                 pet_string = f"sub-{subject_id}"
 
+            # skip anything in the exclude list
+            if ses_id.replace("ses-", "") in sessions_to_exclude:
+                continue
+
             # collect run info from pet file
             try:
                 run_id = "_" + re.search("run-[^_|\/]*", str(pet_file)).group(0)
@@ -744,7 +763,9 @@ def __init__(
         remove_existing=True,
         placement="adjacent",
         preview_pics=True,
-        excludeparticipant=[],
+        exclude_participant=[],
+        session=[],
+        exclude_session=[],
     ):
         self.bids_dir = bids_dir
         self.remove_existing = remove_existing
@@ -755,7 +776,9 @@ def __init__(
         self.n_procs = n_procs
         self.skip_bids_validator = skip_bids_validator
         self.preview_pics = preview_pics
-        self.excludeparticipant = excludeparticipant
+        self.exclude_participant = exclude_participant
+        self.session = session
+        self.exclude_session = exclude_session
 
         # check if freesurfer license is valid
         self.fs_license = check_valid_fs_license()
@@ -785,7 +808,9 @@ def run(self):
                 "placement": self.placement,
                 "remove_existing": self.remove_existing,
                 "preview_pics": self.preview_pics,
-                "excludeparticipant": self.excludeparticipant,
+                "exclude_participant": self.exclude_participant,
+                "session": self.session,
+                "exclude_session": self.exclude_session,
             }
         )
         wrap_up_defacing(
@@ -886,13 +911,15 @@ def cli():
         default=False,
     )
     parser.add_argument(
-        "--excludeparticipant",
-        help="Exclude a subject(s) from the defacing workflow. e.g. --excludeparticipant sub-01 sub-02",
+        "--exclude_participant",
+        help="Exclude a subject(s) from the defacing workflow. e.g. --exclude_participant sub-01 sub-02",
         type=str,
         nargs="+",
         required=False,
         default=[],
     )
+    parser.add_argument("--session", help="Select only a specific session(s) to include in the defacing workflow", type=str, nargs="+", required=False, default=[])
+    parser.add_argument("--exclude_session", help="Select a specific session(s) to exclude from the defacing workflow", type=str, nargs="+", required=False, default=[])
 
     arguments = parser.parse_args()
     return arguments
@@ -1087,7 +1114,9 @@ def main():  # noqa: max-complexity: 12
             remove_existing=args.remove_existing,
             placement=args.placement,
             preview_pics=args.preview_pics,
-            excludeparticipant=args.excludeparticipant,
+            exclude_participant=args.exclude_participant,
+            session=args.session,
+            exclude_session=args.exclude_session,
         )
         petdeface.run()