pymovements.gaze.from_numpy#

Get a GazeDataFrame from a numpy array.

There are two mutually exclusive ways of conversion.

Single data array: Pass a single numpy array via data and specify its schema and orientation. You can then additionally pass column specifiers, e.g. time_column and position_columns.

Column specific arrays: For each type of signal, you can pass the numpy array explicitly, e.g. position or velocity. You must not pass data or any column list specifiers using this method.

Parameters:

data (np.ndarray | None) – Two-dimensional data represented as a numpy ndarray. (default: None)
experiment (Experiment | None) – The experiment definition. (default: None)
events (EventDataFrame | None) – A dataframe of events in the gaze signal. (default: None)
trial (np.ndarray | None) – Array of trial identifiers for each timestep. (default: None)
time (np.ndarray | None) – Array of timestamps. (default: None)
pixel (np.ndarray | None) – Array of gaze pixel positions. (default: None)
position (np.ndarray | None) – Array of gaze positions in degrees of visual angle. (default: None)
velocity (np.ndarray | None) – Array of gaze velocities in degrees of visual angle per second. (default: None)
acceleration (np.ndarray | None) – Array of gaze accelerations in degrees of visual angle per square second. (default: None)
distance (np.ndarray | None) – Array of eye-to-screen distances in millimiters. (default: None)
schema (list[str] | None) – A list of column names. (default: None)
orient (Literal['col', 'row']) – Whether to interpret the two-dimensional data as columns or as rows. (default: ‘col’)
trial_columns (str | list[str] | None) – The name of the trial columns in the input data frame. If the list is empty or None, the input data frame is assumed to contain only one trial. If the list is not empty, the input data frame is assumed to contain multiple trials and the transformation methods will be applied to each trial separately. (default: None)
time_column (str | None) – The name of the timestamp column in the input data frame. (default: None)
time_unit (str | None) – The unit of the timestamps. Supported units are ‘s’ for seconds, ‘ms’ for milliseconds and ‘step’ for steps. If the unit is ‘step’ the experiment definition must be specified. All timestamps will be converted to milliseconds. (default: None)
pixel_columns (list[str] | None) – The name of the pixel position columns in the input data frame. (default: None)
position_columns (list[str] | None) – The name of the dva position columns in the input data frame. (default: None)
velocity_columns (list[str] | None) – The name of the dva velocity columns in the input data frame. (default: None)
acceleration_columns (list[str] | None) – The name of the dva acceleration columns in the input data frame. (default: None)
distance_column (str | None) – The name of the column containing eye-to-screen distance in millimiters for each sample in the input data frame. If specified, the column will be used for pixel to dva transformations. If not specified, the constant eye-to-screen distance will be taken from the experiment definition. (default: None)

Returns:

Returns gaze data frame read from numpy array.

Return type:

GazeDataFrame

Examples

Creating an example numpy array with 4 columns and 100 rows. We call this layout column orientation. >>> import numpy as np >>> import pymovements as pm >>> >>> arr = np.zeros((3, 100)) >>> arr.shape (3, 100)

Specifying the underlying schema: >>> schema = [‘t’, ‘x’, ‘y’]

Pass the array as data to pm.gaze.from_numpy(), by specifying schema and components. >>> gaze = pm.gaze.from_numpy( … arr, … schema=schema, … time_column=’t’, … time_unit=’ms’, … position_columns=[‘x’, ‘y’], … orient=’col’, … ) >>> gaze.frame shape: (100, 2) ┌──────┬────────────┐ │ time ┆ position │ │ — ┆ — │ │ i64 ┆ list[f64] │ ╞══════╪════════════╡ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ … ┆ … │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ └──────┴────────────┘

Use the orient keyword argument to specify the layout of your array. >>> arr.T.shape (100, 3)

>>> gaze = pm.gaze.from_numpy(
...     arr.T,
...     schema=schema,
...     time_column='t',
...     time_unit='ms',
...     position_columns=['x', 'y'],
...     orient='row',
... )
>>> gaze.frame
shape: (100, 2)
┌──────┬────────────┐
│ time ┆ position   │
│ ---  ┆ ---        │
│ i64  ┆ list[f64]  │
╞══════╪════════════╡
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
│ …    ┆ …          │
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
└──────┴────────────┘

Pass the data explicitly via the specific keyword arguments, without having to specify a schema. >>> gaze = pm.gaze.from_numpy( … time=arr[0], … time_unit=’ms’, … position=arr[[1, 2]], … orient=’col’, … ) >>> gaze.frame shape: (100, 2) ┌──────┬────────────┐ │ time ┆ position │ │ — ┆ — │ │ i64 ┆ list[f64] │ ╞══════╪════════════╡ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ … ┆ … │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ └──────┴────────────┘