README_BIDS.txt

GE to BIDS conversion

M. Czisch
2.3.2018  version 1.0.1
29.5.2018 version 1.0.2

BecomeVersion: 1.0.2

**************
*  PURPOSE:  *
**************

This collection of MATLAB files serves to transfer GE and other data from the
BeCome study and to create a common data structure according to the BIDS
format. This format has been proposed in:

"The brain imaging data structure, a format for organizing and describing
outputs of neuroimaging experiments."

Gorgolewski KJ, Auer T, Calhoun VD, Craddock RC, Das S, Duff EP, Flandin G, 
Ghosh SS, Glatard T, Halchenko YO, Handwerker DA, Hanke M, Keator D, Li X, 
Michael Z, Maumet C, Nichols BN, Nichols TE, Pellman J, Poline JB, Rokem A, 
Schaefer G, Sochat V, Triplett W, Turner JA, Varoquaux G, Poldrack RA.

Sci Data. 2016 Jun 21;3:160044. doi: 10.1038/sdata.2016.44.


**************
*    CALL :  *
**************

make_BIDS(directory_name)

e.g. make_BIDS('/run/media/spectro/DATAPART1/FORSCHUNGSAMBULANZ/Archiv_Garching/FOK/FOK0075')

****************
*    OUTPUT :  *
****************

subdirectory with the BIDS structure as described in detail below

e.g.
/run/media/spectro/DATAPART1/FORSCHUNGSAMBULANZ/Archiv_Garching/FOK/FOK0075/FOK0075_BIDS

********************
*   SUBROUTINES:   *
********************
all versions 1.0.1, if not otherwise indicated
check_BIOMAX
check_BIDS
mkdir_BIDS
read_GE_BIDS
convert_GE_BIDS
    dataset_func_description_BIDS
dataset_description_BIDS
convert_ANALYZER_BIDS
convert_LOG_BIDS
convert_EDF_BIDS
convert_PPG_BIDS (starting version 1.0.2)
Hariri_logfile_bids
NBack_logfile_bids
TET_logfile_bids
IST_logfile_bids


*****************
* REQUIREMENTS  *
*****************


The script expects that the data have already been checked for consistency by using the script "consistency.m". This initial check must have created a file named

biomax_out_<SUBJECT_ID>_<VERIFIED/MODIFIED>_<DATE><USER>.txt

e.g.
    biomax_out_FOK0052_VERIFIED_12072017IE.txt
or
    biomax_out_FOR0047_MODIFIED_29082017MC.txt

For all 19 MR experiments of the BeCOME study, this file contains information
whether all data are available:
    Ser = MR dicom files
    LOG = presentation log files
    EDF = Eyetracker edf files
    PPG = GE physiological recordings
    Analyzer = Analyzer ECG data
    Blood = blood samples (not used in version 1.0.1)
  

*****************
*  DESCRIPTION  *
*****************

After running the script, the BIDS data directory contains:

- a copy of the biomax_out* file described above

- a json file with general BeCome data, date of BIDS conversion, BIDS version, and a summary
of the biomax_out data. 

- five subdirectories "anat" (anatomy), "func" (functional) and "dwi" (DTI
data) with MRI data, "dicom" containing a single raw dicom file for later 
reference to any header information, and "physio" containing 
Eye Tracker edf (and asc) data and Analyzer data.

"anat":     sub-FOK0079_T1w.nii.gz
            sub-FOK0079_FLAIR.nii.gz    

            2 files with the reference EPI images:
            sub-FOK0079_inplaneT2star_run-1.nii.gz
            sub-FOK0079_inplaneT2star_run-2.nii.gz

        all files come with json files as created by dicom2niix

"dwi":      sub-FOK0079_run-1_dwi.nii.gz
            sub-FOK0079_run-2_dwi.nii.gz

        run1 contains the full DTI images
        run2 is a short data set with inverted phase encoding direction,
            needed for topup correction in FSL
        all files come with json files as created by dicom2niix

        for each run, two files "bval" and "bvec", created by dicom2niix,
        are describing the bvalues and gradient directions used in the
        DTI experiment. These values are already in the image coordinate 
        system.

"func":     sub-FOK0079_task-hariri_bold.nii.gz
            sub-FOK0079_task-ist_bold.nii.gz
            sub-FOK0079_task-nback_bold.nii.gz
            sub-FOK0079_task-reward_bold.nii.gz
            sub-FOK0079_task-tet_bold.nii.gz

            sub-FOK0079_task-rest_run-1_bold.nii.gz
            sub-FOK0079_task-rest_run-2_bold.nii.gz
            sub-FOK0079_task-rest_run-3_bold.nii.gz

        with the fMRI timeseries of Hariri, IST, Nback, Reward, and 
        time-estimation tasks, and the 3 resting state dataset

        all files come with json files as created by dicom2niix, and
        being augmented with time series information suggested by BIDS,
        and BIOMAX flags indicating existence of edf, log, eeg, and ppg
        files.

        The original Presentations logfiles are also stored here with
        the following naming convention:

            sub-FOK0079_task-hariri_bold.log
            sub-FOK0079_task-ist_bold.log
            sub-FOK0079_task-nback_bold.log
            sub-FOK0079_task-reward_bold.log
            sub-FOK0079_task-tet_bold.log

        In addition, "tsv" files are present, however, not been 
        extensively tested:

            sub-FOK0079_task-hariri_events.tsv
            sub-FOK0079_task-ist_events.tsv
            sub-FOK0079_task-nback_events.tsv
            sub-FOK0079_task-tet_events.tsv
            (reward missing)

        Finally, README files exist which include information on the
        experiment as written down during data collection by the MTAs.
        If the file is empty, there has been nothing special to report,
        i.e. it can be assumed that the experiment was running smoothly:

            sub-FOK0079_task-hariri_bold_README.txt
            sub-FOK0079_task-ist_bold_README.txt
            sub-FOK0079_task-nback_bold_README.txt
            sub-FOK0079_task-rest_run-1_bold_README.txt
            sub-FOK0079_task-rest_run-2_bold_README.txt
            sub-FOK0079_task-rest_run-3_bold_README.txt
            sub-FOK0079_task-reward_bold_README.txt
            sub-FOK0079_task-tet_bold_README.txt

"dicom": For each MR dataset, ONE dicom slice (the first one in the data
            set) is stored for later reference to the dicom header, if
            necessary

            sub-FOK0079_FLAIR.dicom.1
            sub-FOK0079_inplaneT2star_run-1.dicom.1
            sub-FOK0079_inplaneT2star_run-2.dicom.1
            sub-FOK0079_run-1_dwi.dicom.1
            sub-FOK0079_run-2_dwi.dicom.1
            sub-FOK0079_T1w.dicom.1
            sub-FOK0079_task-hariri_bold.dicom.1
            sub-FOK0079_task-ist_bold.dicom.1
            sub-FOK0079_task-nback_bold.dicom.1
            sub-FOK0079_task-rest_run-1_bold.dicom.1
            sub-FOK0079_task-rest_run-2_bold.dicom.1
            sub-FOK0079_task-rest_run-3_bold.dicom.1
            sub-FOK0079_task-reward_bold.dicom.1
            sub-FOK0079_task-tet_bold.dicom.1

"physio": For a clearer arrangment, physiological data are not stored in 
            the "func" folder, but separately. These data comprise the 
            eye tracker edf data:

            sub-FOK0079_task-hariri_bold.edf
            sub-FOK0079_task-nback_bold.edf
            sub-FOK0079_task-rest_run-1_bold.edf
            sub-FOK0079_task-rest_run-2_bold.edf
            sub-FOK0079_task-reward_bold.edf
            sub-FOK0079_task-tet_bold.edf

        along with the edf to ascii converted file, performed using the
        EyeLink software.

        ... and the ANALYZER files:

            sub-FOK0079_task-hariri_eeg.eeg
            sub-FOK0079_task-hariri_eeg.vhdr
            sub-FOK0079_task-hariri_eeg.vmrk
            sub-FOK0079_task-IST_eeg.eeg
            sub-FOK0079_task-IST_eeg.vhdr
            sub-FOK0079_task-IST_eeg.vmrk

	... and the PPG and RESP files from GE:

	    sub-FOK0079_task-rest_run-1_ppg.txt
	    sub-FOK0079_task-rest_run-1_resp.txt
	    sub-FOK0079_task-tet_ppg.txt
	    sub-FOK0079_task-tet_resp.txt
	    sub-FOK0079_task-reward_ppg.txt
	    sub-FOK0079_task-reward_resp.txt
	    sub-FOK0079_task-nback_ppg.txt
	    sub-FOK0079_task-nback_resp.txt

- a number of logfiles in the subdirectories describing the conversion 
steps and having a time stamp of the conversion date

"anat": e.g.    logfile_FOK0079_anat_dcm2nii.txt

"dwi": e.g.     logfile_FOK0079_dwi_dcm2nii.txt

"func": e.g.    logfile_FOK0079_func_dcm2nii.txt
                logfile_FOK0079_log_conversion.txt

"physio": e.g.  logfile_FOK0079_ppg_resp_conversion.txt

*******************
*  further steps  *
*******************

After BIDS conversion, data should be transfered to slurmgate, in the 
directory /mr/BECOME/BIDS. No subdirectory structure on slurmgate. Use the
following command:

e.g.    rsync -av FOK0079_BIDS mczisch@slurmgate:/mr/BECOME/BIDS

Finally, the BIDS data should be send to the archive in Garching:

e.g.

        tar fc FOK0079_BIDS.tar FOK0079_BIDS
        bzip2 FOK0079_BIDS.tar
        rsync -a --progress FOK0079_BIDS.tar.bz2 micz@archive.rzg.mpg.de:/ghi/r/m/micz/BECOME_BIDS