From 4f0bd424a368b9e3c0a75fa861d325f91a9fcd0a Mon Sep 17 00:00:00 2001 From: Marcel Zwiers Date: Tue, 13 Feb 2024 17:00:21 +0100 Subject: [PATCH] Doc tweaks --- bidscoin/bidsapps/deface.py | 2 +- bidscoin/bidsapps/medeface.py | 2 +- bidscoin/bidsapps/skullstrip.py | 2 +- bidscoin/cli/_bcoin.py | 6 +++--- bidscoin/plugins/README | 2 +- docs/bidsapps.rst | 35 +++++++++++++++++++-------------- docs/utilities.rst | 10 ++++++---- docs/workflow.rst | 29 +++++++++++++++------------ 8 files changed, 49 insertions(+), 39 deletions(-) diff --git a/bidscoin/bidsapps/deface.py b/bidscoin/bidsapps/deface.py index e7e64e86..56b76770 100755 --- a/bidscoin/bidsapps/deface.py +++ b/bidscoin/bidsapps/deface.py @@ -21,7 +21,7 @@ if find_spec('bidscoin') is None: sys.path.append(str(Path(__file__).parents[2])) from bidscoin import bcoin, bids, lsdirs, trackusage, DEBUG -from ..due import due, Doi +from bidscoin.due import due, Doi @due.dcite(Doi('10.5281/zenodo.3524400'), description='A tool to remove facial structure from MRI images', tags=['reference-implementation']) diff --git a/bidscoin/bidsapps/medeface.py b/bidscoin/bidsapps/medeface.py index 4d8ff0c6..004feb55 100755 --- a/bidscoin/bidsapps/medeface.py +++ b/bidscoin/bidsapps/medeface.py @@ -23,7 +23,7 @@ if find_spec('bidscoin') is None: sys.path.append(str(Path(__file__).parents[2])) from bidscoin import bcoin, bids, lsdirs, trackusage, DEBUG -from ..due import due, Doi +from bidscoin.due import due, Doi @due.dcite(Doi('10.5281/zenodo.3524400'), description='A tool to remove facial structure from MRI images', tags=['reference-implementation']) diff --git a/bidscoin/bidsapps/skullstrip.py b/bidscoin/bidsapps/skullstrip.py index 29590d89..d43ce114 100755 --- a/bidscoin/bidsapps/skullstrip.py +++ b/bidscoin/bidsapps/skullstrip.py @@ -21,7 +21,7 @@ if find_spec('bidscoin') is None: sys.path.append(str(Path(__file__).parents[2])) from bidscoin import bcoin, bids, lsdirs, trackusage, DEBUG -from ..due import due, Doi +from bidscoin.due import due, Doi @due.dcite(Doi('10.1016/j.neuroimage.2022.119474'), description='Robust, universal skull-stripping for brain images of any type', tags=['reference-implementation']) diff --git a/bidscoin/cli/_bcoin.py b/bidscoin/cli/_bcoin.py index 8e61129d..5bc1521a 100755 --- a/bidscoin/cli/_bcoin.py +++ b/bidscoin/cli/_bcoin.py @@ -7,11 +7,11 @@ $ bidsmapper sourcefolder bidsfolder # This produces a study bidsmap and launches a GUI $ bidscoiner sourcefolder bidsfolder # This converts your data to BIDS according to the study bidsmap -Default settings and template bidsmaps are stored in the ".bidscoin" folder in your home directory +Default settings and template bidsmaps are stored in the `.bidscoin` folder in your home directory (you can modify them to your needs with any plain text editor) -Set the environment variable BIDSCOIN_DEBUG=TRUE to run BIDScoin in a more verbose logging mode and -BIDSCOIN_CONFIG=/writable/path/to/config.toml if you like to use a different config file. +Set the environment variable `BIDSCOIN_DEBUG=TRUE` to run BIDScoin in a more verbose logging mode and +`BIDSCOIN_CONFIG=/writable/path/to/config.toml` if you like to use a different config file. Citation reports can be generated with the help of duecredit (https://github.com/duecredit/duecredit) For more documentation see: https://bidscoin.readthedocs.io diff --git a/bidscoin/plugins/README b/bidscoin/plugins/README index cb726bec..b1b712d4 100644 --- a/bidscoin/plugins/README +++ b/bidscoin/plugins/README @@ -14,7 +14,7 @@ BIDScoin's library modules named 'bcoin' and, most notably, 'bids'""" import logging from pathlib import Path -from ..due import due, Doi +from bidscoin.due import due, Doi from bidscoin.bids import Bidsmap, Run, Plugin LOGGER = logging.getLogger(__name__) diff --git a/docs/bidsapps.rst b/docs/bidsapps.rst index 8e68a39a..3419d069 100644 --- a/docs/bidsapps.rst +++ b/docs/bidsapps.rst @@ -174,7 +174,7 @@ The ``skullstrip``-tool is a wrapper around the synthstrip tool that writes BIDS :: usage: skullstrip [-h] [-p PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [-m MASKED] - [-o OUTPUT [OUTPUT ...]] [-f] [-a ARGS] [-c {torque,slurm}] + [-o OUTPUT [OUTPUT ...]] [-f] [-a ARGS] [-c] [-n NATIVESPEC] bidsfolder pattern A wrapper around FreeSurfer's 'synthstrip' skull stripping tool @@ -211,14 +211,17 @@ 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) - -c {torque,slurm}, --cluster {torque,slurm} - Use `torque` or `slurm` to submit the skullstrip jobs to a high-performance - compute (HPC) cluster. Can only be used if `--masked` is left empty + include at least one space character to prevent overearly 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) examples: skullstrip myproject/bids anat/*_T1w* - skullstrip myproject/bids anat/*_T1w* -p 001 003 -a ' --no-csf' + skullstrip myproject/bids anat/*_T1w* -p 001 003 -a " --no-csf" skullstrip myproject/bids fmap/*_magnitude1* -m fmap/*_phasediff* -o extra_data fmap skullstrip myproject/bids fmap/*_acq-mylabel*_magnitude1* -m fmap/*_acq-mylabel_* -o fmap @@ -231,8 +234,8 @@ 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] + [-x XLINKFOLDER [XLINKFOLDER ...]] [-q QCSCORES [QCSCORES ...]] + [-c {torque,slurm}] [--operations OPERATIONS] [--suboperations SUBOPERATIONS] [--options OPTIONS [OPTIONS ...]] [--outputs OUTPUTS [OUTPUTS ...]] [--suboptions SUBOPTIONS [SUBOPTIONS ...]] [--suboutputs SUBOUTPUTS [SUBOUTPUTS ...]] @@ -247,6 +250,8 @@ Quality control Requires an existing installation of FSL + Set the environment variable BIDSCOIN_DEBUG=TRUE to save intermediate data + positional arguments: bidsfolder The bids-directory with the subject data pattern Globlike search pattern to select the images in bidsfolder to be reported, @@ -255,9 +260,9 @@ Quality control options: -h, --help show this help message and exit -o OUTLINEPATTERN, --outlinepattern OUTLINEPATTERN - Globlike search pattern to select red outline images that are projected on top - of the reported images (i.e. 'outlinepattern' must yield the same number of - images as 'pattern'. Prepend `outlinedir:` if your outline images are in + Globlike search pattern to select red outline images that are projected on + top of the reported images (i.e. 'outlinepattern' must yield the same number + of images as 'pattern'. Prepend `outlinedir:` if your outline images are in `outlinedir` instead of `bidsdir` (see examples below)` -i OUTLINEIMAGE, --outlineimage OUTLINEIMAGE A common red-outline image that is projected on top of all images @@ -284,13 +289,13 @@ Quality control space character to prevent overearly 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 report: - `fslmaths inputimage SUBOPERATIONS subreportimage` (default: -Tmean) + The same as OPERATIONS but then for the sub-report instead of the main + report: `fslmaths inputimage SUBOPERATIONS subreportimage` (default: -Tmean) --options OPTIONS [OPTIONS ...] Main options of slicer (see below). (default: "s 1") --outputs OUTPUTS [OUTPUTS ...] - 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") + 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") --suboptions SUBOPTIONS [SUBOPTIONS ...] Main options of slicer for creating the sub-reports (same as OPTIONS, see below). (default: OPTIONS) diff --git a/docs/utilities.rst b/docs/utilities.rst index e3a9addf..472ef97c 100644 --- a/docs/utilities.rst +++ b/docs/utilities.rst @@ -19,10 +19,11 @@ The bidscoin command-line utility serves as a central starting point to test and $ bidsmapper sourcefolder bidsfolder # This produces a study bidsmap and launches a GUI $ bidscoiner sourcefolder bidsfolder # This converts your data to BIDS according to the study bidsmap - Default settings and template bidsmaps are stored in the ".bidscoin" folder in your home directory + Default settings and template bidsmaps are stored in the `.bidscoin` folder in your home directory (you can modify them to your needs with any plain text editor) - Set the environment variable BIDSCOIN_DEBUG=TRUE to run BIDScoin in a more verbose logging mode. + Set the environment variable `BIDSCOIN_DEBUG=TRUE` to run BIDScoin in a more verbose logging mode and + `BIDSCOIN_CONFIG=/writable/path/to/config.toml` if you like to use a different config file. Citation reports can be generated with the help of duecredit (https://github.com/duecredit/duecredit) For more documentation see: https://bidscoin.readthedocs.io @@ -202,8 +203,9 @@ The bidsparticipants tool is useful for (re-)generating a participants.tsv file -d, --dryrun Do not save anything, only print the participants info on screen -b BIDSMAP, --bidsmap BIDSMAP 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 - bidsfolder/code/bidscoin. Default: bidsmap.yaml + 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 examples: bidsparticipants myproject/raw myproject/bids diff --git a/docs/workflow.rst b/docs/workflow.rst index e7ee6375..05fadbd6 100644 --- a/docs/workflow.rst +++ b/docs/workflow.rst @@ -46,13 +46,14 @@ Step 1a: Running the bidsmapper -h, --help show this help message and exit -b BIDSMAP, --bidsmap BIDSMAP 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 - bidsfolder/code/bidscoin. Default: bidsmap.yaml + 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 -t TEMPLATE, --template TEMPLATE The bidsmap template file with the default heuristics (this could be provided - by your institute). If the bidsmap filename is just the basename (i.e. no '/' in - the name) then it is assumed to be located in the bidscoin config folder. Default: - bidsmap_dccn + by your institute). If the bidsmap filename is just the basename (i.e. no '/' + in the name) then it is assumed to be located in the bidscoin config folder. + Default: bidsmap_dccn -p PLUGINS [PLUGINS ...], --plugins PLUGINS [PLUGINS ...] List of plugins to be used. Default: the plugin list of the study/template bidsmap) @@ -112,13 +113,14 @@ Step 1b: Running the bidseditor -h, --help show this help message and exit -b BIDSMAP, --bidsmap BIDSMAP 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 - bidsfolder/code/bidscoin. Default: bidsmap.yaml + 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 -t TEMPLATE, --template TEMPLATE The template bidsmap file with the default heuristics (this could be provided - by your institute). If the bidsmap filename is just the basename (i.e. no "/" in - the name) then it is assumed to be located in the bidscoin config folder. Default: - bidsmap_dccn + by your institute). If the bidsmap filename is just the basename (i.e. no "/" + in the name) then it is assumed to be located in the bidscoin config folder. + Default: bidsmap_dccn examples: bidseditor myproject/bids @@ -182,7 +184,7 @@ Step 2: Running the bidscoiner information from the bidsmap.yaml file. Edit this bidsmap to your needs using the bidseditor tool before running this function or (re-)run the bidsmapper whenever you encounter unexpected data. You can run bidscoiner after all data has been collected, or run / re-run it whenever - new data has been added to your source folder (presuming the scan protocol hasn't changed). + new data has been added to your source folder (presuming the scan protocol has not changed). Also, if you delete a subject/session folder from the bidsfolder, it will simply be re-created from the sourcefolder the next time you run the bidscoiner. @@ -203,8 +205,9 @@ Step 2: Running the bidscoiner be selected -b BIDSMAP, --bidsmap BIDSMAP 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 - bidsfolder/code/bidscoin. Default: bidsmap.yaml + 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 -f, --force Process all subjects, regardless of existing subject folders in the bidsfolder. Otherwise these subject folders will be skipped -c, --cluster Use the DRMAA library to submit the bidscoiner jobs to a high-performance