Improving gaze analysis pipeline documentation.

1 files changed, 97 insertions, 0 deletions

diff --git a/docs/user_guide/gaze_analysis_pipeline/gaze_analysis_logging.md b/docs/user_guide/gaze_analysis_pipeline/gaze_analysis_logging.md
new file mode 100644
index 0000000..d79e3a6
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/gaze_analysis_logging.md
@@ -0,0 +1,97 @@
+Log gaze analysis
+=================
+
+[ArFrame](../../../argaze/#argaze.ArFeatures.ArFrame) and [ArLayer](../../../argaze/#argaze.ArFeatures.ArLayer) logging are optional pipeline steps. They are executed at each new scan path step to update logs.
+
+## Enable ArFrame and ArLayer logging
+
+[ArFrame](../../../argaze/#argaze.ArFeatures.ArFrame) and [ArLayer](../../../argaze/#argaze.ArFeatures.ArLayer) have a log attribute to enable analysis logging.
+
+Here is the JSON ArFrame configuration file example where logging is enabled for the ArFrame and for one ArLayer:
+
+```json
+{
+    "name": "My FullHD screen",
+    "size": [1920, 1080],
+    "log": true,
+    ...
+    "layers": {
+        "MyLayer": {
+            "log": true,
+            ...
+        }
+    }
+}
+```
+
+Then, here is how to access to logs dictionaries:
+
+```python
+# Assuming that all timestamped gaze positions have been processed by ArFrame.look method
+...
+
+# Access to ArFame scan path analysis logs
+for analysis, log in ar_frame.logs.items():
+    
+    # Do something with scan path analysis log
+    ...
+
+# Access to ArLayers AOI scan path analysis logs
+for layer_name, layer in ar_frame.layers.items():
+
+    for analysis, log in layer.logs.items():
+
+        # Do something with AOI scan path analysis log
+        ...
+```
+
+!!! note
+    [ArFrame](../../../argaze/#argaze.ArFeatures.ArFrame) and its [ArLayers](../../../argaze/#argaze.ArFeatures.ArLayer) logging are automatically done each time the [ArFrame.look](../../../argaze/#argaze.ArFeatures.ArFrame.look) method is called.  
+    [ArFrame](../../../argaze/#argaze.ArFeatures.ArFrame) logging records each scan path analysis into a dedicated timestamped data buffer each time a new scan path step happens.  
+    [ArLayer](../../../argaze/#argaze.ArFeatures.ArLayer) logging records each AOI scan path analysis into a dedicated timestamped data buffer each time a new AOI scan path step happens.
+
+## Export gaze analysis logs to CSV file
+
+It is possible to convert gaze analysis log as [Pandas DataFrame](https://pandas.pydata.org/docs/getting_started/intro_tutorials/01_table_oriented.html#min-tut-01-tableoriented) object which can be writen into a CSV file.
+
+```python
+import pandas
+
+# Assuming that all timestamped gaze positions have been processed by ArFrame.look method
+...
+
+# Export ArFame scan path analysis logs
+for analysis, log in ar_frame.logs.items():
+    
+    log.as_dataframe().to_csv(f'./{ar_frame.name}_{analysis}.csv')
+
+# Export ArLayers layers AOI scan path analysis logs
+for layer_name, layer in ar_frame.layers.items():
+
+    for analysis, log in layer.logs.items():
+
+        log.as_dataframe().to_csv(f'./{ar_frame.name}_{layer_name}_{analysis}.csv')
+
+```
+
+Assuming that [ArGaze.GazeAnalysis.Basic](../../../argaze/#argaze.GazeAnalysis.Basic) scan path analysis module is enabled for 'My FullHD screen' ArFrame, a ***My FullHD screen_argaze.GazeAnalysis.Basic.csv*** file would be created:
+
+|timestamped|path_duration|step_fixation_durations_average|steps_number|
+|:----------|:------------|:------------------------------|:-----------|
+|3460       |1750         |563.0                          |2           |
+|4291       |2623         |652.0                          |3           |
+|4769       |3107         |544.0                          |4           |
+|6077       |4411         |652.8                          |5           |
+|6433       |4760         |595.1                          |6           |
+|7719       |6050         |652.8                          |7           |
+|...        |...          |...                            |...         |
+
+Assuming that [ArGaze.GazeAnalysis.NGram](../../../argaze/#argaze.GazeAnalysis.NGram) AOI scan path analysis module is enabled for 'MyLayer' ArLayer, a ***My FullHD screen_MyLayer_argaze.GazeAnalysis.NGram.csv*** file would be created:
+
+|timestamped|ngrams_count|
+|:----------|:-----------|
+|5687       |"{3: {}, 4: {}, 5: {}}"|
+|6208       |"{3: {('upper_left_corner', 'lower_left_corner', 'lower_right_corner'): 1}, 4: {}, 5: {}}"|
+|...        |...         |
+
+