pymovements.Dataset.report_data_quality#

Dataset.report_data_quality(*, output_path: Path | str | None = None, checks: list[str] | None = None, measures: list[str] | None = None, levels: list[str] | None = None, raise_on_error: bool = False, max_gap_factor: float = 5.0, max_deviation: float = 0.05, min_fraction: float = 0.95) → DataQualityReport[source]#

Run sanity checks and compute data quality measures for all loaded gaze data.

Three processing stages are executed in sequence:

  1. Validation checks — eight stimulus-agnostic checks (see checks parameter) that verify column presence, dtypes, temporal continuity, and gaze range.

  2. Quality measures — data_loss, std_rms, rms_s2s, and bcea aggregated at dataset, subject, session, and trial level.

  3. BIDS output (optional) — writes derivative TSV/JSON files and a warnings.log under output_path / 'derivatives' / 'pymovements' /.

Parameters:
  • output_path (Path | str | None) – If provided, write BIDS-conformant derivative report files here. (default: None)

  • checks (list[str] | None) – Check identifiers to run. None runs all eight checks. Valid identifiers: 'trial_columns_exist', 'trial_columns_dtype', 'time_column_exists', 'gaze_components_defined', 'time_monotone', 'max_gap', 'sampling_rate_consistency', 'gaze_range'. (default: None)

  • measures (list[str] | None) – Measure identifiers to compute. None computes all four. Valid: 'data_loss', 'std_rms', 'rms_s2s', 'bcea'. (default: None)

  • levels (list[str] | None) – Aggregation levels for measures. None uses all four. Valid: 'dataset', 'subject', 'session', 'trial'. (default: None)

  • raise_on_error (bool) – If True, raise ValidationError on the first check result with severity 'fail' or 'error'. (default: False)

  • max_gap_factor (float) – Maximum allowed inter-sample gap as a multiple of the expected ISI. Passed to the 'max_gap' check. (default: 5.0)

  • max_deviation (float) – Maximum allowed relative deviation between empirical and declared sampling rate. Passed to the 'sampling_rate_consistency' check. (default: 0.05, i.e. 5%)

  • min_fraction (float) – Minimum fraction of non-null samples that must lie within screen bounds. Passed to the 'gaze_range' check. (default: 0.95, i.e. 95%)

Returns:

An object containing all CheckResult objects and per-level measure polars.DataFrame tables.

Return type:

DataQualityReport

Raises:
  • ValidationError – If raise_on_error is True and any check produces an error result.

  • ValueError – If any name in checks is not a valid check identifier.

Examples

>>> import pymovements as pm
>>> # dataset = pm.Dataset('ExampleDataset', path='data/')
>>> # dataset.load()
>>> # report = dataset.report_data_quality()
>>> # print(report.summary())