Writing User guide and use cases section.

5 files changed, 176 insertions, 0 deletions

diff --git a/docs/user_guide/timestamped_data/data_synchronisation.md b/docs/user_guide/timestamped_data/data_synchronisation.md
new file mode 100644
index 0000000..4454fa4
--- /dev/null
+++ b/docs/user_guide/timestamped_data/data_synchronisation.md
@@ -0,0 +1,106 @@
+Data synchronisation
+====================
+
+Recorded data needs to be synchronized to link them before further processings. 
+
+The [TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) class provides various methods to help in such task.
+
+## Pop last before
+
+![Pop last before](../../img/pop_last_before.png)
+
+The code below shows how to use [pop_last_before](/argaze/#argaze.DataStructures.TimeStampedBuffer.pop_last_before) method in order to synchronise two timestamped data buffers with different timestamps:
+
+``` python
+from argaze import DataStructures
+
+# Assuming A_data_record and B_data_record are [TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) instances with different timestamps
+
+for A_ts, A_data in A_data_record.items():
+
+       try:
+              
+              # Get nearest B data before current A data and remove all B data before (including the returned one)
+              B_ts, B_data = B_data_record.pop_last_before(A_ts)
+
+       # No data stored before A_ts timestamp
+       except KeyError:
+
+              pass
+
+```
+
+## Pop last until
+
+![Pop last until](../../img/pop_last_until.png)
+
+The code below shows how to use [pop_last_until](/argaze/#argaze.DataStructures.TimeStampedBuffer.pop_last_until) method in order to synchronise two timestamped data buffers with different timestamps:
+
+``` python
+from argaze import DataStructures
+
+# Assuming A_data_record and B_data_record are [TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) instances with different timestamps
+
+for A_ts, A_data in A_data_record.items():
+
+       try:
+
+              # Get nearest B data after current A data and remove all B data before
+              B_ts, B_data = B_data_record.pop_last_until(A_ts)
+
+       # No data stored until A_ts timestamp
+       except KeyError:
+
+              pass
+
+```
+
+## Get last before
+
+![Get last before](../../img/get_last_before.png)
+
+The code below shows how to use [get_last_before](/argaze/#argaze.DataStructures.TimeStampedBuffer.get_last_before) method in order to synchronise two timestamped data buffers with different timestamps:
+
+``` python
+from argaze import DataStructures
+
+# Assuming A_data_record and B_data_record are [TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) instances with different timestamps
+
+for A_ts, A_data in A_data_record.items():
+
+       try:
+              
+              # Get nearest B data before current A data
+              B_ts, B_data = B_data_record.get_last_before(A_ts)
+
+       # No data stored before A_ts timestamp
+       except KeyError:
+
+              pass
+
+```
+
+## Get last until
+
+![Get last until](../../img/get_last_until.png)
+
+The code below shows how to use [get_last_until](/argaze/#argaze.DataStructures.TimeStampedBuffer.get_last_until) method in order to synchronise two timestamped data buffers with different timestamps:
+
+``` python
+from argaze import DataStructures
+
+# Assuming A_data_record and B_data_record are TimeStampedBuffer instances with different timestamps
+
+for A_ts, A_data in A_data_record.items():
+
+       try:
+              
+              # Get nearest B data after current A data
+              B_ts, B_data = B_data_record.get_last_until(A_ts)
+
+       # No data stored until A_ts timestamp
+       except KeyError:
+
+              pass
+
+```
diff --git a/docs/user_guide/timestamped_data/introduction.md b/docs/user_guide/timestamped_data/introduction.md
new file mode 100644
index 0000000..2cee263
--- /dev/null
+++ b/docs/user_guide/timestamped_data/introduction.md
@@ -0,0 +1,6 @@
+Timestamped data
+================
+
+Working with wearable eye tracker devices implies to handle various timestamped data like frames, gaze positions, pupils diameter, fixations, saccades, ...
+
+This section mainly refers to [DataStructures.TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) class.
diff --git a/docs/user_guide/timestamped_data/ordered_dictionary.md b/docs/user_guide/timestamped_data/ordered_dictionary.md
new file mode 100644
index 0000000..8c93fc6
--- /dev/null
+++ b/docs/user_guide/timestamped_data/ordered_dictionary.md
@@ -0,0 +1,19 @@
+Ordered dictionary
+==================
+
+[TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) class inherits from [OrderedDict](https://docs.python.org/3/library/collections.html#collections.OrderedDict) as data are de facto ordered by time.
+
+Any data type can be stored using int or float keys as timestamp.
+
+```python
+from argaze import DataStructures
+
+# Create a timestamped data buffer
+ts_data = DataStructures.TimeStampedBuffer()
+
+# Store any data type using numeric keys
+ts_data[0] = 123
+ts_data[0.1] = "message"
+ts_data[0.23] = {"key": value}
+...
+```
diff --git a/docs/user_guide/timestamped_data/pandas_dataframe_conversion.md b/docs/user_guide/timestamped_data/pandas_dataframe_conversion.md
new file mode 100644
index 0000000..caddb11
--- /dev/null
+++ b/docs/user_guide/timestamped_data/pandas_dataframe_conversion.md
@@ -0,0 +1,31 @@
+Pandas dataframe conversion
+===========================
+
+A [Pandas dataframe](https://pandas.pydata.org/docs/getting_started/intro_tutorials/01_table_oriented.html#min-tut-01-tableoriented) is a python data structure allowing powerful table processings.
+
+[TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) instance can be converted into dataframe provided that data values are stored as dictionaries.
+
+```python
+from argaze import DataStructures
+
+# Create a timestamped data buffer
+ts_data = DataStructures.TimeStampedBuffer()
+
+# Store various data as dictionary
+ts_data[10] = {"A_key": 0, "B_key": 0.123}}
+ts_data[20] = {"A_key": 4, "B_key": 0.567}}
+ts_data[30] = {"A_key": 8, "B_key": 0.901}}
+...
+
+# Convert timestamped data buffer into dataframe
+ts_buffer_dataframe = ts_buffer.as_dataframe()
+```
+
+ts_buffer_dataframe would look like:
+
+|timestamp|A_key|B_key|
+|:--------|:----|:----|
+|10       |0    |0.123|
+|20       |4    |0.567|
+|30       |8    |0.901|
+|...      |...  |...  |
\ No newline at end of file
diff --git a/docs/user_guide/timestamped_data/saving_and_loading.md b/docs/user_guide/timestamped_data/saving_and_loading.md
new file mode 100644
index 0000000..d3f2b9c
--- /dev/null
+++ b/docs/user_guide/timestamped_data/saving_and_loading.md
@@ -0,0 +1,14 @@
+Saving and loading
+==================
+
+[TimeStampedBuffer](/argaze/#argaze.DataStructures.TimeStampedBuffer) instance can be saved as and loaded from JSON file format.
+
+```python
+
+# Save
+ts_data.to_json('./data.json')
+
+# Load
+ts_data = DataStructures.TimeStampedBuffer.from_json('./data.json')
+
+```