MRI scan transfer - katielavigne/documentation GitHub Wiki

Table of Contents

PREAMBLE
TRANSFER SCANS
1. Log in to the CIC
2. Define subjects to transfer
3. Transfer scans
4. Check for errors
5. Check for output files
6. Backup output files
7. Update QC database

PREAMBLE

MRI scans acquired at the Douglas are put onto the Douglas Neuroinformatics Platform (DNP) and must be transferred to your lab storage space, converted from dicom to minc and/or nifti, and quality controlled.

After a scan is acquired at the DNP, it remains on the DNP server temporarily for two weeks only. This means you must transfer a scan to your group storage space less than two weeks after it was done. It is good practice to transfer the scans once a week at minimum.

In the case that a scan was not transferred in time, the scans are moved to “cold storage” and can be retrieved by contacting [email protected]. There will be a charge to retrieve each scan and it will only be available on temporary storage for 24 hours, after which it will be returned to cold storage.

ONE TIME ONLY SETUP: Copy the MRI_scan_transfer code onto the DNP and modify it for your study as described in the repository README.

TRANSFER SCANS

The following steps must be completed within two weeks of the scan acquisition date (preferably all on the same day) before a transfer is considered complete.

1. Log in to the DNP

Using a Unix terminal, log in to the DNP using your username (usually first three letters of lastname + first three letters of first name, e.g., lavkat) and password. For more information or if you need a user account, see the Douglas Neuroinformatics Platform Documentation.

For simple copy pasting of the commands in this documentation, define ${username} with your specific information:

username="lavkat"

If using a Douglas/lab computer connected to Douglas Network/IUSMD:

ssh ${username}@cicws05

If working remotely, contact [email protected]

If you receive a could not resolve hostname error, try any number up to cicws41. As of August 2021, cicws02 to cicws04 are not working, cicws05 or higher recommended.

PERMISSIONS

If multiple people will be transferring scans, all should have read and write access to the relevant directories and files. By default, write permission is only given to the owner of the files (whoever created them). To change default permissions so that the entire lab group has read/write permission, do the following each time you login:

umask u=rwx,g=rwx,o=

This will make all newly created directories/files readable and writable by your group. To modify previously created files with these permissions, use chmod 770 filename for files and chmod -R 770 dirname for directories, replacing filename and dirname with the desired absolute path.

2. Define subjects to transfer

For simple copy pasting of the commands in this documentation, define ${PIname} and ${studyname} with your specific information:

PIname="lepage"
studyname="LAM"

Once logged in, check which scans are available for transfer:

ls /home/cic/dicom/transfers

This directory contains all the MRI scans acquired at the Cerebral Imaging Centre (CIC) within the past two weeks, with directories named in the following pattern: year_mm_dd_groupID_studyID_subjectID_timepoint_timestamp. Find the scan(s) for your group/study, e.g., 2021_08_06_lepmar_LAM_1234_1_20210806_123456789. Copy the filename into a text file and add the subject ID and scan number on the same line, making a list of all the directories, subject IDs, and scan IDs you want to transfer, e.g. (replace the text in quotes with your subject information):

echo "2021_08_06_lepmar_LAM_1234_1_20210806_123456789 1234 1" > /data/${PIname}/${studyname}/IDs_to_transfer.txt

To transfer multiple subjects, simply append others to this list (replace the text in quotes with your subject information):

echo "2021_08_06_lepmar_LAM_1235_1_20210806_123456789 1235 1" >> /data/${PIname}/${studyname}/IDs_to_transfer.txt

Check that the directory, subject ID, and session ID are properly listed with cat /data/${PIname}/${studyname}/IDs_to_transfer.txt.

The next time you want to transfer scans, the first command will simply overwrite the previous file so you don't need to worry about re-transferring old scans.

RENAMING DICOMS

Issues may occur where the MRI technician or research staff provide the incorrect participant ID to be entered as the “Patient Name” when acquiring data at the scanner. Although we take as many steps as possible to ensure this doesn’t happen, in the case that it does, the DICOMS need to be modified first, and then you can proceed with converting the dicoms to mincs.

Manually create the appropriate dicom directory and then copy the contents of the CIC dicom folder (e.g., 2021_08_06_lepmar_LAM_1235_1_20210806_123456789) to that directory:

mkdir /data/${PIname}/${studyname}/dicom/1234/Scan1
cp /home/cic/dicom/transfers/2021_08_06_lepmar_LAM_1235_1_20210806_123456789/* /data/${PIname}/${studyname}/1234/Scan1/

Once copied, run the renamedicoms.sh script: ./renamedicoms.sh {directory} {correct subject ID} {correct timepoint}

./renamedicoms.sh /data/${PIname}/${studyname}/1234/Scan1 1234 1

While you wait, add a note to the LAM QC database stating the original (wrong) subject ID/timepoint and what you changed it to (if we ever have to get the scans again from CIC storage, those will not be renamed!). You can proceed as normal to convert the scans except you should use a placeholder (e.g., test) instead of the actual dicom directory when defining IDs_to_transfer.txt for that subject above.

3. Transfer scans

cd to your study directory and run the transfer script, which should already be modified for your study based on ONE TIME ONLY SETUP above:

cd /data/${PIname}/${studyname}
./transfer_scans.sh IDs_to_transfer.txt

Wait patiently for dicoms to transfer, to be converted to minc and nifti, and for links to be made. Do not close the terminal window until it has completed. Once complete, you will see 1234 1 scan transfer COMPLETE! Please check outputs.

4. Check for errors

The transfer_scans.sh script has several error checks built in and outputs logs for each step into the created logs directory. Warnings are in yellow and errors are in red. The following issues may come up during transfer, so pay attention to the terminal.

ERRORS

ERROR: module load not found. Please login to a cic workstation (e.g., ssh cicws05) and try again.

PROBLEM: You are not logged into a workstation (only relevant for remote users).

SOLUTION: ssh cicws05

ERROR with DICOM transfer: see /data/lepage/LAM/logs/1234_Scan1_dicom_transfer.log

PROBLEM: Something went wrong with rsync and conversion was skipped.

SOLUTION: cat /data/${PIname}/${studyname}/logs/1234_Scan1_dicom_transfer.log to view rsync log and diagnose (e.g., lost connection). You will need to re-run the transfer for this subject!

WARNINGS

Skipping DICOM transfer... 2021_08_06_lepmar_LAM_1234_1_20210806_123456789 not found on /home/cic/dicom/transfers

PROBLEM: The subject directory listed in IDs_to_transfer.txt is not found in the CIC DICOM directory.

SOLUTION: ls /home/cic/dicom/transfers and cat /data/${PIname}/${studyname}/IDs_to_transfer.txt and check for typos. If you simply want to reconvert your files, you can ignore this warning.

Skipping MINC/NIFTI conversion... 1234 Scan1 directory exists

PROBLEM: These two warnings indicate that this subject has already been converted (to either MINC or NIFTI depending on the warning). Conversion to either MINC or NIFTI is skipped to avoid overwriting the files.

SOLUTION: If you want to reconvert the scans, backup/rename the directory first: e.g. for MINC, mv /data/${PIname}/${studyname}/raw-minc/1234/Scan1 /data/${PIname}/${studyname}/raw-minc/1234/Scan1_bk. Once you are satisfied with the new conversion, remove the backup: e.g., rm -r /data/${PIname}/${studyname}/raw-minc/1234/Scan1_bk. For NIFTI, simply replace raw-minc with nifti in the paths.

5. Check for output files

DICOMs are converted to MINCs in the raw-minc directory and to NIFTI in the nifti directory. These contain all the scan sequences acquired by the scanner. Since we don't need all of them (e.g., localizer) and processing pipelines require certain naming conventions, links are created in the bids (for nifti) and minc-output (for minc) directories. You must check whether these links were created properly for each subject/timepoint listed in your IDs_to_transfer.txt. For the LAM/BREX studies, which have the same acquisition sequences, we would expect to find the following links (assuming subjectID=1234 and sessionID=1):

MINC-OUTPUT

  • T1-weighted/MPRAGE (/data/${PIname}/${studyname}/minc-output/t1w):
1234_1_T1.mnc
  • Quantitative T1-weighted/MP2RAGE (/data/${PIname}/${studyname}/minc-output/qt1):
1234_1_T1map.mnc
  • T2-weighted (/data/${PIname}/${studyname}/minc-output/t2w):
1234_1_T2.mnc

BIDS

All .nii.gz files will have accompanying .jsons with same filename but .json extension. Some additional files may be present, e.g., bval & bvec for dwi.

  • T1-weighted/MPRAGE (/data/${PIname}/${studyname}/bids/sub-1234/ses-1/anat):
sub-1234_ses-1_run-1_T1w.nii.gz / .json
  • Quantitative T1-weighted/MP2RAGE(/data/${PIname}/${studyname}/bids/sub-1234/ses-1/anat):
sub-1234_ses-1_run-1_T1map.nii.gz / .json
  • T2-weighted/MPRAGE (/data/${PIname}/${studyname}/bids/sub-1234/ses-1/anat):
sub-1234_ses-1_run-1_T2w.nii.gz / .json
  • Functional/fMRI (/data/${PIname}/${studyname}/bids/sub-1234/ses-1/func):
sub-1234_ses-1_run-1_bold.nii.gz / .json
  • Fieldmap/GRE (/data/${PIname}/${studyname}/bids/sub-1234/ses-1/fmap):
sub-1234_ses-1_run-1_magnitude1.nii.gz / .json
sub-1234_ses-1_run-1_magnitude2.nii.gz / .json
sub-1234_ses-1_run-1_phasediff.nii.gz / .json
  • Diffusion-weighted/DWI (/data/${PIname}/${studyname}/bids/sub-1234/ses-1/dwi):
sub-1234-ses-1_acq-b0AP_run-1_dwi.nii.gz / .json
sub-1234_ses-1_acq-b0AP_run-1_dwi.nii.gz / .json
sub-1234_ses-1_acq-b1000AP_run-1_dwi.nii.gz / .json / .bval / .bvec
sub-1234_ses-1_acq-b1000PA_run-1_dwi.nii.gz / .json / .bval / .bvec
sub-1234_ses-1_acq-b2000AP_run-1_dwi.nii.gz / .json / .bval / .bvec
sub-1234_ses-1_acq-b2000PA_run-1_dwi.nii.gz / .json / .bval / .bvec

MULTIPLE RUNS

If there are multiple runs (e.g., run-2), you need to check which is the correct one to use. This could involve checking the scan notes and visually inspecting the images to see which is better quality or less motion. For fmap, which will have two sets of files if the optional high risk scan sequence was done (LAM study only), use ls -la to see which files they are linking to and choose the acquisition numbers (e.g., 6/7) that are just before the linked resting state scan (e.g., 8). In some cases, they may not be the acquisition numbers just before but they should be very close (only a few off). Delete the files that should not be included (these are just links so you won't delete actual data):

cd /data/${PIname}/${studyname}/bids/sub-1234/ses-1/fmap
ls -la
rm /data/${PIname}/${studyname}/bids/sub-1234/ses-1/fmap/*run-2*

If you deleted run 1 you have to rename run 2 to run 1: rename 's/run-2/run-1/' *

6. Backup output files

This is an example of backing up your files to Compute Canada's Beluga server. This works if you have a standard Compute Canada account, but if you have a storage space on Niagara, that is preferred as it is where most of the processing will take place. If you don't have a Compute Canada account, you should request one here. You will need to ask your PI for their CCRI to be your sponsor.

Copy files to beluga (replace CCgroupname with Compute Canada PI username, CCusername with your Compute Canada username, and studyname with your study directory that you've already created on beluga):

CCgroupname="mlepage"
CCusername="katie"
studyname="LAM"
rsync -rvL /data/${PIname}/${studyname}/minc-output/* ${CCusername}@beluga.computecanada.ca:/project/def-${CCgroupname}/${studyname}/minc

When finished, exit (you will have to exit twice if remote working) and login to beluga replacing with your CCusername:

CCusername="katie"
ssh ${CCusername}@beluga.computecanada.ca

Give permission to your group to write/access the scans:

groupname="mlepage"
studyname="LAM"
chmod -fR 770 /project/def-${groupname}/${studyname}/minc

When complete, logout (exit).

7. Update QC database

See this QC database example and feel free to copy and modify it for your needs.

You must update all sheets of the QC database for each subject you transfer and cross-reference some sections with the paper/assessment files. Add a row for that subject/timepoint in the appropriate place in each sheet.

For the Scan Info Sheet, fill out the "Full ID", "Subject ID", "Timepoint", and "Group" columns.

For Scan Date (yyyymmdd), check the paper files and cross-reference with a scan (on the DNP, module load minc-toolkit; mincheader filename | grep study:start_date) to get the date of acquisition for that subject. You can choose any scan type unless you know they were not acquired on the same date. If there are two scan visits, put the earlier date in and make a note in the scan notes section.

For Scan Notes, copy and paste any relevant comments from the paper file.

ls /data/${PIname}/${studyname} on the DNP to check which scans were acquired and confirm this is consistent with the paper file. If they are inconsistent, you must figure out whether it is a transfer issue or a mistake on the paper file and fix it.

In the QC database, for each acquisition type, enter the selected filename for that acquisition. You can use ls -la /data/${PIname}/${studyname}/minc-output/t1w/*1234_1* to see which scans are available and copy/paste the linked file name (after the arrow) excluding the extension. For minc files, if there are two sets of numbers at the end of the filename (e.g., 1234_1_mprage_9_25.mnc), exclude the last number (25) as this is the file number and you only want to copy/paste up to the acquisition number so it is consistent between minc and nifti filetypes. You should have already dealt with multiple scans, but if you haven't, do that first. Here are the appropriate commands for each scan type (replace 1234 and 1 with your subjectID and visitID):

  • MPRAGE: ls -la /data/${PIname}/${studyname}/minc-output/t1w/*1234_1*
  • MP2RAGE: ls -la /data/${PIname}/${studyname}/minc-output/qt1/*1234_1*
  • T2w: ls -la /data/${PIname}/${studyname}/minc-output/t2w/*1234_1*
  • Resting State: ls -la /data/${PIname}/${studyname}/bids/*1234/*1/func
  • GRE Field Map: ls -la /data/${PIname}/${studyname}/bids/*1234/*1/fmap
  • DWI: ls -la /data/${PIname}/${studyname}/bids/*1234/*1/dwi

If you receive a "No such file or directory" error, the scan was either not acquired or was not linked properly. If it was acquired, ls /data/${PIname}/${studyname}/minc-output/1234/Scan1 directory to see what went wrong. If there is a scan there, but not linked, link it now:

ln -sv /data/${PIname}/${studyname}/raw-minc/1234/Scan1/1234_1_T2W_space_10.mnc /data/${PIname}/${studyname}/minc-output/t2w/1234_1_T2.mnc