Usage¶
The convert_source
package is intended to be used for the conversion of source DICOM
, PAR REC
, and NIFTI
data to BIDS NIFTI.
Warning
The use of
PAR REC
files for image conversion should be discouraged as this is not an archival format (as most of the necessary metadata is not written to file). See this link for further details.The use of
NIFTI
files is also discouraged as most, if not all of the metadata information is lost once the source data has been converted (, unless there is a corresponding JSON file of the same name).
Command Line Interface¶
usage: study_proc [-h] [-s STUDY_DIR] [-o OUT_DIR] [-c CONFIG.yml] [--no-gzip]
[--compress INT] [--zero-pad INT] [--append-dwi-info]
[--verbose] [--version] [--path-env PATH_VAR]
Convert source data of a study's imaging data to BIDS NIFTI data.
optional arguments:
-h, --help show this help message and exit
Required Argument(s):
-s STUDY_DIR, -study STUDY_DIR, --study-dir STUDY_DIR
Parent study image directory for all subjects.
-o OUT_DIR, -out OUT_DIR, --out-dir OUT_DIR
Output directory.
Optional Argument(s):
-c CONFIG.yml, -config CONFIG.yml, --config-file CONFIG.yml
Input YAML configuration file. If no configuration
file is provided, then the default configuration file
is used.
--no-gzip DO NOT gzip the resulting BIDS NIFTI files [default:
False].
--compress INT Compression level [1 - 9] - 1 is fastest, 9 is
smallest [default: 6].
--zero-pad INT The amount of zeropadding to pad the run numbers of
the BIDS NIFTI files (e.g. '--zero-pad=2' corresponds
to '01') [default: 2].
--append-dwi-info RECOMMENDED: Appends DWI acquisition information
(unique non-zero b-values, and TE, in msec.) to BIDS
acquisition filename of diffusion weighted image files
[default: False].
--verbose Enables verbose output to the command line.
--version Prints the version of 'convert_source', then exits.
Expert Option(s):
--path-env PATH_VAR Environmental path variable or variables for
dependencies (e.g. the path to 'dcm2niix'). NOTE: This
option is repeatable, and can thus be specified
multiple times.
Python Module Interface¶
from convert_source.batch_convert import batch_proc
[imgs, jsons, bvals, bvecs] = batch_proc(study_img_dir='</path/to/study/directory>',
... out_dir='</path/to/output/directory>',
... gzip=True,
... append_dwi_info=True,
... zero_pad=2,
... cprss_lvl=6)
...
Study Directory Layout¶
Note
The following directory layouts shown below are used in the following examples in the examples section.
Study Directory Layout 1¶
For convert_source
to infer each subject’s and session ID correctly, the study directory layout must conform to one of the layouts shown below.
The study directory layout shown here is for a study consisting of 14 subjects, each with one session.
Study_Image_Directory
├── 001-001
├── 002-001
├── 003-001
├── 004-001
├── 005-001
├── 006-001
├── 007-001
├── 008-001
├── 009-001
├── 010-001
├── 011-001
├── 012-001
├── 013-001
└── 014-001
Study Directory Layout 2¶
In the case of a study with only one session, the directory layout could also be as shown:
Study_Image_Directory
├── 001
├── 002
├── 003
├── 004
├── 005
├── 006
├── 007
├── 008
├── 009
├── 010
├── 011
├── 012
├── 013
└── 014
Study Directory Layout 3¶
This layout is for a study of 7 subjects with 2 sessions.
Study_Image_Directory
├── 001-001
├── 001-002
├── 002-001
├── 002-002
├── 003-001
├── 003-002
├── 004-001
├── 004-002
├── 005-001
├── 005-002
├── 006-001
├── 006-002
├── 007-001
└── 007-002
Subject Directory Layout¶
Each subject’s directory should consist of image files, or in the case shown below, nested directories of image files.
Study_Image_Directory
└── 001-001
├── DICOM
│ └── ST000000
│ ├── SE000000
│ │ └── MR000002.dcm
│ ├── SE000001
│ │ ├── MR000001.dcm
│ │ .
│ │ .
│ │ .
│ │ └── MR000056.dcm
│ └── SE000002
│ ├── MR000000.dcm
│ .
│ .
│ .
│ └── MR000015.dcm
├── NIFTI
│ ├── DWI_68_DIR.bvec
│ ├── DWI_68_DIR.bval
│ ├── DWI_68_DIR.json
│ ├── DWI_68_DIR.nii.gz
│ ├── DWI_B0.json
│ ├── DWI_B0.nii.gz
│ ├── rsfMRI.json
│ ├── rsfMRI.nii.gz
│ ├── T1_AXIAL.json
│ └── T1_AXIAL.nii.gz
└── PAR REC
├── AXIAL.PAR
├── AX_SWIP_MPR.PAR
├── B0_DWI.PAR
└── DWI_MB4_SENSE_1_3.PAR