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
lastsession=01
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:

derivatives
    ├── 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 <theaxonlab@gmail.com>
#
# 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
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# 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
#
#     https://www.nipreps.org/community/licensing/

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 = [
    "acq-undistorted_T1w",
    "acq-undistorted_T2w",
    "acq-original_T2w",
    "task-qct_*_bold",
    "task-bht_*_bold",
    "task-rest_*_bold",
    "acq-highres_dir-*_dwi",
]

# 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:
            missing_reports[session].append(pattern)

# 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}")
    else:
        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 protocols¹, 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 defacing².

Assessing anatomical images (T₁-weighted and T₂-weighted)¶

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

Immediately report RSfMRI images deemed exclude as an issue in the dataset's repository.
Proceed to scheduling an extra session after the initially-planned scanning period.

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 (QCT — BHT — RSfMRI) 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.