docstring improvements and adopted sphinxcontrib-bibtex

docs/conf.py

@@ -21,6 +21,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
+    "sphinxcontrib.bibtex",
     "sphinx_autodoc_typehints",
 ]
 
@@ -48,7 +49,12 @@
 
 myst_heading_anchors = 2
 
-# -- Substitutions -----------------------------------------------------------
+# -- Configure sphinxcontrib-bibtex -------------------------------------------
+
+bibtex_bibfiles = ['references.bib']
+
+
+# -- Substitutions ------------------------------------------------------------
 
 commit_hash = (
     subprocess.check_output(["git", "rev-parse", "--short", "HEAD"])

docs/getting_started/contributing_code/contributing_code.md

@@ -49,24 +49,18 @@ Some relevant conventions in a nutshell:
 
 ### Style Guide for docstrings
 
-Please use [documentation strings](https://docs.python.org/3/tutorial/controlflow.html#documentation-strings) to document modules, classes and functions. There exist several different conventions on how to
-format these docstrings. We will follow the Google style as described in the
+Please use [documentation strings](https://docs.python.org/3/tutorial/controlflow.html#documentation-strings) 
+to document modules, classes and functions. There exist several different conventions on 
+how to dormat these docstrings. We will follow the Google style as described in the
 [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
 
-
-Please add references to the literature if you are implementing a published algorithm.
-
-**Example:**
+**Example 1:**
 ```
     def func(arg1 : int, arg2 : str) -> bool:
         """One sentence description of function.
 
         Some more details on what the function does.
 
-        Reference to related work or source material [1]
-
-        [1] Authors et al., Title, Journal, Year
-
         Args:
             arg1: Description of arg1
             arg2: Description of arg2
@@ -77,6 +71,48 @@ Please add references to the literature if you are implementing a published algo
         return True
 ```
 
+**Example 2:**
+```
+    def func(
+        arg1 : cdt.NDTimeSeries, 
+        arg2 : cdt.NDTimeSeries, 
+        arg3 : Quantity
+    ) -> cdt.NDTimeSeries:
+        """Implements algorithm XY based on :cite:t:`BIBTEXLABEL`.
+
+        Some more details on what the function does.
+        
+        Args:
+            arg1 (:class:`NDTimeSeries`, (channel, wavelength, time)): Description of 
+                first argument. For NDTimeSeries we can specify expect dimensions
+                like this.
+            arg2 (:class:`NDTimeSeries`, (time, *)): Some algorithms work only along
+                a given dimension (e.g. frequency filtering) and are agnostic to any
+                other dimensions in the array. This should be documentated like this.
+            arg3 (:class:`Quantity`, [time]): Parameters with physical units (e.g.
+                lengths or time intervals) should be passed as pint.Quantities. The
+                expected dimensionality could should be documented like this.
+
+        Returns:
+            Description of return value. 
+        """
+        return True
+```
+
+Please add references to the literature if you are implementing a published algorithm.
+There is is a global bibtex file under `docs/references.bib` to which reference entries
+should be added with a unique bibtex label. Refer to a reference entry with 
+with ":cite:t:`BIBTEXLABEL`". Further options are documented in the
+[sphinxcontrib-bibtex documentation](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html#minimal-example).
+
+All references will be listed under [References](../../references.rst).
+
+Additional [docstring sections](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/index.html#docstring-sections)
+may be added, like for example: References, Notes, etc.
+
+
+
+
 ### Where to add my code?
 
 When contributing code to Cedalion (=package), try to incorporate it into the existing file and folder structure, which also defines Cedalions package and subpackages. Python files (=modules) contain functions of the same category; folders (subpackages) contain python files of the same family. Examples:
@@ -136,10 +172,14 @@ from cedalion import Quantity, units
 
 @cdc.validate_schemas
 def function_name(inputVar1: cdt.NDTimeSeries, inputVar2: Quantity):
+    """What this function does.
 
-    """What does this function do?.
+    Args:
+        inputVar1: ...
+        inputVar2: ...
 
-    [1] Authors et al., "title", Journal vol., year, doi:
+    Returns:
+        description of the return value
     """
 
     #
@@ -157,6 +197,14 @@ The function is wrapped by putting `@cdc.validate_schemas`in front, which will c
 The following examples are implemented in the [quality.py module](https://github.com/ibs-lab/cedalion/blob/main/src/cedalion/sigproc/quality.py)
 
 ### The helper functions
+
+```{admonition} Update needed
+:class: attention
+
+The code examples are not up to date. Please refer to the 
+[current source code](https://github.com/ibs-lab/cedalion/blob/main/src/cedalion/sigproc/quality.py)
+```
+
 Now we can create the small helper functions that calculate and check the SNR, Source-Detector Distances and Amplitudes of fNIRS channels. Using the coordinates and units from Xarrays these are effectively implemented:
 
 `def snr_range():`
@@ -169,7 +217,8 @@ def snr_range(amplitudes: cdt.NDTimeSeries, snr_thresh: Quantity):
     INPUTS:
     amplitues:  NDTimeSeries, input fNIRS data xarray with time and channel dimensions.
     snr_thresh:  Quantity, SNR threshold (unitless).
-                If mean(d)/std(d) < SNRthresh then it is excluded as an active channel
+                If meaArgs:
+        inputVar1:n(d)/std(d) < SNRthresh then it is excluded as an active channel
     OUTPUTS:
     snr:        ratio betwean mean and std of the amplitude signal for all channels.
     MeasList:   list of active channels that meet the conditions

docs/index.md

@@ -14,6 +14,7 @@ getting_started/index.md
 data_structures/index.md
 examples/index.md
 api/modules.rst
+references.rst
 ```
 
 This documentation was built from commit {{commit_hash}}.

docs/references.bib

@@ -0,0 +1,41 @@
+@article{Pollonini2014,
+title = {Auditory cortex activation to natural speech and simulated cochlear implant speech measured with functional near-infrared spectroscopy},
+journal = {Hearing Research},
+volume = {309},
+pages = {84-93},
+year = {2014},
+issn = {0378-5955},
+doi = {https://doi.org/10.1016/j.heares.2013.11.007},
+author = {Luca Pollonini and Cristen Olds and Homer Abaya and Heather Bortfeld and Michael S. Beauchamp and John S. Oghalai},
+abstract = {The primary goal of most cochlear implant procedures is to improve a patient's ability to discriminate speech. To accomplish this, cochlear implants are programmed so as to maximize speech understanding. However, programming a cochlear implant can be an iterative, labor-intensive process that takes place over months. In this study, we sought to determine whether functional near-infrared spectroscopy (fNIRS), a non-invasive neuroimaging method which is safe to use repeatedly and for extended periods of time, can provide an objective measure of whether a subject is hearing normal speech or distorted speech. We used a 140 channel fNIRS system to measure activation within the auditory cortex in 19 normal hearing subjects while they listed to speech with different levels of intelligibility. Custom software was developed to analyze the data and compute topographic maps from the measured changes in oxyhemoglobin and deoxyhemoglobin concentration. Normal speech reliably evoked the strongest responses within the auditory cortex. Distorted speech produced less region-specific cortical activation. Environmental sounds were used as a control, and they produced the least cortical activation. These data collected using fNIRS are consistent with the fMRI literature and thus demonstrate the feasibility of using this technique to objectively detect differences in cortical responses to speech of different intelligibility.}
+}
+
+@article{Huppert2009,
+author = {Theodore J. Huppert and Solomon G. Diamond and Maria A. Franceschini and David A. Boas},
+journal = {Appl. Opt.},
+keywords = {Fourier optics and signal processing ; Medical and biological imaging; Spectroscopy; Functional monitoring and imaging ; Absorption coefficient; Brain imaging; Laser sources; Optical absorption; Optical imaging; Tissue optics},
+number = {10},
+pages = {D280--D298},
+publisher = {Optica Publishing Group},
+title = {HomER: a review of time-series analysis methods for near-infrared spectroscopy of the brain},
+volume = {48},
+month = {Apr},
+year = {2009},
+doi = {https://doi.org/10.1364/AO.48.00D280},
+abstract = {Near-infrared spectroscopy (NIRS) is a noninvasive neuroimaging tool for studying evoked hemodynamic changes within the brain. By this technique, changes in the optical absorption of light are recorded over time and are used to estimate the functionally evoked changes in cerebral oxyhemoglobin and deoxyhemoglobin concentrations that result from local cerebral vascular and oxygen metabolic effects during brain activity. Over the past three decades this technology has continued to grow, and today NIRS studies have found many niche applications in the fields of psychology, physiology, and cerebral pathology. The growing popularity of this technique is in part associated with a lower cost and increased portability of NIRS equipment when compared with other imaging modalities, such as functional magnetic resonance imaging and positron emission tomography. With this increasing number of applications, new techniques for the processing, analysis, and interpretation of NIRS data are continually being developed. We review some of the time-series and functional analysis techniques that are currently used in NIRS studies, we describe the practical implementation of various signal processing techniques for removing physiological, instrumental, and motion-artifact noise from optical data, and we discuss the unique aspects of NIRS analysis in comparison with other brain imaging modalities. These methods are described within the context of the MATLAB-based graphical user interface program, HomER, which we have developed and distributed to facilitate the processing of optical functional brain data.},
+url = "https://github.com/BUNPC/Homer3",
+}
+
+@article{Oostenveld2001,
+title = {The five percent electrode system for high-resolution EEG and ERP measurements},
+journal = {Clinical Neurophysiology},
+volume = {112},
+number = {4},
+pages = {713-719},
+year = {2001},
+issn = {1388-2457},
+doi = {https://doi.org/10.1016/S1388-2457(00)00527-7},
+author = {Robert Oostenveld and Peter Praamstra},
+keywords = {Electrode placement, High resolution EEG, High resolution ERP, Nomenclature},
+abstract = {Objective: A system for electrode placement is described. It is designed for studies on topography and source analysis of spontaneous and evoked EEG activity. Method: The proposed system is based on the extended International 10–20 system which contains 74 electrodes, and extends this system up to 345 electrode locations. Results: The positioning and nomenclature of the electrode system is described, and a subset of locations is proposed as especially useful for modern EEG/ERP systems, often having 128 channels available. Conclusion: Similar to the extension of the 10–20 system to the 10–10 system (‘10% system’), proposed in 1985, the goal of this new extension to a 10–5 system is to further promote standardization in high-resolution EEG studies.}
+}

docs/references.rst

@@ -0,0 +1,5 @@
+References
+==========
+
+.. bibliography::
+    :all:

environment_dev.yml

@@ -56,3 +56,4 @@ dependencies:
       - setuptools-scm==7.1.0
       - snirf==0.7.4
       - pmcx
+      - sphinxcontrib-bibtex

src/cedalion/geometry/landmarks.py

@@ -109,10 +109,12 @@ def _intersect_mesh_with_triangle(
 
 
 class LandmarksBuilder1010:
-    """Construct the 10-10-system on a scalp surface.
+    """Construct the 10-10-system on scalp surface based on :cite:t:`Oostenveld2001`.
+
+    Args:
+        scalp_surface: a triangle-mesh representing the scalp
+        landmarks: positions of "Nz", "Iz", "LPA", "RPA"
 
-    [1] R. Oostenveld and P. Praamstra, “The five percent electrode system for
-        high-resolution EEG and ERP measurements,” Clinical Neurophysiology, 2001.
     """
 
     @validate_schemas