tobii_pytracker.analyze.DataLoader

class tobii_pytracker.analyze.DataLoader(config: CustomConfig, root: Path | None = None)

Main analysis orchestrator. Handles loading data from each participant’s set folder (set_name), and delegates work to specialized analyzers.

__init__(config: CustomConfig, root: Path | None = None)

Methods

__init__(config[, root])
add_column(column_name[, value, func, ...])	Add a new column to one or more subjects' data.csv files.
get_all_data([flatten])	Return all subjects’ data.
get_slide_data(set_name, index[, flatten])	Return all information for a single slide.
get_subject_data(set_name[, flatten])	Return the full DataFrame for one subject.
get_subjects()	Return list of all discovered subjects.
plot_gaze(set_name, index[, size, alpha, ...])	Plot gaze points for a specified slide on its screenshot image.

add_column(column_name: str, value: Any | None = None, func: callable | None = None, subjects: List[str] | None = None, overwrite: bool = False, save: bool = True)

Add a new column to one or more subjects’ data.csv files.

Parameters

column_namestr

Name of the new column to add.

valueAny, optional

Constant value to assign to all rows (ignored if func is provided).

funccallable, optional

A function that takes a DataFrame and returns a Series or list of values to populate the new column (e.g. lambda df: df[‘x’] + df[‘y’]).

subjectslist of str, optional

List of subject names to modify. If None, applies to all subjects.

overwritebool, optional

If False (default), raises an error if the column already exists.

savebool, optional

If True, overwrites the modified data.csv on disk.

get_all_data(flatten: bool = False) → Dict[str, DataFrame]

Return all subjects’ data. If flatten=True, returns flattened gaze data for each subject.

get_slide_data(set_name: str, index: int, flatten: bool = False) → Any

Return all information for a single slide. If flatten=True, returns a DataFrame of gaze points (via _flatten_gaze_data()).

get_subject_data(set_name: str, flatten: bool = False) → DataFrame

Return the full DataFrame for one subject. If flatten=True, expands gaze data into individual rows.

get_subjects() → List[str]

Return list of all discovered subjects.

plot_gaze(set_name: str, index: int, size: int = 40, alpha: float = 0.6, color: str = 'red', save_path: Path | None = None, show: bool = True, flip_y: bool = True, gradient: bool = False, cmap: str = 'viridis', draw_both_eyes: bool = False, show_legend: bool = False)

Plot gaze points for a specified slide on its screenshot image.

By default, draws average gaze positions (avg_gaze_x, avg_gaze_y). If draw_both_eyes=True, also plots separate left (L) and right (R) gaze traces.

Parameters

set_namestr

Subject folder name.

indexint

Slide index in data.csv.

sizeint, optional

Marker size for gaze points.

alphafloat, optional

Transparency of gaze markers.

colorstr, optional

Uniform color (ignored if gradient=True).

save_pathPath, optional

If given, saves the plot to this path.

showbool, optional

Whether to display the plot interactively.

flip_ybool, optional

Whether to invert Y axis (default True).

gradientbool, optional

If True, color points along a colormap based on time/order.

cmapstr, optional

Colormap to use when gradient=True.

draw_both_eyesbool, optional

If True, also plot separate left/right gaze traces (default False).

show_legendbool, optional

If True, shows a legend for the gaze traces (default False).