Skip to content

QC of unprocessed data

Executing MRIQC

  • Create a dataset to host the MRIQC derivatives. Remember to set the correct version of the container (in our case 23.1.0).
    mkdir -p /data/datasets/hcph-derivatives
    cd /data/datasets/hcph-derivatives
    datalad create -c bids mriqc_23.1.0
Note that MRIQC derivatives will be handled as a standalone dataset (hence, the -d flag is omitted above).

We will consider MRIQC's derivatives as an standalone dataset (as opposed to sub-datasets) to permit a more flexible management with DataLad. Before data release, the MRIQC-Derivatives dataset will be added as a sub-dataset to the unprocessed dataset.

  • Run MRIQC.

    #Assign the variable to the last session ID
    datalad containers-run \
        --container-name mriqc \
        --input sourcedata \
        --output ./derivatives/mriqc-23.1.0 \
        "{inputs} {outputs} participant --session-id ${lastsession} -w ${HOME}/tmp/hcph-derivatives/mriqc-23.1.0 --mem 40G --bids-database-dir /data/datasets/hcph-dataset/.bids-index --dsname hcph"

  • Check that MRIQC generated all expected individual reports. For each session, the following files must be generated:

        ├── mriqc_23.2.0
        │   ├── dataset_description.json
        │   ├── logs
        │   ├── sub-001
        │   ├── sub-001_ses-001_acq-highres_dir-AP_dwi.html
        │   ├── sub-001_ses-001_acq-original_T2w.html
        │   ├── sub-001_ses-001_acq-undistorted_T1w.html
        │   ├── sub-001_ses-001_acq-undistorted_T2w.html
        │   ├── sub-001_ses-001_task-bht_dir-AP_bold.html
        │   ├── sub-001_ses-001_task-qct_dir-AP_bold.html
        │   ├── sub-001_ses-001_task-rest_dir-AP_bold.html

    • Adapt the following code to your setup to check this automatically. Adapt it to your setup.
      # emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
      # vi: set ft=python sts=4 ts=4 sw=4 et:
      # Copyright 2023 The Axon Lab <>
      # Licensed under the Apache License, Version 2.0 (the "License");
      # you may not use this file except in compliance with the License.
      # You may obtain a copy of the License at
      # Unless required by applicable law or agreed to in writing, software
      # distributed under the License is distributed on an "AS IS" BASIS,
      # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      # See the License for the specific language governing permissions and
      # limitations under the License.
      # We support and encourage derived works from this project, please read
      # about our expectations at
      import glob
      import os
      # Set the paths
      cprovins = "/home/data"
      data_dir = os.path.join(cprovins, "hcph")
      derivatives_dir = os.path.join(cprovins, "hcph-derivatives", "mriqc-24.0.0/")
      # Use glob to find all folders matching the pattern ses-*
      session_folders = glob.glob(os.path.join(data_dir, "sub-001", "ses-[0-9]*"))
      # Extract session numbers from folder names
      sessions = [folder.split("-")[-1] for folder in session_folders]
      # Define the patterns you want to filter in filenames
      patterns = [
      # Iterate over each session
      missing_reports = {}
      for session in sessions:
          # Initialize a list to store missing reports for this session
          missing_reports[session] = []
          # Iterate over each pattern
          for pattern in patterns:
              # Construct the regex pattern
              glob_pattern = f"sub-001_ses-{session}_{pattern}.html"
              # Use glob to check if any report files matching the pattern exist
              report_files = glob.glob(os.path.join(derivatives_dir, glob_pattern))
              if not report_files:
      # Print sessions with missing reports
      for session_name, missing_patterns in missing_reports.items():
          if missing_patterns:
              print(f"Session {session_name} is missing reports for the following patterns:")
              for pattern in missing_patterns:
                  print(f" - {pattern}")
              print(f"All reports found for session {session_name}.")

    MRIQC failed to produce all the expected visual reports

    Depending on the specific error condition hit by MRIQC, some visual reports may not be generated at all.

    • Check for corresponding crash files under the logs/ directory under the output folder.
    • Address the issue (e.g., insufficient disk space) and re-run MRIQC. If the issue is unclear, search for similar problems reported previously in the issues of the MRIQC GitHub repository. The solution could be documented in some existing issue opened by a user who experienced the same problem before you and reported it. Don't forget to check closed issues! If that did not help, you might find help on NeuroStars.
    • Open a new issue in the MRIQC GitHub repository if all the above fails.
  • Check that the group_{T1w,T2w,bold,dwi}.tsv file contains the image quality metrics (IQMs) for all the expected inputs (one row per individual run at the input).

  • Push the new derivatives to the remote storage.
    datalad push --to ria-storage
    datalad push --to origin

Visualizing MRIQC's individual reports

Following our protocols1, the quality of unprocessed images MUST be assessed before executing any processing (e.g., fMRIPrep or dMRIPrep for preprocessing). In addition, MRIQC is executed prior any further processing step considering our preliminary findings regarding defacing2.

Assessing anatomical images (T1-weighted and T2-weighted)

  • Open each MRIQC report on a Web Browser.
  • Check that the visual report is complete when you open it.

    A visual report is incomplete
    • Identify what failed in the subsection "Errors" of section "About" of the visual report.
    • Address the issue (e.g., out-of-memory when running a container) and re-run MRIQC. Proceed as earlier by finding documentation on the MRIQC repository or NeuroStars.
  • Visualize the first mosaic (background mosaic) and apply the exclusion criteria.

    Do not hesitate to jump back and forth through sections while screening the visual report.

  • Scroll down to the zoomed-in brain mosaic and apply the exclusion criteria.

  • Verify that no errors are reported in the subsection "Errors" of section "About". If there are, follow the procedure described in "MRIQC failed to produce all the expected visual reports".
  • Assign a quality rating and indicate artifacts with the Rating widget. To assign a quality rating:
    • Open the Rating widget by clicking on the slider next to it in the upper right corner of the MRIQC visual report.
    • Open up the "Record specific artifacts" menu and select the artifacts that you spotted according to the QA/QC criteria.
    • Assign a quality grade that reflects the number of artifacts you spotted and their severity, using the slider.
    • Optionally, you can write down any extra comment you might have about the data and indicate your level of confidence regarding your ratings in the "Extra details" menu.
  • Download the rating file as a JSON and add it to the derivatives dataset.

Immediately report images deemed exclude, as an issue in the dataset's repository

Assessing functional images

Insufficient quality of an RSfMRI run requires recalling the session

  • Open each MRIQC report on a Web Browser in the following order:

    1. QCT,
    2. BHT, and
    3. RSfMRI.
    IMPORTANT — QCT and BHT are assessed first as proxies for the RSfMRI run's quality.

    We employ the QCT (mainly) and the BHT as proxies for the quality of the RSfMRI run. Screening the reports in the prescribed order (QCTBHTRSfMRI) helps identify issues in the QCT and BHT that may anticipate problems in the RSfMRI.

  • Screen all echo-wise visualizations of the base report following these four steps:

    • Visualize the first mosaic (standard-deviation) and apply the corresponding exclusion criteria
    • Proceed to the background view and search for artifacts.
    • Inspect the zoomed-in view of the average BOLD mosaic and apply the same exclusion criteria.
    • Scroll down to the carpet plot and apply the corresponding exclusion criteria.
  • Inspect the average BOLD mosaic for each echo in the "Extended echo-wise reports" section and apply the corresponding exclusion criteria.

  • Proceed as earlier if errors are reported within the "Errors" section.

Visualizing MRIQC's group reports

Visualize the group report for each modality in the following order: anatomical, functional and diffusion. - [ ] Open the MRIQC group report on a Web Browser. - [ ] Visualize the IQM distributions and apply the exclusion criteria corresponding to the modality.