tobii_pytracker.analyze.ClusterAnalyzer

class tobii_pytracker.analyze.ClusterAnalyzer(output_folder: Path, columns: List[str] | None = None, clustering_model: object | None = None, eps: float = 0.05, min_samples: int = 5, n_clusters: int | None = None)

Performs clustering on gaze coordinates.

Supports flexible clustering backends (DBSCAN, KMeans, or custom). Results can be visualized by overlaying cluster-colored gaze points on the corresponding screenshot.

Parameters

output_folderPath

Directory where results or plots can be saved.

columnslist[str], optional

Columns to use for clustering (default: [‘avg_gaze_x’, ‘avg_gaze_y’]).

clustering_modelobject, optional

Custom scikit-learn–compatible clustering model. If None, DBSCAN(eps, min_samples) is used.

epsfloat, optional

DBSCAN epsilon parameter (ignored if using custom model).

min_samplesint, optional

DBSCAN min_samples parameter (ignored if using custom model).

n_clustersint, optional

KMeans number of clusters (only used if clustering_model=’kmeans’).

__init__(output_folder: Path, columns: List[str] | None = None, clustering_model: object | None = None, eps: float = 0.05, min_samples: int = 5, n_clusters: int | None = None)

Methods

__init__(output_folder[, columns, ...])
analyze(data[, clustering_model, eps, ...])	Perform clustering on gaze coordinates.
plot_analysis(background_data, screenshot_path)	Visualize gaze points colored by cluster assignment.

analyze(data: DataFrame, clustering_model: object | None = None, eps: float | None = None, min_samples: int | None = None, n_clusters: int | None = None) → DataFrame

Perform clustering on gaze coordinates.

Parameters

datapd.DataFrame

Flattened gaze data with columns like [‘avg_gaze_x’, ‘avg_gaze_y’, ‘set_name’, ‘slide_index’].

clustering_modelobject, optional

Custom clustering model. Must implement .fit(X) and .labels_.

epsfloat, optional

DBSCAN epsilon parameter.

min_samplesint, optional

DBSCAN min_samples parameter.

n_clustersint, optional

KMeans n_clusters parameter.

Returns

pd.DataFrame

DataFrame with an additional ‘cluster’ column.

plot_analysis(background_data: DataFrame, screenshot_path: Path, title: str | None = None, set_name: str | None = None, slide_index: int | None = None, flip_y: bool = True, alpha: float = 0.7, point_size: float = 30.0, show_noise: bool = True, show: bool = True, save_path: Path | None = None)

Visualize gaze points colored by cluster assignment.

Parameters

background_datapd.DataFrame

Data returned by analyze(), with a ‘cluster’ column.

screenshot_pathPath

Path to the screenshot for this slide.

titlestr, optional

Plot title.

set_namestr, optional

Filter to a particular set.

slide_indexint, optional

Filter to a particular slide.

flip_ybool, optional

Whether to flip Y-axis (consistent with other analyzers).

alphafloat, optional

Transparency of points.

point_sizefloat, optional

Marker size.

show_noisebool, optional

Whether to show noise points (cluster = -1).

showbool, optional

Whether to display the figure interactively.

save_pathPath, optional

If provided, saves the plot to this path.