Timestamp Unit Specification

aeye-lab / pymovements

A python package for processing eye movement data

https://pymovements.readthedocs.io

MIT License

57 stars 11 forks source link

Timestamp Unit Specification #626

Closed jakobchwastek closed 3 months ago

jakobchwastek commented 7 months ago

Description of the problem

Currently GazeDataFrame and DatabaseDefinition lack explicit information about the unit of timestamps in the time column, which is crucial for some future functions.

Description of a solution

Add a time_column_unit parameter to the constructor of GazeDataFrame defining the unit of time_column.
Implement a check in GazeDataFrame to verify if the unit has been set when a time column is specified.
Add time_column_unit attribute in the DatasetDefinition class.
Expand functions gaze.from_csv, gaze.from_pandas, gaze.from_numpy to include a time_column_unit parameter.

Minmum Acceptance Criteria

Successful implementation of the proposed solution.
Add or adjust unit and integrations tests.
Update Documentation

jakobchwastek commented 7 months ago

Would it be beneficial to standardize all timestamps to milliseconds during the initialization of GazeDataFrame? This approach could simplify the implementation and testing of functions that handle timestamps by limiting them to a single unit. In that case time_column_unit would only reflect the unit of timestamps in input data frame.

dkrako commented 7 months ago

Yes I think that's the way to go! That way we have a standardized unit for all our subsequent transformations and only need to check in the init

dkrako commented 7 months ago

How do we want to specify the unit? as a string, e.g. ms, sec?

jakobchwastek commented 7 months ago

Yes, i would go with string. Do you think supporting seconds and milliseconds is sufficient for now?

jakobchwastek commented 7 months ago

Should we call the parameter time_column_unit or just time_unit

dkrako commented 7 months ago

Yes, i would go with string. Do you think supporting seconds and milliseconds is sufficient for now?

As a fallback we would probably also need to have a step unit. The specific time values in milliseconds would then be calculated by using the sampling rate.

So all in all we should support: seconds, milliseconds, step

dkrako commented 7 months ago

Should we call the parameter time_column_unit or just time_unit

I like simply time_unit. We just need to document that all time values will be transformed to milliseconds.