from_numpy#

Get a Gaze 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 samples or any column list specifiers using this method.

Parameters:

samples (np.ndarray | None) – Two-dimensional samples data represented as a numpy ndarray. (default: None)
experiment (Experiment | None) – The experiment definition. (default: None)
events (Events | 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 samples data as columns or as rows. (default: ‘col’)
trial_columns (str | list[str] | None) – The name of the trial columns in the samples data frame. If the list is empty or None, the samples data frame is assumed to contain only one trial. If the list is not empty, the samples 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 samples data frame. (default: None)
time_unit (str | None) – The unit of the timestamps in the timestamp column in the samples data frame. 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. If time_unit is None, milliseconds are assumed. (default: None)
pixel_columns (list[str] | None) – The name of the pixel position columns in the samples data frame. (default: None)
position_columns (list[str] | None) – The name of the dva position columns in the samples data frame. (default: None)
velocity_columns (list[str] | None) – The name of the dva velocity columns in the samples data frame. (default: None)
acceleration_columns (list[str] | None) – The name of the dva acceleration columns in the samples 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 samples 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)
data (np.ndarray | None) – Two-dimensional samples data represented as a numpy ndarray. (default: None) .. deprecated:: v0.23.0 Please use samples instead. This field will be removed in v0.28.0.

Returns:

Returns Gaze object with data read from numpy array.

Return type:

Gaze

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 samples to pm.gaze.from_numpy(), by specifying schema and components. >>> gaze = pm.gaze.from_numpy( … samples=arr, … schema=schema, … time_column=’t’, … time_unit=’ms’, … position_columns=[‘x’, ‘y’], … orient=’col’, … ) >>> gaze.samples 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] │ │ 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(
...     samples=arr.T,
...     schema=schema,
...     time_column='t',
...     time_unit='ms',
...     position_columns=['x', 'y'],
...     orient='row',
... )
>>> gaze.samples
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] │
│ 0    ┆ [0.0, 0.0] │
│ 0    ┆ [0.0, 0.0] │
└──────┴────────────┘

Pass the samples 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.samples 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] │ │ 0 ┆ [0.0, 0.0] │ │ 0 ┆ [0.0, 0.0] │ └──────┴────────────┘

from_numpy#

This Page