Skip to content

Commit

Permalink
Merge pull request #948 from qiqiliang/docsoverhaul
Browse files Browse the repository at this point in the history
Starting doc overhaul
  • Loading branch information
arokem authored Apr 26, 2023
2 parents c1637a8 + f820afa commit 029b496
Show file tree
Hide file tree
Showing 70 changed files with 2,548 additions and 175 deletions.
7 changes: 4 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 30 additions & 0 deletions AFQ/definitions/mapping.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------
Expand Down Expand Up @@ -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())
Expand Down Expand Up @@ -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())
Expand Down Expand Up @@ -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())
Expand Down
68 changes: 67 additions & 1 deletion docs/source/_static/custom.css
Original file line number Diff line number Diff line change
@@ -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;
}
19 changes: 11 additions & 8 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,7 @@
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinx_gallery.gen_gallery',
'sphinx_design',
'sphinx.ext.autosummary',
'autoapi.extension',
'numpydoc',
Expand Down Expand Up @@ -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'
Expand Down Expand Up @@ -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 ---------------------------------------------

Expand Down Expand Up @@ -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),
}
Expand All @@ -232,3 +234,4 @@
autoapi_type = 'python'
autoapi_dirs = ['../../AFQ']
autoapi_ignore = ['*test*', '*_fixes*', '*version*', 'pyAFQ', 'License']
autoapi_root = 'reference/api'
Binary file added docs/source/explanations/_static/down_arrow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/explanations/_static/left_arrow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/explanations/_static/right_arrow.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 4 additions & 0 deletions docs/source/explanations/cleaning.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. _cleaning:

Cleaning
========
29 changes: 29 additions & 0 deletions docs/source/explanations/index.rst
Original file line number Diff line number Diff line change
@@ -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
Original file line number Diff line number Diff line change
@@ -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
Expand Down
21 changes: 21 additions & 0 deletions docs/source/explanations/modeling.rst
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 4 additions & 0 deletions docs/source/explanations/profiling.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. _profiling:

Profiling
=========
4 changes: 4 additions & 0 deletions docs/source/explanations/recognition.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. _recognition:

Bundle Recognition
==================
21 changes: 21 additions & 0 deletions docs/source/explanations/tractography.rst
Original file line number Diff line number Diff line change
@@ -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.
71 changes: 71 additions & 0 deletions docs/source/explanations/tractometry_pipeline.rst
Original file line number Diff line number Diff line change
@@ -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`



4 changes: 4 additions & 0 deletions docs/source/explanations/visualization.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
.. _visualization:

Visualization
=============
Loading

0 comments on commit 029b496

Please sign in to comment.