Utilities¶
bidscoin¶
The bidscoin command-line utility serves as a central starting point to test and manage your BIDScoin installation
usage: bidscoin [-h] [-l] [-p] [-i INSTALL [INSTALL ...]] [-u UNINSTALL [UNINSTALL ...]]
[-d DOWNLOAD] [-t [TEST]] [-b BIDSMAPTEST] [-v]
BIDScoin is a toolkit to convert and organize raw data-sets according to the Brain Imaging
Data Structure (BIDS)
The basic workflow is to run these two tools:
$ 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
Set the environment variable BIDSCOIN_DEBUG=TRUE in your console to run BIDScoin in it's more
verbose DEBUG logging mode
For more documentation see: https://bidscoin.readthedocs.io
optional arguments:
-h, --help show this help message and exit
-l, --list List all executables (i.e. the apps, bidsapps and utilities)
-p, --plugins List all installed plugins and template bidsmaps
-i INSTALL [INSTALL ...], --install INSTALL [INSTALL ...]
A list of template bidsmaps and/or bidscoin plugins to install
-u UNINSTALL [UNINSTALL ...], --uninstall UNINSTALL [UNINSTALL ...]
A list of template bidsmaps and/or bidscoin plugins to uninstall
-d DOWNLOAD, --download DOWNLOAD
Download folder. If given, tutorial MRI data will be downloaded here
-t [TEST], --test [TEST]
Test the bidscoin installation and template bidsmap
-b BIDSMAPTEST, --bidsmaptest BIDSMAPTEST
Test the run-items and their bidsnames of all normal runs in the
study bidsmap. Provide the bids-folder or the bidsmap filepath
-v, --version Show the installed version and check for updates
examples:
bidscoin -l
bidscoin -d data/bidscoin_tutorial
bidscoin -t
bidscoin -t my_template_bidsmap
bidscoin -b my_study_bidsmap
bidscoin -i data/my_template_bidsmap.yaml downloads/my_plugin.py
dicomsort¶
The dicomsort
command-line tool is a utility to move your flat- or DICOMDIR-organized files (see above) into a ‘seriesfolder’ organization. This can be useful to organise your source data in a more convenient and human readable way (DICOMDIR or flat DICOM directories can often be hard to comprehend). The BIDScoin tools will run dicomsort in a temporary folder if your data is not already organized in series-folders, so in principle you don’t really need to run it yourself (unless when you have a single multi-subject DICOMDIR file for your entire repository). Running dicomsort beforehand does, however, give you more flexibility in handling special cases that are not handled properly and it can also give you a speed benefit. If dicomsort do not satisfy your needs, then have a look at this reorganize_dicom_files tool.
usage: dicomsort [-h] [-i SUBPREFIX] [-j SESPREFIX] [-f FOLDERSCHEME] [-n NAMESCHEME]
[-p PATTERN] [--force] [-d]
dicomsource
Sorts and/or renames DICOM files into local subfolders, e.g. with 3-digit SeriesNumber-SeriesDescription
folder names (i.e. following the same listing as on the scanner console)
Supports flat DICOM as well as multi-subject/session DICOMDIR file structures.
positional arguments:
dicomsource The root folder containing the dicomsource/[sub/][ses/] dicomfiles or
the DICOMDIR file
optional arguments:
-h, --help show this help message and exit
-i SUBPREFIX, --subprefix SUBPREFIX
Provide a prefix string for recursive sorting of dicomsource/subject
subfolders (e.g. "sub-") (default: None)
-j SESPREFIX, --sesprefix SESPREFIX
Provide a prefix string for recursive sorting of
dicomsource/subject/session subfolders (e.g. "ses-") (default: None)
-f FOLDERSCHEME, --folderscheme FOLDERSCHEME
Naming scheme for the sorted DICOM Series subfolders. Follows the
Python string formatting syntax with DICOM field names in curly
bracers with an optional number of digits for numeric fields. Sorting
in subfolders is skipped when an empty folderscheme is given (but
note that renaming the filenames can still be performed) (default:
{SeriesNumber:03d}-{SeriesDescription})
-n NAMESCHEME, --namescheme NAMESCHEME
Optional naming scheme that can be provided to rename the DICOM
files. Follows the Python string formatting syntax with DICOM field
names in curly bracers with an optional number of digits for numeric
fields. Use e.g. "{PatientName}_{SeriesNumber:03d}_{SeriesDescription
}_{AcquisitionNumber:05d}_{InstanceNumber:05d}.dcm" or
"{InstanceNumber:05d}_{SOPInstanceUID}.IMA" for default names
(default: None)
-p PATTERN, --pattern PATTERN
The regular expression pattern used in re.match(pattern, dicomfile)
to select the dicom files (default: .*\.(IMA|dcm)$)
--force Sort the DICOM data even the DICOM fields of the folder/name scheme
are not in the data (default: False)
-d, --dryrun Add this flag to just print the dicomsort commands without actually
doing anything (default: False)
examples:
dicomsort sub-011/ses-mri01
dicomsort sub-011/ses-mri01/DICOMDIR -n {AcquisitionNumber:05d}_{InstanceNumber:05d}.dcm
dicomsort myproject/raw/DICOMDIR --subprefix pat^ --sesprefix
rawmapper¶
Another command-line utility that can be helpful in organizing your source data is rawmapper
. This utility can show you an overview (map) of all the values of DICOM-attributes of interest in your data-set and, optionally, used to rename your source data sub-folders. The latter option can be handy e.g. if you manually entered subject-identifiers as [Additional info] at the scanner console and you want to use these to rename your subject folders.
usage: rawmapper [-h] [-s SESSIONS [SESSIONS ...]] [-f FIELD [FIELD ...]] [-w WILDCARD]
[-o OUTFOLDER] [-r] [-c] [-n SUBPREFIX] [-m [SESPREFIX]] [-d]
sourcefolder
Maps out the values of a dicom attribute of all subjects in the sourcefolder, saves the result
in a mapper-file and, optionally, uses the dicom values to rename the sub-/ses-id's of the
subfolders. This latter option can be used, e.g. when an alternative subject id was entered in
the [Additional info] field during subject registration at the scanner console (i.e. this data
is stored in the dicom attribute named 'PatientComments')
positional arguments:
sourcefolder The source folder with the raw data in sub-#/ses-#/series
organisation
optional arguments:
-h, --help show this help message and exit
-s SESSIONS [SESSIONS ...], --sessions SESSIONS [SESSIONS ...]
Space separated list of selected sub-#/ses-# names / folders to be
processed. Otherwise all sessions in the bidsfolder will be selected
(default: None)
-f FIELD [FIELD ...], --field FIELD [FIELD ...]
The fieldname(s) of the dicom attribute(s) used to rename or map the
subid/sesid foldernames (default: ['PatientComments',
'ImageComments'])
-w WILDCARD, --wildcard WILDCARD
The Unix style pathname pattern expansion that is used to select the
series from which the dicomfield is being mapped (can contain
wildcards) (default: *)
-o OUTFOLDER, --outfolder OUTFOLDER
The mapper-file is normally saved in sourcefolder or, when using this
option, in outfolder (default: None)
-r, --rename If this flag is given sub-subid/ses-sesid directories in the
sourcefolder will be renamed to sub-dcmval/ses-dcmval (default:
False)
-c, --clobber Flag to rename the directories, even if the target-directory already
exists (default: False)
-n SUBPREFIX, --subprefix SUBPREFIX
The prefix common for all the source subject-folders. Use a '*'
wildcard if there is no prefix (default: sub-)
-m [SESPREFIX], --sesprefix [SESPREFIX]
The prefix common for all the source session-folders. Use a '*'
wildcard if there is no prefix or an empty value if there are no
sessions (default: ses-)
-d, --dryrun Add this flag to dryrun (test) the mapping or renaming of the sub-
subid/ses-sesid directories (i.e. nothing is stored on disk and
directory names are not actually changed)) (default: False)
examples:
rawmapper myproject/raw
rawmapper myproject/raw -f AcquisitionDate
rawmapper myproject/raw -s sub-100/ses-mri01 sub-126/ses-mri01
rawmapper myproject/raw -r -f ManufacturerModelName AcquisitionDate --dryrun
rawmapper myproject/raw -r -s sub-1*/* sub-2*/ses-mri01 --dryrun
rawmapper -f EchoTime -w *fMRI* myproject/raw
bidsparticipants¶
The bidsparticipants tool is useful for (re-)generating a participants.tsv file from your source data (without having to run bidscoiner)
usage: bidsparticipants [-h] [-k KEYS [KEYS ...]] [-d] [-b BIDSMAP] [-v]
sourcefolder bidsfolder
(Re)scans data sets in the source folder for subject meta data to populate the participants.tsv
file in the bids directory, e.g. after you renamed (be careful there!), added or deleted data
in the bids folder yourself.
Provenance information, warnings and error messages are stored in the
bidsfolder/code/bidscoin/bidsparticipants.log file.
positional arguments:
sourcefolder The study root folder containing the raw source data folders
bidsfolder The destination / output folder with the bids data
optional arguments:
-h, --help show this help message and exit
-k KEYS [KEYS ...], --keys KEYS [KEYS ...]
Space separated list of the participants.tsv columns. Default:
'session_id' 'age' 'sex' 'size' 'weight'
-d, --dryrun Add this flag to only print the participants info on screen
-b BIDSMAP, --bidsmap BIDSMAP
The study bidsmap file with the mapping heuristics. If the bidsmap
filename is relative (i.e. no "/" in the name) then it is assumed to
be located in bidsfolder/code/bidscoin. Default: bidsmap.yaml
-v, --version Show the BIDS and BIDScoin version
examples:
bidsparticipants myproject/raw myproject/bids
bidsparticipants myproject/raw myproject/bids -k participant_id age sex