Merge pull request #948 from qiqiliang/docsoverhaul

Starting doc overhaul

.gitignore

@@ -4,9 +4,10 @@ AFQ/version.py
 .coverage*
 docs/_build
 docs/build
-docs/auto_examples
-docs/source/auto_examples
-docs/source/usage/config.rst
+docs/source/auto_examples/
+docs/source/tutorials/tutorial_examples/
+docs/source/howto/howto_examples/
+docs/source/reference/config.rst
 examples/**/*.nii.gz
 examples/**/*.trk
 examples/**/*.npy

AFQ/definitions/mapping.py

@@ -66,6 +66,11 @@ class FnirtMap(Definition):
         the space file.
         Default: {}
 
+    Notes
+    -----
+    If you have an existing mapping calculated using Fnirt,
+    you can pass bids filters to :class:`AFQ.definitions.mapping.FnirtMap`
+    and pyAFQ will find and use that mapping.
 
     Examples
     --------
@@ -380,6 +385,15 @@ class SynMap(GeneratedMapMixin, Definition):
         Parameters to pass to syn_registration
         in dipy.align, which does the SyN alignment.
         Default: {}
+
+    Notes
+    -----
+    The default mapping class is to
+    use Symmetric Diffeomorphic Image Registration (SyN).
+    This is done with an optional linear pre-alignment by default.
+    The parameters of the pre-alginment can be specified when
+    initializing the SynMap.
+
     Examples
     --------
     api.GroupAFQ(mapping=SynMap())
@@ -414,11 +428,21 @@ class SlrMap(GeneratedMapMixin, Definition):
     Calculate a SLR registration for each subject/session
     using reg_subject and reg_template.
 
+    Parameters
+    ----------
     slr_kwargs : dictionary, optional
         Parameters to pass to whole_brain_slr
         in dipy, which does the SLR alignment.
         Default: {}
 
+    Notes
+    -----
+    Use this class to tell pyAFQ to use
+    Streamline-based Linear Registration (SLR) 
+    for registration. Note that the reg_template and reg_subject
+    parameters passed to :class:`AFQ.api.group.GroupAFQ` should
+    be streamlines when using this registration.
+
     Examples
     --------
     api.GroupAFQ(mapping=SlrMap())
@@ -448,11 +472,17 @@ class AffMap(GeneratedMapMixin, Definition):
     Calculate an affine registration for each subject/session
     using reg_subject and reg_template.
 
+    Parameters
+    ----------
     affine_kwargs : dictionary, optional
         Parameters to pass to affine_registration
         in dipy.align, which does the linear pre-alignment.
         Default: {}
 
+    Notes
+    -----
+    This will only perform a linear alignment for registration.
+
     Examples
     --------
     api.GroupAFQ(mapping=AffMap())

docs/source/_static/custom.css

@@ -1,4 +1,70 @@
 tbody, tr, td
 {
     border: 0 !important;
-}
+    height: 100%;
+    width: 100%;
+}
+
+.sd-card {
+    margin-bottom: 20px
+}
+
+.sd-card-header {
+    text-align: center;
+    background-color: white;
+    color: #150458 !important;
+    font-size: var(--pst-font-size-h5);
+    font-weight: bold;
+
+}
+
+.sd-card-footer {
+    display: none;
+}
+
+.top-image {
+    float: left;
+    width: 25%;
+    height: 100%;
+}
+
+.bottom-image {
+    float: right;
+    width: 25%;
+    height: 100%;
+    clear: left;
+}
+
+.right-arrow {
+    float: left;
+    width: 10%;
+}
+
+.left-arrow {
+    float: right;
+    width: 10%;
+}
+
+/* fitting down arrow */
+.reference.internal.image-reference {
+    margin-left: 20%;
+}
+
+/* fitting right arrows */
+.right-arrow.figure.align-default {
+    margin-top: 5%;
+}
+
+/* fitting left arrows */
+.left-arrow.figure.align-default {
+    margin-top: 5%;
+}
+
+/* fitting bottom images to match top images.. shift bottom rightmost image to the left*/
+#id5.bottom-image.figure.align-default {
+    margin-right: 5%;
+}
+
+.top-image.figure.align-default {
+    margin-bottom: 0px;
+}

docs/source/conf.py

@@ -54,6 +54,7 @@
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
     'sphinx_gallery.gen_gallery',
+    'sphinx_design',
     'sphinx.ext.autosummary',
     'autoapi.extension',
     'numpydoc',
@@ -84,8 +85,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = [
-    "examples/cloudknot_*"]
+exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -142,9 +142,11 @@
 #
 # html_sidebars = {}
 
-html_css_files = [
-    'css/custom.css',
-]
+# html_css_files = [
+#     'css/custom.css'
+# ]
+
+html_css_files = ['custom.css']
 
 # -- Options for HTMLHelp output ---------------------------------------------
 
@@ -220,10 +222,10 @@
 
 sphinx_gallery_conf = {
     # path to your examples scripts
-    'examples_dirs': '../../examples',
+    'examples_dirs': ['../../examples/howto_examples', '../../examples/tutorial_examples'],
     # path where to save gallery generated examples
-    'gallery_dirs': 'auto_examples',
-    'ignore_pattern': 'plot_baby_afq.py',
+    'gallery_dirs': ['howto/howto_examples', 'tutorials/tutorial_examples'],
+    'ignore_pattern': 'plot_baby_afq.py|cloudknot_hcp_example.py|cloudknot_example.py',
     'image_scrapers': image_scrapers,
     'reset_modules': (reset_progressbars),
 }
@@ -232,3 +234,4 @@
 autoapi_type = 'python'
 autoapi_dirs = ['../../AFQ']
 autoapi_ignore = ['*test*', '*_fixes*', '*version*', 'pyAFQ', 'License']
+autoapi_root = 'reference/api'

docs/source/explanations/cleaning.rst

@@ -0,0 +1,4 @@
+.. _cleaning:
+
+Cleaning
+========

docs/source/explanations/index.rst

@@ -0,0 +1,29 @@
+Explanations
+------------
+
+Automated Fiber Quantification
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Tractography based on diffusion weighted MRI (dMRI) is used to find the major
+white matter fascicles (tracts) in the living human brain. The health of these
+tracts is an important factor underlying many cognitive and neurological
+disorders.
+
+Tissue properties may vary systematically along each tract: different
+populations of axons enter and exit the tract, and disease can strike at local
+positions within the tract. Because of this, quantifying and understanding
+diffusion measures along each fiber tract (the tract profile) may reveal new
+insights into white matter development, function, and disease that are not
+obvious from mean measures of that tract ([Yeatman2012]_).
+
+
+`pyAFQ` is a software package focused on automated delineation of the major
+fiber tracts in individual human brains, and quantification of the tissue
+properties within the tracts. To learn more about the software please refer to the Table of Contents.
+
+For further statistical analysis of pyAFQ results, see `AFQ-Insight <https://github.com/richford/AFQ-Insight>`_ .
+
+.. toctree::
+    :maxdepth: 2
+
+    tractometry_pipeline

docs/source/usage/mapping.rst → docs/source/explanations/mapping.rst

@@ -1,13 +1,14 @@
 The pyAFQ Mapping API
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~
+
 pyAFQ has a system for users to specify how to register an image from each
 subject to a given template, called the mapping. The mapping API is similar
 to our Mask API.
 
-In AFQ/definitions/mapping.py, there are four mapping classes one
-can use to specify the mapping. As a user, one should initialize mapping
-classes and pass them to the AFQ.api objects, or write out the initialization as
-a string inside of one's configuration file for use with the CLI.
+In the :mod:`AFQ.definitions.mapping` module, there are four mapping classes
+one can use to specify the mapping. As a user, one should initialize mapping
+classes and pass them to the AFQ.api objects, or write out the initialization
+as a string inside of one's configuration file for use with the CLI.
 
 - :class:`AFQ.definitions.mapping.SynMap`: The default mapping class is to
   use Symmetric Diffeomorphic Image Registration (SyN). This is done with an

docs/source/explanations/modeling.rst

@@ -0,0 +1,21 @@
+.. _modeling:
+
+Modeling White Matter
+=====================
+
+In order to make inferences about white matter tissue properties, we use a
+variety of models. The models are fit to the data in each voxel and the
+parameters of the model are used to interpret the signal.
+
+For an interesting perspective on modeling of tissue properties from diffusion
+MRI data, please refer to a recent paper by Novikov and colleagues
+[Novikov2018]_.
+
+`This page <https://yeatmanlab.github.io/pyAFQ/reference/methods.rst>` includes
+a list of the model parameters that are accessible through the
+:class:`AFQ.api.group.GroupAFQ` and :class:`AFQ.api.participant.ParticipantAFQ`
+objects.
+
+.. [Novikov2018] Novikov DS, Kiselev VG, Jespersen SN. On modeling. Magn Reson
+    Med. 2018 Jun;79(6):3172-3193. doi: 10.1002/mrm.27101. Epub 2018 Mar 1.
+    PMID: 29493816; PMCID: PMC5905348.

docs/source/explanations/profiling.rst

@@ -0,0 +1,4 @@
+.. _profiling:
+
+Profiling
+=========

docs/source/explanations/recognition.rst

@@ -0,0 +1,4 @@
+.. _recognition:
+
+Bundle Recognition
+==================

docs/source/explanations/tractography.rst

@@ -0,0 +1,21 @@
+.. _tractography:
+
+Tractography
+------------
+
+Tractography, or computational tract tracing is the process that generates
+estimates of the trajectories of long-range white matter bundles. For a
+detailed explanation of this process, please refer to a review article by
+Jeurissen et al. [Jeurissen2019]_.
+
+The pyAFQ software implements a simplified programming interface to the myriad
+methods that are implemented in DIPY. Please refer to the detailed
+documentation of the :mod:`AFQ.tractography.tractography` module for details.
+
+
+References
+~~~~~~~~~~~
+
+.. [Jeurissen2019] Jeurissen B, Descoteaux M, Mori S, Leemans A. Diffusion MRI
+    fiber tractography of the brain. NMR Biomed. 2019 Apr;32(4):e3785. doi:
+    10.1002/nbm.3785. Epub 2017 Sep 25. PMID: 28945294.

docs/source/explanations/tractometry_pipeline.rst

@@ -0,0 +1,71 @@
+AFQ Tractometry Pipeline
+~~~~~~~~~~~~~~~~~~~~
+.. include:: <isonum.txt>
+
+.. todo::
+  include tractometry pipeline process flow diagram. create and link detail
+  paged that elaborates on the process and each step within.
+
+.. .. list-table:: AFQ Tractometry Pipeline
+..    :widths: auto
+
+..    * - Tractography
+..      - |rArr| `Registration <http://yeatmanlab.github.io/pyAFQ/autoapi/AFQ/registration/index.html>`_
+..      - |rArr| `Segmentation <http://yeatmanlab.github.io/pyAFQ/autoapi/AFQ/segmentation/index.html>`_
+..      - |rArr| `Cleaning <http://yeatmanlab.github.io/pyAFQ/autoapi/AFQ/segmentation/index.html#AFQ.segmentation.clean_bundles>`_
+..      - |rArr| `Profiling <https://dipy.org/documentation/1.4.0./reference/dipy.stats/#afq-profile>`_
+..      - |rArr| `Visualization <http://yeatmanlab.github.io/pyAFQ/autoapi/AFQ/viz/index.html>`_
+
+.. figure:: _static/tract_tractography.png
+   :figclass: top-image
+   :target: tractography.html
+
+   :ref:`tractography`
+
+.. figure:: _static/right_arrow.png
+   :figclass: right-arrow
+
+.. figure:: _static/tract_modeling.png
+   :figclass: top-image
+   :target: modeling.html
+
+   :ref:`modeling`
+
+.. figure:: _static/right_arrow.png
+   :figclass: right-arrow
+
+.. figure:: _static/tract_recognition.png
+   :figclass: top-image
+   :target: recognition.html
+
+   :ref:`recognition`
+
+.. image:: _static/down_arrow.png
+   :width: 8%
+
+.. figure:: _static/tract_cleaning.png
+   :figclass: bottom-image
+   :target: cleaning.html
+
+   :ref:`cleaning`
+
+.. figure:: _static/left_arrow.png
+   :figclass: left-arrow
+
+.. figure:: _static/tract_profiling.png
+   :figclass: bottom-image
+   :target: profiling.html
+
+   :ref:`profiling`
+
+.. figure:: _static/left_arrow.png
+   :figclass: left-arrow
+
+.. figure:: _static/tract_visualization.png
+   :figclass: bottom-image
+   :target: visualization.html
+
+   :ref:`visualization`
+
+
+

docs/source/explanations/visualization.rst

@@ -0,0 +1,4 @@
+.. _visualization:
+
+Visualization
+=============