Prepare the 4.3.1 release

COPYRIGHT.rst

@@ -14,4 +14,4 @@ If not, see `https://www.gnu.org/licenses <https://www.gnu.org/licenses/>`__
 
 SPDX-License-Identifier: GPL-3.0-or-later
 
-Copyright (c): 2018-2023, Marcel Zwiers
+Copyright (c): 2018-2024, Marcel Zwiers

bidscoin/cli/_bidscoiner.py

@@ -34,6 +34,6 @@ def get_parser():
     parser.add_argument('-b','--bidsmap',           help='The study bidsmap file with the mapping heuristics. If the bidsmap filename is just the basename (i.e. no "/" in the name) then it is assumed to be located in the current directory or in bidsfolder/code/bidscoin. Default: bidsmap.yaml', default='bidsmap.yaml')
     parser.add_argument('-f','--force',             help='Process all subjects, regardless of existing subject folders in the bidsfolder. Otherwise these subject folders will be skipped', action='store_true')
     parser.add_argument('-c','--cluster',           help='Use the DRMAA library to submit the bidscoiner jobs to a high-performance compute (HPC) cluster', action='store_true')
-    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting bidscoiner jobs to the HPC cluster. NB: Use quotes and include at least one space character to prevent overearly parsing (default: -l walltime=00:30:00,mem=4gb)', default='-l walltime=00:30:00,mem=4gb')
+    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting bidscoiner jobs to the HPC cluster. NB: Use quotes and include at least one space character to prevent premature parsing (default: -l walltime=00:30:00,mem=4gb)', default='-l walltime=00:30:00,mem=4gb')
 
     return parser

bidscoin/cli/_deface.py

@@ -34,7 +34,7 @@ class CustomFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescri
     parser.add_argument('-p','--participant_label', help='Space separated list of sub-# identifiers to be processed (the sub-prefix can be left out). If not specified then all sub-folders in the bidsfolder will be processed', nargs='+')
     parser.add_argument('-o','--output',            help=f"A string that determines where the defaced images are saved. It can be the name of a BIDS datatype folder, such as 'anat', or of the derivatives folder, i.e. 'derivatives'. If output is left empty then the original images are replaced by the defaced images")
     parser.add_argument('-c','--cluster',           help='Use the DRMAA library to submit the deface jobs to a high-performance compute (HPC) cluster', action='store_true')
-    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting deface jobs to the HPC cluster (NB: Use quotes and include at least one space character to prevent overearly parsing)', default='-l walltime=00:30:00,mem=2gb')
+    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting deface jobs to the HPC cluster (NB: Use quotes and include at least one space character to prevent premature parsing)', default='-l walltime=00:30:00,mem=2gb')
     parser.add_argument('-a','--args',              help='Additional arguments (in dict/json-style) that are passed to pydeface (NB: Use quotes). See examples for usage', type=json.loads, default={})
     parser.add_argument('-f','--force',             help='Deface all images, regardless if they have already been defaced (i.e. if {"Defaced": True} in the json sidecar file)', action='store_true')
 

bidscoin/cli/_medeface.py

@@ -37,7 +37,7 @@ class CustomFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescri
     parser.add_argument('-p','--participant_label', help='Space separated list of sub-# identifiers to be processed (the sub-prefix can be left out). If not specified then all sub-folders in the bidsfolder will be processed', nargs='+')
     parser.add_argument('-o','--output',            help=f"A string that determines where the defaced images are saved. It can be the name of a BIDS datatype folder, such as 'anat', or of the derivatives folder, i.e. 'derivatives'. If output is left empty then the original images are replaced by the defaced images")
     parser.add_argument('-c','--cluster',           help='Use the DRMAA library to submit the deface jobs to a high-performance compute (HPC) cluster', action='store_true')
-    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting deface jobs to the HPC cluster (NB: Use quotes and include at least one space character to prevent overearly parsing)', default='-l walltime=00:30:00,mem=2gb')
+    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting deface jobs to the HPC cluster (NB: Use quotes and include at least one space character to prevent premature parsing)', default='-l walltime=00:30:00,mem=2gb')
     parser.add_argument('-a','--args',              help='Additional arguments (in dict/json-style) that are passed to pydeface (NB: Use quotes). See examples for usage', type=json.loads, default={})
     parser.add_argument('-f','--force',             help='Process all images, regardless if images have already been defaced (i.e. if {"Defaced": True} in the json sidecar file)', action='store_true')
 

bidscoin/cli/_skullstrip.py

@@ -31,8 +31,8 @@ class CustomFormatter(argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescri
     parser.add_argument('-m','--masked',            help="Globlike search pattern (relative to the subject/session folder) to select additional (3D/4D) images from the same space that need to be masked with the same mask, e.g. 'fmap/*_phasediff'. NB: This option can only be used if pattern yields a single file per session", type=str)
     parser.add_argument('-o','--output',            help="One or two output strings that determine where the skullstripped + additional masked images are saved. Each output string can be the name of a BIDS datatype folder, such as 'anat', or of the derivatives folder, i.e. 'derivatives' (default). If the output string is the same as the datatype then the original images are replaced by the skullstripped images", nargs='+')
     parser.add_argument('-f','--force',             help="Process images, regardless whether images have already been skullstripped (i.e. if {'SkullStripped': True} in the json sidecar file)", action='store_true')
-    parser.add_argument('-a','--args',              help="Additional arguments that are passed to synthstrip (NB: Use quotes and include at least one space character to prevent overearly parsing)", type=str, default='')
+    parser.add_argument('-a','--args',              help="Additional arguments that are passed to synthstrip (NB: Use quotes and include at least one space character to prevent premature parsing)", type=str, default='')
     parser.add_argument('-c','--cluster',           help='Use the DRMAA library to submit the skullstrip jobs to a high-performance compute (HPC) cluster', action='store_true')
-    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting skullstrip jobs to the HPC cluster (NB: Use quotes and include at least one space character to prevent overearly parsing)', default='-l walltime=0:05:00,mem=8gb')
+    parser.add_argument('-n','--nativespec',        help='Opaque DRMAA argument with native specifications for submitting skullstrip jobs to the HPC cluster (NB: Use quotes and include at least one space character to prevent premature parsing)', default='-l walltime=0:05:00,mem=8gb')
 
     return parser

bidscoin/cli/_slicereport.py

@@ -62,7 +62,7 @@ def get_parser():
     parser.add_argument('-q','--qcscores',          help="Column names for creating an accompanying tsv-file to store QC-rating scores (default: rating_overall)", default=['rating_overall'], nargs='+')
     parser.add_argument('-c','--cluster',           help='Use `torque` or `slurm` to submit the slicereport jobs to a high-performance compute (HPC) cluster', choices=['torque','slurm'])
     parser.add_argument('-m','--mem',               help='The amount of requested memory in GB for the cluster jobs', default='')
-    parser.add_argument('--operations',             help='One or more fslmaths operations that are performed on the input image (before slicing it for the report). OPERATIONS is opaquely passed as is: `fslmaths inputimage OPERATIONS reportimage`. NB: Use quotes and include at least one space character to prevent overearly parsing, e.g. " -Tmean" or "-Tstd -s 3" (default: -Tmean)', default='-Tmean')
+    parser.add_argument('--operations',             help='One or more fslmaths operations that are performed on the input image (before slicing it for the report). OPERATIONS is opaquely passed as is: `fslmaths inputimage OPERATIONS reportimage`. NB: Use quotes and include at least one space character to prevent premature parsing, e.g. " -Tmean" or "-Tstd -s 3" (default: -Tmean)', default='-Tmean')
     parser.add_argument('--suboperations',          help='The same as OPERATIONS but then for the sub-report instead of the main report: `fslmaths inputimage SUBOPERATIONS subreportimage` (default: -Tmean)', default='-Tmean')
     parser.add_argument('--options',                help='Main options of slicer (see below). (default: "s 1")', default=['s','1'], nargs='+')
     parser.add_argument('--outputs',                help='Output options of slicer (see below). (default: "x 0.4 x 0.5 x 0.6 y 0.4 y 0.5 y 0.6 z 0.4 z 0.5 z 0.6")', default=['x','0.4','x','0.5','x','0.6','y','0.4','y','0.5','y','0.6','z','0.4','z','0.5','z','0.6'], nargs='+')

docs/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ## [dev]
 
+## [4.3.1] - 2024-03-27
+
 ### Added
 - Update B0FieldIdentifier/Source when having multiple fieldmap runs (Github issue [#198](https://github.com/Donders-Institute/bidscoin/issues/198))
 - Slicereport support for all nibabel file-formats
@@ -436,7 +438,8 @@ A first stable release of BIDScoin :-)
 ### To do
 - Add support for non-imaging data
 
-[dev]: https://github.com/Donders-Institute/bidscoin/compare/4.3.0...HEAD
+[dev]: https://github.com/Donders-Institute/bidscoin/compare/4.3.1...HEAD
+[4.3.1]: https://github.com/Donders-Institute/bidscoin/compare/4.3.0...4.3.1
 [4.3.0]: https://github.com/Donders-Institute/bidscoin/compare/4.2.1...4.3.0
 [4.2.1]: https://github.com/Donders-Institute/bidscoin/compare/4.2.0...4.2.1
 [4.2.0]: https://github.com/Donders-Institute/bidscoin/compare/4.1.1...4.2.0

docs/_static/dictionary-custom.txt

@@ -11,6 +11,7 @@ AcquisitionTime
 Apptainer
 B0
 B0FieldIdentifier
+B0FieldIdentifiers
 B0FieldSource
 BEP024
 BIDSCOIN
@@ -237,7 +238,6 @@ nibabel
 nibabel2bids
 nr
 optimizations
-overearly
 p2
 parsable
 parsers
@@ -303,6 +303,7 @@ task2
 tempdir
 tooltip
 tooltips
+trackusage
 tsv
 underspecified
 unhandled

docs/bidsapps.rst

@@ -62,7 +62,8 @@ Before sharing or pre-processing their images, users may want to deface their an
                   [-a ARGS] [-f]
                   bidsfolder pattern
 
-    A wrapper around the 'pydeface' defacing tool (https://github.com/poldracklab/pydeface).
+    A wrapper around the 'pydeface' defacing tool (https://github.com/poldracklab/pydeface). Pydeface
+    requires an existing installation of FSL flirt
 
     Except for BIDS inheritances and IntendedFor usage, this wrapper is BIDS-aware (a 'bidsapp')
     and writes BIDS compliant output
@@ -93,7 +94,7 @@ Before sharing or pre-processing their images, users may want to deface their an
       -n NATIVESPEC, --nativespec NATIVESPEC
                             Opaque DRMAA argument with native specifications for submitting deface jobs
                             to the HPC cluster (NB: Use quotes and include at least one space character
-                            to prevent overearly parsing) (default: -l walltime=00:30:00,mem=2gb)
+                            to prevent premature parsing) (default: -l walltime=00:30:00,mem=2gb)
       -a ARGS, --args ARGS  Additional arguments (in dict/json-style) that are passed to pydeface (NB:
                             Use quotes). See examples for usage (default: {})
       -f, --force           Deface all images, regardless if they have already been defaced (i.e. if
@@ -118,7 +119,7 @@ This utility is very similar to the `deface <#defacing>`__ utility above, except
 
     A wrapper around the 'pydeface' defacing tool (https://github.com/poldracklab/pydeface) that
     computes a defacing mask on a (temporary) echo-combined image and then applies it to each
-    individual echo-image.
+    individual echo-image. Pydeface requires an existing installation of FSL flirt
 
     Except for BIDS inheritances and IntendedFor usage, this wrapper is BIDS-aware (a 'bidsapp')
     and writes BIDS compliant output
@@ -153,7 +154,7 @@ This utility is very similar to the `deface <#defacing>`__ utility above, except
       -n NATIVESPEC, --nativespec NATIVESPEC
                             Opaque DRMAA argument with native specifications for submitting deface jobs
                             to the HPC cluster (NB: Use quotes and include at least one space character
-                            to prevent overearly parsing) (default: -l walltime=00:30:00,mem=2gb)
+                            to prevent premature parsing) (default: -l walltime=00:30:00,mem=2gb)
       -a ARGS, --args ARGS  Additional arguments (in dict/json-style) that are passed to pydeface (NB:
                             Use quotes). See examples for usage (default: {})
       -f, --force           Process all images, regardless if images have already been defaced (i.e. if
@@ -211,13 +212,13 @@ The ``skullstrip``-tool is a wrapper around the synthstrip tool that writes BIDS
       -f, --force           Process images, regardless whether images have already been skullstripped
                             (i.e. if {'SkullStripped': True} in the json sidecar file) (default: False)
       -a ARGS, --args ARGS  Additional arguments that are passed to synthstrip (NB: Use quotes and
-                            include at least one space character to prevent overearly parsing) (default:)
+                            include at least one space character to prevent premature parsing) (default:)
       -c, --cluster         Use the DRMAA library to submit the skullstrip jobs to a high-performance
                             compute (HPC) cluster (default: False)
       -n NATIVESPEC, --nativespec NATIVESPEC
                             Opaque DRMAA argument with native specifications for submitting skullstrip
                             jobs to the HPC cluster (NB: Use quotes and include at least one space
-                            character to prevent overearly parsing) (default: -l walltime=0:05:00,mem=8gb)
+                            character to prevent premature parsing) (default: -l walltime=0:05:00,mem=8gb)
 
     examples:
       skullstrip myproject/bids anat/*_T1w*
@@ -235,20 +236,21 @@ Quality control
     usage: slicereport [-h] [-o OUTLINEPATTERN] [-i OUTLINEIMAGE]
                        [-p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-r REPORTFOLDER]
                        [-x XLINKFOLDER [XLINKFOLDER ...]] [-q QCSCORES [QCSCORES ...]]
-                       [-c {torque,slurm}] [--operations OPERATIONS] [--suboperations SUBOPERATIONS]
-                       [--options OPTIONS [OPTIONS ...]] [--outputs OUTPUTS [OUTPUTS ...]]
-                       [--suboptions SUBOPTIONS [SUBOPTIONS ...]]
+                       [-c {torque,slurm}] [-m MEM] [--operations OPERATIONS]
+                       [--suboperations SUBOPERATIONS] [--options OPTIONS [OPTIONS ...]]
+                       [--outputs OUTPUTS [OUTPUTS ...]] [--suboptions SUBOPTIONS [SUBOPTIONS ...]]
                        [--suboutputs SUBOUTPUTS [SUBOUTPUTS ...]]
                        bidsfolder pattern
 
-    A wrapper around the 'slicer' imaging tool (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Miscvis)
-    to generate a web page with a row of image slices for each subject in the BIDS repository, as
-    well as individual sub-pages displaying more detailed information. The input images are
-    selectable using wildcards, and the output images are configurable via various user options,
-    allowing you to quickly create a custom 'slicer' report to do visual quality control on any
-    3D/4D imagetype in your repository.
+    A wrapper around the 'fslmaths' (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Fslutils) and 'slicer'
+    imaging tools (https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/Miscvis) to generate a web page with a
+    row of image slices for each subject in the BIDS repository, as well as individual sub-pages
+    displaying more detailed information. The input images are selectable using wildcards (all
+    nibabel image formats are supported), and the output images are configurable via various user
+    options, allowing you to quickly create a custom 'slicer' report to do visual quality control
+    on any 3D/4D imagetype in your repository.
 
-    Requires an existing installation of FSL
+    Requires an existing installation of FSL tools (i.e. fsl-libvis, fsl-avwutils and fsl-flirt)
 
     Set the environment variable BIDSCOIN_DEBUG=TRUE to save intermediate data
 
@@ -282,11 +284,12 @@ Quality control
       -c {torque,slurm}, --cluster {torque,slurm}
                             Use `torque` or `slurm` to submit the slicereport jobs to a high-performance
                             compute (HPC) cluster
+      -m MEM, --mem MEM     The amount of requested memory in GB for the cluster jobs
       --operations OPERATIONS
                             One or more fslmaths operations that are performed on the input image (before
                             slicing it for the report). OPERATIONS is opaquely passed as is: `fslmaths
                             inputimage OPERATIONS reportimage`. NB: Use quotes and include at least one
-                            space character to prevent overearly parsing, e.g. " -Tmean" or "-Tstd -s 3"
+                            space character to prevent premature parsing, e.g. " -Tmean" or "-Tstd -s 3"
                             (default: -Tmean)
       --suboperations SUBOPERATIONS
                             The same as OPERATIONS but then for the sub-report instead of the main
@@ -305,7 +308,7 @@ Quality control
 
     OPTIONS:
       L                  : Label slices with slice number.
-      l [LUT]            : Use a different colour map from that specified in the header.
+      l [LUT]            : Use a different colour map from that specified in the header (see $FSLDIR/etc/luts)
       i [MIN] [MAX]      : Specify intensity min and max for display range.
       e [THR]            : Use the specified threshold for edges (if > 0 use this proportion of max-min,
                            if < 0, use the absolute value)