Add glossary.

docs/about.rst

@@ -11,6 +11,7 @@ Because of its ease of use, a wide array of preprocessing and analysis tools and
 pipelines have been developed specifically to operate on data curated in BIDS [#f2]_.
 These tools are able to automatically self-configure to the user's BIDS dataset,
 which saves time and effort on the part of the user.
+
 However, as datasets increase in size and complexity,
 it can be dangerous to blindly run these pipelines without a careful understanding of
 what's really in your BIDS data.
@@ -20,7 +21,7 @@ avoid running **unwanted or unusable data**,
 and **budget their computational time and resources** effectively.
 
 ``CuBIDS`` is designed to facilitate the curation of large,
-neuroimaging data so that users can infer useful information from descriptive and
+neuroimaging datasets so that users can infer useful information from descriptive and
 accurate BIDS labels before running pipelines *en masse*.
 ``CuBIDS`` accomplishes this by summarizing BIDS data using :ref:`keygroup`,
 :ref:`paramgroup`, and :ref:`acquisitiongroup` categorizations in your data
@@ -35,43 +36,13 @@ The image below demonstrates the ``CuBIDS`` workflow that we'll discuss on the n
 enhancing reproducibility, and supporting collaboration [#f3]_.
 
 
-Definitions
------------
-
-.. topic:: Key Group
-
-    *   A set of scans whose filenames share all
-        `BIDS filename key-value pairs <https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#file-name-structure>`_,
-        excluding subject and session
-    *   Derived from the BIDS Filename
-    *   Example structure: ``acquisition-*_datatype-*_run-*_task-*_suffix``
-
-.. topic:: Parameter (Param) Group
-
-    *   The set of scans with identical metadata parameters in their sidecars
-    *   Defined within a Key Group
-    *   Numerically identified (each Key Group will have n Param Groups,
-        where n is the number of unique sets of scanning parameters present in that Key Group.
-        e.g. 1, 2, etc.)
-
-.. topic:: Dominant Group
-
-    *   The Param Group that contains the most scans in its Key Group
-
-.. topic:: Variant Group
-
-    *   Any Param Group that is non-dominant
-
-.. topic:: Rename Key Group
-
-    *   Auto-generated, recommended new Key Group name for Variant Groups
-    *   Based on the metadata parameters that cause scans in Variant Groups to vary from those
-        in their respective Dominant Groups
-
-.. topic:: Acquisition Group
+What CuBIDS Is Not
+------------------
 
-    *   A collection of sessions across participants that contains the exact same set of Key
-        and Param Groups
+``CuBIDS`` is not designed to convert raw data into BIDS format.
+For that, we recommend using `conversion tools <https://bids.neuroimaging.io/benefits.html#converters>`_.
+``CuBIDS`` then takes over once you have a valid BIDS dataset,
+prior to running any preprocessing or analysis pipelines, or to sharing the dataset.
 
 
 Examples
@@ -81,7 +52,7 @@ Dominant Group resting state BOLD:
 
     *   Example Filename: ``sub-01_ses-A_task-rest_acq-singleband_bold.nii.gz``
     *   Key Group: ``acquisition-singleband_datatype-func_suffix-bold_task-rest``
-    *   Param Group: ``1`` (Dominaint Group)
+    *   Param Group: ``1`` (Dominant Group)
 
 Variant Group resting state BOLD (all scans in this Param Group are missing a fieldmap)
 

docs/conf.py

@@ -39,6 +39,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "hoverxref.extension",
     "nbsphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
@@ -181,3 +182,16 @@
 
 # -- Fix automodule config
 add_module_names = False
+
+# --
+# hoverxref
+# --
+hoverxref_auto_ref = True
+hoverxref_mathjax = True
+hoverxref_roles = [
+    "numref",
+    "confval",
+    "setting",
+    "term",
+    "footcite",
+]

docs/glossary.rst

@@ -0,0 +1,37 @@
+.. include:: links.rst
+
+.. glossary::
+
+    Key Group
+        A set of scans whose filenames share all `BIDS filename key-value pairs`_,
+        excluding subject and session.
+        The key group is derived from the common BIDS filename elements.
+        For example, ``acquisition-*_datatype-*_run-*_task-*_suffix``.
+
+    Parameter Group
+        A set of scans with identical metadata parameters in their sidecars.
+        Defined within a Key Group.
+        Numerically identified, meaning that each Key Group will have *n* Param Groups,
+        where *n* is the number of unique sets of scanning parameters present in that Key Group
+        (e.g., 1, 2, etc.).
+
+    Dominant Group
+        The Param Group that contains the most scans in its Key Group.
+
+    Variant Group
+        Any Param Group that is non-dominant.
+
+    Rename Key Group
+        Auto-generated, recommended new Key Group name for Variant Groups.
+        Based on the metadata parameters that cause scans in Variant Groups to vary from those
+        in their respective Dominant Groups.
+
+    Acquisition Group
+        A collection of sessions across participants that contains the exact same set of Key
+        and Param Groups.
+
+
+References
+==========
+
+.. footbibliography::

docs/links.rst

@@ -0,0 +1 @@
+.. _`BIDS filename key-value pairs`: https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#file-name-key-value-pairs

docs/usage.rst

@@ -15,8 +15,8 @@ More definitions
 Key Group
 ~~~~~~~~~
 
-A *Key Group* is a unique set of BIDS key-value pairs, excluding identifiers such as
-subject and session.
+A :term:`Key Group`` is a unique set of BIDS key-value pairs,
+excluding identifiers such as subject and session.
 For example, the files::
 
     bids-root/sub-1/ses-1/func/sub-1_ses-1_acq-mb_dir-PA_task-rest_bold.nii.gz
@@ -42,6 +42,9 @@ The subsets of consistent acquisition parameter sets within a Key Group are call
 Parameter Group
 ~~~~~~~~~~~~~~~
 
+A :term:`Parameter Group` is a subset of a Key Group that contains images with the same
+acquisition parameters.
+
 Even though two images may belong to the same Key Group and are valid BIDS,
 they may have images with different acquisition parameters.
 There is nothing fundamentally wrong with this —
@@ -57,8 +60,8 @@ same preprocessing pipelines to configure differently to images of the same Key
 Acquisition Group
 ~~~~~~~~~~~~~~~~~
 
-We define an “Acquisition Group” as a collection of sessions across participants that contain the exact
-same set of Key and Parameter Groups.
+We define an :term:`Acquisition Group` as a collection of sessions across participants that
+contain the exact same set of Key and Parameter Groups.
 Since Key Groups are based on the BIDS filenames—
 and therefore both MRI image type and acquisition specific—
 each BIDS session directory contains images that belong to a set of Parameter Groups.
@@ -170,10 +173,11 @@ pass that edited tsv as an argument to ``cubids apply``.
 Detecting Variant Groups
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Additionally, ``cubids apply`` can automatically rename files in ``Variant Groups``
-based on their scanning parameters that vary from those in their Key Groups' Dominant Parameter Groups.
+Additionally, ``cubids apply`` can automatically rename files in :term:`Variant Groups <Variant Group>`
+based on their scanning parameters that vary from those in their Key Groups'
+:term:`Dominant Parameter Groups <Dominant Group>`.
 Renaming is automatically suggested when the summary.tsv is generated from a ``cubids group`` run,
-with the suggested new name listed in the tsv's “Rename Key Group” column.
+with the suggested new name listed in the tsv's :term:`Rename Key Group` column.
 CuBIDS populates this column for all Variant Groups
 (e.g., every Parameter Group except the Dominant one).
 Specifically, CuBIDS will suggest renaming all non-dominant Parameter Group to include ``VARIANT*``

pyproject.toml

@@ -47,6 +47,7 @@ doc = [
     "sphinx >= 2.2",
     "sphinx-argparse",
     "sphinx_gallery",
+    "sphinx-hoverxref",
     "sphinx_markdown_tables",
     "sphinx_rtd_theme",
 ]