From 123ecee2c6c94bd1d14fe5046fc97ea65e31c35f Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 28 Oct 2024 11:09:02 -0400 Subject: [PATCH 1/2] Work on reformatting docs. --- docs/api.rst | 13 +- docs/changes.rst | 4 +- docs/citing.rst | 7 +- docs/comparisons.md | 76 ------- docs/comparisons.rst | 211 +++++++++++++++++++ docs/contributors.rst | 24 ++- docs/help.rst | 3 +- docs/installation.rst | 17 +- docs/license.rst | 3 +- docs/preprocessing.rst | 378 ++++++++++++++++++++--------------- docs/requirements.txt | 8 - qsiprep/data/boilerplate.bib | 25 +++ 12 files changed, 486 insertions(+), 283 deletions(-) delete mode 100644 docs/comparisons.md create mode 100644 docs/comparisons.rst delete mode 100644 docs/requirements.txt diff --git a/docs/api.rst b/docs/api.rst index da7f62e6..8645888b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -17,7 +17,7 @@ Library API *********** Preprocessing Workflows ------------------------ +======================= .. toctree:: :glob: @@ -28,17 +28,8 @@ Preprocessing Workflows api/qsiprep.workflows.fieldmap -Reconstruction Workflows ------------------------- - -.. toctree:: - :glob: - - api/qsiprep.workflows.recon - - Other Utilities ---------------- +=============== .. toctree:: :glob: diff --git a/docs/changes.rst b/docs/changes.rst index ac10c4f5..86b6cd41 100644 --- a/docs/changes.rst +++ b/docs/changes.rst @@ -1,7 +1,7 @@ .. include:: links.rst ----------- +########## What's new ----------- +########## .. include:: ../CHANGES.rst diff --git a/docs/citing.rst b/docs/citing.rst index 231d16f0..316885cd 100644 --- a/docs/citing.rst +++ b/docs/citing.rst @@ -2,9 +2,10 @@ .. _citation: -=============== -Citing qsiprep -=============== +############## +Citing QSIPrep +############## + .. [Cieslak2022] Cieslak, M., Cook, P.A., He, X. et al. (2021) QSIPrep: an integrative platform for preprocessing and reconstructing diffusion MRI data. Nat Methods 18 (775–778) doi: https://doi.org/10.1038/s41592-021-01185-5 .. [Fonov2011] Fonov VS, Evans AC, Botteron K, Almli CR, McKinstry RC, Collins DL and BDCG, diff --git a/docs/comparisons.md b/docs/comparisons.md deleted file mode 100644 index 1f21d0a4..00000000 --- a/docs/comparisons.md +++ /dev/null @@ -1,76 +0,0 @@ -# Comparisons to other pipelines - -Other pipelines for preprocessing DWI data are currently being developed. Below are tables comparing -their current feature sets. These other - - * [Tractoflow](https://doi.org/10.1016/j.neuroimage.2020.116889) - * [PreQual](https://doi.org/10.1101/2020.09.14.260240) - * [MRtrix3_connectome](https://github.com/BIDS-Apps/MRtrix3_connectome) - * [dMRIPrep](https://github.com/nipreps/dmriprep) - - dMRIPrep exclusively performs preprocessing and is therefore omitted from the [reconstruction](#reconstruction) and [tractography](#tractography) sections. - -## Supported Sampling Schemes - -| | QSIPrep | Tractoflow | PreQual | MRtrix3_connectome | dMRIPrep | -| --------------------------- | :-----: | :--------: | :-----: | :----------------: | :------: | -| Single Shell | ✔ | ✔ | ✔ | ✔ | ✔ | -| Multi Shell | ✔ | ✔ | ✔ | ✔ | ✔ | -| Cartesian | ✔ | ✘ | ✘ | ✘ | ✘ | -| Random (Compressed Sensing) | ✔ | ✘ | ✘ | ✘ | ✘ | - -## Preprocessing - -| | QSIPrep | Tractoflow | PreQual | MRtrix3_connectome | dMRIPrep | -| --------------------------------------------------- | :----------------------: | :--------------------: | :---------------------: | :----------------: | :--------------: | -| BIDS App | ✔ | ✔ | ✘ | ✔ | ✔ | -| Gradient direction sanity check | Q-form matching | ✘ | `dwigradcheck` | ✘ | ✘ | -| Workflow management | NiPyPe | NextFlow | Custom | Custom | NiPyPe | -| MP-PCA denoising | ✔ | ✔ | ✔ | ✔ | ✘ | -| Patch2self denoising | ✔ | ✘ | ✘ | ✘ | ✘ | -| Gibbs unringing | `mrdegibbs` | `mrdegibbs` (disabled) | `mrdegibbs` (disabled) | `mrdegibbs` | ✘ | -| B1 bias field correction | N4 | N4 | N4 | N4 | ✘ | -| Automatic distortion group concatenation | ✔ | ✘ | ✘ | ✔ | ✘ | -| T1w brain extraction | ANTs | ANTs | ✘ | ✘ | ANTs | -| Intensity normalization | scaled by *b*=0 means | *b*=0 mean set to 1000 | ✘ | `mtnormalize` | ✘ | -| b=0 to T1w coregistration | ANTs linear registration | ANTs Non-Linear SyN | ✘ | `mrregister` | FSL BBR | -| Head Motion Correction (shelled schemes) | `eddy` | `eddy` | `eddy` | `eddy` | ✘ | -| Head Motion Correction (Cartesian / Random Schemes) | SHORELine | ✘ | ✘ | ✘ | ✘ | -| PEPOLAR EPI distortion correction | `TOPUP` | `TOPUP` | `TOPUP` | `TOPUP` | `TOPUP` | -| GRE Fieldmap EPI distortion correction | ✔ | ✘ | ✘ | ✘ | ✔ | -| Fieldmapless Distortion Correction | PE-Direction SyN | ✘ | Non-Linear registration | SyN b0-DISCO | PE-Direction SyN | -| T1w-based Normalization | ANTs (SyN) | ✘ | ✘ | ✘ | ANTs (SyN) | -| HTML Report | ✔ | ✘ | ✔ | ✘ | ✔ | -| Containerized | ✔ | ✔ | ✔ | ✔ | ✔ | - - -## Reconstruction - -| | QSIPrep | Tractoflow | PreQual | MRtrix3_connectome | -| ------------------------- | :-----: | :--------: | :-----: | :----------------: | -| MRTrix3 MSMT CSD | ✔ | ✘ | ✘ | ✔ | -| CSD | MRtrix3 | DIPY | ✘ | MRtrix3 | -| Single Shell 3-Tissue CSD | ✔ | ✘ | ✘ | ✘ | -| DTI Metrics | ✔ | ✔ | ✔ | ✔ | -| DSI Studio GQI | ✔ | ✘ | ✘ | ✘ | -| MAPMRI | ✔ | ✘ | ✘ | ✘ | -| 3dSHORE | ✔ | ✘ | ✘ | ✘ | - -## Tractography - -| | QSIPrep | Tractoflow | PreQual | MRtrix3_connectome | -| ------------------------------------- | :-----: | :--------: | :-----: | :----------------: | -| DIPY Particle Filtering | ✘ | ✔ | ✘ | ✘ | -| MRtrix3 iFOD2 | ✔ | ✘ | ✘ | ✔ | -| Anatomically constrained Tractography | ✔ | ✔ | ✘ | ✔ | -| DSI Studio QA-Enhanced Tractography | ✔ | ✘ | ✘ | ✘ | -| Across-Software tractography | ✔ | ✘ | ✘ | ✘ | -| SIFT weighting | ✔ | ✘ | ✘ | ✔ | - -## QC - -| | QSIPrep | Tractoflow | PreQual | MRtrix3_connectome | -| ----------------------------- | :---------------: | :--------: | :-----: | :----------------: | -| Automated methods boilerplate | ✔ | ✘ | ✘ | ✘ | -| HTML Preprocessing Report | [NiWorkflows-based](preprocessing.html#visual-reports) | ✘ | Custom | EddyQuad | -| HTML Reconstruction Report | NiWorkflows-based | ✘ | Custom | ✘ | \ No newline at end of file diff --git a/docs/comparisons.rst b/docs/comparisons.rst new file mode 100644 index 00000000..6c4cf920 --- /dev/null +++ b/docs/comparisons.rst @@ -0,0 +1,211 @@ +############################## +Comparisons to other pipelines +############################## + +Other pipelines for preprocessing DWI data are currently being developed. +Below are tables comparing their current feature sets. + +* `Tractoflow `_ +* `PreQual `_ +* `MRtrix3_connectome `_ +* `dMRIPrep `_ + + +************************** +Supported Sampling Schemes +************************** + +.. list-table:: + :header-rows: 1 + + * - + - QSIPrep + - Tractoflow + - PreQual + - MRtrix3_connectome + - dMRIPrep + * - Single Shell + - ✔ + - ✔ + - ✔ + - ✔ + - ✔ + * - Multi Shell + - ✔ + - ✔ + - ✔ + - ✔ + - ✔ + * - Cartesian + - ✔ + - ✘ + - ✘ + - ✘ + - ✘ + * - Random (Compressed Sensing) + - ✔ + - ✘ + - ✘ + - ✘ + - ✘ + + +************* +Preprocessing +************* + +.. list-table:: + :header-rows: 1 + + * - + - QSIPrep + - Tractoflow + - PreQual + - MRtrix3_connectome + - dMRIPrep + * - BIDS App + - ✔ + - ✔ + - ✘ + - ✔ + - ✔ + * - Gradient direction sanity check + - Q-form matching + - ✘ + - ``dwigradcheck`` + - ✘ + - ✘ + * - Workflow management + - NiPyPe + - NextFlow + - Custom + - Custom + - NiPyPe + * - MP-PCA denoising + - ✔ + - ✔ + - ✔ + - ✔ + - ✘ + * - Patch2self denoising + - ✔ + - ✘ + - ✘ + - ✘ + - ✘ + * - Gibbs unringing + - ``mrdegibbs`` + - ``mrdegibbs`` (disabled) + - ``mrdegibbs`` (disabled) + - ``mrdegibbs`` + - ✘ + * - B1 bias field correction + - N4 + - N4 + - N4 + - N4 + - ✘ + * - Automatic distortion group concatenation + - ✔ + - ✘ + - ✘ + - ✔ + - ✘ + * - T1w brain extraction + - ANTs + - ANTs + - ✘ + - ✘ + - ANTs + * - Intensity normalization + - scaled by *b*=0 means + - *b*=0 mean set to 1000 + - ✘ + - ``mtnormalize`` + - ✘ + * - b=0 to T1w coregistration + - ANTs linear registration + - ANTs Non-Linear SyN + - ✘ + - ``mrregister`` + - FSL BBR + * - Head Motion Correction (shelled schemes) + - ``eddy`` + - ``eddy`` + - ``eddy`` + - ``eddy`` + - ✘ + * - Head Motion Correction (Cartesian / Random Schemes) + - SHORELine + - ✘ + - ✘ + - ✘ + - ✘ + * - PEPOLAR EPI distortion correction + - ``TOPUP`` + - ``TOPUP`` + - ``TOPUP`` + - ``TOPUP`` + - ``TOPUP`` + * - GRE Fieldmap EPI distortion correction + - ✔ + - ✘ + - ✘ + - ✘ + - ✔ + * - Fieldmapless Distortion Correction + - PE-Direction SyN + - ✘ + - Non-Linear registration + - SyN b0-DISCO + - PE-Direction SyN + * - T1w-based Normalization + - ANTs (SyN) + - ✘ + - ✘ + - ✘ + - ANTs (SyN) + * - HTML Report + - ✔ + - ✘ + - ✔ + - ✘ + - ✔ + * - Containerized + - ✔ + - ✔ + - ✔ + - ✔ + - ✔ + + +*************** +Quality Control +*************** + +.. list-table:: + :header-rows: 1 + + * - + - QSIPrep + - Tractoflow + - PreQual + - MRtrix3_connectome + * - Automated methods boilerplate + - ✔ + - ✘ + - ✘ + - ✘ + * - HTML Preprocessing Report + - `NiWorkflows-based `_ + - ✘ + - Custom + - EddyQuad + * - HTML Reconstruction Report + - NiWorkflows-based + - ✘ + - Custom + - ✘ + +QSIPrep versus other modality preps +=================================== diff --git a/docs/contributors.rst b/docs/contributors.rst index 47f46327..70df0fb7 100644 --- a/docs/contributors.rst +++ b/docs/contributors.rst @@ -1,8 +1,8 @@ .. include:: links.rst ------------------------- -Contributing to qsiprep ------------------------- +####################### +Contributing to QSIPrep +####################### This document explains how to prepare a new development environment and update an existing environment, as necessary. @@ -14,8 +14,10 @@ By default, work should be built off of `pennbbl/qsiprep:latest installation_ guide for the basic procedure for running). +***************************** Patching working repositories -============================= +***************************** + In order to test new code without rebuilding the Docker image, it is possible to mount working repositories as source directories within the container. @@ -33,7 +35,7 @@ For example, :: pennbbl/qsiprep:latest /data /out/out participant \ -w /out/work/ -In order to work directly in the container, use ``--entrypoint=bash`` +In order to work directly in the container, use ``--entrypoint=bash`` arguments in a ``docker`` command:: $ docker run --rm -v $HOME/fullds005:/data:ro -v $HOME/dockerout:/out \ @@ -54,8 +56,10 @@ Or you can patch Singularity containers using the PYTHONPATH variable: :: /scratch/dataset /scratch/out participant -w /out/work/ +******************* Adding dependencies -=================== +******************* + New dependencies to be inserted into the Docker image will either be Python or non-Python dependencies. Python dependencies may be added in three places, depending on whether @@ -81,8 +85,11 @@ For example, installing an ``apt`` package may be done as follows: :: RUN apt-get update && \ apt-get install -y + +*********************** Rebuilding Docker image -======================= +*********************** + If it is necessary to rebuild the Docker image, a local image named ``qsiprep`` may be built from within the working qsiprep repository, located in ``~/projects/qsiprep``: :: @@ -93,8 +100,9 @@ To work in this image, replace ``pennbbl/qsiprep:latest`` with ``qsiprep`` in any of the above commands. +*********************************************** Adding new features to the citation boilerplate -=============================================== +*********************************************** The citation boilerplate is built by adding two dunder attributes of workflow objects: ``__desc__`` and ``__postdesc__``. diff --git a/docs/help.rst b/docs/help.rst index 25052ac4..02454a90 100644 --- a/docs/help.rst +++ b/docs/help.rst @@ -1,5 +1,6 @@ +############ Getting help -============ +############ If you have a problem, would like to ask a question about how to use QSIprep, or have a question about the features and behavior of QSIprep, please submit diff --git a/docs/installation.rst b/docs/installation.rst index a5843457..64c7d6d4 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -1,8 +1,8 @@ .. include:: links.rst ------------- +############ Installation ------------- +############ There are two easy ways to use qsiprep: in a `Docker Container`_, or in a `Singularity Container`_. @@ -13,10 +13,12 @@ To install:: $ pip install --user --upgrade qsiprep-container + .. _`Docker Container`: +**************** Docker Container -================ +**************** In order to run qsiprep in a Docker container, Docker must be `installed `_. @@ -63,9 +65,9 @@ See `External Dependencies`_ for more information on what is included in the Doc and how it's built. - +********************* Singularity Container -===================== +********************* The easiest way to get a Sigularity image is to run:: @@ -83,10 +85,11 @@ As with Docker, you will need to bind the Freesurfer license.txt when running Si --fs-license-file /opt/freesurfer/license.txt +********************* External Dependencies ---------------------- +********************* -qsiprep is written using Python 3.10 (or above), and is based on +QSIPrep is written using Python 3.10 (or above), and is based on nipype_. The external dependencies are built in the `qsiprep_build `_ repository. There you can find the URLs used to download the dependency source code diff --git a/docs/license.rst b/docs/license.rst index dc785012..c7881782 100644 --- a/docs/license.rst +++ b/docs/license.rst @@ -1,5 +1,6 @@ +################### License information -------------------- +################### We use the 3-clause BSD license; the full license may be found in the `LICENSE `_ file diff --git a/docs/preprocessing.rst b/docs/preprocessing.rst index 222531e4..0d393cdb 100644 --- a/docs/preprocessing.rst +++ b/docs/preprocessing.rst @@ -2,11 +2,13 @@ .. _preprocessing: +############# Preprocessing -============= +############# +******************* Building a pipeline --------------------- +******************* QSIPrep builds a pipeline based on your BIDS inputs. In general the pipeline will incorporate all the data it knows how to handle (i.e. fieldmaps, dMRI and anatomical data) automatically. @@ -25,7 +27,7 @@ There may be cases where you want to change the default behavior, particularly i .. _merging: Merging multiple scans from a session -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +===================================== For q-space imaging sequences it is common to have multiple separate scans to acquire the entire sampling scheme. These scans get aligned and merged into @@ -53,10 +55,11 @@ with eddy/motion correction and will merge scans with different PE directions. If you have some scans you want to combine and others you want to preprocess separately, you can call qsiprep more than once with BIDS filters to process the different scans. + .. _bids_filters: Using BIDS filters -^^^^^^^^^^^^^^^^^^^ +================== BIDS filters allow users to filter the set of images available to QSIPrep at run time. BIDS filters should be stored in a json file and passed to QSIPrep with @@ -113,10 +116,11 @@ You can enable regular expressions for more detailed filtering, for example:: will do a case-insensitive match of "mprage" within the "t1w" query. + .. _merge_denoise: Denoising and Merging Images -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +============================ The user can decide whether to do certain preprocessing steps and, if so, whether they are performed *before* or *after* the DWI series are @@ -167,11 +171,8 @@ they are concatenated. When warped groups are concatenated an additional b=0 image intensity normalization is performed. - - - Preprocessing HCP-style -^^^^^^^^^^^^^^^^^^^^^^^ +======================= QSIPrep can be configured to produce a very similar pipeline to the HCP dMRI pipelines. HCP and HCP-Lifespan scans acquire complete multi-shell sequences in opposing phase @@ -189,10 +190,11 @@ many images, you can substitute ``average`` with ``concat``. .. _outputs: -Outputs of qsiprep -------------------- +****************** +Outputs of QSIPrep +****************** -qsiprep generates three broad classes of outcomes: +QSIPrep generates three broad classes of outcomes: 1. **Visual QA (quality assessment) reports**: one :abbr:`HTML (hypertext markup language)` per subject, @@ -212,9 +214,9 @@ qsiprep generates three broad classes of outcomes: Visual Reports -^^^^^^^^^^^^^^^ +============== -qsiprep outputs summary reports, written to ``/qsiprep/sub-.html``. These reports provide a quick way to make visual inspection of the results easy. One useful graphic is the animation of the q-space sampling scheme before and after the pipeline. Here @@ -228,8 +230,8 @@ is a sampling scheme from a DSI scan: that head motion correction has not disrupted the scheme extensively. -Preprocessed data (qsiprep *derivatives*) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Preprocessed data (QSIPrep *derivatives*) +========================================= There are additional files, called "Derivatives", written to ``/qsiprep/sub-/``. @@ -252,7 +254,8 @@ can be found in the ``anat`` subfolder: - ``*T1w_space-MNI152NLin2009cAsym_target-T1w_warp.h5`` Composite (warp and affine) transform to map from MNI to T1 space - ``*T1w_target-MNI152NLin2009cAsym_warp.h5`` Composite (warp and affine) transform to transform T1w into MNI space -.. Note: +.. note:: + These are in LPS+ orientation, so are not identical to FMRIPREP's anatomical outputs Derivatives related to diffusion images are in the ``dwi`` subfolder. @@ -279,7 +282,7 @@ Volumetric output spaces include ``T1w`` (default) and ``MNI152NLin2009cAsym``. .. _dwi_confounds: Confounds -^^^^^^^^^^^^ +========= See implementation on :func:`~qsiprep.workflows.dwi.confounds.init_dwi_confs_wf`. @@ -312,7 +315,7 @@ working on specific gradient strengths or directions. .. _qc_data: Quality Control data -^^^^^^^^^^^^^^^^^^^^^ +==================== A single-line csv file (``desc-ImageQC_dwi.csv``) is created for each output image. This file is particularly useful for comparing the relative quality @@ -329,11 +332,12 @@ Finally, the difference in spatial overlap between the anatomical mask and the anatomical brain mask and the DWI brain mask is calculated using the Dice distance in ``t1_dice_distance`` and ``mni_dice_distance``. + Confounds and "carpet"-plot on the visual reports -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +================================================= fMRI has been using a "carpet" visualization of the -:abbr:`BOLD (blood-oxygen level-dependent)` time-series (see [Power2016]_), +:abbr:`BOLD (blood-oxygen level-dependent)` time-series (see :footcite:t:`power2017simple`), but this type of plot does not make sense for DWI data. Instead, we plot the cross-correlation value between each raw slice and the HMC model signal resampled into that slice. @@ -357,17 +361,19 @@ Examples of these plots follow: For eddy slices with more outliers appear more yellow, while fewer outliers is more blue. + .. _workflow_details: +****************************** Preprocessing pipeline details ------------------------------- +****************************** ``qsiprep`` adapts its pipeline depending on what data and metadata are available and are used as the input. Processing the *Subject Anatomical Reference* T1w or T2w images -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +=============================================================== :func:`qsiprep.workflows.anatomical.init_anat_preproc_wf` @@ -376,21 +382,24 @@ Processing the *Subject Anatomical Reference* T1w or T2w images :simple_form: yes from qsiprep.workflows.anatomical import init_anat_preproc_wf - wf = init_anat_preproc_wf(omp_nthreads=1, - reportlets_dir='.', - output_dir='.', - dwi_only=False, - infant_mode=False, - template='MNI152NLin2009cAsym', - output_spaces=['T1w'], - output_resolution=1.25, - skull_strip_template='OASIS', - force_spatial_normalization=True, - freesurfer=True, - longitudinal=False, - debug=False, - hires=True, - num_t1w=1) + + wf = init_anat_preproc_wf( + omp_nthreads=1, + reportlets_dir='.', + output_dir='.', + dwi_only=False, + infant_mode=False, + template='MNI152NLin2009cAsym', + output_spaces=['T1w'], + output_resolution=1.25, + skull_strip_template='OASIS', + force_spatial_normalization=True, + freesurfer=True, + longitudinal=False, + debug=False, + hires=True, + num_t1w=1, + ) As of version 0.18 QSIPrep has been changed to be very flexible with anatomical processing workflows. Versions prior to 0.18 were focused on the T1w images and @@ -460,7 +469,7 @@ Processing the *Anatomical Reference* images .. _t1preproc_steps: Handling Lesions and abnormalities -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------- When processing images from patients with focal brain lesions (e.g. stroke, tumor resection), it is possible to provide a lesion mask to be used during spatial @@ -481,7 +490,7 @@ to be run through ``qsiprep``. Longitudinal T1w processing -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------- In the case of multiple T1w images (across sessions and/or within a session), T1w images are merged into a single template image using FreeSurfer's @@ -504,17 +513,18 @@ flag, which forces the estimation of an unbiased template. Processing Infant Data -^^^^^^^^^^^^^^^^^^^^^^ +======================= When processing infant DWI data, users may add ``--infant`` to their QSIPrep call. This will swap the default MNI152NLin2009cAsym template with the MNI infant template. It is highly advisable to also include ``--dwi-only`` to avoid problems with T1w skull-stripping. + .. _dwi_overview: DWI preprocessing -^^^^^^^^^^^^^^^^^ +================= :func:`qsiprep.workflows.dwi.base.init_dwi_preproc_wf` @@ -523,48 +533,51 @@ DWI preprocessing :simple_form: yes from qsiprep.workflows.dwi.base import init_dwi_preproc_wf - wf = init_dwi_preproc_wf(dwi_only=False, - scan_groups={'dwi_series': ['fake.nii'], - 'fieldmap_info': {'suffix': None}, - 'dwi_series_pedir': 'j'}, - source_file='/data/sub-1/dwi/sub-1_dwi.nii.gz', - output_prefix='', - ignore=[], - b0_threshold=100, - motion_corr_to='iterative', - b0_to_t1w_transform='Rigid', - hmc_model='3dSHORE', - hmc_transform='Rigid', - shoreline_iters=2, - impute_slice_threshold=0, - eddy_config=None, - reportlets_dir='.', - output_spaces=['T1w'], - dwi_denoise_window=5, - denoise_method='dwidenoise', - unringing_method='mrdegibbs', - b1_biascorr_stage='final', - no_b0_harmonization=False, - denoise_before_combining=True, - template='MNI152NLin2009cAsym', - output_dir='.', - omp_nthreads=1, - fmap_bspline=False, - fmap_demean=True, - use_syn=True, - force_syn=False, - low_mem=False, - sloppy=True, - layout=None) + wf = init_dwi_preproc_wf( + dwi_only=False, + scan_groups={'dwi_series': ['fake.nii'], + 'fieldmap_info': {'suffix': None}, + 'dwi_series_pedir': 'j'}, + source_file='/data/sub-1/dwi/sub-1_dwi.nii.gz', + output_prefix='', + ignore=[], + b0_threshold=100, + motion_corr_to='iterative', + b0_to_t1w_transform='Rigid', + hmc_model='3dSHORE', + hmc_transform='Rigid', + shoreline_iters=2, + impute_slice_threshold=0, + eddy_config=None, + reportlets_dir='.', + output_spaces=['T1w'], + dwi_denoise_window=5, + denoise_method='dwidenoise', + unringing_method='mrdegibbs', + b1_biascorr_stage='final', + no_b0_harmonization=False, + denoise_before_combining=True, + template='MNI152NLin2009cAsym', + output_dir='.', + omp_nthreads=1, + fmap_bspline=False, + fmap_demean=True, + use_syn=True, + force_syn=False, + low_mem=False, + sloppy=True, + layout=None, + ) Preprocessing of :abbr:`DWI (Diffusion Weighted Image)` files is split into multiple sub-workflows described below. + .. _fsl_wf: Head-motion / Eddy Current/ Distortion correction (FSL) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------------- :func:`qsiprep.workflows.dwi.fsl.init_fsl_hmc_wf` @@ -585,8 +598,9 @@ The FSL workflow can take three different forms. 2. PEPOLAR distortion correction (using topup) 3. Fieldmap-based distortion correction + No distortion correction -++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^ If there are no fieldmap images or the user has specified ``--ignore fieldmaps``, no distortion correction will occur. In this case, only head motion correction @@ -597,20 +611,25 @@ and eddy current correction will be performed. The workflow looks like this: :simple_form: yes from qsiprep.workflows.dwi.fsl import init_fsl_hmc_wf - wf = init_fsl_hmc_wf({'dwi_series':['dwi1.nii', 'dwi2.nii'], - 'fieldmap_info': {'suffix': None}, - 'dwi_series_pedir': 'j'}, - b0_threshold=100, - impute_slice_threshold=0., - fmap_demean=False, - fmap_bspline=False, - eddy_config=None, - source_file='/path/to/dwi/sub-X_dwi.nii.gz', - omp_nthreads=1) + + wf = init_fsl_hmc_wf( + { + 'dwi_series': ['dwi1.nii', 'dwi2.nii'], + 'fieldmap_info': {'suffix': None}, + 'dwi_series_pedir': 'j', + }, + b0_threshold=100, + impute_slice_threshold=0., + fmap_demean=False, + fmap_bspline=False, + eddy_config=None, + source_file='/path/to/dwi/sub-X_dwi.nii.gz', + omp_nthreads=1, + ) PEPOLAR (TOPUP) Distortion Correction -+++++++++++++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When images with different phase encoding directions are available, either dedicated fieldmaps (in the ``fmap/`` directory) or DWI series @@ -621,23 +640,29 @@ dedicated fieldmaps (in the ``fmap/`` directory) or DWI series :simple_form: yes from qsiprep.workflows.dwi.fsl import init_fsl_hmc_wf - wf = init_fsl_hmc_wf({'dwi_series': [ - '.../opposite/sub-1/dwi/sub-1_dir-AP_dwi.nii.gz'], - 'dwi_series_pedir': 'j', - 'fieldmap_info': {'suffix': 'rpe_series', - 'rpe_series': ['.../opposite/sub-1/dwi/sub-1_dir-PA_dwi.nii.gz']}, - 'concatenated_bids_name': 'sub-1'}, - b0_threshold=100, - impute_slice_threshold=0., - fmap_demean=False, - fmap_bspline=False, - eddy_config=None, - source_file='/path/to/dwi/sub-X_dwi.nii.gz', - omp_nthreads=1) + + wf = init_fsl_hmc_wf( + { + 'dwi_series': ['.../opposite/sub-1/dwi/sub-1_dir-AP_dwi.nii.gz'], + 'dwi_series_pedir': 'j', + 'fieldmap_info': { + 'suffix': 'rpe_series', + 'rpe_series': ['.../opposite/sub-1/dwi/sub-1_dir-PA_dwi.nii.gz'], + }, + 'concatenated_bids_name': 'sub-1', + }, + b0_threshold=100, + impute_slice_threshold=0., + fmap_demean=False, + fmap_bspline=False, + eddy_config=None, + source_file='/path/to/dwi/sub-X_dwi.nii.gz', + omp_nthreads=1, + ) Fieldmap-based Distortion Correction -++++++++++++++++++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If a GRE fieldmap or SyN-based fieldmapless distortion correction are detected, these will be performed on the outputs of ``eddy``. @@ -648,25 +673,35 @@ For details see :ref:`dwi_sdc`. :simple_form: yes from qsiprep.workflows.dwi.fsl import init_fsl_hmc_wf - wf = init_fsl_hmc_wf({'dwi_series': ['.../phasediff/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz', - '.../phasediff/sub-1/dwi/sub-1_dir-AP_run-2_dwi.nii.gz'], - 'fieldmap_info': {'phasediff': '.../phasediff/sub-1/fmap/sub-1_phasediff.nii.gz', - 'magnitude1': '.../magnitude1/sub-1/fmap/sub-1_magnitude1.nii.gz', - 'suffix': 'phasediff'}, - 'dwi_series_pedir': 'j', - 'concatenated_bids_name': 'sub-1_dir-AP'}, - b0_threshold=100, - impute_slice_threshold=0., - fmap_demean=False, - fmap_bspline=False, - eddy_config=None, - source_file='/path/to/dwi/sub-X_dwi.nii.gz', - omp_nthreads=1) + + wf = init_fsl_hmc_wf( + { + 'dwi_series': [ + '.../phasediff/sub-1/dwi/sub-1_dir-AP_run-1_dwi.nii.gz', + '.../phasediff/sub-1/dwi/sub-1_dir-AP_run-2_dwi.nii.gz', + ], + 'fieldmap_info': { + 'phasediff': '.../phasediff/sub-1/fmap/sub-1_phasediff.nii.gz', + 'magnitude1': '.../magnitude1/sub-1/fmap/sub-1_magnitude1.nii.gz', + 'suffix': 'phasediff', + }, + 'dwi_series_pedir': 'j', + 'concatenated_bids_name': 'sub-1_dir-AP', + }, + b0_threshold=100, + impute_slice_threshold=0., + fmap_demean=False, + fmap_bspline=False, + eddy_config=None, + source_file='/path/to/dwi/sub-X_dwi.nii.gz', + omp_nthreads=1, + ) + .. _configure_eddy: Configuring ``eddy`` -+++++++++++++++++++++ +^^^^^^^^^^^^^^^^^^^^ ``eddy`` has many configuration options. Instead of making these commandline options, you can specify them in a JSON file and pass that to ``qsiprep`` @@ -675,15 +710,13 @@ be viewed or downloaded `here `__ - .. _dwi_hmc: Head-motion estimation (SHORELine) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------------------------- :func:`qsiprep.workflows.dwi.hmc.init_dwi_hmc_wf` - A long-standing issue for q-space imaging techniques, particularly DSI, has been the lack of motion correction methods. DTI and multi-shell HARDI have had ``eddy_correct`` and ``eddy`` in FSL, but DSI has relied on aligning the @@ -716,36 +749,40 @@ fed to the :ref:`confounds workflow `. These are used to estimate framewise displacement. Additionally, measures of model fits are saved for each slice for display in a carpet plot-like thing. - .. workflow:: :graph2use: colored :simple_form: yes from qsiprep.workflows.dwi.hmc_sdc import init_qsiprep_hmcsdc_wf - wf = init_qsiprep_hmcsdc_wf({'dwi_series':['dwi1.nii', 'dwi2.nii'], - 'fieldmap_info': {'suffix': None}, - 'dwi_series_pedir': 'j'}, - source_file='/data/sub-1/dwi/sub-1_dwi.nii.gz', - b0_threshold=100, - hmc_transform='Affine', - hmc_model='3dSHORE', - hmc_align_to='iterative', - template='MNI152NLin2009cAsym', - shoreline_iters=1, - impute_slice_threshold=0, - omp_nthreads=1, - fmap_bspline=False, - fmap_demean=False, - use_syn=True, - force_syn=False, - name='qsiprep_hmcsdc_wf', - dwi_metadata={}) + + wf = init_qsiprep_hmcsdc_wf( + { + 'dwi_series': ['dwi1.nii', 'dwi2.nii'], + 'fieldmap_info': {'suffix': None}, + 'dwi_series_pedir': 'j', + }, + source_file='/data/sub-1/dwi/sub-1_dwi.nii.gz', + b0_threshold=100, + hmc_transform='Affine', + hmc_model='3dSHORE', + hmc_align_to='iterative', + template='MNI152NLin2009cAsym', + shoreline_iters=1, + impute_slice_threshold=0, + omp_nthreads=1, + fmap_bspline=False, + fmap_demean=False, + use_syn=True, + force_syn=False, + name='qsiprep_hmcsdc_wf', + dwi_metadata={}, + ) .. _dwi_sdc: Susceptibility correction methods -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +================================= :func:`qsiprep.workflows.fieldmap.base.init_sdc_wf` @@ -774,7 +811,7 @@ fields in the JSON sidecars in the ``fmap/`` directory. .. _best_b0: Selecting representative images for PEPOLAR -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------- ``TOPUP`` estimates EPI distortion based on the shapes of images with different phase encoding directions and total readout times (i.e. warped @@ -801,7 +838,7 @@ column in the confounds tsv file. .. _dwi_only: Using only DWI data (bypassing the T1w workflows) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------------------- It is possible to use QSIPrep to process *only* diffusion-weighted images. In the case of infant data, where robust skull-stripping methods are not @@ -817,10 +854,11 @@ In this case the ``b0_anat_coreg`` workflow instead registers the b=0 reference to an AC-PC-oriented template and the rigid components of the coregistration transform are extracted. + .. _dwi_ref: DWI reference image estimation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------ :func:`qsiprep.workflows.dwi.util.init_dwi_reference_wf` @@ -829,21 +867,24 @@ DWI reference image estimation :simple_form: yes from qsiprep.workflows.anatomical import init_dwi_reference_wf - wf = init_dwi_reference_wf(omp_nthreads=1, - gen_report=True, - source_file="sub-1_dwi.nii.gz", - register_t1=True) + + wf = init_dwi_reference_wf( + omp_nthreads=1, + gen_report=True, + source_file="sub-1_dwi.nii.gz", + register_t1=True, + ) This workflow estimates a reference image for a DWI series. This procedure is different from the DWI reference image workflow in the sense that true brain masking isn't usually done until later in the -pipeline for DWIs +pipeline for DWIs. .. _resampling: Pre-processed DWIs in a different space -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------- :func:`qsiprep.workflows.dwi.resampling.init_dwi_trans_wf` @@ -852,14 +893,17 @@ Pre-processed DWIs in a different space :simple_form: yes from qsiprep.workflows.dwi.resampling import init_dwi_trans_wf - wf = init_dwi_trans_wf(source_file='sub-1_dwi.nii.gz', - template="ACPC", - output_resolution=1.2, - use_compression=True, - to_mni=False, - write_local_bvecs=True, - mem_gb=3, - omp_nthreads=1) + + wf = init_dwi_trans_wf( + source_file='sub-1_dwi.nii.gz', + template="ACPC", + output_resolution=1.2, + use_compression=True, + to_mni=False, + write_local_bvecs=True, + mem_gb=3, + omp_nthreads=1, + ) A DWI series is resampled to an output space. The ``output_resolution`` is specified on the commandline call. All transformations, including head motion @@ -877,7 +921,7 @@ use these yet, but it's an interesting idea. .. _b0_reg: b0 to T1w registration -^^^^^^^^^^^^^^^^^^^^^^ +======================= :func:`qsiprep.workflows.dwi.registration.init_b0_to_anat_registration_wf` @@ -886,17 +930,19 @@ b0 to T1w registration :simple_form: yes from qsiprep.workflows.dwi.registration import init_b0_to_anat_registration_wf + wf = init_b0_to_anat_registration_wf( - mem_gb=3, - omp_nthreads=1, - transform_type="Rigid", - write_report=False) + mem_gb=3, + omp_nthreads=1, + transform_type="Rigid", + write_report=False, + ) This just uses `antsRegistration`. +********** +References +********** -.. topic:: References - - .. [Power2016] Power JD, A simple but useful way to assess fMRI scan qualities. - NeuroImage. 2016. doi: `10.1016/j.neuroimage.2016.08.009 `_ +.. footbibliography:: diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index b0569e70..00000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,8 +0,0 @@ -mock -numpy -sphinx-argparse==0.2.1 -CommonMark==0.7.5 -nbsphinx -pydotplus -pydot>=1.2.3 --r ../requirements.txt diff --git a/qsiprep/data/boilerplate.bib b/qsiprep/data/boilerplate.bib index 06b8062a..f3718dce 100644 --- a/qsiprep/data/boilerplate.bib +++ b/qsiprep/data/boilerplate.bib @@ -1,3 +1,16 @@ +@article{cieslak2021qsiprep, + title={QSIPrep: an integrative platform for preprocessing and reconstructing diffusion MRI data}, + author={Cieslak, Matthew and Cook, Philip A and He, Xiaosong and Yeh, Fang-Cheng and Dhollander, Thijs and Adebimpe, Azeez and Aguirre, Geoffrey K and Bassett, Danielle S and Betzel, Richard F and Bourque, Josiane and others}, + journal={Nature methods}, + volume={18}, + number={7}, + pages={775--778}, + year={2021}, + publisher={Nature Publishing Group US New York}, + url={https://doi.org/10.1038/s41592-021-01185-5}, + doi={10.1038/s41592-021-01185-5} +} + @article{fmriprep1, author = {Esteban, Oscar and Markiewicz, Christopher and Blair, Ross W and Moodie, Craig and Isik, Ayse Ilkay and Erramuzpe Aliaga, Asier and Kent, James and Goncalves, Mathias and DuPre, Elizabeth and Snyder, Madeleine and Oya, Hiroyuki and Ghosh, Satrajit and Wright, Jessey and Durnez, Joke and Poldrack, Russell and Gorgolewski, Krzysztof Jacek}, title = {fmriprep: a robust preprocessing pipeline for functional {MRI}}, @@ -615,3 +628,15 @@ @article{autotrack year={2020}, publisher={Elsevier} } + +@article{power2017simple, + title={A simple but useful way to assess fMRI scan qualities}, + author={Power, Jonathan D}, + journal={Neuroimage}, + volume={154}, + pages={150--158}, + year={2017}, + publisher={Elsevier}, + doi={10.1016/j.neuroimage.2016.08.009}, + url={https://doi.org/10.1016/j.neuroimage.2016.08.009} +} From c75abef4fe0ecd31c7e0791d0b4db1ab0759397c Mon Sep 17 00:00:00 2001 From: Taylor Salo Date: Mon, 28 Oct 2024 11:30:46 -0400 Subject: [PATCH 2/2] Keep working. --- docs/comparisons.rst | 48 ++++++++++++++++++++++++++++++++--------- docs/quickstart.rst | 15 ++++++++----- docs/reconstruction.rst | 4 ++-- docs/usage.rst | 17 ++++++++++----- 4 files changed, 62 insertions(+), 22 deletions(-) diff --git a/docs/comparisons.rst b/docs/comparisons.rst index 6c4cf920..f7cbf405 100644 --- a/docs/comparisons.rst +++ b/docs/comparisons.rst @@ -1,6 +1,10 @@ -############################## -Comparisons to other pipelines -############################## +########################## +Comparisons to other tools +########################## + +*********************************** +Comparisons to other dMRI pipelines +*********************************** Other pipelines for preprocessing DWI data are currently being developed. Below are tables comparing their current feature sets. @@ -11,9 +15,8 @@ Below are tables comparing their current feature sets. * `dMRIPrep `_ -************************** Supported Sampling Schemes -************************** +========================== .. list-table:: :header-rows: 1 @@ -50,9 +53,8 @@ Supported Sampling Schemes - ✘ -************* Preprocessing -************* +============= .. list-table:: :header-rows: 1 @@ -179,9 +181,8 @@ Preprocessing - ✔ -*************** Quality Control -*************** +=============== .. list-table:: :header-rows: 1 @@ -207,5 +208,32 @@ Quality Control - Custom - ✘ + +*********************************** QSIPrep versus other modality preps -=================================== +*********************************** + +Diffusion processing has idiosyncrasies that may confuse users who are used to +working with other modalities. +This section is designed to orient users who are familiar with pipelines like fMRIPrep and ASLPrep. + + +Output spaces +============= + +With fMRIPrep and other, similar pipelines, the user defines any output spaces they want, +and the workflow will write out preprocessed data in those spaces. +With QSIPrep, the pipeline will write out the preprocessed DWI data in a native anatomical space- +typically the T1w space, aligned to the ACPC. +The "output spaces" in this case will be provided as transforms from the T1w space to the +desired output space. +It is then up to the reconstruction pipeline (typically QSIRecon) to apply these transforms to the +preprocessed DWI data to get reconstructed outputs in the requested spaces. + + +Output resolution +================= + + +Concatenation across runs +========================= diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 666fd763..873c5efb 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -1,7 +1,8 @@ .. include:: links.rst +########### Quick Start ------------ +########### There are many options for running ``qsiprep`` but most have sensible defaults and don't need to be changed. This page describes the options most likely to be @@ -26,8 +27,9 @@ One way to process these data would be to call ``qsiprep`` like this:: See :ref:`output_resolution` for specifics. +************** Grouping scans -============== +************** .. note:: This section explains ``--separate-all-dwis``, ``--denoise-after-combining`` and @@ -54,8 +56,9 @@ the denoising preprocessing step has important caveats that should be considered discussion see :ref:`merge_denoise`. +****************** Specifying outputs -================== +****************** .. note:: This section covers ``--output-resolution X``, and @@ -83,9 +86,11 @@ brain graphs. If you want to save ~20 minutes of computation time, this normalization can be disabled with the ``--skip-t1-based-spatial-normalization`` option. + .. _output_resolution: + Output Resolution and Resampling -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +================================ The ``--output-resolution`` argument determines the spatial resolution of the preprocessed dwi series. You can specify the resolution of the original data @@ -100,7 +105,7 @@ interpolation. Head motion correction model -=============================== +============================ Although FSL's ``eddy`` is technically model-free, it is an option for ``--hmc-model`` along with ``3dSHORE`` and ``none``. Choosing ``eddy`` (the diff --git a/docs/reconstruction.rst b/docs/reconstruction.rst index 93d65e62..bd3a40ea 100644 --- a/docs/reconstruction.rst +++ b/docs/reconstruction.rst @@ -2,8 +2,8 @@ .. _reconstruction: - +############## Reconstruction -============== +############## Reconstruction workflows have been moved to a separate package: QSIRecon. \ No newline at end of file diff --git a/docs/usage.rst b/docs/usage.rst index 2debef61..4537b949 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,7 +1,8 @@ .. include:: links.rst +##### Usage ------ +##### The ``qsiprep`` preprocessing workflow takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in @@ -20,8 +21,9 @@ Example: :: qsiprep data/bids_root/ out/ participant -w work/ +********************** Command-Line Arguments -====================== +********************** .. argparse:: :ref: qsiprep.cli.parser._build_parser @@ -30,8 +32,9 @@ Command-Line Arguments :nodefaultconst: +****************** Note on using CUDA -================== +****************** The CUDA runtime version 9.1 is included in the QSIPrep docker image. The CUDA version of eddy is dramatically faster than the openmp version. @@ -39,8 +42,10 @@ Information on running Docker with CUDA enabled can be found on `dockerhub `_. If running with singularity, the call to singularity should include ``--nv``. To enable CUDA, see :ref:`configure_eddy`. + +********* Debugging -========= +********* Logs and crashfiles are outputted into the ``/qsiprep/sub-/log`` directory. @@ -48,8 +53,10 @@ Information on how to customize and understand these files can be found on the `nipype debugging `_ page. + +************ CUDA Support -============ +************ As of version 0.6.7 CUDA version 9.1 is supported in the QSIPrep container! To run locally using docker you will need the nvidia container runtime installed for Docker version 19.0.3