MRIQC: Enhancing MRI Data Quality Assessment

MRI Quality Control (MRIQC)
PT 1: How to Run
How to run your data through the MRIQC Singularity
container on CCV and locally through Docker
Brown University Clinical
Neuroimaging Research Core
Version Date 0
5
/0
3
/202
3
What is MRIQC?
A software tool for extracting quality measures/performing quality assessments on
T1w, T2w, and functional MRI data
Fully automated pipeline assesses data quality and enables visual examination of MRI
scans
Outputs reports assessing Image Quality Metrics (IQMs) for each subject
Numerical output, can compare across subjects
Runs as a singularity (like Heudiconv) on CCV
Built on established software toolboxes (FSL, ANT’s, and AFNI)
Developed by the Poldrack Lab at Stanford University
Features of
 MRIQC
 
Containerized versions bundle software dependencies together for easy installation on
local servers and workstations
Can also be run through a free online service (OpenNeuro.org)
No-reference quality norms help quantify quality differences across study sites
Brain Imaging Data Structure (BIDS) compatible
Easy integration with popular pipelines (fMRIPrep; NiPy)
Automatically generates 
anonymized
 HTML reports
Can easily share the summarized QA data between group members and
collaborators over email or other low-security apps
How does 
MRIQC 
improve QA
?
Problems with visual QA
Subjective
Impractical for large data sets
Time consuming
Prone to variability (inter-rater differences)
Some artifacts evade human detection
 
Help with large scale imaging efforts
Less subject to site or population-specific biases
Standardize procedures between sites
MRIQC Mechanisms
Image Quality Metrics (IQM)
No-reference metric of data quality
Structural IQM Categories
Signal and noise comparisons
Information theory measures
Mechanical artifacts
Functional IQM Categories
Spatial artifact detection
Temporal stability
For more information on IQM’s please see the
the tutorial 
MRIQC PT2: IQMS
Other relevant info: What are Artifacts?
A feature appearing in an image that is not in the original object
May cause unwanted distortions in brain images
Do not always affect image quality but can affect diagnostic quality
i.e. an artifact may be confused with pathology
Some artifacts cannot be detected by the human eye - programs like MRIQC help to
detect these
Two main overarching categories:
Machine specific artifacts
Patient related artifacts
See the tutorial titled 
MRIQC PT3: Artifacts
 for more information
How to Run MRIQC
Singularity container on CCV
Skills and access you need to run MRIQC
A CCV account
See 
Setting Up an Oscar Lab Account and Signing in
 
f
or instructions
Access to a BIDS formatted dataset on Brown’s OSCAR server.
Know what a bash shell is and be able to use a few simple commands with
the help of a cheat sheet
See 
Shell Basics
 for an introduction to shell
Running MRIQC
Data needs to put into BIDS format to run it
Can run MRIQC at the 
participant
 level and 
group 
level
Running MRIQC at the participant level generates:
A summary .json file for each subject in the bids-root folder
Individual reports with mosaic views of a number of cutting planes and supporting
information
Summary section, visual reports, and metadata for T1w & T2w images and BOLD
images
Running MRIQC at the group level generates:
Scatter plots
 for each of the 
IQMs 
so that 
outliers
 are easily identified
One set for structural IQMs and another for functional
All the following 
Running MRIQC
 slides will detail how to run MRIQC using a 
SLURM
Array Job
What is an array job?
Runs the same job on a list of subjects
i.e. we want to run MRIQC on every subject in the study
Completes the same program/job for every subject
specified
You DO NOT need to re-enter the code for each
individual subject
The code on the right requests the resources you
need to run one job
These resources are then repeated, entirely separately
for each subject
Using the code on the right EVERY subject will get their
own 2 cores, 4 hours, and 30g of memory to run that job
array= specifies how many subjects you will be
running the job on
#!/bin/bash
#SBATCH -N 1
#SBATCH -c 2
#SBATCH --mem-per-cpu=30G
#SBATCH --time 04:00:00
#SBATCH -J mriqc
#SBATCH --output
/gpfs/scratch/%u/mriqc-log%A_%a.out
#SBATCH --array=1-3
#!/bin/bash
#SBATCH -N 1
#SBATCH -c 2
#SBATCH --mem-per-cpu=30G
#SBATCH --time 04:00:00
#SBATCH -J mriqc
#SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out
#SBATCH --array=1
 
#---------CONFIGURE THESE VARIABLES--------------------
mkdir -p /tmp/$SLURM_JOB_ID
bids_root=/gpfs/data/<pathtostudyfolder>   #the study folder
nthreads=2
mem=24 #gb
 
#---------END OF VARIABLES-----------------------------
#-----DICTIONARIES FOR SUBJECT SPECIFIC VARIABLES------
 
mriqc="`sed -n ${SLURM_ARRAY_TASK_ID}p subjects.txt`"
 
echo $mriqc
 
#--------------------RUN MRIQC-------------------------
singularity run --cleanenv                                                \
  --bind ${bids_root}:/data
 
         \
  --bind /tmp/$SLURM_JOB_ID:/scratch                          \
  /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif                 \
  /data/rawdata                                                                 \
  /data/derivatives/mriqc
 
         \
  participant --participant_label $mriqc
 
          \
  --no-sub                                                                          \
  --n_proc $nthreads
  
                              \
  --mem_gb $mem
 
          \
  --float32
  
          \
  --ants-nthreads $nthreads                                              \
  -m T1w bold                                                                    \
  -w /scratch/$mriqc
Running MRIQC: Individual pt. 1
In your 
derivatives 
folder use the
 
mkdir 
command
to make a 
sub directory titles 
mriqc
Create an sbatch script in a text editor
 
(emacs) 
and
copy the code on the right into it
Save this in your 
code 
folder as 
mriqc_individual.sh
In the line 
mriqc=
 the symbol circled in 
pink
 
( ` )
 is
located in the top left hand corner of your keyboard --
under the tilde 
( ~ ) 
– it is 
NOT
 a single quote mark
S
ections that need to be changed for your
individual study are circled and numbered
1
:
 
t
h
e
 
n
u
m
b
e
r
 
c
h
a
n
g
e
s
 
b
a
s
e
d
 
o
n
 
h
o
w
 
m
a
n
y
s
u
b
j
e
c
t
s
 
y
o
u
 
a
r
e
 
r
u
n
n
i
n
g
 
t
h
e
 
j
o
b
 
o
n
e.g.
16 subjects 
would look like
: 
array=1-16
#!/bin/bash
#SBATCH -N 1
#SBATCH -c 2
#SBATCH --mem-per-cpu=30G
#SBATCH --time 04:00:00
#SBATCH -J mriqc
#SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out
#SBATCH --array=1
 
#---------CONFIGURE THESE VARIABLES--------------------
mkdir -p /tmp/$SLURM_JOB_ID
bids_root=/gpfs/data/<pathtostudyfolder>   #the study folder
nthreads=2
mem=24 #gb
 
#---------END OF VARIABLES-----------------------------
#-----DICTIONARIES FOR SUBJECT SPECIFIC VARIABLES------
 
mriqc="`sed -n ${SLURM_ARRAY_TASK_ID}p subjects.txt`"
 
echo $mriqc
 
#--------------------RUN MRIQC-------------------------
singularity run --cleanenv                                                \
  --bind ${bids_root}:/data
 
         \
  --bind /tmp/$SLURM_JOB_ID:/scratch                          \
  /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif                 \
  /data/rawdata                                                                 \
  /data/derivatives/mriqc
 
         \
  participant --participant_label $mriqc
 
          \
  --no-sub                                                                          \
  --n_proc $nthreads
  
                              \
  --mem_gb $mem
 
          \
  --float32
  
          \
  --ants-nthreads $nthreads                                              \
  -m T1w bold                                                                    \
  -w /scratch/$mriqc
Running MRIQC: Individual pt. 2
2
:
 
E
n
t
e
r
 
t
h
e
 
p
a
t
h
 
t
o
 
t
h
e
 
s
t
u
d
y
 
f
o
l
d
e
r
 
t
h
e
 
i
m
a
g
e
 
d
a
t
a
 
i
s
 
i
n
E.g. /jbarredo/studyname
3
:
 
C
r
e
a
t
e
 
a
 
.
t
x
t
 
f
i
l
e
 
c
o
n
t
a
i
n
i
n
g
 
t
h
e
 
n
a
m
e
s
 
o
f
 
a
l
l
 
t
h
e
s
u
b
j
e
c
t
s
 
y
o
u
 
w
i
s
h
 
t
o
 
r
u
n
 
M
R
I
Q
C
 
o
n
Save this in your 
code
 folder
See example txt file on next slide
This script runs MRIQC on all of the 
T1w and BOLD
Images
 in the BIDS compliant folder
If you want to run just T1 or just BOLD erase the one you
don't want to run from the line circled in 
pink
To run navigate to your 
code
 folder through your
terminal and then enter the following command:
sbatch <scriptname>.sh
MRIQC takes around 20-30 min to run for every scan
Example Subjects Text File
Make your text file using the Kwrite
application
Subjects should be listed as they
appear in the rawdata folder
i.e. sub-01
Subjects should be on separate lines
Do not list all the subjects on one
line as sub-01, sub-02, sub-03 etc
The number of lines in your subject
list is the amount of array jobs you
will be running
This should match the number in
array=
#!/bin/bash
#SBATCH -N 1
#SBATCH -c 2
#SBATCH --mem-per-cpu=24G
#SBATCH --time 00:30:00
#SBATCH -J mriqc
#SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out
 
#---------CONFIGURE THESE VARIABLES--------------------
mkdir -p /tmp/$SLURM_JOB_ID
bids_root=/gpfs/data/<pathtostudyfolder>   #the study folder
nthreads=2
mem=24 #gb
 
#---------END OF VARIABLES----------------------------
#--------------------RUN MRIQC-------------------------
singularity run --cleanenv                                                 \
  --bind ${bids_root}:/data
 
                    \
  --bind /tmp/$SLURM_JOB_ID:/scratch                          \
  /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif                 \
  /data/rawdata                                                                 \
  /data/derivatives/mriqc
  
   \
  group
\
  --no-sub                                                                          \
  --n_proc $nthreads
\
  --mem_gb $mem
 
                    \
  --float32
  
                    \
  --ants-nthreads $nthreads                                              \
  -m T1w bold                                                                    \
  -w /scratch/mriqc
Running MRIQC: Group
After running MRIQC at the individual level you
can now run it at the Group level
 
The changes to the script are
Remove “SBATCH array=1-4”
Remove the “Dictionaries for subject specific
variables” section of the script
R
e
m
o
v
e
 
t
h
e
 
P
a
r
t
i
c
i
p
a
n
t
 
l
a
b
e
l
 
a
n
d
 
r
e
p
l
a
c
e
 
i
t
 
w
i
t
h
g
r
o
u
p
 
Enter the following into your command line:
sbatch <scriptname>.sh
 
Group MRIQC takes around 1-5 minutes to run
Recommendations & Other Flags
You can run mriqc and specify just one task
i.e. run on just rest or ssrt tasks
Add the flag
--task-id <taskname>
Recommend running mriqc separately for each and having
the output go into a separate task-specific folder
i.e. 
mriqc_rest
When the group report is run it bunches all the bold scans
together in the output box plots
Running mriqc separately for each task allows you to look
at the IQMs for each task individually
Check to make sure you are running the latest version of
mriqc
/gpfs/data/bnc/simgs/nipreps/
mriqc-
latest.sif
#!/bin/bash
#SBATCH -N 1
#SBATCH -c 2
#SBATCH --mem-per-cpu=30G
#SBATCH --time 04:00:00
#SBATCH -J mriqc
#SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out
#SBATCH --array=1
 
#---------CONFIGURE THESE VARIABLES--------------------
mkdir -p /tmp/$SLURM_JOB_ID
bids_root=/gpfs/data/<pathtostudyfolder>   #the study folder
nthreads=2
mem=24 #gb
 
#---------END OF VARIABLES-----------------------------
#-----DICTIONARIES FOR SUBJECT SPECIFIC VARIABLES------
 
mriqc="`sed -n ${SLURM_ARRAY_TASK_ID}p subjects.txt`"
 
echo $mriqc
 
#--------------------RUN MRIQC-------------------------
singularity run --cleanenv                                                \
  --bind ${bids_root}:/data
 
         \
  --bind /tmp/$SLURM_JOB_ID:/scratch                          \
  /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif                 \
  /data/rawdata                                                                 \
  /data/derivatives/mriqc_rest                                           \
  participant --participant_label $mriqc
 
          \
  --no-sub                                                                          \
  --n_proc $nthreads
  
                              \
  --mem_gb $mem
 
          \
  --float32
  
          \
  --ants-nthreads $nthreads                                              \
  --task-id rest                                                                    \
  -m T1w bold                                                                    \
  -w /scratch/$mriqc
How To Check The Status of Your Job pt. 1
E
n
t
e
r
 
m
y
q
 
i
n
t
o
 
t
h
e
 
c
o
m
m
a
n
d
 
l
i
n
e
 
-
-
 
W
i
l
l
 
s
h
o
w
 
y
o
u
 
y
o
u
r
 
j
o
b
 
I
D
 
a
n
d
 
i
f
 
y
o
u
r
 
j
o
b
 
i
s
 
p
e
n
d
i
n
g
 
o
r
r
u
n
n
i
n
g
 
 
In the above example (circled in green) the JobID is 2034569_1 -- the 1 denoting what
number array it is -- and the job is running normally
How To Check The Status of Your Job pt. 2
Once running, enter the below commands to follow along with the progress or the second to
check for errors/job failure
t
a
i
l
 
-
f
 
~
/
s
c
r
a
t
c
h
/
m
r
i
q
c
-
l
o
g
<
j
o
b
i
d
>
.
o
u
t
 
 
s
h
o
w
s
 
t
h
e
 
l
a
s
t
 
l
i
n
e
s
 
o
f
 
t
h
e
 
l
o
g
 
o
u
t
p
u
t
 
a
n
d
 
u
p
d
a
t
e
s
 
a
s
M
R
I
Q
C
 
c
o
n
t
i
n
u
e
s
 
t
o
 
r
u
n
 
 
y
o
u
 
w
i
l
l
 
b
e
 
a
b
l
e
 
t
o
 
s
e
e
 
i
f
 
a
n
 
e
r
r
o
r
 
o
c
c
u
r
s
 
a
s
 
i
t
 
h
a
p
p
e
n
s
O
R
c
a
t
 
~
/
s
c
r
a
t
c
h
/
m
r
i
q
c
-
l
o
g
<
j
o
b
i
d
>
.
o
u
t
 
 
s
h
o
w
s
 
t
h
e
 
e
n
t
i
r
e
t
y
 
o
f
 
t
h
e
 
l
o
g
 
o
u
t
p
u
t
 
a
n
d
 
d
o
e
s
 
n
o
t
 
c
o
n
t
i
n
u
e
t
o
 
u
p
d
a
t
e
,
 
a
l
l
o
w
s
 
y
o
u
 
t
o
 
s
c
a
n
 
e
n
t
i
r
e
 
l
o
g
 
f
o
r
 
w
a
r
n
i
n
g
s
/
e
r
r
o
r
s
How to tell if MRIQC ran successfully
The following output indicates that MRIQC is done running
 
There may be lag time between the participant finishing and its files being shown in the
output folder → If it seems to be taking a while exit out of and restart your CCV session
The outputs “The use of ‘
‘template_resolution’ ‘ is
deprecated” and “Building bold
report: no exclude index was
found” indicate that MRIQC is
running as it should. The amount
of them that show up depends on
the number of images you are
using
 
Entering “
control c
” into your
terminal returns your command
line to normal but does not kill any
jobs that are running
Where to find MRIQC Output Files
After running the Individual Level
MRIQC will output:
Subject folders containing .json files
.html files for each type of scan run
(T1w, T2w, Bold) for each subject --
located outside of the subject folders
After running the Group Level MRIQC
will output
.html and .tsv files for each type of scan
See the tutorial
 MRIQC PT4:
Interpreting Results 
for more info
These will be located in:
/gpfs/data/<studydir>/derivatives/mriqc
How to Run MRIQC
Locally with docker
Running MRIQC
Will need to put data into BIDS format to run it
See 
BIDS I & II
 powerpoints or 
here
 
for help
 
Can run MRIQC at the 
participant
 level and 
group 
level
 
Running MRIQC at the participant level generates:
A summary .json file for each subject in the bids-root folder
Individual reports with mosaic views of a number of cutting planes and supporting information
Summary section, visual reports, and metadata for T1w & T2w images and BOLD
images
 
Running MRIQC at the group level generates:
Scatter plots
 for each of the 
IQMs 
so that 
outliers
 are easily identified
One set for structural IQMs and another for functional
Running MRIQC: Individual pt. 1
Make sure docker is installed, running, and the memory is set to 16 GB
Use 
mkdir 
to make a directory titled 
derivatives 
in your data folder
Then make subfolder titled 
mriqc or qa
Open a terminal window
cd
 to your new 
mriqc / qa
 directory
Type the following command:
 
 
 
 
This will run ALL subjects for ALL sessions in your BIDS directory - at the individual
level
docker run -it --rm -v /path/to/bids/directory:/data:ro -v /path/to/qa/output:/out nipreps/mriqc:latest /data /out participant --
no-sub
Running MRIQC: Individual pt. 2
If you want to run one subject, a few subjects, or a subject(s) and a particular session,
you can do the following:
Type the following command:
 
 
 
These changes indicate that you are now running mriqc for subjects 1001, 1002, and
1003 for only session 01.
docker run -it --rm -v /path/to/bids/directory:/data:ro -v /path/to/qa/output:/out nipreps/mriqc:latest /data /out participant 
--
participant_label 1001 1002 1003 --session-id 01
 --no-sub
Running MRIQC: Group
After running MRIQC at the individual level you can now run it at the Group level
 
 
 
 
 
Group MRIQC takes around 1 minute to run
docker run -it --rm -v /path/to/bids/directory:/data:ro -v /path/to/qa/output:/out nipreps/mriqc:latest /data /out 
group
 --no-
sub
How to tell if MRIQC ran successfully
The following output indicates that MRIQC is done running
 
There may be lag time between the participant finishing and its files being shown in the
output folder
The outputs “The use of ‘
‘template_resolution’ ‘ is
deprecated” and “Building bold
report: no exclude index was
found” indicate that MRIQC is
running as it should. The amount
of them that show up depends on
the number of images you are
using
MRIQC Output Files
After running the Individual Level
MRIQC will output:
Subject folders containing .json files
.html files for each type of scan run
(T1w, T2w, Bold) for each subject --
located outside of the subject folders
 
After running the Group Level
MRIQC will output
.html and .tsv files for each type of
scan
 
These will be located in:
<studydir>/derivatives/mriqc
Helpful Links
https://mriqc.readthedocs.io/en/stable/about.html
https://rpubs.com/sarenseeley/bids-fmriprep-mriqc
References
Esteban, O., Birman, D., Schaer, M., Koyejo, O. O., Poldrack, R. A., & Gorgolewski, K. J. (2017). MRIQC: Advancing the automatic
prediction of image quality in MRI from unseen sites. 
PLOS ONE
, 
12
(9). 
https://doi.org/10.1371/journal.pone.0184661
Jarrahi, B., & Mackey, S. (2018). Characterizing the effects of MR image quality metrics on intrinsic connectivity brain networks: A
multivariate approach. 
Annual International Conference of the IEEE Engineering in Medicine and Biology Society. IEEE
Engineering in Medicine and Biology Society. Annual International Conference
, 
2018
, 1041–1045.
https://doi.org/10.1109/EMBC.2018.8512478
 
Slide Note
Embed
Share

MRIQC is a software tool for automatic quality assessment of MRI data, allowing comparisons across subjects and sites. It generates reports on Image Quality Metrics, identifying and standardizing quality procedures. Improves QA by overcoming visual assessment limitations, reducing time consumption, and increasing detection accuracy. The tool is containerized for easy installation, BIDS compatible, and facilitates data sharing. MRIQC Mechanisms include Structural and Functional Image Quality Metrics. Learn more in the provided tutorial resources.


Uploaded on Dec 23, 2023 | 1 Views


Download Presentation

Please find below an Image/Link to download the presentation.

The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author. Download presentation by click this link. If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.

E N D

Presentation Transcript


  1. MRI Quality Control (MRIQC) PT 1: How to Run How to run your data through the MRIQC Singularity container on CCV and locally through Docker Brown University Clinical Neuroimaging Research Core Version Date 05/03/2023

  2. What is MRIQC? A software tool for extracting quality measures/performing quality assessments on T1w, T2w, and functional MRI data Fully automated pipeline assesses data quality and enables visual examination of MRI scans Outputs reports assessing Image Quality Metrics (IQMs) for each subject Numerical output, can compare across subjects Runs as a singularity (like Heudiconv) on CCV Built on established software toolboxes (FSL, ANT s, and AFNI) Developed by the Poldrack Lab at Stanford University

  3. Features of MRIQC Containerized versions bundle software dependencies together for easy installation on local servers and workstations Can also be run through a free online service (OpenNeuro.org) No-reference quality norms help quantify quality differences across study sites Brain Imaging Data Structure (BIDS) compatible Easy integration with popular pipelines (fMRIPrep; NiPy) Automatically generates anonymized HTML reports Can easily share the summarized QA data between group members and collaborators over email or other low-security apps

  4. How does MRIQC improve QA? Problems with visual QA Subjective Impractical for large data sets Time consuming Prone to variability (inter-rater differences) Some artifacts evade human detection Help with large scale imaging efforts Less subject to site or population-specific biases Standardize procedures between sites

  5. MRIQC Mechanisms Image Quality Metrics (IQM) No-reference metric of data quality Structural IQM Categories Signal and noise comparisons Information theory measures Mechanical artifacts Functional IQM Categories Spatial artifact detection Temporal stability For more information on IQM s please see the the tutorial MRIQC PT2: IQMS

  6. Other relevant info: What are Artifacts? A feature appearing in an image that is not in the original object May cause unwanted distortions in brain images Do not always affect image quality but can affect diagnostic quality i.e. an artifact may be confused with pathology Some artifacts cannot be detected by the human eye - programs like MRIQC help to detect these Two main overarching categories: Machine specific artifacts Patient related artifacts See the tutorial titled MRIQC PT3: Artifacts for more information

  7. How to Run MRIQC Singularity container on CCV

  8. Skills and access you need to run MRIQC A CCV account See Setting Up an Oscar Lab Account and Signing in for instructions Access to a BIDS formatted dataset on Brown s OSCAR server. Know what a bash shell is and be able to use a few simple commands with the help of a cheat sheet See Shell Basics for an introduction to shell

  9. Running MRIQC Data needs to put into BIDS format to run it Can run MRIQC at the participant level and group level Running MRIQC at the participant level generates: A summary .json file for each subject in the bids-root folder Individual reports with mosaic views of a number of cutting planes and supporting information Summary section, visual reports, and metadata for T1w & T2w images and BOLD images Running MRIQC at the group level generates: Scatter plots for each of the IQMs so that outliers are easily identified One set for structural IQMs and another for functional All the following Running MRIQC slides will detail how to run MRIQC using a SLURM Array Job

  10. What is an array job? #!/bin/bash #SBATCH -N 1 #SBATCH -c 2 #SBATCH --mem-per-cpu=30G #SBATCH --time 04:00:00 #SBATCH -J mriqc #SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out #SBATCH --array=1-3 Runs the same job on a list of subjects i.e. we want to run MRIQC on every subject in the study Completes the same program/job for every subject specified You DO NOT need to re-enter the code for each individual subject The code on the right requests the resources you need to run one job These resources are then repeated, entirely separately for each subject Using the code on the right EVERY subject will get their own 2 cores, 4 hours, and 30g of memory to run that job array= specifies how many subjects you will be running the job on

  11. Running MRIQC: Individual pt. 1 #!/bin/bash #SBATCH -N 1 #SBATCH -c 2 #SBATCH --mem-per-cpu=30G #SBATCH --time 04:00:00 #SBATCH -J mriqc #SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out #SBATCH --array=1 1 In your derivatives folder use the mkdir command to make a sub directory titles mriqc Create an sbatch script in a text editor (emacs) and copy the code on the right into it Save this in your code folder as mriqc_individual.sh In the line mriqc= the symbol circled in pink ( ` ) is located in the top left hand corner of your keyboard -- under the tilde ( ~ ) it is NOT a single quote mark Sections that need to be changed for your individual study are circled and numbered 1: the number changes based on how many subjects you are running the job on e.g.16 subjects would look like: array=1-16 #---------CONFIGURE THESE VARIABLES-------------------- mkdir -p /tmp/$SLURM_JOB_ID bids_root=/gpfs/data/<pathtostudyfolder> #the study folder nthreads=2 mem=24 #gb 2 #---------END OF VARIABLES----------------------------- #-----DICTIONARIES FOR SUBJECT SPECIFIC VARIABLES------ mriqc="`sed -n ${SLURM_ARRAY_TASK_ID}p subjects.txt`" 3 echo $mriqc #--------------------RUN MRIQC------------------------- singularity run --cleanenv \ --bind ${bids_root}:/data \ --bind /tmp/$SLURM_JOB_ID:/scratch \ /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif \ /data/rawdata \ /data/derivatives/mriqc \ participant --participant_label $mriqc --no-sub \ --n_proc $nthreads --mem_gb $mem \ \ \ --float32 \ --ants-nthreads $nthreads \ -m T1w bold \

  12. Running MRIQC: Individual pt. 2 #!/bin/bash #SBATCH -N 1 #SBATCH -c 2 #SBATCH --mem-per-cpu=30G #SBATCH --time 04:00:00 #SBATCH -J mriqc #SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out #SBATCH --array=1 1 2: Enter the path to the study folder the image data is in E.g. /jbarredo/studyname 3: Create a .txt file containing the names of all the subjects you wish to run MRIQC on Save this in your code folder See example txt file on next slide This script runs MRIQC on all of the T1w and BOLD Images in the BIDS compliant folder If you want to run just T1 or just BOLD erase the one you don't want to run from the line circled in pink To run navigate to your code folder through your terminal and then enter the following command: sbatch <scriptname>.sh MRIQC takes around 20-30 min to run for every scan #---------CONFIGURE THESE VARIABLES-------------------- mkdir -p /tmp/$SLURM_JOB_ID bids_root=/gpfs/data/<pathtostudyfolder> #the study folder nthreads=2 mem=24 #gb 2 #---------END OF VARIABLES----------------------------- #-----DICTIONARIES FOR SUBJECT SPECIFIC VARIABLES------ mriqc="`sed -n ${SLURM_ARRAY_TASK_ID}p subjects.txt`" 3 echo $mriqc #--------------------RUN MRIQC------------------------- singularity run --cleanenv \ --bind ${bids_root}:/data \ --bind /tmp/$SLURM_JOB_ID:/scratch \ /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif \ /data/rawdata \ /data/derivatives/mriqc \ participant --participant_label $mriqc --no-sub \ --n_proc $nthreads --mem_gb $mem \ \ \ --float32 \ --ants-nthreads $nthreads \ -m T1w bold \

  13. Example Subjects Text File Make your text file using the Kwrite application Subjects should be listed as they appear in the rawdata folder i.e. sub-01 Subjects should be on separate lines Do not list all the subjects on one line as sub-01, sub-02, sub-03 etc The number of lines in your subject list is the amount of array jobs you will be running This should match the number in array=

  14. Running MRIQC: Group #!/bin/bash #SBATCH -N 1 #SBATCH -c 2 #SBATCH --mem-per-cpu=24G #SBATCH --time 00:30:00 #SBATCH -J mriqc #SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out After running MRIQC at the individual level you can now run it at the Group level #---------CONFIGURE THESE VARIABLES-------------------- mkdir -p /tmp/$SLURM_JOB_ID bids_root=/gpfs/data/<pathtostudyfolder> #the study folder nthreads=2 mem=24 #gb The changes to the script are Remove SBATCH array=1-4 Remove the Dictionaries for subject specific variables section of the script Remove the Participant label and replace it with group #---------END OF VARIABLES---------------------------- #--------------------RUN MRIQC------------------------- singularity run --cleanenv \ --bind ${bids_root}:/data \ --bind /tmp/$SLURM_JOB_ID:/scratch \ /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif \ /data/rawdata \ /data/derivatives/mriqc Enter the following into your command line: sbatch <scriptname>.sh \ group \ --no-sub \ --n_proc $nthreads Group MRIQC takes around 1-5 minutes to run \ --mem_gb $mem \ --float32 \ --ants-nthreads $nthreads \ -m T1w bold \

  15. Recommendations & Other Flags #!/bin/bash #SBATCH -N 1 #SBATCH -c 2 #SBATCH --mem-per-cpu=30G #SBATCH --time 04:00:00 #SBATCH -J mriqc #SBATCH --output /gpfs/scratch/%u/mriqc-log%A_%a.out #SBATCH --array=1 You can run mriqc and specify just one task i.e. run on just rest or ssrt tasks Add the flag --task-id <taskname> Recommend running mriqc separately for each and having the output go into a separate task-specific folder i.e. mriqc_rest When the group report is run it bunches all the bold scans together in the output box plots Running mriqc separately for each task allows you to look at the IQMs for each task individually Check to make sure you are running the latest version of mriqc /gpfs/data/bnc/simgs/nipreps/ mriqc-latest.sif #---------CONFIGURE THESE VARIABLES-------------------- mkdir -p /tmp/$SLURM_JOB_ID bids_root=/gpfs/data/<pathtostudyfolder> #the study folder nthreads=2 mem=24 #gb #---------END OF VARIABLES----------------------------- #-----DICTIONARIES FOR SUBJECT SPECIFIC VARIABLES------ mriqc="`sed -n ${SLURM_ARRAY_TASK_ID}p subjects.txt`" echo $mriqc #--------------------RUN MRIQC------------------------- singularity run --cleanenv \ --bind ${bids_root}:/data \ --bind /tmp/$SLURM_JOB_ID:/scratch \ /gpfs/data/bnc/simgs/nipreps/mriqc-latest.sif \ /data/rawdata \ /data/derivatives/mriqc_rest \ participant --participant_label $mriqc --no-sub \ --n_proc $nthreads --mem_gb $mem \ \ \ --float32 \ --ants-nthreads $nthreads \ --task-id rest \ -m T1w bold \ -w /scratch/$mriqc

  16. How To Check The Status of Your Job pt. 1 Enter myq into the command line -- Will show you your job ID and if your job is pending or running In the above example (circled in green) the JobID is 2034569_1 -- the 1 denoting what number array it is -- and the job is running normally

  17. How To Check The Status of Your Job pt. 2 Once running, enter the below commands to follow along with the progress or the second to check for errors/job failure tail -f ~/scratch/mriqc-log<jobid>.out shows the last lines of the log output and updates as MRIQC continues to run you will be able to see if an error occurs as it happens OR cat ~/scratch/mriqc-log<jobid>.out shows the entirety of the log output and does not continue to update, allows you to scan entire log for warnings/errors

  18. How to tell if MRIQC ran successfully The following output indicates that MRIQC is done running There may be lag time between the participant finishing and its files being shown in the output folder If it seems to be taking a while exit out of and restart your CCV session The outputs The use of template_resolution is deprecated and Building bold report: no exclude index was found indicate that MRIQC is running as it should. The amount of them that show up depends on the number of images you are using Entering control c into your terminal returns your command line to normal but does not kill any jobs that are running

  19. Where to find MRIQC Output Files After running the Individual Level MRIQC will output: Subject folders containing .json files .html files for each type of scan run (T1w, T2w, Bold) for each subject -- located outside of the subject folders After running the Group Level MRIQC will output .html and .tsv files for each type of scan See the tutorial MRIQC PT4: Interpreting Results for more info These will be located in: /gpfs/data/<studydir>/derivatives/mriqc

  20. How to Run MRIQC Locally with docker

  21. Running MRIQC Will need to put data into BIDS format to run it See BIDS I & II powerpoints or here for help Can run MRIQC at the participant level and group level Running MRIQC at the participant level generates: A summary .json file for each subject in the bids-root folder Individual reports with mosaic views of a number of cutting planes and supporting information Summary section, visual reports, and metadata for T1w & T2w images and BOLD images Running MRIQC at the group level generates: Scatter plots for each of the IQMs so that outliers are easily identified One set for structural IQMs and another for functional

  22. Running MRIQC: Individual pt. 1 Make sure docker is installed, running, and the memory is set to 16 GB Use mkdir to make a directory titled derivatives in your data folder Then make subfolder titled mriqc or qa Open a terminal window cd to your new mriqc / qa directory Type the following command: docker run -it --rm -v /path/to/bids/directory:/data:ro -v /path/to/qa/output:/out nipreps/mriqc:latest /data /out participant -- no-sub This will run ALL subjects for ALL sessions in your BIDS directory - at the individual level

  23. Running MRIQC: Individual pt. 2 If you want to run one subject, a few subjects, or a subject(s) and a particular session, you can do the following: Type the following command: docker run -it --rm -v /path/to/bids/directory:/data:ro -v /path/to/qa/output:/out nipreps/mriqc:latest /data /out participant -- participant_label 1001 1002 1003 --session-id 01 --no-sub These changes indicate that you are now running mriqc for subjects 1001, 1002, and 1003 for only session 01.

  24. Running MRIQC: Group After running MRIQC at the individual level you can now run it at the Group level docker run -it --rm -v /path/to/bids/directory:/data:ro -v /path/to/qa/output:/out nipreps/mriqc:latest /data /out group --no- sub Group MRIQC takes around 1 minute to run

  25. How to tell if MRIQC ran successfully The following output indicates that MRIQC is done running There may be lag time between the participant finishing and its files being shown in the output folder The outputs The use of template_resolution is deprecated and Building bold report: no exclude index was found indicate that MRIQC is running as it should. The amount of them that show up depends on the number of images you are using

  26. MRIQC Output Files After running the Individual Level MRIQC will output: Subject folders containing .json files .html files for each type of scan run (T1w, T2w, Bold) for each subject -- located outside of the subject folders After running the Group Level MRIQC will output .html and .tsv files for each type of scan These will be located in: <studydir>/derivatives/mriqc

  27. Helpful Links https://mriqc.readthedocs.io/en/stable/about.html https://rpubs.com/sarenseeley/bids-fmriprep-mriqc

  28. References Esteban, O., Birman, D., Schaer, M., Koyejo, O. O., Poldrack, R. A., & Gorgolewski, K. J. (2017). MRIQC: Advancing the automatic prediction of image quality in MRI from unseen sites. PLOS ONE, 12(9). https://doi.org/10.1371/journal.pone.0184661 Jarrahi, B., & Mackey, S. (2018). Characterizing the effects of MR image quality metrics on intrinsic connectivity brain networks: A multivariate approach. Annual International Conference of the IEEE Engineering in Medicine and Biology Society. IEEE Engineering in Medicine and Biology Society. Annual International Conference, 2018, 1041 1045. https://doi.org/10.1109/EMBC.2018.8512478

More Related Content

giItT1WQy@!-/#giItT1WQy@!-/#giItT1WQy@!-/#giItT1WQy@!-/#giItT1WQy@!-/#