Parsing

Functions for parsing EyeLink ASC files into structured Python objects.

extract

Parse EyeLink ASC data into structured Python objects (dataclasses).

Provides functions to extract calibration, validation, and display data from ASC files.

syelink.extract.parse_calibration_points(text)

Parse !CAL <a>, <b>  <c>, <d> lines into CalibrationPoint records.

First pair is the polynomial input (P-CR in HREF angular space); second pair is the target HREF gaze.

Return type:

list[CalibrationPoint]

Parameters:

text (str)

syelink.extract.parse_coefficients(text)

Parse calibration coefficients for X and Y.

Return type:

tuple[PolynomialCoefficients | None, PolynomialCoefficients | None]

Parameters:

text (str)

syelink.extract.parse_gains(text)

Parse calibration gains.

Return type:

CalibrationGains | None

Parameters:

text (str)

syelink.extract.parse_prenormalize(text)

Parse prenormalize offsets.

Return type:

tuple[float, float]

Parameters:

text (str)

syelink.extract.parse_corner_correction(text)

Parse corner correction coefficients.

Return type:

CornerCorrection | None

Parameters:

text (str)

Format in ASC file:

MSG 270129 !CAL Corner correction:

-1.3496e-05, -1.6691e-05 -4.8914e-05, -3.957e-05 -1.7359e-06, -5.3909e-05 -1.947e-05, 0.00017288

4 lines of (x, y) pairs for quadrants:

0 = top-left, 1 = top-right, 2 = bottom-left, 3 = bottom-right

syelink.extract.parse_calibration_block(block)

Parse a complete calibration block.

Return type:

CalibrationData

Parameters:

block (dict[str, Any])

syelink.extract.parse_validation_block(block)

Parse a complete validation block.

Return type:

ValidationData

Parameters:

block (dict[str, Any])

syelink.extract.parse_display_coords(asc_path)

Parse DISPLAY_COORDS from ASC file header.

Looks for line like: MSG 228029 DISPLAY_COORDS 0 0 1279 1023

Return type:

DisplayCoords | None

Parameters:

asc_path (str | Path)

syelink.extract.parse_gaze_samples(asc_path)

Parse gaze samples and raw pupil/CR data from ASC file.

Extracts all gaze samples from recording segments with mode, tracking parameters, and optional raw pupil/CR data.

Raw pupil + CR is parsed from MSG L/R … lines written by pyelink’s raw thread. These can be present in RECORD mode and, when the raw thread is also started across do_tracker_setup, in CALIBRATE/VALIDATE modes too.

In CALIBRATE and VALIDATE modes, the EyeLink sample line “gaze” fields actually contain raw pupil coordinates in camera sensor units (per EyeLink docs: “GAZE = pupil position for calibration”). They are used as a bare-pupil fallback for timestamps with no MSG-derived raw record, and gaze fields are set to None.

Parameters:

asc_path (str | Path) – Path to the ASC file

Return type:

list[GazeSample]

Returns:

List of GazeSample objects with gaze and optional raw data

syelink.extract.parse_href_samples(href_asc_path)

Parse per-sample HREF coordinates from an edf2asc -sh ASC export.

The HREF ASC has the same SAMPLE-line cadence as the gaze ASC but the per-eye coordinate columns carry head-referenced angular coordinates (HREF) instead of screen pixels. Binocular column order matches the gaze ASC:

time l_hx l_hy l_pa r_hx r_hy r_pa status

Only the binocular layout is supported here; the recordings this is built for are all binocular. Missing columns (".") are returned as None.

Parameters:

href_asc_path (str | Path) – Path to an edf2asc -sh ASC export.

Return type:

dict[int, tuple[float | None, float | None, float | None, float | None, float | None, float | None]]

Returns:

{timestamp: (l_hx, l_hy, l_pa, r_hx, r_hy, r_pa)}.

syelink.extract.parse_messages(asc_path)

Return user-sent messages from the asc, in file order.

Each entry corresponds to one tracker.send_message(text) call during the experiment (e.g. STEP_3_CALIBRATE_DARK_START, TARGET x=960 y=540). EyeLink-internal MSG lines (calibration coefficients, validation results, display setup, mode/config rows) are filtered out — they’re already represented as CalibrationData / ValidationData / DisplayCoords.

Return type:

list[Message]

Parameters:

asc_path (str | Path)

syelink.extract.parse_asc_file(asc_path, href_asc_path=None)

Parse an EyeLink ASC file and return structured session data.

This is the main entry point for parsing ASC files. It extracts: - Display coordinates - All calibration blocks with polynomial coefficients, gains, corner correction - All validation blocks with per-point errors and summary statistics

Parameters:

• asc_path (str | Path) – Path to the gaze-format ASC file (default edf2asc export).

• href_asc_path (str | Path | None) – Optional path to a matching HREF-format ASC export (edf2asc -sh). When provided, per-sample HREF coordinates are merged into each gaze sample by timestamp and exposed as left_href_x/y, right_href_x/y. Pupil area is cross-checked against the gaze ASC to make sure the two files were exported from the same EDF; a mismatch raises ValueError.

Return type:

SessionData

Returns:

SessionData object containing all parsed data

Raises:

ValueError – If the file is not an ASC file or is a binary file, or if an HREF ASC is provided whose pupil-area column disagrees with the gaze ASC at any matched timestamp.

Example

>>> session = parse_asc_file("data/recording.asc")
>>> print(f"Found {len(session.calibrations)} calibrations")
>>> session.save_json("output.json")

parser

ASC file parser for EyeLink eye tracking data.

Extracts calibrations, validations, and recordings from ASC files.

syelink.parser.find_all_segments(asc_file)

Extract complete calibration, validation, and recording blocks from an ASC file.

Parameters:

asc_file (str | Path) – Path to the ASC file

Return type:

tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]

Returns:

Tuple of (calibrations, validations, recordings) where each is a list of dicts with ‘timestamp’ and ‘text’ keys (recordings also have ‘start’ and ‘end’).