.. include:: links.rst

.. _outputs:

---------------------------
Outputs of *fMRIPost-rapidtide*
---------------------------

*fMRIPost-rapidtide* outputs conform to the :abbr:`BIDS (brain imaging data structure)`
Derivatives specification (see `BIDS Derivatives`_, along with the
upcoming `BEP 011`_ and `BEP 012`_).
*fMRIPost-rapidtide* generates three broad classes of outcomes:

1.  **Visual QA (quality assessment) reports**:
    One :abbr:`HTML (hypertext markup language)` per subject,
    that allows the user a thorough visual assessment of the quality
    of processing and ensures the transparency of *fMRIPost-rapidtide* operation.

2.  **ICA outputs**:
    Outputs from the independent component analysis (ICA).
    For example, the mixing matrix and component weight maps.

3.  **Derivatives (denoised data)**:
    Denoised fMRI data in the requested output spaces and resolutions.

4.  **Confounds**:
    Time series of ICA components,
    as well as labels indicating if the components are accepted or rejected.


Layout
------

Assuming fMRIPost-rapidtide is invoked with::

    fmripost_rapidtide <input_dir>/ <output_dir>/ participant [OPTIONS]

The outputs will be a `BIDS Derivatives`_ dataset of the form::

    <output_dir>/
      logs/
      sub-<label>/
      sub-<label>.html
      dataset_description.json
      .bidsignore

For each participant in the dataset,
a directory of derivatives (``sub-<label>/``)
and a visual report (``sub-<label>.html``) are generated.
The log directory contains `citation boilerplate`_ text.
``dataset_description.json`` is a metadata file in which fMRIPost-rapidtide
records metadata recommended by the BIDS standard.


Visual Reports
--------------

*fMRIPost-rapidtide* outputs summary reports,
written to ``<output dir>/fmripost_rapidtide/sub-<label>.html``.
These reports provide a quick way to make visual inspection of the results easy.


Derivatives of *fMRIPost-rapidtide* (denoised data)
-----------------------------------------------

Derivative data are written to
``<output dir>/sub-<label>/``.
The `BIDS Derivatives`_ specification describes the naming and metadata conventions we follow.


ICA derivatives
~~~~~~~~~~~~~~~

ICA outputs are stored in the ``func/`` subfolder::

  sub-<label>/
    func/
      sub-<label>_space-<label>_desc-melodic_mixing.tsv
      sub-<label>_space-<label>_desc-melodic_mixing.json
      sub-<label>_space-<label>_desc-melodic_components.nii.gz
      sub-<label>_space-<label>_desc-melodic_components.json


Functional derivatives
~~~~~~~~~~~~~~~~~~~~~~

Functional derivatives are stored in the ``func/`` subfolder.
All derivatives contain ``task-<task_label>`` (mandatory) and ``run-<run_index>`` (optional), and
these will be indicated with ``[specifiers]``::

  sub-<label>/
    func/
      sub-<label>_[specifiers]_space-<label>_desc-brain_mask.nii.gz
      sub-<label>_[specifiers]_space-<label>_desc-aggrDenoised_bold.nii.gz
      sub-<label>_[specifiers]_space-<label>_desc-nonaggrDenoised_bold.nii.gz
      sub-<label>_[specifiers]_space-<label>_desc-orthaggrDenoised_bold.nii.gz

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

**Extracted confounding time series**.
For each :abbr:`BOLD (blood-oxygen level dependent)` run processed with *fMRIPost-rapidtide*,
an accompanying *confounds* file will be generated.
Confounds_ are saved as a :abbr:`TSV (tab-separated value)` file::

  sub-<label>/
    func/
      sub-<label>_[specifiers]_desc-rapidtide_metrics.tsv
      sub-<label>_[specifiers]_desc-rapidtide_metrics.json
      sub-<label>_[specifiers]_desc-confounds_timeseries.tsv
      sub-<label>_[specifiers]_desc-confounds_timeseries.json

Confounds
---------

*fMRIPost-rapidtide* outputs a set of confounds that can be used to denoise the data.
These are stored in a TSV file (``desc-confounds_timeseries.tsv``) and a JSON file
(``desc-confounds_timeseries.json``) that contains metadata about the confounds.

The confounds generated by *fMRIPost-rapidtide* are ICA component time series,
which may be labeled as "accepted" or "rejected" based on the ICA-rapidtide classification.

Confounds and "carpet"-plot on the visual reports
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The visual reports provide several sections per task and run to aid designing
a denoising strategy for subsequent analysis.
Some of the estimated confounds are plotted with a "carpet" visualization of the
:abbr:`BOLD (blood-oxygen level-dependent)` time series [Power2016]_.
An example of these plots follows:

See implementation on :mod:`~fmripost_rapidtide.workflows.bold.confounds.init_bold_confs_wf`.