Parquet handoff¶

This is a runnable repository example, not a new stable 1.2.0 API. It converts an already loaded pandas or optional Polars table with declared column names and units, and refuses to call the dense importer when support is not complete.

Run the example and contract tests¶

python -m pip install -e .
python examples/interop_tabular_handoff.py
python scripts/validate_ecosystem_interop.py

To additionally check Polars to pandas conversion using official optional libraries:

python -m pip install polars pyarrow
python scripts/validate_ecosystem_interop.py

The example uses invented structural CSV fixtures, not real gaze or independent reference calibration.

View complete example source · View tests

Explicit Parquet / Polars conversion¶

Polars provides read_parquet and to_pandas. The latter requires pandas and PyArrow. Filenames and source fields must be supplied; there is no network download.

import polars as pl
from examples.interop_tabular_handoff import (
    canonicalize_gaze_table,
    to_dense_trajectory_set,
)

frame = pl.read_parquet("my_local_gaze_samples.parquet")
canonical, audit = canonicalize_gaze_table(
    frame,
    column_map={
        "participant_id": "person",
        "trial_id": "trial",
        "time_s": "seconds",
        "x": "horizontal",
        "y": "vertical",
    },
    time_unit="s",
    coordinate_system="normalized",
    metadata_columns=("condition",),
)
print(audit)
# Refuses missing x/y or unequal observed time grids.
gaze = to_dense_trajectory_set(canonical, audit)

For input already prepared using pymovements, the Gaze reference identifies its samples property as a Polars dataframe. Given an upstream Gaze instance, inspect its actual source columns and explicit units before mapping:

sample_frame = gaze.samples  # Given a pymovements.Gaze object
# Review source column names, trial keys and coordinate semantics first.
# Then pass sample_frame to canonicalize_gaze_table(...).

Do not conflate event detections with raw gaze samples, infer that upstream preprocessing guarantees accurate timestamps, or treat numerical agreement with another estimator as calibrated frequentist inference.

Why the example refuses some data¶

Dense conversion requires complete paired x/y observations at identical recorded times across curves. Missing, sparse or asynchronous gaze is not an error in itself; it simply needs a different mathematical representation. The example makes no hidden interpolation, sorting, aggregation, imputation or trial-level independence assumption.

Native irregular representation · Sparse planar MFPCA · Reproducibility checklist