From 9d032ca858646f985de27c16d9acc62ac1f51c92 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Tue, 29 Aug 2023 14:19:22 +0200
Subject: Improving gaze analysis modules documentation.

---
 src/argaze/GazeAnalysis/Basic.py                   | 12 +++++++---
 src/argaze/GazeAnalysis/DeviationCircleCoverage.py |  7 +++---
 .../DispersionThresholdIdentification.py           | 14 ++++++-----
 src/argaze/GazeAnalysis/Entropy.py                 | 20 ++++++++--------
 src/argaze/GazeAnalysis/ExploitExploreRatio.py     | 28 +++++++++++-----------
 src/argaze/GazeAnalysis/FocusPointInside.py        |  3 ++-
 src/argaze/GazeAnalysis/KCoefficient.py            |  6 +++--
 src/argaze/GazeAnalysis/LempelZivComplexity.py     | 16 ++++++++-----
 src/argaze/GazeAnalysis/NGram.py                   | 21 ++++++++--------
 src/argaze/GazeAnalysis/NearestNeighborIndex.py    | 19 +++++++--------
 src/argaze/GazeAnalysis/TransitionMatrix.py        | 16 ++++++++-----
 .../VelocityThresholdIdentification.py             | 16 ++++---------
 12 files changed, 96 insertions(+), 82 deletions(-)

diff --git a/src/argaze/GazeAnalysis/Basic.py b/src/argaze/GazeAnalysis/Basic.py
index c57b447..7b41731 100644
--- a/src/argaze/GazeAnalysis/Basic.py
+++ b/src/argaze/GazeAnalysis/Basic.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of basic analysis.
+"""Basic analysis module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -16,7 +16,7 @@ import numpy
 
 @dataclass
 class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
-    """"""
+    """Basic scan path analysis."""
 
     def __post_init__(self):
 
@@ -43,22 +43,25 @@ class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
 
     @property
     def path_duration(self) -> float:
+        """Scan path duration."""
 
         return self.__path_duration
 
     @property
     def steps_number(self) -> float:
+        """Scan path steps number."""
 
         return self.__steps_number
 
     @property
     def step_fixation_durations_average(self) -> float:
+        """Scan path step fixation durations average."""
 
         return self.__step_fixation_durations_average
     
 @dataclass
 class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
-    """"""
+    """Basic AOI scan path analysis."""
 
     def __post_init__(self):
 
@@ -85,15 +88,18 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
         
     @property
     def path_duration(self) -> float:
+        """AOI scan path duration."""
 
         return self.__path_duration
 
     @property
     def steps_number(self) -> float:
+        """AOI scan path steps number."""
 
         return self.__steps_number
 
     @property
     def step_fixation_durations_average(self) -> float:
+        """AOI scan path step fixation durations average."""
 
         return self.__step_fixation_durations_average
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/DeviationCircleCoverage.py b/src/argaze/GazeAnalysis/DeviationCircleCoverage.py
index 8e7acef..bde486d 100644
--- a/src/argaze/GazeAnalysis/DeviationCircleCoverage.py
+++ b/src/argaze/GazeAnalysis/DeviationCircleCoverage.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-"""Matching algorithm based on fixation's deviation circle coverage over AOI
+"""Module for matching algorithm based on fixation's deviation circle coverage over AOI.
 """
 
 __author__ = "Théo de la Hogue"
@@ -22,9 +22,10 @@ GazeMovementType = TypeVar('GazeMovement', bound="GazeMovement")
 
 @dataclass
 class AOIMatcher(GazeFeatures.AOIMatcher):
+    """Matching algorithm based on fixation's deviation circle coverage over AOI."""
 
-    coverage_threshold: int|float
-    """ """
+    coverage_threshold: float
+    """Minimal coverage ratio to consider a fixation over an AOI (1 means that whole fixation's deviation circle have to be over the AOI)."""
 
     def __post_init__(self):
         """Init looked aoi data."""
diff --git a/src/argaze/GazeAnalysis/DispersionThresholdIdentification.py b/src/argaze/GazeAnalysis/DispersionThresholdIdentification.py
index 34be490..4a55911 100644
--- a/src/argaze/GazeAnalysis/DispersionThresholdIdentification.py
+++ b/src/argaze/GazeAnalysis/DispersionThresholdIdentification.py
@@ -1,11 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of the I-DT algorithm as described in:
-        
-    **Dario D. Salvucci and Joseph H. Goldberg (2000).**  
-    *Identifying fixations and saccades in eye-tracking protocols.*  
-    Proceedings of the 2000 symposium on Eye tracking research & applications (ETRA'00, 71-78).  
-    [https://doi.org/10.1145/355017.355028](https://doi.org/10.1145/355017.355028)
+"""Dispersion threshold identification (I-DT) module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -101,6 +96,13 @@ class Saccade(GazeFeatures.Saccade):
 
 @dataclass
 class GazeMovementIdentifier(GazeFeatures.GazeMovementIdentifier):
+    """Implementation of the I-DT algorithm as described in:
+            
+        **Dario D. Salvucci and Joseph H. Goldberg (2000).**  
+        *Identifying fixations and saccades in eye-tracking protocols.*  
+        Proceedings of the 2000 symposium on Eye tracking research & applications (ETRA'00, 71-78).  
+        [https://doi.org/10.1145/355017.355028](https://doi.org/10.1145/355017.355028)
+    """
 
     deviation_max_threshold: int|float
     """Maximal distance allowed to consider a gaze movement as a fixation."""
diff --git a/src/argaze/GazeAnalysis/Entropy.py b/src/argaze/GazeAnalysis/Entropy.py
index c57900d..f248845 100644
--- a/src/argaze/GazeAnalysis/Entropy.py
+++ b/src/argaze/GazeAnalysis/Entropy.py
@@ -1,11 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of entropy algorithm as described in:
-
-    **Krejtz K., Szmidt T., Duchowski A.T. (2014).**  
-    *Entropy-based statistical analysis of eye movement transitions.*  
-    Proceedings of the Symposium on Eye Tracking Research and Applications (ETRA'14, 159-166).  
-    [https://doi.org/10.1145/2578153.2578176](https://doi.org/10.1145/2578153.2578176)
+"""Stationary and transition entropy module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -24,12 +19,16 @@ import numpy
 
 @dataclass
 class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
-    """ 
-    Parameters
-        transition_matrix_analyzer: to get its transition_matrix_probabilities result.
+    """Implementation of entropy algorithm as described in:
+
+        **Krejtz K., Szmidt T., Duchowski A.T. (2014).**  
+        *Entropy-based statistical analysis of eye movement transitions.*  
+        Proceedings of the Symposium on Eye Tracking Research and Applications (ETRA'14, 159-166).  
+        [https://doi.org/10.1145/2578153.2578176](https://doi.org/10.1145/2578153.2578176)
     """
 
     transition_matrix_analyzer: TransitionMatrix.AOIScanPathAnalyzer = field(default_factory=TransitionMatrix.AOIScanPathAnalyzer)
+    """To get its transition_matrix_probabilities result."""
 
     def __post_init__(self):
 
@@ -71,12 +70,13 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
 
     @property
     def stationary_entropy(self) -> float:
+        """Stationary entropy."""
 
         return self.__stationary_entropy
 
     @property
     def transition_entropy(self) -> float:
+        """Transition entropy."""
 
         return self.__transition_entropy
-    
     
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/ExploitExploreRatio.py b/src/argaze/GazeAnalysis/ExploitExploreRatio.py
index 0c55170..f35561f 100644
--- a/src/argaze/GazeAnalysis/ExploitExploreRatio.py
+++ b/src/argaze/GazeAnalysis/ExploitExploreRatio.py
@@ -1,16 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of exploit vs explore ratio algorithm as described in:
-
-    **Goldberg J. H., Kotval X. P. (1999).**  
-    *Computer interface evaluation using eye movements: methods and constructs.*   
-    International Journal of Industrial Ergonomics (631–645).  
-    [https://doi.org/10.1016/S0169-8141(98)00068-7](https://doi.org/10.1016/S0169-8141\\(98\\)00068-7)  
-        
-    **Dehais F., Peysakhovich V., Scannella S., Fongue J., Gateau T. (2015).**  
-    *Automation surprise in aviation: Real-time solutions.*  
-    Proceedings of the 33rd annual ACM conference on Human Factors in Computing Systems (2525–2534).  
-    [https://doi.org/10.1145/2702123.2702521](https://doi.org/10.1145/2702123.2702521)
+"""Exploit/Explore ratio module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -26,12 +16,21 @@ import numpy
 
 @dataclass
 class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
-    """
-    Parameters:
-        short_fixation_duration_threshold: time below which a fixation is considered to be short and so as exploratory.
+    """Implementation of exploit vs explore ratio algorithm as described in:
+
+        **Goldberg J. H., Kotval X. P. (1999).**  
+        *Computer interface evaluation using eye movements: methods and constructs.*   
+        International Journal of Industrial Ergonomics (631–645).  
+        [https://doi.org/10.1016/S0169-8141(98)00068-7](https://doi.org/10.1016/S0169-8141\\(98\\)00068-7)  
+            
+        **Dehais F., Peysakhovich V., Scannella S., Fongue J., Gateau T. (2015).**  
+        *Automation surprise in aviation: Real-time solutions.*  
+        Proceedings of the 33rd annual ACM conference on Human Factors in Computing Systems (2525–2534).  
+        [https://doi.org/10.1145/2702123.2702521](https://doi.org/10.1145/2702123.2702521)
     """
 
     short_fixation_duration_threshold: float = field(default=0.)
+    """Time below which a fixation is considered to be short and so as exploratory."""
     
     def __post_init__(self):
 
@@ -70,6 +69,7 @@ class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
 
     @property
     def exploit_explore_ratio(self) -> float:
+        """Exploit/Explore ratio."""
         
         return self.__exploit_explore_ratio
         
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/FocusPointInside.py b/src/argaze/GazeAnalysis/FocusPointInside.py
index bcb77b1..ac712a7 100644
--- a/src/argaze/GazeAnalysis/FocusPointInside.py
+++ b/src/argaze/GazeAnalysis/FocusPointInside.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-"""Matching algorithm based on fixation's focus point
+"""Module for matching algorithm based on fixation's focus point
 """
 
 __author__ = "Théo de la Hogue"
@@ -22,6 +22,7 @@ GazeMovementType = TypeVar('GazeMovement', bound="GazeMovement")
 
 @dataclass
 class AOIMatcher(GazeFeatures.AOIMatcher):
+    """Matching algorithm based on fixation's focus point."""
 
     def __post_init__(self):
         """Init looked aoi data."""
diff --git a/src/argaze/GazeAnalysis/KCoefficient.py b/src/argaze/GazeAnalysis/KCoefficient.py
index 46ecca3..80fe1fd 100644
--- a/src/argaze/GazeAnalysis/KCoefficient.py
+++ b/src/argaze/GazeAnalysis/KCoefficient.py
@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of K coefficient and K-modified coefficient.
+"""K coefficient and K-modified coefficient module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -61,6 +61,7 @@ class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
 
     @property
     def K(self) -> float:
+        """K coefficient."""
 
         return self.__K
     
@@ -111,6 +112,7 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
         self.__K = numpy.array(Ks).mean()
 
     @property
-    def K(self):
+    def K(self) -> float:
+        """K coefficient."""
 
         return self.__K
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/LempelZivComplexity.py b/src/argaze/GazeAnalysis/LempelZivComplexity.py
index 82ef05f..50c7a90 100644
--- a/src/argaze/GazeAnalysis/LempelZivComplexity.py
+++ b/src/argaze/GazeAnalysis/LempelZivComplexity.py
@@ -1,11 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of Lempel-Ziv complexity algorithm as described in:
-
-    **Lounis C., Peysakhovich V., Causse M. (2020).**  
-    *Lempel-Ziv Complexity of dwell sequences: visual scanning pattern differences between novice and expert aircraft pilots.*  
-    Proceedings of the 1st International Workshop on Eye-Tracking in Aviation (ETAVI'20, 61-68).  
-    [https://doi.org/10.3929/ethz-b-000407653](https://doi.org/10.3929/ethz-b-000407653)
+"""Lempel-Ziv complexity module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -22,6 +17,14 @@ from lempel_ziv_complexity import lempel_ziv_complexity
 @dataclass
 class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
 
+    """Implementation of Lempel-Ziv complexity algorithm as described in:
+
+        **Lounis C., Peysakhovich V., Causse M. (2020).**  
+        *Lempel-Ziv Complexity of dwell sequences: visual scanning pattern differences between novice and expert aircraft pilots.*  
+        Proceedings of the 1st International Workshop on Eye-Tracking in Aviation (ETAVI'20, 61-68).  
+        [https://doi.org/10.3929/ethz-b-000407653](https://doi.org/10.3929/ethz-b-000407653)
+    """
+
     def __post_init__(self):
 
         super().__init__()
@@ -37,6 +40,7 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
 
     @property
     def lempel_ziv_complexity(self) -> int:
+        """Lempel-Ziv complexity."""
         
         return self.__lempel_ziv_complexity
     
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/NGram.py b/src/argaze/GazeAnalysis/NGram.py
index bee9767..a19974a 100644
--- a/src/argaze/GazeAnalysis/NGram.py
+++ b/src/argaze/GazeAnalysis/NGram.py
@@ -1,11 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of N-Gram algorithm as proposed in:
-
-    **Lounis C., Peysakhovich V., Causse M. (2021).**  
-    *Visual scanning strategies in the cockpit are modulated by pilots’ expertise: A flight simulator study.*  
-    PLoS ONE (16(2), 6).  
-    [https://doi.org/10.1371/journal.pone.0247061](https://doi.org/10.1371/journal.pone.0247061)
+"""N-Gram module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -20,14 +15,19 @@ from argaze import GazeFeatures
 
 @dataclass
 class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
-    """
-    Parameters:
-        n_min: minimal grams length to search.
-        n_max: maximal grams length to search.
+    """Implementation of N-Gram algorithm as proposed in:
+
+        **Lounis C., Peysakhovich V., Causse M. (2021).**  
+        *Visual scanning strategies in the cockpit are modulated by pilots’ expertise: A flight simulator study.*  
+        PLoS ONE (16(2), 6).  
+        [https://doi.org/10.1371/journal.pone.0247061](https://doi.org/10.1371/journal.pone.0247061)
     """
 
     n_min: int = field(default=2)
+    """Minimal grams length to search."""
+
     n_max: int = field(default=2)
+    """Maximal grams length to search."""
 
     def __post_init__(self):
 
@@ -53,6 +53,7 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
 
     @property
     def ngrams_count(self) -> dict:
+        """N-Grams count."""
         
         return self.__ngrams_count
     
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/NearestNeighborIndex.py b/src/argaze/GazeAnalysis/NearestNeighborIndex.py
index 3a3807f..34432ad 100644
--- a/src/argaze/GazeAnalysis/NearestNeighborIndex.py
+++ b/src/argaze/GazeAnalysis/NearestNeighborIndex.py
@@ -1,11 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of Nearest Neighbor Index algorithm as described in:
-
-    **Di Nocera F., Terenzi M., Camilli M. (2006).**  
-    *Another look at scanpath: distance to nearest neighbour as a measure of mental workload.*  
-    Developments in Human Factors in Transportation, Design, and Evaluation.  
-    [https://www.researchgate.net](https://www.researchgate.net/publication/239470608_Another_look_at_scanpath_distance_to_nearest_neighbour_as_a_measure_of_mental_workload)
+"""Nearest Neighbor Index module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -23,13 +18,16 @@ from scipy.spatial.distance import cdist
 
 @dataclass
 class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
-    """Implementation of Nearest Neighbor Index (NNI) as described in Di Nocera et al., 2006
-    
-    Parameters:
-        size: frame dimension.
+    """Implementation of Nearest Neighbor Index algorithm as described in:
+
+        **Di Nocera F., Terenzi M., Camilli M. (2006).**  
+        *Another look at scanpath: distance to nearest neighbour as a measure of mental workload.*  
+        Developments in Human Factors in Transportation, Design, and Evaluation.  
+        [https://www.researchgate.net](https://www.researchgate.net/publication/239470608_Another_look_at_scanpath_distance_to_nearest_neighbour_as_a_measure_of_mental_workload)
     """
 
     size: tuple[float, float]
+    """Frame dimension."""
 
     def __post_init__(self):
 
@@ -63,6 +61,7 @@ class ScanPathAnalyzer(GazeFeatures.ScanPathAnalyzer):
 
     @property
     def nearest_neighbor_index(self) -> float:
+        """Nearest Neighbor Index."""
         
         return self.__nearest_neighbor_index
     
diff --git a/src/argaze/GazeAnalysis/TransitionMatrix.py b/src/argaze/GazeAnalysis/TransitionMatrix.py
index 1b2c41d..6f408e4 100644
--- a/src/argaze/GazeAnalysis/TransitionMatrix.py
+++ b/src/argaze/GazeAnalysis/TransitionMatrix.py
@@ -1,11 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of transition matrix probabilities and density algorithm as described in:
-
-    **Krejtz K., Szmidt T., Duchowski A.T. (2014).**  
-    *Entropy-based statistical analysis of eye movement transitions.*  
-    Proceedings of the Symposium on Eye Tracking Research and Applications, (ETRA'14, 159-166).  
-    [https://doi.org/10.1145/2578153.2578176](https://doi.org/10.1145/2578153.2578176)
+"""Transition matrix probabilities and density module.
 """
 
 __author__ = "Théo de la Hogue"
@@ -23,6 +18,13 @@ import numpy
 
 @dataclass
 class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
+    """Implementation of transition matrix probabilities and density algorithm as described in:
+
+        **Krejtz K., Szmidt T., Duchowski A.T. (2014).**  
+        *Entropy-based statistical analysis of eye movement transitions.*  
+        Proceedings of the Symposium on Eye Tracking Research and Applications, (ETRA'14, 159-166).  
+        [https://doi.org/10.1145/2578153.2578176](https://doi.org/10.1145/2578153.2578176)
+    """
 
     def __post_init__(self):
 
@@ -48,10 +50,12 @@ class AOIScanPathAnalyzer(GazeFeatures.AOIScanPathAnalyzer):
 
     @property
     def transition_matrix_probabilities(self) -> pandas.DataFrame:
+        """Transition matrix probabilities"""
 
         return self.__transition_matrix_probabilities
 
     @property
     def transition_matrix_density(self) -> float:
+        """Transition matrix density."""
 
         return self.__transition_matrix_density
\ No newline at end of file
diff --git a/src/argaze/GazeAnalysis/VelocityThresholdIdentification.py b/src/argaze/GazeAnalysis/VelocityThresholdIdentification.py
index fa38edf..c315b8c 100644
--- a/src/argaze/GazeAnalysis/VelocityThresholdIdentification.py
+++ b/src/argaze/GazeAnalysis/VelocityThresholdIdentification.py
@@ -1,12 +1,6 @@
 #!/usr/bin/env python
 
-"""Implementation of the I-VT algorithm as described in:
-        
-    **Dario D. Salvucci and Joseph H. Goldberg (2000).**  
-    *Identifying fixations and saccades in eye-tracking protocols.*  
-    In Proceedings of the 2000 symposium on Eye tracking research & applications (ETRA'00, 71-78).  
-    [https://doi.org/10.1145/355017.355028](https://doi.org/10.1145/355017.355028)
-"""
+"""Velocity threshold identification (I-VT) module."""
 
 __author__ = "Théo de la Hogue"
 __credits__ = []
@@ -103,10 +97,10 @@ class Saccade(GazeFeatures.Saccade):
 class GazeMovementIdentifier(GazeFeatures.GazeMovementIdentifier):
     """Implementation of the I-VT algorithm as described in:
         
-            Dario D. Salvucci and Joseph H. Goldberg. 2000. Identifying fixations and
-            saccades in eye-tracking protocols. In Proceedings of the 2000 symposium
-            on Eye tracking research & applications (ETRA '00). ACM, New York, NY, USA,
-            71-78. [http://dx.doi.org/10.1145/355017.355028](http://dx.doi.org/10.1145/355017.355028)
+        Dario D. Salvucci and Joseph H. Goldberg. 2000. Identifying fixations and
+        saccades in eye-tracking protocols. In Proceedings of the 2000 symposium
+        on Eye tracking research & applications (ETRA '00). ACM, New York, NY, USA,
+        71-78. [http://dx.doi.org/10.1145/355017.355028](http://dx.doi.org/10.1145/355017.355028)
     """
 
     velocity_max_threshold: int|float
-- 
cgit v1.1