Merge pull request #238 from FCP-INDI/docs/CIFTI-atlases

📚 Document lack of support for CIFTI atlases

Author: sgiavasis

.circleci/config.yml

@@ -15,7 +15,7 @@ commands:
           command: |
             sudo apt-get update && sudo apt-get -y install git python3-dev graphviz graphviz-dev libgraphviz-dev pkg-config python3-sphinx
             pip install --user -r https://raw.githubusercontent.com/FCP-INDI/C-PAC/<< parameters.version >>/requirements.txt
-            pip install --user git+https://github.com/${CIRCLE_PROJECT_USERNAME}/C-PAC.git@<< parameters.version >> sphinx m2r numpydoc PyGithub sphinxcontrib-fulltoc sphinxcontrib-programoutput semver torch
+            pip install --user git+https://github.com/${CIRCLE_PROJECT_USERNAME}/C-PAC.git@<< parameters.version >> sphinx m2r numpydoc PyGithub sphinxcontrib-bibtex sphinxcontrib-fulltoc sphinxcontrib-programoutput semver torch
             git clone https://github.com/${CIRCLE_PROJECT_USERNAME}/C-PAC.git /home/circleci/build/C-PAC
             cd /home/circleci/build/C-PAC
             git checkout << parameters.version >>
@@ -114,7 +114,6 @@ jobs:
           command: ./bin/build nightly
       - store-commit-message
       - persist-new-build
-
   build-version:
     working_directory: /home/circleci/build
     docker:
@@ -131,7 +130,6 @@ jobs:
           command: ./bin/build ${BUILD_VERSION}
       - store-commit-message
       - persist-new-build
-
   deploy-nightly:
     working_directory: /home/circleci/
     docker:
@@ -141,7 +139,6 @@ jobs:
           at: /home/circleci/
       - prep-deploy
       - deploy
-
   deploy-version:
     working_directory: /home/circleci/
     docker:

CONTRIBUTING.md

@@ -64,6 +64,56 @@ where `{width}` and `{height}` are the values already present in the existing `w
     <object data="../_static/path/to/chart.svg" type="image/svg+xml"></object>
 ```
 
+## References and citations
+
+[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/) is installed and configured. This extension creates links between the citations and the reference in the reference list and formats citations in referenced BibTeX files using built-in or [custom styles](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references/style.py). To use this Sphinx extension, 
+
+1. Include your citations in a BibTeX file (see the `*.bib` files in [docs/_sources/references](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references) for examples).
+2. Using the key (the text between the opening `{` and the first `,` in a BibTeX entry) use the ReStructuredText syntax `` :cite:`key` `` to cite your reference in a ReStructuredText file.
+3. Include a `.. bibliography::` directive somewhere on any page that you want to use this extension to format references and create two-way links between the references and citations. Specify the (one) BibTeX file for this reference list any formatting for the reference list in this directive. Both `:cite:` and `.. bibliography::` need to be rendered on the same page for the links to generate.
+4. If you will (or might) use more than one `.. bibliography::` directive on a single rendered page (including `.. include::` directives), choose a prefix for the keys and include that prefix in both the `:cite:` role (like `` :cite:`prefix-key` ``) and the bibliography directive (like `:keyprefix: prefix-`).
+5. If you want to include a header over a reference list, use the `.. rubric::` directive above its `.. bibliography` directive.
+6. If the entry type (e.g., `book`, `article`, `misc`) of any of the entries in your BibTeX file(s) is not included in [docs/_sources/references/style.py](https://github.com/FCP-INDI/fcp-indi.github.com/blob/source/docs/_sources/references/style.py), add a `get_{entry_type}_template` [Pybtex](https://pybtex.org) method to `CPAC_DocsStyle`.
+
+For example, if you have a BibTeX file called `cpac_citation.bib` that contains
+
+```BibTeX
+@ARTICLE{cpac2013,
+    AUTHOR={Craddock, Cameron  and  Sikka, Sharad  and  Cheung, Brian  and  Khanuja, Ranjeet  and  Ghosh, Satrajit S
+        and Yan, Chaogan  and  Li, Qingyang  and  Lurie, Daniel  and  Vogelstein, Joshua  and  Burns, Randal  and
+        Colcombe, Stanley  and  Mennes, Maarten  and  Kelly, Clare  and  Di Martino, Adriana  and  Castellanos,
+        Francisco Xavier  and  Milham, Michael},
+    TITLE={Towards Automated Analysis of Connectomes: The {Configurable Pipeline for the Analysis of Connectomes (C-PAC)}},
+    JOURNAL={Frontiers in Neuroinformatics},
+    YEAR={2013},
+    NUMBER={42},
+    URL={http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full},
+    DOI={10.3389/conf.fninf.2013.09.00042},
+    ISSN={1662-5196}
+}
+```
+
+If you include
+
+```rst
+To cite C-PAC, use :cite:`cite-cpac2013`.
+
+.. rubric Cite C-PAC
+
+.. bibliography:: cpac_citation.bib
+   :style: cpac_docs_style
+   :cited:
+   :keyprefix: cite-
+```
+
+The rendered file should look something like
+
+> To cite C-PAC, use <a name="backref1" href="#ref1">[1]</a>.
+> 
+> __Cite C-PAC__
+> 
+> <a name="ref1" href="#backref1">[1]</a> Craddock, C., Sikka, S., Cheung, B., Khanuja, R., Ghosh, S. S., Yan, C., Li, Q., Lurie, D., Vogelstein, J., Burns, R., Colcombe, S., Mennes, M., Kelly, C., Di Martino, A., Castellanos, F. X., and Milham, M. 2013. [Towards automated analysis of connectomes: the Configurable Pipeline for the Analysis of Connectomes (C-PAC).](http://www.frontiersin.org/neuroinformatics/10.3389/conf.fninf.2013.09.00042/full) *Frontiers in neuroinformatics* 42. doi:[10.3389/conf.fninf.2013.09.00042](https://dx.doi.org/10.3389/conf.fninf.2013.09.00042)
+
 ## Environment notes
 * Because [C-PAC](https://github.com/FCP-INDI/C-PAC.git) and [cpac](https://github.com/FCP-INDI/cpac.git) have conflicting commandline commands, we first run any `cpac` commands in a virtual environment and spoof the `command-output` directive with `code-block` like 
    ```RST

docs/_sources/_static/custom.css

@@ -8,4 +8,16 @@ div.flowchart-container {
 
 object {
     max-width: 100%;
-}
+}
+
+
+.bibtex .brackets::before {
+  content: "[";
+}
+.bibtex .brackets::after {
+  content: "]"
+}
+
+.bibtex.label {
+  display: grid;
+}

docs/_sources/conf.py

@@ -23,6 +23,13 @@
 from github import Github
 from github.GithubException import RateLimitExceededException, \
     UnknownObjectException
+from pybtex.plugin import register_plugin
+
+sys.path.append(os.path.dirname(__file__))
+
+from references import CPAC_DocsStyle
+
+register_plugin('pybtex.style.formatting', 'cpac_docs_style', CPAC_DocsStyle)
 
 # "Dealing with Invalid Versions" from
 # https://python-semver.readthedocs.io/en/latest/usage.html
@@ -110,6 +117,7 @@ def compare_versions(new, old):
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinxcontrib.bibtex',
     'sphinxcontrib.fulltoc',
     'sphinx.ext.ifconfig',
     'sphinx.ext.intersphinx',

docs/_sources/developer/atlas_support.rst

@@ -0,0 +1,10 @@
+Currently C-PAC only supports atlases in NifTI format.
+
+CIFTI is a popular atlas format not yet supported by C-PAC. As always, if anyone wants to share any tips or hacks with us, we are an open-source platform after all. Below are some resources that might help enable CIFTI atlas support in a future version of C-PAC.
+
+.. rubric:: CIFTI Resources
+
+.. bibliography:: /references/cifti.bib
+   :all:
+   :list: bullet
+   :style: cpac_docs_style

docs/_sources/glossary/atlas.rst

@@ -0,0 +1,10 @@
+Atlas
+`````
+
+    An *atlas* provides a guide to the location of anatomical features in a coordinate space.
+
+    -- :cite:`glossary-PoMN11` p. 55
+
+An atlas provides a defined coordinate space, a :doc:`template </glossary/template>` for aligning images, and labels for regions of interest.
+
+.. include:: /developer/atlas_support.rst

docs/_sources/glossary/template.rst

@@ -0,0 +1,6 @@
+Template
+````````
+
+    A *template* is an image that is representative of the :doc:`atlas </glossary/atlas>` and provides a target to which individual images can be aligned.
+
+    -- :cite:`glossary-PoMN11` p. 55

docs/_sources/references/__init__.py

@@ -0,0 +1,3 @@
+from .style import CPAC_DocsStyle
+
+__all__ = ['CPAC_DocsStyle']

docs/_sources/references/cifti.bib

@@ -0,0 +1,32 @@
+@misc{Meji15,
+	title = {A layman’s guide to working with {CIFTI} files},
+	url = {https://mandymejia.com/2015/08/10/a-laymans-guide-to-working-with-cifti-files/},
+	language = {en},
+	urldate = {2020-08-26},
+	journal = {{Mandy Mejia}},
+	author = {Mejia, Mandy},
+	month = aug,
+	year = {2015}
+}
+
+@misc{Habe18,
+	title = {Convert from {CIFTI2} ({HCP}) to {3D} array},
+	url = {https://neurostars.org/t/convert-from-cifti2-hcp-to-3d-array/3054},
+	language = {en-US},
+	urldate = {2020-08-26},
+	journal = {Neurostars},
+	author = {Habeeb, Haroun},
+	collaborator = {Etzel, Jo and Rokem, Ariel},
+	month = dec,
+	year = {2018}
+}
+
+@misc{Etze14,
+	title = {{NIfTI}, {CIFTI}, {GIFTI} in the {HCP} and {Workbench}: a primer},
+	shorttitle = {{MVPA} {Meanderings}},
+	url = {http://mvpa.blogspot.com/2014/03/nifti-cifti-gifti-in-hcp-and-workbench.html},
+	journal = {{MVPA} Meanderings},
+	author = {Etzel, Jo},
+	month = mar,
+	year = {2014}
+}

docs/_sources/references/glossary.bib

@@ -0,0 +1,11 @@
+@book{PoMN11,
+	address = {New York},
+	title = {Handbook of {Functional} {MRI} {Data} {Analysis}},
+	isbn = {978-0-521-51766-9},
+	abstract = {Functional magnetic resonance imaging (fMRI) has become the most popular method for imaging brain function. Handbook for Functional MRI Data Analysis provides a comprehensive and practical introduction to the methods used for fMRI data analysis. Using minimal jargon, this book explains the concepts behind processing fMRI data, focusing on the techniques that are most commonly used in the field. This book provides background about the methods employed by common data analysis packages including FSL, SPM, and AFNI. Some of the newest cutting-edge techniques, including pattern classification analysis, connectivity modeling, and resting state network analysis, are also discussed. Readers of this book, whether newcomers to the field or experienced researchers, will obtain a deep and effective knowledge of how to employ fMRI analysis to ask scientific questions and become more sophisticated users of fMRI analysis software.},
+	language = {English},
+	publisher = {Cambridge University Press},
+	author = {Poldrack, Russell A. and Mumford, Jeanette A. and Nichols, Thomas E.},
+	month = aug,
+	year = {2011}
+}