GriddedDistributionEntropy

class eyefeatures.features.measures.GriddedDistributionEntropy(grid_size=10, x=None, y=None, aoi=None, pk=None, return_df=True, ignore_errors=False)[source]

Bases: MeasureTransformer

Gridded Distribution Entropy.

Measures the randomness of the spatial distribution of fixations by discretizing the 2D plane into a grid. It calculates the Shannon entropy of the 2D histogram of fixations over this grid. High entropy indicates fixations are spread out across the grid; low entropy indicates clustering.

Parameters:

  • grid_size (int) – the number of bins (grid cells) per dimension for creating the histogram.

  • x (str) – X coordinate column name.

  • y (str) – Y coordinate column name.

  • aoi (str) – Area Of Interest column name(-s).

  • pk (list[str]) – primary key.

  • return_df (bool) – whether to return output as DataFrame or numpy array.

  • ignore_errors (bool) – If True, return NaN when feature computation fails; otherwise raise.

  • Given a set of 2D points \(\left\{(x_i, y_i) \right\}_{i=1}^N\) algorithm partitions the space into a grid consisting of \(g \times g\) cells.

  • Define the edges of the cells for each dimension: \(\text{Edges}_x = \left\{x_0, \dots, x_g \right\},\) \(\text{Edges}_y = \left\{y_0, \dots, y_g \right\}\).

  • Then, each bin is basically a \(B_{jk} = \left\{ (x, y): x_{j-1} \leq x < x_j, \, y_{k-1} \leq y < y_k \right\}\).

  • Construct a multi-dimensional histogram \(H\) where each element \(H_{jk}\) represents the count of data points falling to the \(B_{jk}\):

\[H_{jk} = \sum_{i=1}^N \mathbb{I}\left\{(x_i, y_i) \in B_{jk} \right\}\]

  • Normalize the histogram to obtain a probability distribution \(P \sim P_{jk} = \frac{H_{jk}}{N}\) and calculate its entropy.

\[S = -\sum_{i=1}^g\sum_{j=1}^g P_{jk}\log(P_{jk})\]

Reference

Melnyk, K., Friedman, L., & Komogortsev, O. V. (2024). What can entropy metrics tell us about the characteristics of ocular fixation trajectories? PLoS ONE, 19(1), e0291823. https://doi.org/10.1371/journal.pone.0291823.