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:
Validation checks — eight stimulus-agnostic checks (see checks parameter) that verify column presence, dtypes, temporal continuity, and gaze range.
Quality measures —
data_loss,std_rms,rms_s2s, andbceaaggregated at dataset, subject, session, and trial level.BIDS output (optional) — writes derivative TSV/JSON files and a
warnings.logunderoutput_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.
Noneruns 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.
Nonecomputes all four. Valid:'data_loss','std_rms','rms_s2s','bcea'. (default: None)levels (list[str] | None) – Aggregation levels for measures.
Noneuses all four. Valid:'dataset','subject','session','trial'. (default: None)raise_on_error (bool) – If
True, raiseValidationErroron 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
CheckResultobjects and per-level measurepolars.DataFrametables.- Return type:
- Raises:
ValidationError – If raise_on_error is
Trueand 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())