aeye-lab / pymovements

A python package for processing eye movement data
https://pymovements.readthedocs.io
MIT License
61 stars 12 forks source link

improve usability of gaze.from_numpy() by explicit array passing #501

Closed dkrako closed 1 year ago

dkrako commented 1 year ago

Description of the problem

The current implementation expects one big numpy array: https://github.com/aeye-lab/pymovements/blob/279d886c9c380a3bf17439c08cb30cf84ad8aa51/src/pymovements/gaze/integration.py#L33-L42

This list of names is then used to specify the columns in the data via pixel_columns etc.

Description of a solution

Instead it would be much nicer to directly specify the arrays like this

gaze_pixel = np.zeros((2, 1000))
pm.gaze.from_numpy(pixel=gaze_pixel)

but also something like this

dva_xr = np.zeros(1000)
dva_yr = np.zeros(1000)
dva_xl = np.zeros(1000)
dva_yl = np.zeros(1000)
pm.gaze.from_numpy(position=[dva_xl, dva_yl, dva_xr, dva_yr]))

i think this would need a signature similar to this:

def from_numpy(
        data: np.ndarray = None,
        time: np.ndarray | None,
        pixel: np.ndarray | list[np.ndarray] | None = None,
        position: np.ndarray | list[np.ndarray] | None = None,
        velocity: np.ndarray | list[np.ndarray] | None = None,
        acceleration: np.ndarray | list[np.ndarray] | None = None,
        schema: list[str] = None,
        experiment: Experiment | None = None,
        orient: Literal['col', 'row'] = 'col',
        time_column: str | None,
        pixel_columns: list[str] | list[int] | None = None,
        position_columns: list[str] | list[int] | None = None,
        velocity_columns: list[str] | list[int] | None = None,
        acceleration_columns: list[str] | list[int] | None = None,
) -> GazeDataFrame:

where pixel and pixel_columns would be mutually exclusive, etc.

we could also discuss adding **kwargs to the signature which then would be added as additional columns in the gaze frame.