📚 Document lack of support for CIFTI atlases

Author: shnizzedy

.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:

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}
+}

docs/_sources/references/style.py

@@ -0,0 +1,56 @@
+from pybtex.style.formatting import toplevel
+from pybtex.style.formatting.plain import Style
+from pybtex.style.names.lastfirst import NameStyle as LastFirst
+from pybtex.style.sorting.none import SortingStyle as NoSort
+from pybtex.style.template import field, href, join, optional, \
+                                  optional_field, sentence, tag, words
+
+date = words[field('year'), optional_field('month')]
+
+
+class CPAC_DocsStyle(Style):
+    def __init__(self, *args, **kwargs):
+        super().__init__(
+            abbreviate_names=True,
+            name_style=LastFirst,
+            sorting_style=NoSort
+        )
+
+    def get_book_template(self, entry):
+        template = toplevel[optional[
+            sentence[self.format_names('author')]],
+            optional[sentence[date]],
+            optional[sentence[href[
+                field('url'),
+                optional[tag('em')[self.format_title(entry, 'title')]]
+            ]]] if entry.fields.get('url') else optional[sentence[
+                tag('em')[self.format_title(entry, 'title')]
+            ]],
+            optional[sentence[
+                join(sep=': ')[
+                    optional_field('address'),
+                    optional_field('publisher')
+                ],
+            ]],
+            sentence[optional_field('note')],
+        ]
+        return template
+
+    def get_misc_template(self, entry):
+        template = toplevel[
+            optional[sentence[self.format_names('author')]],
+            optional[sentence[
+                optional[field('howpublished')],
+                optional[date],
+            ]],
+            optional[sentence[join(sep=', ')[href[
+                optional_field('url'),
+                optional[self.format_title(entry, 'title', as_sentence=False)]]
+                if entry.fields.get('url') else optional[
+                    self.format_title(entry, 'title')
+                ],
+                optional[tag('em')[self.format_title(entry, 'journal')]],
+            ]]],
+            sentence[optional_field('note')],
+        ]
+        return template