Merge pull request #59 from Deep-MI/dev

Introducing additional processing options

Author: kdiers

.github/workflows/build.yml

@@ -15,20 +15,19 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu, macos, windows]
-        python-version: [3.8, 3.9, "3.10", "3.11"]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
     name: ${{ matrix.os }} - py${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}-latest
     defaults:
       run:
         shell: bash
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          #architecture: 'x64'
       - name: Install dependencies
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel

.github/workflows/code-style.yml

@@ -14,25 +14,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
-      - name: Setup Python 3.9
-        uses: actions/setup-python@v4
+        uses: actions/checkout@v4
+      - name: Setup Python 3.10
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.10'
           architecture: 'x64'
       - name: Install dependencies
         run: |
           python -m pip install --progress-bar off --upgrade pip setuptools wheel
           python -m pip install --progress-bar off .[style]
       - name: Run Ruff
         run: ruff check .
-      - name: Run isort
-        uses: isort/isort-action@master
-      - name: Run black
-        uses: psf/black@stable
-        with:
-          options: "--check --verbose"
-          version: "23.10.1"
       - name: Run codespell
         uses: codespell-project/actions-codespell@master
         with:

.github/workflows/doc.yml

@@ -20,10 +20,10 @@ jobs:
         uses: actions/checkout@v4
         with:
           path: ./main
-      - name: Setup Python 3.9
-        uses: actions/setup-python@v4
+      - name: Setup Python 3.10
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.9
+          python-version: '3.10'
           architecture: 'x64'
       - name: Install package
         run: |
@@ -56,7 +56,7 @@ jobs:
           name: doc-dev
           path: ./doc-dev
       - name: Deploy dev documentation
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./doc-dev

.github/workflows/publish.yml

@@ -10,11 +10,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
-      - name: Setup Python 3.9
-        uses: actions/setup-python@v4
+        uses: actions/checkout@v4
+      - name: Setup Python 3.10
+        uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.10'
           architecture: 'x64'
       - name: Install dependencies
         run: |

CHANGES.md

@@ -3,6 +3,11 @@
 
 This is a document summarizing the changes that are associated with (major) updates and releases. Priority is given to changes that are relevant to the user, and those that introduce new features or break compatibility with prior versions.
 
+## Version 2.1.0
+
+- Added group-only, no-group options to allow for running the scripts at the individual or group level only. Default is to run at both levels.
+- Added status file and skip-existing option to allow for incremental updates of a given output directory; additional cases or additional modules will be added. Existing ones will not be recomputed.
+
 ## Version 2.0.2
 
 - This fixes an issue with the outlier module, which did not run for FastSurfer output due to incorrect expectations for names of stats files.

DESCRIPTION.md

@@ -150,7 +150,8 @@ run_fsqc --subjects_dir <directory> --output_dir <directory>
     [--fornix] [--fornix-html] [--hippocampus]
     [--hippocampus-html] [--hippocampus-label ... ]
     [--hypothalamus] [--hypothalamus-html] [--shape]
-    [--outlier] [--fastsurfer] [-h] [--more-help]
+    [--outlier] [--fastsurfer] [--exit-on-error]
+    [--skip-existing] [-h] [--more-help]
     [...]
 
 
@@ -194,6 +195,9 @@ optional arguments:
   --exit-on-error        terminate the program when encountering an error;
                          otherwise, try to continue with the next module or
                          case
+  --skip-existing        skips processing for a given case if output
+                         already exists, even with possibly different 
+                         parameters or settings.                           
 
 getting help:
   -h, --help            display this help message and exit

README.md

@@ -222,7 +222,9 @@ run_fsqc --subjects_dir <directory> --output_dir <directory>
     [--fornix] [--fornix-html] [--hippocampus]
     [--hippocampus-html] [--hippocampus-label ... ]
     [--hypothalamus] [--hypothalamus-html] [--shape]
-    [--outlier] [--fastsurfer] [-h] [--more-help]
+    [--outlier] [--fastsurfer] [--no-group]
+    [--group-only] [--exit-on-error]
+    [--skip-existing] [-h] [--more-help]
     [...]
 
 
@@ -263,9 +265,17 @@ optional arguments:
   --outlier-table        specify normative values (only in conjunction with
                          --outlier)
   --fastsurfer           use FastSurfer instead of FreeSurfer output
+  --no-group             run script in subject-level mode. will compute
+                         individual files and statistics, but not create
+                         group-level summaries.
+  --group-only           run script in group mode. will create group-level
+                         summaries from existing inputs
   --exit-on-error        terminate the program when encountering an error;
                          otherwise, try to continue with the next module or
                          case
+  --skip-existing        skips processing for a given case if output
+                         already exists, even with possibly different
+                         parameters or settings
 
 getting help:
   -h, --help            display this help message and exit
@@ -395,7 +405,7 @@ Call `help(fsqc.run_fsqc)` for further usage info and additional options.
 
 ### As a Docker image
 
-We provide a configuration files that can be used to create a Docker or
+We provide configuration files that can be used to create a Docker or
 Singularity image for the fsqc scripts. Documentation can be found on the
 [Docker](docker/Docker.md) and [Singularity](singularity/Singularity.md) pages.
 
@@ -467,7 +477,7 @@ ___
   all required packages will be installed automatically and manual installation
   as detailed above will not be necessary.
 
-- This software has been tested on Ubuntu 20.04.
+- This software has been tested on Ubuntu 20.04 and 22.04.
 
 - A working [FreeSurfer](https://freesurfer.net) installation (version 6 or
   newer) is required for running the 'shape' module of this toolbox. Also make

VERSION

@@ -1 +1 @@
-2.0.2
+2.1.0

doc/Requirements.rst

@@ -14,7 +14,7 @@ Requirements
   ```
 - If installing the toolbox as a Python package or if using the Docker image, all required packages will be installed automatically, and manual installation as detailed above will not be necessary.
 
-- This software has been tested on Ubuntu 20.04.
+- This software has been tested on Ubuntu 20.04 and Ubuntu 22.04.
 
 - A working `FreeSurfer <https://freesurfer.net/>`_ installation (version 6 or newer) is required for running the 'shape' module of this toolbox. Also, make sure that FreeSurfer is sourced (i.e., FREESURFER_HOME is set as an environment variable) before running an analysis.
 

doc/Usage.rst

@@ -6,23 +6,25 @@ As a Command Line Tool
 
 .. code-block:: sh
 
-    run_fsqc 
-    --subjects_dir <directory> 
+    run_fsqc
+    --subjects_dir <directory>
     --output_dir <directory>
-    [--subjects SubjectID]
+    [--subjects SubjectID [SubjectID ...]]
     [--subjects-file <file>] [--screenshots]
     [--screenshots-html] [--surfaces] [--surfaces-html]
     [--skullstrip] [--skullstrip-html]
     [--fornix] [--fornix-html] [--hippocampus]
     [--hippocampus-html] [--hippocampus-label ... ]
     [--hypothalamus] [--hypothalamus-html] [--shape]
-    [--outlier] [--fastsurfer] [-h] [--more-help]
+    [--outlier] [--fastsurfer] [--no-group]
+    [--group-only] [--exit-on-error]
+    [--skip-existing] [-h] [--more-help]
     [...]
 
     Required Arguments:
     -------------------
     --subjects_dir <directory>
-        Subjects directory with a set of Freesurfer- or 
+        Subjects directory with a set of Freesurfer- or
         Fastsurfer-processed individual datasets.
 
     --output_dir <directory>
@@ -88,9 +90,18 @@ As a Command Line Tool
     --fastsurfer
         Use FastSurfer instead of FreeSurfer output
 
+    --no-group
+        run script in subject-level mode. will compute individual files and statistics, but not create group-level summaries.
+
+    --group-only
+        run script in group mode. will create group-level summaries from existing inputs. needs to be run on output directory with already existing results.
+
     --exit-on-error
         Terminate the program when encountering an error; otherwise, try to continue with the next module or case
 
+    --skip-existing
+        skips processing for a given case if output already exists, even with possibly different parameters or settings
+
     Getting Help:
     -------------
     -h, --help
@@ -102,34 +113,34 @@ As a Command Line Tool
     ---------------
     --screenshots_base <image>
         Filename of an image that should be used instead of
-        norm.mgz as the base image for the screenshots. Can be 
-        an individual file (which would not be appropriate for 
-        multi-subject analysis) or can be a file without 
+        norm.mgz as the base image for the screenshots. Can be
+        an individual file (which would not be appropriate for
+        multi-subject analysis) or can be a file without
         pathname and with the same filename across subjects within the 'mri'
-        subdirectory of an individual FreeSurfer results directory 
+        subdirectory of an individual FreeSurfer results directory
         (which would be appropriate for multi-subject analysis).
 
     --screenshots_overlay <image>
-        Path to an image that should be used instead of aseg.mgz 
-        as the overlay image for the screenshots can also be none. 
-        Can be an individual file (which would not be appropriate 
+        Path to an image that should be used instead of aseg.mgz
+        as the overlay image for the screenshots can also be none.
+        Can be an individual file (which would not be appropriate
         for multi-subject analysis) or can be a file without pathname
         and with the same filename across subjects within the 'mri' subdirectory
-        of an individual FreeSurfer results directory 
+        of an individual FreeSurfer results directory
         (which would be appropriate for multi-subject analysis).
 
     --screenshots_surf <surf> [<surf> ...]
-        One or more surface files that should be used instead of 
+        One or more surface files that should be used instead of
         [lr]h.white and [lr]h.pial; can also be none.
-        Can be one or more individual file(s) (which would not 
+        Can be one or more individual file(s) (which would not
         be appropriate for multi-subject analysis) or
-        can be a (list of) file(s) without pathname and with the same 
+        can be a (list of) file(s) without pathname and with the same
         filename across subjects within the 'surf'
-        subdirectory of an individual FreeSurfer results directory 
+        subdirectory of an individual FreeSurfer results directory
         (which would be appropriate for multi-subject analysis).
 
     --screenshots_views <view> [<view> ...]
-        One or more views to use for the screenshots in the form of 
+        One or more views to use for the screenshots in the form of
         x=<numeric> y=<numeric> and/or z=<numeric>.
         Order does not matter. Default views are x=-10 x=10 y=0 z=0.
 

fsqc/checkCCSize.py

@@ -70,7 +70,7 @@ def checkCCSize(subjects_dir, subject):
     relative_cc = sum_cc / intracranial_volume
 
     logging.info(
-        "Relative size of the corpus callosum is " + "{:.4}".format(relative_cc)
+        "Relative size of the corpus callosum is " + f"{relative_cc:.4}"
     )
 
     # Return

fsqc/checkContrast.py

@@ -49,20 +49,23 @@ def checkContrast(subjects_dir, subject):
     # Check if files exist
     path_pct_lh = os.path.join(subjects_dir, subject, "surf", "lh.w-g.pct.mgh")
     if not os.path.exists(path_pct_lh):
-        warnings.warn("WARNING: could not find " + path_pct_lh + ", returning NaNs")
+        warnings.warn("WARNING: could not find " + path_pct_lh + ", returning NaNs",
+            stacklevel = 2)
         return numpy.nan
 
     path_pct_rh = os.path.join(subjects_dir, subject, "surf", "rh.w-g.pct.mgh")
     if not os.path.exists(path_pct_rh):
-        warnings.warn("WARNING: could not find " + path_pct_rh + ", returning NaNs")
+        warnings.warn("WARNING: could not find " + path_pct_rh + ", returning NaNs",
+            stacklevel = 2)
         return numpy.nan
 
     path_label_cortex_lh = os.path.join(
         subjects_dir, subject, "label", "lh.cortex.label"
     )
     if not os.path.exists(path_label_cortex_lh):
         warnings.warn(
-            "WARNING: could not find " + path_label_cortex_lh + ", returning NaNs"
+            "WARNING: could not find " + path_label_cortex_lh + ", returning NaNs",
+            stacklevel = 2
         )
         return numpy.nan
 
@@ -71,7 +74,8 @@ def checkContrast(subjects_dir, subject):
     )
     if not os.path.exists(path_label_cortex_rh):
         warnings.warn(
-            "WARNING: could not find " + path_label_cortex_rh + ", returning NaNs"
+            "WARNING: could not find " + path_label_cortex_rh + ", returning NaNs",
+            stacklevel = 2
         )
         return numpy.nan
 
@@ -91,14 +95,14 @@ def checkContrast(subjects_dir, subject):
     con_lh_std = numpy.std(con_lh)
     con_lh_snr = con_lh_mean / con_lh_std
     logging.info(
-        "WM/GM contrast SNR for the left hemisphere: " + "{:.4}".format(con_lh_snr)
+        "WM/GM contrast SNR for the left hemisphere: " + f"{con_lh_snr:.4}"
     )
 
     con_rh_mean = numpy.mean(con_rh)
     con_rh_std = numpy.std(con_rh)
     con_rh_snr = con_rh_mean / con_rh_std
     logging.info(
-        "WM/GM contrast SNR for the right hemisphere: " + "{:.4}".format(con_rh_snr)
+        "WM/GM contrast SNR for the right hemisphere: " + f"{con_rh_snr:.4}"
     )
 
     # Return

fsqc/checkRotation.py

@@ -50,7 +50,8 @@ def checkRotation(subjects_dir, subject):
 
     if importlib.util.find_spec("transforms3d") is None:
         warnings.warn(
-            "WARNING: 'transforms3d' package required for running this script, returning NaNs."
+            "WARNING: 'transforms3d' package required for running this script, returning NaNs.",
+            stacklevel = 2
         )
         return np.nan, np.nan, np.nan
     else:
@@ -64,12 +65,13 @@ def checkRotation(subjects_dir, subject):
         warnings.warn(
             "WARNING: could not open "
             + os.path.join(subjects_dir, subject, "mri", "transforms", "talairach.lta")
-            + ", returning NaNs."
+            + ", returning NaNs.",
+            stacklevel = 2
         )
         return np.nan, np.nan, np.nan
 
     with open(
-        os.path.join(subjects_dir, subject, "mri", "transforms", "talairach.lta"), "r"
+        os.path.join(subjects_dir, subject, "mri", "transforms", "talairach.lta")
     ) as datafile:
         lines = datafile.readlines()
 
@@ -102,11 +104,11 @@ def checkRotation(subjects_dir, subject):
 
     logging.info(
         "Found Talairach rotation angles: x = "
-        + "{:.3}".format(rot_x)
+        + f"{rot_x:.3}"
         + ", y = "
-        + "{:.3}".format(rot_y)
+        + f"{rot_y:.3}"
         + ", z = "
-        + "{:.3}".format(rot_z)
+        + f"{rot_z:.3}"
         + " radians.",
     )