Basic Feature Extraction

This example shows how to use the Extractor class to calculate a mix of features (statistics, measures, and distance-based) from fixation data.

 1"""
 2Basic Feature Extraction Example
 3================================
 4
 5This example shows how to use the ``Extractor`` class to calculate a mix of features
 6(statistics, measures, and distance-based) from fixation data.
 7"""
 8
 9import pandas as pd
10
11from eyefeatures.features.dist import EucDist
12from eyefeatures.features.extractor import Extractor
13from eyefeatures.features.measures import HurstExponent, SpectralEntropy
14from eyefeatures.features.stats import SaccadeFeatures
15
16fixations_df = pd.read_csv("data/fixations/fixations_subset.csv")
17print("Loaded fixations data:", fixations_df.shape)
18
19# Initialize Transformers
20# We select a few representative transformers from different categories
21transformers = [
22    # 1. Statistical Features: Saccade properties (length, speed, angles)
23    SaccadeFeatures(),
24    # 2. Measures: Complexity/Entropy measures
25    SpectralEntropy(),
26    HurstExponent(coordinate="norm_pos_x", n_iters=5),
27    # 3. Scanpath Distances: Euclidean distance to the 'mean' path of the group
28    EucDist(),
29]
30
31# Initialize Extractor
32extractor = Extractor(
33    features=transformers,
34    x="norm_pos_x",
35    y="norm_pos_y",
36    t="start_timestamp",
37    duration="duration",
38    dispersion="dispersion",
39    aoi="AOI",
40    pk=["Participant"],  # Group by participant
41    path_pk=["Participant"],  # Compare each participant to mean path of participants
42    return_df=True,
43)
44
45# Calculate Features
46fixations_df.dropna(inplace=True)
47features_df = extractor.fit_transform(fixations_df)
48
49print("\nResulting Features DataFrame:")
50print(features_df.head())
51print(f"\nShape: {features_df.shape}")
52print("\nColumns:", list(features_df.columns))