Improve documentation (#218)

* Add API.

* Update requirements.

* Remove Napoleon.

* Update conf.py

* Add badges.

* Lots of changes.

* Move test data.

* More work.

* More work.

* More work.

* Rename references.

* Fix line lengths.

* Fix things.

* Remove unused package data.

* More improvements.

* Use consistent rst heading characters.

# with overline, for parts
* with overline, for chapters
= for sections
- for subsections
^ for subsubsections
" for paragraphs

* Update conf.py

* Improve conf.py.

* Add NeuroStars link.

* Add issue templates.

* Update graph images.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug report
+about: Something not working as described? Missing/incorrect documentation? This is the place.
+title: ''
+labels: 'bug'
+assignees: ''
+
+---
+## Summary
+<!--What is the nature of the bug?-->
+
+## Additional details
+<!--Please fill in the following details-->
+- ASLPrep version:
+- Docker version:
+- Singularity version:
+
+### What were you trying to do?
+
+### What did you expect to happen?
+
+### What actually happened?
+
+## Reproducing the bug
+<!--Please share any steps you performed that revealed the bug-->
+<!--Please include any code snippets.
+Enclose them in triple back-ticks (```)
+Like this:
+
+```
+<code>
+```
+-->

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,4 @@
+contact_links:
+  - name: Usage question
+    url: https://neurostars.org/tags/c/software-support/234/aslprep
+    about: Please ask questions about using ASLPrep on NeuroStars.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Got an idea for a new feature, or changing an existing one? This is the place.
+title: ''
+labels: 'enhancement'
+assignees: ''
+
+---
+## Summary
+<!--What would you like changed/added and why?-->
+
+## Additional details
+<!--What would be the benefit?-->
+
+## Next steps
+<!--Do you have any ideas about the implementation?-->

.gitignore

@@ -1,12 +1,9 @@
 .circleci/local_aslprep_path.txt
 
-aslprep/data/atlas/.DS_Store
-aslprep/data/.DS_Store
-aslprep/.DS_Store
 .DS_Store
 .trash
-docs/sphinxext/__pycache__/github_link.cpython-37.pyc
-aslprep/pybids/__pycache__/__init__.cpython-38.pyc
+docs/generated/
+docs/api/
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.rst

@@ -1,71 +1,89 @@
+#######################################################
+*ASLPrep*: A Robust Preprocessing Pipeline for ASL Data
+#######################################################
+
+.. image:: https://img.shields.io/badge/Source%20Code-pennlinc%2Faslprep-purple
+   :target: https://github.com/PennLINC/aslprep
+   :alt: GitHub Repository
+
+.. image:: https://readthedocs.org/projects/aslprep/badge/?version=latest
+   :target: http://aslprep.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation
+
+.. image:: https://img.shields.io/badge/docker-pennlinc/aslprep-brightgreen.svg?logo=docker&style=flat
+   :target: https://hub.docker.com/r/pennlinc/aslprep/tags/
+   :alt: Docker
+
+.. image:: https://circleci.com/gh/PennLINC/aslprep.svg?style=svg
+   :target: https://circleci.com/gh/PennLINC/aslprep
+   :alt: Test Status
+
+.. image:: https://codecov.io/gh/PennLINC/aslprep/branch/main/graph/badge.svg
+   :target: https://codecov.io/gh/PennLINC/aslprep
+   :alt: Codecov
+
 .. image:: https://zenodo.org/badge/256420694.svg
    :target: https://zenodo.org/badge/latestdoi/256420694
-
-   
-   
-*ASLPrep*: A Robust Preprocessing Pipeline for ASL Data
-=========================================================
+   :alt: DOI
+
+.. image:: https://img.shields.io/github/license/pennlinc/aslprep
+   :target: https://opensource.org/licenses/BSD-3-Clause
+   :alt: License
 
-This pipeline is developed by the `Satterthwaite lab at the University of Pennysilvania
+This pipeline is developed by the `Satterthwaite lab at the University of Pennsylvania
 <https://www.satterthwaitelab.com/>`_ for use at the `The Lifespan Informatics and Neuroimaging Center
-at the University of Pennylvannia <https://www.satterthwaitelab.com/>`_, as well as for
+at the University of Pennsylvania <https://www.satterthwaitelab.com/>`_, as well as for
 open-source software distribution.
 
+*****
 About
------
-
-
-.. image:: https://raw.githubusercontent.com/a3sha2/aslprep/master/docs/_static/aslprepworkflow.png
+*****
 
+.. image:: https://raw.githubusercontent.com/PennLINC/aslprep/main/docs/_static/aslprepworkflow.png
 
 *ASLPrep* is a Arterial Spin Labeling  (ASL) data
-preprocessing  and Cerebral Blood FLow (CBF) computation pipeline
+preprocessing  and Cerebral Blood Flow (CBF) computation pipeline
 that is designed to provide an easily accessible,
 state-of-the-art interface that is robust to variations in scan acquisition
 protocols and that requires minimal user input, while providing easily
 interpretable and comprehensive error and output reporting.
 It performs basic processing steps (coregistration, normalization, unwarping,
-noise component extraction, segmentation, skullstripping etc.), CBF computation,
-denoising CBF, CBF partial volume correction and providing
-outputs that can be easily submitted to a variety of group level analyses,
-including task-based or resting-state CBF, graph theory measures, surface or
-volume-based statistics, etc.
-
+noise component extraction, segmentation, skullstripping etc.),
+CBF computation, denoising CBF, CBF partial volume correction,
+and providing outputs that can be easily submitted to a variety of group level analyses,
+including task-based or resting-state CBF, graph theory measures, surface or volume-based statistics, etc.
 
 The *ASLPrep* pipeline uses a combination of tools from well-known software
-packages, including FSL_, ANTs_, FreeSurfer_ and AFNI_ .
-This pipeline was designed to provide the best software implementation for each
-state of preprocessing, and will be updated as newer and better neuroimaging
-software become available.
+packages, including FSL_, ANTs_, FreeSurfer_ and AFNI_.
+This pipeline was designed to provide the best software implementation for each state of preprocessing,
+and will be updated as newer and better neuroimaging software become available.
 
 This tool allows you to easily do the following:
 
 - Take ASL data from raw to fully preprocessed form.
-- Compute Cerebral Blood Flow(CBF), denoising and partial volume correction
+- Compute Cerebral Blood Flow (CBF), denoising and partial volume correction.
 - Implement tools from different software packages.
 - Achieve optimal data processing quality by using the best tools available.
 - Receive verbose output concerning the stage of preprocessing for each
   subject, including meaningful errors.
 - Automate and parallelize processing steps, which provides a significant
   speed-up from typical linear, manual processing.
-- 
 
-More information and documentation can be found at
-https://aslprep.readthedocs.io/
+More information and documentation can be found at https://aslprep.readthedocs.io/.
 
+*******
 ASLPrep
---------
-
-*ASLPrep* adapts the preprocessing steps depending on the input dataset 
-and provide results as good as possible independently of scanner make and scanning parameters 
-With the BIDS input, little or no parameter are required allowing ease of operation. 
-*ASLPrep*  also provides visual reports for each subject,
-detailing the the most important processing steps.
-
+*******
 
+*ASLPrep* adapts the preprocessing steps depending on the input dataset
+and provide results as good as possible independently of scanner make and scanning parameters
+With the BIDS input, little or no parameter are required allowing ease of operation.
+*ASLPrep* also provides visual reports for each subject,
+detailing the most important processing steps.
 
+****************
 Acknowledgements
-----------------
+****************
 
 Please acknowledge this work using the citation boilerplate that *ASLPrep* includes
-in the visual report generated for every subject processed. `(link) <https://aslprep.readthedocs.io/en/latest/citing.html>`_
+in the visual report generated for every subject processed.

aslprep/config.py

@@ -11,7 +11,7 @@
 The module has a :py:func:`~aslprep.config.to_filename` function to allow writting out
 the settings to hard disk in *ToML* format, which looks like:
 
-.. literalinclude:: ../aslprep/data/tests/config.toml
+.. literalinclude:: ../../aslprep/tests/data/config.toml
    :language: toml
    :name: aslprep.toml
    :caption: **Example file representation of aslprep settings**.

aslprep/data/boilerplate.bib

@@ -18,7 +18,7 @@ @article{bbr
 	file = {Accepted Version:/Users/adebimpe/Zotero/storage/BRFJ4IKS/Greve and Fischl - 2009 - Accurate and robust brain image alignment using bo.pdf:application/pdf;Accepted Version:/Users/adebimpe/Zotero/storage/U333GSCH/Greve and Fischl - 2009 - Accurate and robust brain image alignment using bo.pdf:application/pdf;Accepted Version:/Users/adebimpe/Zotero/storage/ATZDZAWD/Greve and Fischl - 2009 - Accurate and robust brain image alignment using bo.pdf:application/pdf},
 }
 
-@article{kinetic,
+@article{buxton1998general,
 	title = {A general kinetic model for quantitative perfusion imaging with arterial spin labeling},
 	volume = {40},
 	doi = {10.1002/mrm.1910400308},
@@ -128,7 +128,7 @@ @article{detre_perfusion_1992
 	file = {Full Text PDF:/Users/adebimpe/Zotero/storage/AZY3F2PL/Detre et al. - 1992 - Perfusion imaging.pdf:application/pdf;Snapshot:/Users/adebimpe/Zotero/storage/WPJVE3GZ/mrm.html:text/html;Snapshot:/Users/adebimpe/Zotero/storage/M4E8Y24C/mrm.html:text/html},
 }
 
-@article{chappell_partial_2011,
+@article{chappell2011partial,
 	title = {Partial volume correction of multiple inversion time arterial spin labeling {MRI} data},
 	volume = {65},
 	issn = {1522-2594},
@@ -162,7 +162,7 @@ @article{chappell_variational_2009
 	file = {IEEE Xplore Abstract Record:/Users/adebimpe/Zotero/storage/XVV2KUID/4625948.html:text/html;IEEE Xplore Abstract Record:/Users/adebimpe/Zotero/storage/2IZZGQJK/4625948.html:text/html;IEEE Xplore Full Text PDF:/Users/adebimpe/Zotero/storage/2PM8WXQ4/Chappell et al. - 2009 - Variational Bayesian Inference for a Nonlinear For.pdf:application/pdf},
 }
 
-@article{score_dolui,
+@article{dolui2017structural,
 	title = {Structural {Correlation}-based {Outlier} {Rejection} ({SCORE}) algorithm for arterial spin labeling time series: {SCORE}: {Denoising} {Algorithm} for {ASL}},
 	volume = {45},
 	issn = {10531807},
@@ -483,15 +483,16 @@ @article{posse_t2s
 	file = {Full Text:/Users/adebimpe/Zotero/storage/6GR5B2F4/Posse et al. - 1999 - Enhancement of BOLD-contrast sensitivity by single.pdf:application/pdf},
 }
 
-@article{cbfqc,
+@article{dolui2017automated,
     author = { Dolui, Sudipto and Wolf, Ronald  and Nabavizadeh, Seyed Ali  and Wolk, David A.  and Detre, John A.},
     doi = {http://indexsmart.mirasmart.com/ISMRM2017/PDFfiles/0682.html},
     journal = {International Society for Magnetic Resonance in Medicine},
     number = {1},
     title = {Automated Quality Evaluation Index for 2D ASL CBF Maps},
     year = {2016}
 }
-@article{scrub_dolui,
+
+@article{dolui2016scrub,
     title = {SCRUB: A Structural Correlation and Empirical Robust Bayesian Method for ASL Data},
     doi = {http://archive.ismrm.org/2016/2880.html},
     journal = {International Society for Magnetic Resonance in Medicine},
@@ -500,9 +501,7 @@ @article{scrub_dolui
     year = {2016}
 }
 
-
-
-@article{chappell_basil,
+@article{chappell2008variational,
 	title = {Variational Bayesian Inference for a Nonlinear Forward Model},
 	volume = {57},
 	doi = {10.1109/TSP.2008.2005752},
@@ -582,4 +581,37 @@ @article{scipy
 	note = {Bandiera\_abtest:},
 	pages = {261--272},
 	file = {Full Text PDF:/Users/adebimpe/Zotero/storage/HBFK9K6T/Virtanen et al. - 2020 - SciPy 1.0 fundamental algorithms for scientific c.pdf:application/pdf;Snapshot:/Users/adebimpe/Zotero/storage/F87IPJ7C/s41592-019-0686-2.html:text/html},
-}
+}
+
+@article{wong1998quantitative,
+	title={Quantitative imaging of perfusion using a single subtraction (QUIPSS and QUIPSS II)},
+	author={Wong, Eric C and Buxton, Richard B and Frank, Lawrence R},
+	journal={Magnetic resonance in medicine},
+	volume={39},
+	number={5},
+	pages={702--708},
+	year={1998},
+	publisher={Wiley Online Library}
+}
+
+@article{groves2009combined,
+  title={Combined spatial and non-spatial prior for inference on MRI time-series},
+  author={Groves, Adrian R and Chappell, Michael A and Woolrich, Mark W},
+  journal={Neuroimage},
+  volume={45},
+  number={3},
+  pages={795--809},
+  year={2009},
+  publisher={Elsevier}
+}
+
+@article{dai2012reduced,
+  title={Reduced resolution transit delay prescan for quantitative continuous arterial spin labeling perfusion imaging},
+  author={Dai, Weiying and Robson, Philip M and Shankaranarayanan, Ajit and Alsop, David C},
+  journal={Magnetic resonance in medicine},
+  volume={67},
+  number={5},
+  pages={1252--1265},
+  year={2012},
+  publisher={Wiley Online Library}
+}

aslprep/interfaces/cbf_computation.py

@@ -313,11 +313,11 @@ class ScoreAndScrubCBF(SimpleInterface):
     """Apply the SCORE and SCRUB algorithms.
 
     The Structural Correlation-based Outlier Rejection (SCORE) algorithm is applied to the CBF
-    time series to discard CBF volumes with outlying values :footcite:p:`score_dolui` before
-    computing the mean CBF.
+    time series to discard CBF volumes with outlying values :footcite:p:`dolui2017structural`
+    before computing the mean CBF.
     The Structural Correlation with RobUst Bayesian (SCRUB) algorithm is then applied to the CBF
     maps using structural tissue probability maps to reweight the mean CBF
-    :footcite:p:`scrub_dolui`.
+    :footcite:p:`dolui2016scrub`.
 
     References
     ----------

aslprep/niworkflows/anat/skullstrip.py

@@ -28,7 +28,7 @@ def afni_wf(name="AFNISkullStripWorkflow", unifize=False, n4_nthreads=1):
     Parameters
     ----------
     n4_nthreads : int
-        number of cpus N4 bias field correction can utilize.
+        number of cpus N4 bias field correction can use.
     unifize : bool
         whether AFNI's ``3dUnifize`` should be applied (default: ``False``).
     name : str

aslprep/niworkflows/reports/core.py

@@ -66,7 +66,7 @@ class Reportlet(Element):
     >>> from pkg_resources import resource_filename
     >>> from shutil import copytree
     >>> from bids.layout import BIDSLayout
-    >>> test_data_path = resource_filename('niworkflows', 'data/tests/work')
+    >>> test_data_path = resource_filename('niworkflows', 'tests/data/work')
     >>> testdir = Path(tmpdir)
     >>> data_dir = copytree(test_data_path, str(testdir / 'work'))
     >>> out_figs = testdir / 'out' / 'fmriprep'
@@ -218,7 +218,7 @@ class Report:
     >>> from pkg_resources import resource_filename
     >>> from shutil import copytree
     >>> from bids.layout import BIDSLayout
-    >>> test_data_path = resource_filename('niworkflows', 'data/tests/work')
+    >>> test_data_path = resource_filename('niworkflows', 'tests/data/work')
     >>> testdir = Path(tmpdir)
     >>> data_dir = copytree(test_data_path, str(testdir / 'work'))
     >>> out_figs = testdir / 'out' / 'fmriprep'
@@ -489,7 +489,7 @@ def run_reports(
 
     >>> from pkg_resources import resource_filename
     >>> from shutil import copytree
-    >>> test_data_path = resource_filename('niworkflows', 'data/tests/work')
+    >>> test_data_path = resource_filename('niworkflows', 'tests/data/work')
     >>> testdir = Path(tmpdir)
     >>> data_dir = copytree(test_data_path, str(testdir / 'work'))
     >>> (testdir / 'fmriprep').mkdir(parents=True, exist_ok=True)

aslprep/tests/test_config.py

@@ -10,7 +10,7 @@
 
 def test_config_spaces():
     """Check that all necessary spaces are recorded in the config."""
-    filename = Path(pkgrf("aslprep", "data/tests/config.toml"))
+    filename = Path(pkgrf("aslprep", "tests/data/config.toml"))
     settings = loads(filename.read_text())
     for sectionname, configs in settings.items():
         if sectionname != "environment":

aslprep/tests/tests.py

@@ -17,7 +17,7 @@ def mock_config():
     if not _old_fs:
         os.environ["FREESURFER_HOME"] = mkdtemp()
 
-    filename = Path(pkgrf("aslprep", "data/tests/config.toml"))
+    filename = Path(pkgrf("aslprep", "tests/data/config.toml"))
     settings = loads(filename.read_text())
     for sectionname, configs in settings.items():
         if sectionname != "environment":
@@ -28,7 +28,7 @@ def mock_config():
     config.init_spaces()
 
     config.execution.work_dir = Path(mkdtemp())
-    config.execution.bids_dir = Path(pkgrf("aslprep", "data/tests/ds000240")).absolute()
+    config.execution.bids_dir = Path(pkgrf("aslprep", "tests/data/ds000240")).absolute()
     config.execution.init()
 
     yield

aslprep/utils/qc.py

@@ -118,7 +118,7 @@ def globalcbf(cbf, gm, wm, csf, thresh=0.7):
 def cbf_qei(gm, wm, csf, img, thresh=0.8):
     """Compute quality evaluation index (QEI) of CBF.
 
-    The QEI is based on :footcite:t:`cbfqc`.
+    The QEI is based on :footcite:t:`dolui2017automated`.
 
     References
     ----------

aslprep/workflows/__init__.py

@@ -1 +1,7 @@
 """Nipype workflows for the ASLPrep BIDS App."""
+from aslprep.workflows import asl, base
+
+__all__ = [
+    "asl",
+    "base",
+]