Edit timestamped gaze positions
===============================

Whatever eye data comes from a file on disk or from a live stream, timestamped gaze positions are required before to go further.

![Timestamped gaze positions](../../img/timestamped_gaze_positions.png)

## Import timestamped gaze positions from CSV file

It is possible to load timestamped gaze positions from a [Pandas DataFrame](https://pandas.pydata.org/docs/getting_started/intro_tutorials/01_table_oriented.html#min-tut-01-tableoriented) object which can be loaded from a CSV file.

```python
from argaze import GazeFeatures
import pandas

# Load gaze positions from a CSV file into Panda Dataframe
dataframe = pandas.read_csv('gaze_positions.csv', delimiter=",", low_memory=False)

# Convert Panda dataframe into timestamped gaze positions precising the use of each specific column labels
ts_gaze_positions = GazeFeatures.TimeStampedGazePositions.from_dataframe(dataframe, timestamp = 'Recording timestamp [ms]', x = 'Gaze point X [px]', y = 'Gaze point Y [px]')

# Iterate over timestamped gaze positions
for timestamped_gaze_position in ts_gaze_positions:

	# Do something with each timestamped gaze position
	...
```

## Edit timestamped gaze positions from live stream

When gaze positions comes from a real time input, gaze position can be edited thanks to [GazePosition](../../argaze.md/#argaze.GazeFeatures.GazePosition) class.
Besides, timestamps can be edited from the incoming data stream or, if not available, they can be edited thanks to the python [time package](https://docs.python.org/3/library/time.html).

``` python
from argaze import GazeFeatures

# Assuming to be inside the function where timestamp_µs, gaze_x and gaze_y values are catched
...

	# Define a timestamped gaze position converting microsecond timestamp into second timestamp
	timestamped_gaze_position = GazeFeatures.GazePosition((gaze_x, gaze_y), timestamp=timestamp_µs * 1e-6)

	# Do something with each timestamped gaze position
	...
```

``` python
from argaze import GazeFeatures

import time

# Init timestamp
start_time = time.time()

# Assuming to be inside the function where only gaze_x and gaze_y values are catched (no timestamp)
...

	# Define a timestamped gaze position with millisecond timestamp
	timestamped_gaze_position = GazeFeatures.GazePosition((gaze_x, gaze_y), timestamp=int((time.time() - start_time) * 1e3))

	# Do something with each timestamped gaze position
	...
```

!!! warning "Free time unit"
	Timestamps can either be integer or float, second, millisecond or what ever you need. The only concern is that all time values used in further configurations have to be all the same unit.

Now we have timestamped gaze positions at expected format, let's see how to analyze them.