DOC: Improving accessibility of confounds description

[kfinc]

Changes proposed in this pull request

This PR addresses issues #489 #1726 #1049 related to improving the accessibility and educational value of fMRIPrep documentation, in particular, description of Confounds.

The work was done during fMRIPrep docusprint and is a result of collaborative effort of multiple people, including Pierre Bellec, Elizabeth DuPre, Karolina Finc, James Kent, Chris Markiewicz, Saren Seeley, Ursula Tooley, Hao-Ting Wang.

You can track our discussion here:
https://docs.google.com/document/d/14WyhCvEn0G5fbLY-Rk7BQa9ISzYEB2ll3YCjyd-OjB8/edit

Documentation that should be reviewed

We made major edits to the Confounds subsection in outputs.rst:

• we added a general explanation of sources of noise in fMRI signal and introduction to confound regression - that may help users to grasp the idea and advantage of multiple regressors returned by fMRIPrep;
• we warned a user of possible misuse of confounds_regressors.tsv table, such as (1) regressing out all confounds during denoising procedure, (2) using ICA-AROMA confounds on AROMA-denoised data, and (3) not selecting a subset of CompCor confounds;
• we expanded the list of references by some fresh and informative papers;
• we proposed a structure for describing confounds in sections: (1) Basic confounds, (2) Parameter expansion of basic confounds, (3) Confounds for outlier detection, (4) ICA-AROMA confounds, (5) CompCor confounds [I will be grateful for the discussion on the proposed structure as it is an alternative to the structure discussed during docusprint];
• we added more description to almost all confound regressors.

There is still much to improve and clarify, but I think that this is a good start.

[welcome]

Thanks for opening this pull request! It looks like this is your first time contributing to fMRIPrep. 😄
We invite you to list yourself as an fMRIPrep contributor. To learn more about what that entails and how we credit our contributors, please check out the contributing guidelines. If your name is not already on the list, please insert it, in alphabetical order, into the contributors.json file. Example:

   "name": "Contributor, New FMRIPrep",
   "affiliation": "Department of fMRI prep'ing, Open Science Made-Up University",
   "orcid": "<your id>"
}, ```

Of course, if you want to opt-out this time there is no problem at all with adding your name later. You will be always welcome to add it in the future whenever you feel it should be listed.

[oesteban]

Looking great at a first pass. Documentation build is failing because of the FSL link, added a suggestion to fix that.

A couple of iterated issues that I only marked once:

• New sentences should start with new lines
• fMRIPrep should be capitalized that way, and rendered in italics: fMRIPrep.

[oesteban]

Eyes from @wiheto and @rciric very much appreciated :)

[oesteban]

Okay, rendered here https://10602-53175327-gh.circle-artifacts.com/0/tmp/src/fmriprep/docs/_build/html/outputs.html

Last call for @rciric and @poldracklab/fmriprep-docusprint-leaders to have a look.

[effigies]

We should probably note that these are not BIDS-Derivatives-Draft conformant and subject to change in future versions.

[oesteban]

Thanks for the feedback - will address your mutually exclusive comments later.

[oesteban]

Yes

[oesteban]

Paging @rciric

[adelavega]

Overall, looks great. My comments are super nitpicky so take them with a grain of salt!