| 1 |
full_title="Demo of automatic conversion of DICOMs into BIDS and managing data using DataLad" |
| 2 |
run "set -eu # Fail early if any error happens" |
| 3 |
say "Heudiconv (Heuristic DICOM Converter, https://github.com/nipy/heudiconv) now allows to create DataLad datasets with your neuroimaging data as soon as it comes from the MRI scanner." |
| 4 |
|
| 5 |
say "In this example we will use a heudiconv heuristic developed and used at DBIC (Dartmouth Brain Imaging Center) to have all collected data made available as BIDS datasets. See http://goo.gl/WEoCge describing the naming convention." |
| 6 |
|
| 7 |
say "We will demonstrate it on some data acquired on a phantom, mimicking multiple studies/subjects/sessions setup, and already available through datalad:" |
| 8 |
run "datalad install -r -g -J4 ///dicoms/dartmouth-phantoms/bids_test4-20161014" |
| 9 |
say "We will now run heudiconv pointing to DBIC heuristic on data for the first five sessions (could be done one scanning session at a time, or entire directory as well), while instructing heudiconv to place produced data under DataLad control." |
| 10 |
say "First we will download the heuristic file from heudiconv's repository:" |
| 11 |
run "wget https://raw.githubusercontent.com/nipy/heudiconv/master/heuristics/dbic_bids.py" |
| 12 |
|
| 13 |
say "and then run heudiconv instructing to process multiple sessions, and place all converted data under a dataset called 'demo' (for the purpose of the demo we will convert only all anatomicals):" |
| 14 |
run "heudiconv --bids --datalad -f ./dbic_bids.py -o demo bids_test4-20161014/phantom-[1-5]/*{scout,T1w}*" |
| 15 |
|
| 16 |
say "Heudiconv has created a hierarchy of DataLad datasets, with levels PI/Researcher/study" |
| 17 |
run "datalad ls -r demo" |
| 18 |
|
| 19 |
say "where separate scanning sessions detected by heudiconv were contributed as separate commits to the sub-dataset corresponding to the specific study (as discovered from 'Study Description' field in DICOM):" |
| 20 |
run "cd demo/Halchenko/Yarik/950_bids_test4" |
| 21 |
run "git log --pretty=oneline" |
| 22 |
|
| 23 |
say "Not only that all DICOMs were converted into a BIDS-compliant dataset, this heuristic also provided templates for mandatory files in BIDS format, some of which were placed directly under git to ease modification and integration of changes:" |
| 24 |
run "cat dataset_description.json" |
| 25 |
say "and you can easily find files/fields which need adjustment with information only you might know (design, author, license, etc) by searching for TODO" |
| 26 |
run "git grep TODO" |
| 27 |
say "All binary data and otherwise 'sensitive' files (e.g. _scans.tsv files) where placed under git-annex control:" |
| 28 |
run "git annex list" |
| 29 |
|
| 30 |
say "Original DICOMS, converted anatomicals (which are not yet defaced), and _scans.tsv files also obtained a meta-data tag to allow easy identification of data which did not go through anonimization step yet and might potentially contain subject-identifying information:" |
| 31 |
run "datalad metadata sourcedata/sub-phantom1sid1" |
| 32 |
|
| 33 |
say "These datasets are ready to be installed from this location to the processing box. In the demo we will just perform it on the localhost and only for the current study since sub-datasets are independent of their supers:" |
| 34 |
run 'datalad install -g -r -s localhost:$PWD ~/950_bids_test4-process' |
| 35 |
run "cd ~/950_bids_test4-process" |
| 36 |
|
| 37 |
say "Data now could be processed/analyzed/etc in this dataset 'sibling'." |
| 38 |
|
| 39 |
say "According to BIDS derivative (e.g. preprocessed) data should reside under derivatives/, so we create a new subdataset" |
| 40 |
run "datalad create -d . derivatives/preprocess1" |
| 41 |
say "and do our thorough preprocessing (see http://bids-apps.neuroimaging.io for ready to use pipelines like mriqc and fmriprep), in our case a sample brain extraction:" |
| 42 |
run "source /etc/fsl/fsl.sh # to enable FSL on NeuroDebian systems" |
| 43 |
run "mkdir -p derivatives/preprocess1/sub-phantom1sid1/ses-localizer/anat/ # create target output directory" |
| 44 |
run "bet {,derivatives/preprocess1/}sub-phantom1sid1/ses-localizer/anat/sub-phantom1sid1_ses-localizer_T1w.nii.gz" |
| 45 |
|
| 46 |
say "To keep control over the versions of all data we work with, we add results of pre-processing under DataLad version control" |
| 47 |
run "datalad save -m 'added initial preprocessing (well -- BETing output)' derivatives/preprocess1/*" |
| 48 |
say "and then also adjust meta-data templates heudiconv pre-generated for us:" |
| 49 |
run "sed -i -e 's,First1 Last1,Data Lad,g' -e '/TODO/d' dataset_description.json" |
| 50 |
say "We save all so far accumulated changes" |
| 51 |
run "datalad save -m 'Finished initial preprocessing, specified PI in dataset description and removed TODOs.'" |
| 52 |
|
| 53 |
say "Whenever more data is acquired, heudiconv conversion could be ran again to complement previously acquired datasets with new data." |
| 54 |
run "cd" |
| 55 |
run "heudiconv --bids --datalad -f ./dbic_bids.py -o demo bids_test4-20161014/phantom-[6-9]/*{scout,T1w}*" |
| 56 |
|
| 57 |
say "Now we can go to the processing 'box' again and update the entire hierarchy (in our case actually just one but we could have cloned entire tree for a PI) of the datasets while incorporating with possible changes already done on the processing box, while git would track the entire history of modifications." |
| 58 |
run "cd ~/950_bids_test4-process" |
| 59 |
run "datalad update --merge -r" |
| 60 |
run "git status # all clear" |
| 61 |
run "cat dataset_description.json # and our changes are still in place" |
| 62 |
say "Now you could process newly acquired data... rinse repeat, while keeping the full history of actions:" |
| 63 |
run "git log --pretty=oneline" |
| 64 |
|
| 65 |
say "See also demos on how data could be exported and/or published whenever you are ready to share it publicly or with your collaborators." |