Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history 
Co-authored-by: Chris Markiewicz <[email protected]>
  • Loading branch information
@tsalo @effigies
tsalo and effigies authored Apr 23, 2024
1 parent f724819 commit 8bc81cb
Show file tree
Hide file tree
Showing 3 changed files with 4 additions and 203 deletions.
8 changes: 1 addition & 7 deletions docs/license.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,7 @@ License information
-------------------
Copyright (c) the *NiPreps* Developers.

As of the 21.0.x pre-release and release series, *fMRIPost-AROMA* is
licensed under the Apache License, Version 2.0 (the "License");
*fMRIPost-AROMA* is 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
Expand All @@ -23,9 +22,4 @@ limitations under the License.
Copyright (c), the *fMRIPost-AROMA* developers and the CRN.
All rights reserved.

*fMRIPost-AROMA* 20.2 series and earlier are
licensed under the BSD 3-clause license.
You may obtain a copy of the License at
https://opensource.org/licenses/BSD-3-Clause

All trademarks referenced herein are property of their respective holders.
193 changes: 0 additions & 193 deletions docs/outputs.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,116 +95,6 @@ Preprocessed, or derivative, data are written to
``<output dir>/sub-<subject_label>/``.
The `BIDS Derivatives`_ specification describes the naming and metadata conventions we follow.

Anatomical derivatives
~~~~~~~~~~~~~~~~~~~~~~
Anatomical derivatives are placed in each subject's ``anat`` subfolder::

sub-<subject_label>/
anat/
sub-<subject_label>[_space-<space_label>]_desc-preproc_T1w.nii.gz
sub-<subject_label>[_space-<space_label>]_desc-preproc_T2w.nii.gz
sub-<subject_label>[_space-<space_label>]_desc-brain_mask.nii.gz
sub-<subject_label>[_space-<space_label>]_dseg.nii.gz
sub-<subject_label>[_space-<space_label>]_label-CSF_probseg.nii.gz
sub-<subject_label>[_space-<space_label>]_label-GM_probseg.nii.gz
sub-<subject_label>[_space-<space_label>]_label-WM_probseg.nii.gz

Spatially-standardized derivatives are denoted with a space label,
such as ``MNI152NLin2009cAsym``, while derivatives in
the original ``T1w`` space omit the ``space-`` keyword.

T2w images are aligned to the anatomical (``T1w``) space, if found.

.. note::

T2w derivatives are only generated if FreeSurfer processing is enabled.

Additionally, the following transforms are saved::

sub-<subject_label>/
anat/
sub-<subject_label>_from-MNI152NLin2009cAsym_to-T1w_mode-image_xfm.h5
sub-<subject_label>_from-T1w_to-MNI152NLin2009cAsym_mode-image_xfm.h5

If FreeSurfer reconstructions are used, the following surface files are generated::

sub-<subject_label>/
anat/
sub-<subject_label>_hemi-[LR]_white.surf.gii
sub-<subject_label>_hemi-[LR]_midthickness.surf.gii
sub-<subject_label>_hemi-[LR]_pial.surf.gii
sub-<subject_label>_hemi-[LR]_desc-reg_sphere.surf.gii
sub-<subject_label>_hemi-[LR]_space-fsLR_desc-reg_sphere.surf.gii
sub-<subject_label>_hemi-[LR]_space-fsLR_desc-msmsulc_sphere.surf.gii

The registration spheres target ``fsaverage`` and ``fsLR`` spaces. If MSM
is enabled (i.e., the ``--no-msm`` flag is not passed), then the ``msmsulc``
spheres are generated and used for creating ``space-fsLR`` derivatives.

And the affine translation (and inverse) between the original T1w sampling and FreeSurfer's
conformed space for surface reconstruction (``fsnative``) is stored in::

sub-<subject_label>/
anat/
sub-<subject_label>_from-fsnative_to-T1w_mode-image_xfm.txt
sub-<subject_label>_from-T1w_to-fsnative_mode-image_xfm.txt

Finally, cortical thickness, curvature, and sulcal depth maps are converted to GIFTI
and CIFTI-2::

sub-<subject_label>/
anat/
sub-<subject_label>_hemi-[LR]_thickness.shape.gii
sub-<subject_label>_hemi-[LR]_curv.shape.gii
sub-<subject_label>_hemi-[LR]_sulc.shape.gii
sub-<subject_label>_space-fsLR_den-32k_thickness.dscalar.nii
sub-<subject_label>_space-fsLR_den-32k_curv.dscalar.nii
sub-<subject_label>_space-fsLR_den-32k_sulc.dscalar.nii

.. warning::

GIFTI metric files follow the FreeSurfer conventions and are not modified
by *fMRIPost-AROMA* in any way.

The Human Connectome Project (HCP) inverts the sign of the curvature and
sulcal depth maps. For consistency with HCP, *fMRIPost-AROMA* follows these
conventions and masks the medial wall of CIFTI-2 dscalar files.

.. _fsderivs:

FreeSurfer derivatives
~~~~~~~~~~~~~~~~~~~~~~
If FreeSurfer is run, then a FreeSurfer subjects directory is created in
``<output dir>/sourcedata/freesurfer`` or the directory indicated with the
``--fs-subjects-dir`` flag.
Additionally, FreeSurfer segmentations are resampled into the BOLD space,
and lookup tables are provided. ::

<output_dir>/
sourcedata/
freesurfer/
fsaverage{,5,6}/
mri/
surf/
...
sub-<label>/
mri/
surf/
...
...
desc-aparc_dseg.tsv
desc-aparcaseg_dseg.tsv

Copies of the ``fsaverage`` subjects distributed with the running version of
FreeSurfer are copied into this subjects directory, if any functional data are
sampled to those subject spaces.

Note that the use of ``sourcedata/`` recognizes FreeSurfer derivatives as an input to
the fMRIPost-AROMA workflow.
This is strictly true when pre-computed FreeSurfer derivatives are provided either in
the ``sourcedata/`` directory or passed via the ``--fs-subjects-dir`` flag;
if fMRIPost-AROMA runs FreeSurfer, then there is a mutual dependency.

Functional derivatives
~~~~~~~~~~~~~~~~~~~~~~
Functional derivatives are stored in the ``func/`` subfolder.
Expand All @@ -221,93 +111,10 @@ these will be indicated with ``[specifiers]``::
The mask file is part of the *minimal* processing level. The BOLD series
is only generated at the *full* processing level.

**Motion correction outputs**.

Head-motion correction (HMC) produces a reference image to which all volumes
are aligned, and a corresponding transform that maps the original BOLD series
to the reference image::

sub-<subject_label>/
func/
sub-<subject_label>_[specifiers]_desc-hmc_boldref.nii.gz
sub-<subject_label>_[specifiers]_from-orig_to_boldref_mode-image_desc-hmc_xfm.nii.gz

.. note::

Motion correction outputs are part of the *minimal* processing level.

**Coregistration outputs**.

Registration of the BOLD series to the T1w image generates a further reference
image and affine transform::

sub-<subject_label>/
func/
sub-<subject_label>_[specifiers]_desc-coreg_boldref.nii.gz
sub-<subject_label>_[specifiers]_from-boldref_to-T1w_mode-image_desc-coreg_xfm.txt

.. note::

Coregistration outputs are part of the *minimal* processing level.

**Fieldmap registration**.

If a fieldmap is used for the correction of a BOLD series, then a registration
is calculated between the BOLD series and the fieldmap. If, for example, the fieldmap
is identified with ``"B0Identifier": "TOPUP"``, the generated transform will be named::

sub-<subject_label>/
func/
sub-<subject_label>_[specifiers]_from-boldref_to-TOPUP_mode-image_xfm.nii.gz

If the association is discovered through the ``IntendedFor`` field of the
fieldmap metadata, then the transform will be given an auto-generated name::

sub-<subject_label>/
func/
sub-<subject_label>_[specifiers]_from-boldref_to-auto000XX_mode-image_xfm.txt

.. note::

Fieldmap registration outputs are part of the *minimal* processing level.

**Regularly gridded outputs (images)**.
Volumetric output spaces labels (``<space_label>`` above, and in the following) include
``T1w`` and ``MNI152NLin2009cAsym`` (default).

**Surfaces, segmentations and parcellations from FreeSurfer**.
If FreeSurfer reconstructions are used, the ``(aparc+)aseg`` segmentations are aligned to the
subject's T1w space and resampled to the BOLD grid, and the BOLD series are resampled to the
mid-thickness surface mesh::

sub-<subject_label>/
func/
sub-<subject_label>_[specifiers]_space-T1w_desc-aparcaseg_dseg.nii.gz
sub-<subject_label>_[specifiers]_space-T1w_desc-aseg_dseg.nii.gz
sub-<subject_label>_[specifiers]_hemi-[LR]_space-<space_label>_bold.func.gii

Surface output spaces include ``fsnative`` (full density subject-specific mesh),
``fsaverage`` and the down-sampled meshes ``fsaverage6`` (41k vertices) and
``fsaverage5`` (10k vertices, default).

**Grayordinates files**.
`CIFTI <https://www.nitrc.org/forum/attachment.php?attachid=333&group_id=454&forum_id=1955>`_ is
a container format that holds both volumetric (regularly sampled in a grid) and surface
(sampled on a triangular mesh) samples.
Sub-cortical time series are sampled on a regular grid derived from one MNI template, while
cortical time series are sampled on surfaces projected from the [Glasser2016]_ template.
If CIFTI outputs are requested (with the ``--cifti-outputs`` argument), the BOLD series are also
saved as ``dtseries.nii`` CIFTI2 files::

sub-<subject_label>/
func/
sub-<subject_label>_[specifiers]_bold.dtseries.nii

CIFTI output resolution can be specified as an optional parameter after ``--cifti-output``.
By default, '91k' outputs are produced and match up to the standard `HCP Pipelines`_ CIFTI
output (91282 grayordinates @ 2mm). However, '170k' outputs are also possible, and produce
higher resolution CIFTI output (170494 grayordinates @ 1.6mm).

**Extracted confounding time series**.
For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPost-AROMA*, an
accompanying *confounds* file will be generated.
Expand Down
6 changes: 3 additions & 3 deletions docs/usage.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
Usage Notes
===========
.. warning::
As of *fMRIPost-AROMA* 1.0.12, the software includes a tracking system
to report usage statistics and errors. Users can opt-out using
the ``--notrack`` command line argument.
*fMRIPost-AROMA* includes a tracking system to report usage statistics and errors
for debugging and grant reporting purposes.
Users can opt-out using the ``--notrack`` command line argument.


Execution and the BIDS format
Expand Down

0 comments on commit 8bc81cb

Please sign in to comment.