Merge pull request #111 from NiklasMelton/create-bibtex

Create bibtex and update references

artlib/common/VAT.py

@@ -1,9 +1,8 @@
 """VAT.
 
-Bezdek, J. C., & Hathaway, R. J. (2002).
-VAT: A tool for visual assessment of cluster tendency.
-Proceedings of the 2002 International Joint Conference on Neural Networks.
-doi:10.1109/IJCNN.2002.1007487
+.. # Bezdek, J. C., & Hathaway, R. J. (2002). .. # VAT: A tool for visual assessment of
+cluster tendency. .. # Proceedings of the 2002 International Joint Conference on Neural
+Networks. .. # doi:10.1109/IJCNN.2002.1007487
 
 """
 import numpy as np
@@ -17,6 +16,21 @@ def VAT(
 ) -> Tuple[np.ndarray, np.ndarray]:
     """Visual Assessment of Cluster Tendency (VAT) algorithm.
 
+    VAT was originally designed as a visualization tool for clustering behavior of data.
+    When the VAT-reordered distance matrix is plotted as an image, clusters will appear
+    in visually distinct groups along the diagonal. However, it has since been
+    discovered that the reordering significantly improves the results of order-dependent
+    clustering methods like ART. It is therefore recommended to pre-process data with
+    VAT prior to presentation when possible.
+
+    .. # Bezdek, J. C., & Hathaway, R. J. (2002).
+    .. # VAT: A tool for visual assessment of cluster tendency.
+    .. # Proceedings of the 2002 International Joint Conference on Neural Networks.
+    .. # doi:10.1109/IJCNN.2002.1007487
+
+    .. bibliography:: ../../references.bib
+       :filter: citation_key == "bezdek2002vat"
+
     Parameters
     ----------
     data : np.ndarray

artlib/cvi/iCVIFuzzyArt.py

@@ -1,4 +1,10 @@
-"""TODO: Add Reference in correct format.
+"""iCVI Fuzzy ART
+
+.. # da Silva, Leonardo Enzo Brito, Nagasharath Rayapati, and Donald C. Wunsch.
+.. # "iCVI-ARTMAP: using incremental cluster validity indices and adaptive resonance
+.. # theory reset mechanism to accelerate validation and achieve multiprototype
+.. # unsupervised representations."
+.. # IEEE Transactions on Neural Networks and Learning Systems 34.12 (2022): 9757-9770.
 
 The original matlab code can be found at
 https://github.com/ACIL-Group/iCVI-toolbox/tree/master
@@ -7,6 +13,9 @@
  Pages 314-316 and 319-320 Extended icvi offline mode can be found at
 https://ieeexplore.ieee.org/document/9745260
 
+.. bibliography:: ../../references.bib
+   :filter: citation_key == "da2022icvi"
+
 """
 import numpy as np
 from typing import Optional, Literal, Callable
@@ -15,7 +24,19 @@
 
 
 class iCVIFuzzyART(FuzzyART):
-    """ICVI Fuzzy Art For Clustering."""
+    """ICVI Fuzzy Art For Clustering.
+
+    .. # da Silva, Leonardo Enzo Brito, Nagasharath Rayapati, and Donald C. Wunsch.
+    .. # "iCVI-ARTMAP: using incremental cluster validity indices and adaptive resonance
+    .. # theory reset mechanism to accelerate validation and achieve multiprototype
+    .. # unsupervised representations."
+    .. # IEEE Transactions on Neural Networks and Learning Systems
+    .. # 34.12 (2022): 9757-9770.
+
+    .. bibliography:: ../../references.bib
+       :filter: citation_key == "da2022icvi"
+
+    """
 
     CALINSKIHARABASZ = 1
 

artlib/elementary/ART1.py

@@ -1,10 +1,10 @@
-"""ART1.
+"""ART1 :cite:`carpenter1987massively`."""
 
-Carpenter, G. A., & Grossberg, S. (1987a). A massively parallel architecture for a self-
-organizing neural pattern recognition machine. Computer Vision, Graphics, and Image
-Processing, 37, 54 – 115. doi:10. 1016/S0734-189X(87)80014-2.
-
-"""
+# Carpenter, G. A., & Grossberg, S. (1987a).
+# A massively parallel architecture for a self-organizing neural pattern
+# recognition machine.
+# Computer Vision, Graphics, and Image
+# Processing, 37, 54 – 115. doi:10. 1016/S0734-189X(87)80014-2.
 
 import numpy as np
 from typing import Optional, List, Tuple, Union, Dict
@@ -13,13 +13,18 @@
 
 
 class ART1(BaseART):
-    """ART1 for Clustering.
+    """ART1 for Binary Clustering.
+
+    This module implements ART1 as first published in: :cite:`carpenter1987massively`.
+
+
+    .. # Carpenter, G. A., & Grossberg, S. (1987a).
+    .. # A massively parallel architecture for a self-organizing neural pattern
+    .. # recognition machine.
+    .. # Computer Vision, Graphics, and Image
+    .. # Processing, 37, 54 – 115. doi:10. 1016/S0734-189X(87)80014-2.
 
-    This module implements ART1 as first published in Carpenter, G. A., & Grossberg, S.
-    (1987a). A massively parallel architecture for a self-organizing neural pattern
-    recognition machine. Computer Vision, Graphics, and Image Processing, 37, 54 – 115.
-    doi:10. 1016/S0734-189X(87)80014-2. ART1 is intended for binary data clustering
-    only.
+    ART1 is exclusively for clustering binary data.
 
     """
 

artlib/elementary/ART2.py

@@ -1,21 +1,26 @@
-"""ART2.
+"""ART2 :cite:`carpenter1987art`, :cite:`carpenter1991art`.
 
-Carpenter, G. A., & Grossberg, S. (1987b).
-ART 2: self-organization of stable category recognition codes for analog input patterns.
-Appl. Opt., 26, 4919–4930. doi:10.1364/AO.26.004919.
+::
 
-Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991b).
-ART 2-A: An adaptive resonance algorithm for rapid category learning and recognition.
-Neural Networks, 4, 493 – 504. doi:10.1016/0893-6080(91) 90045-7.
-
-==================================================================
-DISCLAIMER: DO NOT USE ART2!!!
-IT DOES NOT WORK
-It is provided for completeness only.
-Stephan Grossberg himself has said ART2 does not work.
-==================================================================
+    ==================================================================
+    DISCLAIMER: DO NOT USE ART2!!!
+    IT DOES NOT WORK
+    It is provided for completeness only.
+    Stephan Grossberg himself has said ART2 does not work.
+    ==================================================================
 
 """
+
+# Carpenter, G. A., & Grossberg, S. (1987b).
+# ART 2: self-organization of stable category recognition codes for analog input
+# patterns.
+# Appl. Opt., 26, 4919–4930. doi:10.1364/AO.26.004919.
+
+# Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991b).
+# ART 2-A: An adaptive resonance algorithm for rapid category learning and
+# recognition.
+# Neural Networks, 4, 493 – 504. doi:10.1016/0893-6080(91) 90045-7.
+
 import numpy as np
 from typing import Optional, List
 from warnings import warn
@@ -25,14 +30,24 @@
 class ART2A(BaseART):
     """ART2-A for Clustering.
 
-    This module implements ART2-A as first published in
-    Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991b).
-    ART 2-A: An adaptive resonance algorithm for rapid category learning and
-    recognition.
-    Neural Networks, 4, 493 – 504. doi:10.1016/0893-6080(91) 90045-7.
+    This module implements ART2-A as first published in:
+    :cite:`carpenter1987art`, :cite:`carpenter1991art`
+
+
+    .. # Carpenter, G. A., & Grossberg, S. (1987b).
+    .. # ART 2: self-organization of stable category recognition codes for analog input
+    .. # patterns.
+    .. # Appl. Opt., 26, 4919–4930. doi:10.1364/AO.26.004919.
+
+    .. # Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991b).
+    .. # ART 2-A: An adaptive resonance algorithm for rapid category learning and
+    .. # recognition.
+    .. # Neural Networks, 4, 493 – 504. doi:10.1016/0893-6080(91) 90045-7.
+
 
-    ART2-A is similar to ART1 but designed for analog data. This method is implemented
-    for historical purposes and is not recommended for use.
+    ART2-A is similar to :class:`~artlib.elementary.ART1.ART1` but designed for analog
+    data. This method is implemented for historical purposes and is not recommended
+    for use.
 
     """
 

artlib/elementary/BayesianART.py

@@ -1,9 +1,9 @@
-"""Bayesian ART.
+"""Bayesian ART :cite:`vigdor2007bayesian`."""
+# Vigdor, B., & Lerner, B. (2007).
+# The Bayesian ARTMAP.
+# IEEE Transactions on Neural
+# Networks, 18, 1628–1644. doi:10.1109/TNN.2007.900234.
 
-Vigdor, B., & Lerner, B. (2007). The Bayesian ARTMAP. IEEE Transactions on Neural
-Networks, 18, 1628–1644. doi:10.1109/TNN.2007.900234.
-
-"""
 import numpy as np
 from typing import Optional, Iterable, List, Callable, Literal, Tuple, Union, Dict
 import operator
@@ -15,11 +15,17 @@
 class BayesianART(BaseART):
     """Bayesian ART for Clustering.
 
-    This module implements Bayesian ART as first published in Vigdor, B., & Lerner, B.
-    (2007). The Bayesian ARTMAP. IEEE Transactions on Neural Networks, 18, 1628–1644.
-    doi:10.1109/TNN.2007.900234. Bayesian ART clusters data in Bayesian Distributions
-    (Hyper-ellipsoids) and is similar to Gaussian ART but differs in that it allows
-    arbitrary rotation of the hyper-ellipsoid.
+    This module implements Bayesian ART as first published in:
+    :cite:`vigdor2007bayesian`.
+
+     .. # Vigdor, B., & Lerner, B. (2007).
+    .. # The Bayesian ARTMAP.
+    .. # IEEE Transactions on Neural
+    .. # Networks, 18, 1628–1644. doi:10.1109/TNN.2007.900234.
+
+    Bayesian ART clusters data in Bayesian Distributions (Hyper-ellipsoids) and is
+    similar to :class:`~artlib.elementary.GaussianART.GaussianART` but differs in that
+    it allows arbitrary rotation of the hyper-ellipsoid.
 
     """
 

artlib/elementary/EllipsoidART.py

@@ -1,15 +1,14 @@
-"""Ellipsoid ART.
+"""Ellipsoid ART :cite:`anagnostopoulos2001a`, :cite:`anagnostopoulos2001b`."""
+# Anagnostopoulos, G. C., & Georgiopoulos, M. (2001a).
+# Ellipsoid ART and ARTMAP for incremental clustering and classification.
+# In Proc. IEEE International Joint Conference on Neural Networks (IJCNN)
+# (pp. 1221–1226). volume 2. doi:10.1109/IJCNN.2001.939535.
 
-Anagnostopoulos, G. C., & Georgiopoulos, M. (2001a). Ellipsoid ART and ARTMAP for
-incremental clustering and classification. In Proc. IEEE International Joint Conference
-on Neural Networks (IJCNN) (pp. 1221–1226). volume 2. doi:10.1109/IJCNN.2001.939535.
+# Anagnostopoulos, G. C., & Georgiopoulos, M. (2001b).
+# Ellipsoid ART and ARTMAP for incremental unsupervised and supervised learning.
+# In Aerospace/Defense Sensing, Simulation, and Controls (pp. 293– 304).
+# International Society for Optics and Photonics. doi:10.1117/12.421180.
 
-Anagnostopoulos, G. C., & Georgiopoulos, M. (2001b). Ellipsoid ART and ARTMAP for
-incremental unsupervised and supervised learning. In Aerospace/Defense Sensing,
-Simulation, and Controls (pp. 293– 304). International Society for Optics and Photonics.
-doi:10.1117/12.421180.
-
-"""
 import numpy as np
 from typing import Optional, List, Tuple, Union, Dict
 from matplotlib.axes import Axes
@@ -20,12 +19,22 @@
 class EllipsoidART(BaseART):
     """Ellipsoid ART for Clustering.
 
-    This module implements Ellipsoid ART as first published in Anagnostopoulos, G. C., &
-    Georgiopoulos, M. (2001a). Ellipsoid ART and ARTMAP for incremental clustering and
-    classification. In Proc. IEEE International Joint Conference on Neural Networks
-    (IJCNN) (pp. 1221–1226). volume 2. doi:10.1109/IJCNN.2001.939535. Ellipsoid ART
-    clusters data in Hyper-ellipsoids. It is highly sensitive to sample presentation
-    order as the second sample will determine the orientation of the principal axes.
+    This module implements Ellipsoid ART as first published in:
+    :cite:`anagnostopoulos2001a`, :cite:`anagnostopoulos2001b`.
+
+    .. # Anagnostopoulos, G. C., & Georgiopoulos, M. (2001a).
+    .. # Ellipsoid ART and ARTMAP for incremental clustering and classification.
+    .. # In Proc. IEEE International Joint Conference on Neural Networks (IJCNN)
+    .. # (pp. 1221–1226). volume 2. doi:10.1109/IJCNN.2001.939535.
+
+    .. # Anagnostopoulos, G. C., & Georgiopoulos, M. (2001b).
+    .. # Ellipsoid ART and ARTMAP for incremental unsupervised and supervised learning.
+    .. # In Aerospace/Defense Sensing, Simulation, and Controls (pp. 293– 304).
+    .. # International Society for Optics and Photonics. doi:10.1117/12.421180.
+
+    Ellipsoid ART clusters data in Hyper-ellipsoids. It is highly sensitive to sample
+    presentation order as the second sample will determine the orientation of the
+    principal axes.
 
     """
 

artlib/elementary/FuzzyART.py

@@ -1,11 +1,9 @@
-"""Fuzzy ART.
+"""Fuzzy ART :cite:`carpenter1991fuzzy`."""
+# Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991c).
+# Fuzzy ART: Fast stable learning and categorization of analog patterns by an
+# adaptive resonance system.
+# Neural Networks, 4, 759 – 771. doi:10.1016/0893-6080(91)90056-B.
 
-Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991c).
-Fuzzy ART: Fast stable learning and categorization of analog patterns by an adaptive
-resonance system.
-Neural Networks, 4, 759 – 771. doi:10.1016/0893-6080(91)90056-B.
-
-"""
 import numpy as np
 from typing import Optional, Iterable, List, Tuple, Union, Dict
 from matplotlib.axes import Axes
@@ -58,13 +56,16 @@ def get_bounding_box(
 class FuzzyART(BaseART):
     """Fuzzy ART for Clustering.
 
-    This module implements Fuzzy ART as first published in
-    Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991c).
-    Fuzzy ART: Fast stable learning and categorization of analog patterns by an
-    adaptive resonance system.
-    Neural Networks, 4, 759 – 771. doi:10.1016/0893-6080(91)90056-B.
+    This module implements Fuzzy ART as first published in:
+    :cite:`carpenter1991fuzzy`.
+
+    .. # Carpenter, G. A., Grossberg, S., & Rosen, D. B. (1991c).
+    .. # Fuzzy ART: Fast stable learning and categorization of analog patterns by an
+    .. # adaptive resonance system.
+    .. # Neural Networks, 4, 759 – 771. doi:10.1016/0893-6080(91)90056-B.
 
-    Fuzzy ART is a hyper-box based clustering method.
+    Fuzzy ART is a hyper-box based clustering method that is exceptionally fast and
+    explainable.
 
     """
 

artlib/elementary/GaussianART.py

@@ -1,11 +1,8 @@
-"""Gaussian ART.
-
-Williamson, J. R. (1996).
-Gaussian ARTMAP: A Neural Network for Fast Incremental Learning of Noisy
-Multidimensional Maps.
-Neural Networks, 9, 881 – 897. doi:10.1016/0893-6080(95)00115-8.
-
-"""
+"""Gaussian ART :cite:`williamson1996gaussian`."""
+# Williamson, J. R. (1996).
+# Gaussian ARTMAP: A Neural Network for Fast Incremental Learning of Noisy
+# Multidimensional Maps.
+# Neural Networks, 9, 881 – 897. doi:10.1016/0893-6080(95)00115-8.
 
 import numpy as np
 from typing import Optional, Iterable, List, Tuple, Union, Dict
@@ -17,15 +14,18 @@
 class GaussianART(BaseART):
     """Gaussian ART for Clustering.
 
-    This module implements Gaussian ART as first published in
-    Williamson, J. R. (1996).
-    Gaussian ARTMAP: A Neural Network for Fast Incremental Learning of
-    Noisy Multidimensional Maps.
-    Neural Networks, 9, 881 – 897. doi:10.1016/0893-6080(95)00115-8.
+    This module implements Gaussian ART as first published in:
+    :cite:`williamson1996gaussian`.
+
+    .. # Williamson, J. R. (1996).
+    .. # Gaussian ARTMAP: A Neural Network for Fast Incremental Learning of Noisy
+    .. # Multidimensional Maps.
+    .. # Neural Networks, 9, 881 – 897. doi:10.1016/0893-6080(95)00115-8.
 
     Guassian ART clusters data in Gaussian Distributions (Hyper-ellipsoids) and is
-    similar to Bayesian ART but differs in that the hyper-ellipsoid always have their
-    principal axes square to the coordinate frame. It is also faster than Bayesian ART.
+    similar to :class:`~artlib.elementary.BayesianART.BayesianART` but differs in that
+    the hyper-ellipsoid always have their principal axes square to the coordinate
+    frame. It is also faster than :class:`~artlib.elementary.BayesianART.BayesianART`.
 
     """