pymovements.Gaze.validate#

Gaze.validate(*, trial_columns_exist: bool = True, trial_columns_dtype: bool = True, time_column_exists: bool = True, gaze_components_defined: bool = True, time_monotone: bool = True, max_gap: bool = True, max_gap_factor: float = 5.0, sampling_rate_consistency: bool = True, max_deviation: float = 0.05, gaze_range: bool = True, min_fraction: float = 0.95, source_path: str = '') → list[CheckResult][source]#

Run data quality validation checks on this gaze object.

Each check can be individually enabled or disabled via its boolean argument. By default all eight checks are run.

Parameters:

  • trial_columns_exist (bool) – Check that every column listed in trial_columns is present in the sample schema. (default: True)

  • trial_columns_dtype (bool) – Check that trial-identifier columns have integer or string dtype, not float. (default: True)

  • time_column_exists (bool) – Check that a numeric 'time' column is present. (default: True)

  • gaze_components_defined (bool) – Check that at least one coordinate column (pixel, position, velocity or acceleration) is present. (default: True)

  • time_monotone (bool) – Check that timestamps are strictly monotone increasing within each trial. (default: True)

  • max_gap (bool) – Check that no inter-sample gap exceeds max_gap_factor times the expected inter-sample interval. (default: True)

  • max_gap_factor (float) – Maximum allowed inter-sample gap as a multiple of the expected ISI. Only used when max_gap is True. (default: 5.0)

  • sampling_rate_consistency (bool) – Check that the empirical median ISI matches the declared sampling rate within max_deviation. (default: True)

  • max_deviation (float) – Maximum allowed relative deviation between empirical and declared sampling rate. Only used when sampling_rate_consistency is True. (default: 0.05, i.e. 5%)

  • gaze_range (bool) – Check that at least min_fraction of gaze samples fall within screen bounds. (default: True)

  • min_fraction (float) – Minimum fraction of non-null samples that must lie within screen bounds. Only used when gaze_range is True. (default: 0.95, i.e. 95%)

  • source_path (str) – Identifier for this gaze object (e.g. a file path). Included in the sources field of any failing CheckResult. (default: '')

Returns:

One CheckResult per enabled check, in the order listed above.

Return type:

list[CheckResult]

Examples

>>> import polars as pl
>>> from pymovements import Gaze
>>> samples = pl.DataFrame(
...     {'time': [0, 1, 2], 'x': [0.0, 1.0, 2.0], 'y': [0.0, 1.0, 2.0]}
... )
>>> gaze = Gaze(samples=samples, pixel_columns=['x', 'y'])
>>> results = gaze.validate()
>>> all(r.severity in {'pass', 'warning', 'fail', 'error'} for r in results)
True