Skip to content

Commit

Permalink
Merge pull request #331 from CoBrALab/documentation
Browse files Browse the repository at this point in the history 
Documentation
  • Loading branch information
@Gab-D-G
Gab-D-G authored Oct 11, 2023
2 parents 1e0c77c + e31fa06 commit ed641eb
Show file tree
Hide file tree
Showing 21 changed files with 1,999 additions and 99 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,4 +64,4 @@ If you need support in using the software or experience issues that are not docu

## Contributing to RABIES

RABIES is under continuous development to keep up with evolving demand and ongoing research. We welcome suggestions for improvements using the [Github issue system](https://github.com/CoBrALab/RABIES/issues). If you're interested in contributing code, you can reach out on the [Github discussion](https://github.com/CoBrALab/RABIES/discussions) and we welcome contributions as pull requests.
**Read our dedicated [documentation](https://rabies.readthedocs.io/en/latest/contributing.html)**
128 changes: 117 additions & 11 deletions docs/_static/refs.bib
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,79 @@
% Generated by Paperpile. Check out https://paperpile.com for more information.
% BibTeX export options can be customized via Settings -> BibTeX.
@UNPUBLISHED{Desrosiers-Gregoire2023-jm,
title = "Rodent Automated Bold Improvement of {EPI} Sequences ({RABIES)}:
A standardized image processing and data quality platform for
rodent {fMRI}",
author = "Desrosiers-Gregoire, Gabriel and Devenyi, Gabriel A and
Grandjean, Joanes and Mallar Chakravarty, M",
abstract = "Functional magnetic resonance imaging (fMRI) in rodents holds
great potential for advancing our understanding of brain
networks. Unlike the human fMRI community, there remains no
standardized resource in rodents for image processing, analysis
and quality control, posing significant reproducibility
limitations. Our software platform, Rodent Automated Bold
Improvement of EPI Sequences (RABIES), is a novel pipeline
designed to address these limitations for preprocessing, quality
control, and confound correction, along with best practices for
reproducibility and transparency. We demonstrate the robustness
of the preprocessing workflow by validating performance across
multiple acquisition sites and both mouse and rat data. Building
upon a thorough investigation into data quality metrics across
acquisition sites, we introduce guidelines for the quality
control of network analysis and offer recommendations for
addressing issues. Taken together, the RABIES software will allow
the emerging community to adopt reproducible practices and foster
progress in translational neuroscience. \#\#\# Competing Interest
Statement The authors have declared no competing interest.",
journal = "bioRxiv",
pages = "2022.08.20.504597",
month = sep,
year = 2023,
keywords = "RABIES documentation",
language = "en"
}

@ARTICLE{Avants2008-rx,
title = "Symmetric diffeomorphic image registration with
cross-correlation: evaluating automated labeling of elderly and
neurodegenerative brain",
author = "Avants, B B and Epstein, C L and Grossman, M and Gee, J C",
abstract = "One of the most challenging problems in modern neuroimaging is
detailed characterization of neurodegeneration. Quantifying
spatial and longitudinal atrophy patterns is an important
component of this process. These spatiotemporal signals will aid
in discriminating between related diseases, such as
frontotemporal dementia (FTD) and Alzheimer's disease (AD), which
manifest themselves in the same at-risk population. Here, we
develop a novel symmetric image normalization method (SyN) for
maximizing the cross-correlation within the space of
diffeomorphic maps and provide the Euler-Lagrange equations
necessary for this optimization. We then turn to a careful
evaluation of our method. Our evaluation uses gold standard,
human cortical segmentation to contrast SyN's performance with a
related elastic method and with the standard ITK implementation
of Thirion's Demons algorithm. The new method compares favorably
with both approaches, in particular when the distance between the
template brain and the target brain is large. We then report the
correlation of volumes gained by algorithmic cortical labelings
of FTD and control subjects with those gained by the manual
rater. This comparison shows that, of the three methods tested,
SyN's volume measurements are the most strongly correlated with
volume measurements gained by expert labeling. This study
indicates that SyN, with cross-correlation, is a reliable method
for normalizing and making anatomical measurements in volumetric
MRI of patients and at-risk elderly individuals.",
journal = "Med. Image Anal.",
volume = 12,
number = 1,
pages = "26--41",
month = feb,
year = 2008,
keywords = "RABIES documentation",
language = "en"
}

@ARTICLE{Avants2011-av,
title = "A reproducible evaluation of {ANTs} similarity metric
performance in brain image registration",
Expand Down Expand Up @@ -633,7 +706,7 @@ @ARTICLE{Power2017-wn
pages = "609--625",
month = feb,
year = 2017,
keywords = "Sources of BOLD signal;RABIES documentation",
keywords = "RABIES documentation",
language = "en"
}

Expand Down Expand Up @@ -700,6 +773,49 @@ @ARTICLE{Biswal2010-pi
language = "en"
}

@ARTICLE{Zerbi2015-nl,
title = "Mapping the mouse brain with {rs-fMRI}: An optimized pipeline
for functional network identification",
author = "Zerbi, Valerio and Grandjean, Joanes and Rudin, Markus and
Wenderoth, Nicole",
abstract = "The use of resting state fMRI (rs-fMRI) in translational
research is a powerful tool to assess brain connectivity and
investigate neuropathology in mouse models. However, despite
encouraging initial results, the characterization of consistent
and robust resting state networks in mice remains a
methodological challenge. One key reason is that the quality of
the measured MR signal is degraded by the presence of structural
noise from non-neural sources. Notably, in the current pipeline
of the Human Connectome Project, a novel approach has been
introduced to clean rs-fMRI data, which involves automatic
artifact component classification and data cleaning (FIX). FIX
does not require any external recordings of physiology or the
segmentation of CSF and white matter. In this study, we
evaluated the performance of FIX for analyzing mouse rs-fMRI
data. Our results showed that FIX can be easily applied to mouse
datasets and detects true signals with 100\% accuracy and true
noise components with very high accuracy (>98\%), thus reducing
both within- and between-subject variability of rs-fMRI
connectivity measurements. Using this improved pre-processing
pipeline, maps of 23 resting state circuits in mice were
identified including two networks that displayed default mode
network-like topography. Hierarchical clustering grouped these
neural networks into meaningful larger functional circuits.
These mouse resting state networks, which are publicly
available, might serve as a reference for future work using
mouse models of neurological disorders.",
journal = "Neuroimage",
publisher = "Elsevier",
volume = 123,
pages = "11--21",
month = dec,
year = 2015,
keywords = "Artifact detection; Data cleaning; Hierarchical clustering;
Independent component analysis; Mouse; Resting state fMRI;Rodent
fMRI;RABIES documentation",
language = "en"
}

@ARTICLE{Power2012-ji,
title = "Spurious but systematic correlations in functional connectivity
{MRI} networks arise from subject motion",
Expand Down Expand Up @@ -747,16 +863,6 @@ @MISC{Friston1996-sa
keywords = "MRI methods/Image processing;RABIES documentation"
}

@ARTICLE{Avants2009-mn,
title = "Advanced normalization tools ({ANTS})",
author = "Avants, Brian B and Tustison, Nick and Song, Gang",
journal = "Insight J.",
volume = 2,
pages = "1--35",
year = 2009,
keywords = "MRI methods/Image processing;RABIES documentation"
}

@ARTICLE{Esteban2019-rs,
title = "{fMRIPrep}: a robust preprocessing pipeline for functional {MRI}",
author = "Esteban, Oscar and Markiewicz, Christopher J and Blair, Ross W
Expand Down
47 changes: 45 additions & 2 deletions docs/analysis_QC.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,55 @@

(analysis_QC_target)=


```{toctree}
---
maxdepth: 3
---
nested_docs/scan_diagnosis.md
nested_docs/group_stats.md
nested_docs/distribution_plot.md
nested_docs/group_stats.md
nested_docs/optim_CR.md
```

Data quality can have serious impacts on analysis outcomes, leading to false findings. Rodent imaging can suffer from spurious effects on connectivity measures if potential confounds are not well accounted for, or acquisition factors, such as anesthesia levels, can influence network activity (refs to Jo Multisite + RABIES preprint). To support interpretability, troubleshooting and reproducible research, RABIES includes a set of reports for conducting data quality assessment in individual scans and conducting quality control prior to network analysis at the group level. The reports are designed most specifically to evaluate the detectability of canonical brain networks and the impact of potential confounds (motion, physiological instabilities, and more).

This page describes how to generate the reports, our guidelines for conducting quality network of network analysis, and how to include those reports in a publication.

## Generating the reports

At the analysis stage of the pipeline, the `--data_diagnosis` option can be selected to generate the data quality reports. To generate the report, ICA components must also be provided with `--prior_maps` and a set of components corresponding to confounds must be selected using `--conf_prior_idx` (see further details below). Connectivity can be evaluated for both dual regression and seed-based connectivity:
* **For [dual regression](DR_target)**: dual regression is always conducted using the set components from `--prior_maps`, since certain features are derived from confound components defined in `--conf_prior_idx`. On the other hand, connectivity will be evaluated in the reports for each network included in `--bold_prior_idx`.
* **For [seed-based connectivity](SBC_target)**: reports will be generated for each seed provided to `--seed_list`. However, each seed needs to be supplemented with a reference network map (a 3D Nifti file for each seed, provided with `--seed_prior_list`) which should represent the expected connectivity for the canonical network corresponding to that seed.
<br>
The set of reports are generated in the `data_diagnosis_datasink/` (details [here](diagnosis_datasink_target)). The interpretation of each report is described within its dedicated documentation page, and include:

* [Spatiotemporal diagnosis](diagnosis_target): this qualitative report generated for each scan regroups a set of temporal and spatial features allowing to characterize the specific origin of data quality issues.
* [Distribution plots](dist_plot_target): quantitative report displaying the distribution of scans along measures of: specificity of network connectivity, network amplitude (for dual regression), and confound measures. Visualizing the dataset distribution can help identify outliers.
* [Group statistics](group_stats_target): for a given network, this group-level report regroups brain maps for visualizing cross-scan variability in connectivity and the group-wise correlation between connectivity and confounds.

### Classification of group ICA components

Ideally, the ICA components should be derived directly from the dataset analyzed by using [group ICA](ICA_target), although a [pre-computed set](https://zenodo.org/record/5118030/files/melodic_IC.nii.gz) is available by default. Newly-generated components must be visually inspected to identify the set of components corresponding to confound sources (which is inputted with `--conf_prior_idx`). This can be done by visualizing the group_melodic.ica/melodic_IC.nii.gz file, or using the automatically-generated FSL report in group_melodic.ica/report. Similarly, components corresponding to networks of interest can be identified and inputted with `--bold_prior_idx`.

Classifying components requires careful considerations, and we recommend a conservative inclusion (i.e. not every components need to be classified, only include components which have clear feature delineating a network or a confound). Consult {cite}`Zerbi2015-nl` or {cite}`Desrosiers-Gregoire2023-jm` for more information on classifying ICA components in rodents, or the [pre-computed set](https://zenodo.org/record/5118030/files/melodic_IC.nii.gz) can be consulted as reference (the defaults for `--bold_prior_idx` and `--conf_prior_idx` correspond to the classification of these components).

## Guidelines for analysis quality control

![](pics/QC_framework.png)

Below are our recommendations for how the set of quality reports can be used identify and control for the impact of data quality issues on downstream group analysis. Although the reports may be used for a breadth of applications, these guidelines are formulated most specifically for a standard resting-state fMRI design aiming to compare network connectivity between subjects or groups. In particular, the following guidelines aim to identify features of spurious or absent connectivity, remove scans where these features are prominent to avoid false results (e.g. connectivity difference is driven by motion), and determine whether these issues may confound group statistics.

1. Inspect the [spatiotemporal diagnosis](diagnosis_target) for each scan. Particular attention should be given to the 4 main quality markers defining [categories of scan quality](quality_marker_target), and whether features of spurious or absent connectivity are prominent.
2. If spurious or absent connectivity is prominent in a subset of scans, these scans should be detected and removed to mitigate false results. This is done by setting thresholds using `--scan_QC_thresholds` for scan-level measures of network specificity and confound correlation. These measures are documented in the [distribution plots](dist_plot_target), and the specific measures for each scan ID can be consulted in the CSV file accompanying the plot. Using this CSV file, sensible threshold values can be selected for delineating scans with spurious or absent connectivity. Additionally, for dual regression analysis, `--scan_QC_thresholds` can be used to automatically detect and remove scans which present outlier values in network amplitude, which can be an indicator of spurious connectivity {cite}`Nickerson2017-gq`. By applying `--scan_QC_thresholds`, these scans won't be included for generating the group statistical report (thus the reports must re-generated after defining `--scan_QC_thresholds`).
3. Finally, the [group statistical report](group_stats_target) can be consulted to identify the main driven of variability in connectivity across scans, and whether it relates primarily to network activity or to confounds.

If significant issues are found from this evaluation, the design of the confound correction stage may be revisited to improve quality outcomes (see [dedicated documentation](optim_CR)).

**Disclaimer**: Although these guidelines are meant to support identifying analysis pitfalls and improve research transparency, they are not meant to be prescriptive. The judgement of the experimenter is paramount in the adopting adequate practices (e.g. network detectability may not always be expected, if studying the impact of anesthesia or inspecting a visual network in blind subjects), and the conversation surrounding what should constitute proper standards for resting-state fMRI is evolving.

### Reporting in a publication

All figures from the report are generated in PNG (or SVG) format, and can be shared along a publication for data transparency. Ideally, a version of the spatiotemporal diagnosis can be shared for each scan used in deriving connectivity results, together with a group statistical report and its affiliated distribution plot for each groups/datasets if the analysis involves comparing connectivity differences across subjects and/or group.
<br>
The set of ICA components classified as networks and confounds should be reported appropriately (e.g. melodic_IC.nii.gz file can be shared with its associated component classification). If certain scan inclusion/exclusion criteria were selected based on the quality control guidelines described above, it is particularly important to describe the observations motivating these criteria and make the associated reports readily accessible for consultation (e.g. the set of spatiotemporal diagnosis files for scans displaying spurious/absent connectivity and motivated setting a particular QC threshold with `--scan_QC_thresholds`). If the design of confound correction was defined using these tools, this should also be appropriately reported.

2 changes: 1 addition & 1 deletion docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@
author = 'CoBrALab'

# The full version, including alpha/beta/rc tags
release = '0.4.6'
release = '0.5.0'


# -- General configuration ---------------------------------------------------
Expand Down
Loading

0 comments on commit ed641eb

Please sign in to comment.